x/cloudbase-init
Code Issues Proposed changes

Add cloudbase-init Sphinx documentation

Browse Source 
Document plugins, metadata services, configuration file,
how the project is supposed to work and some user related usecases.

Change-Id: I184a9409a9e9173c346f0ab149cb7d78ed87e0b3
This commit is contained in:
Cosmin Poieana 2015-06-03 01:27:37 +03:00
parent 00f995f5cd
commit a48c33e280
12 changed files with 1602 additions and 362 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

344
README.rst
View File

@ -1,334 +1,32 @@
Portable OpenStack Cloud Initialization Service Portable Multi-Cloud Initialization Service
=============================================== ===========================================
The main goal of this project is to provide guest cloud initialization for * Author: Cloudbase Solutions Srl
Windows and other operating systems. * Contact: info@cloudbasesolutions.com
* Home page: http://www.cloudbase.it/cloud-init-windows/
The architecture of the project is highly flexible and allows extensions for * Documentation: http://cloudbase-init.readthedocs.org/en/latest/
additional clouds and plugins. * Source: https://github.com/stackforge/cloudbase-init
* License: Apache 2.0
There's no limitation in the type of supported Hypervisor. This service can be
used on instances running on Hyper-V, KVM, Xen, ESXi, etc
Documentation, support and contacts: http://www.cloudbase.it Downloads
---------
Binaries Stable
-------- ~~~~~~
The latest stable x64 and x86 releases are available at the following urls: * (64bit) https://www.cloudbase.it/downloads/CloudbaseInitSetup_Stable_x64.msi
* (32bit) https://www.cloudbase.it/downloads/CloudbaseInitSetup_Stable_x86.msi
https://www.cloudbase.it/downloads/CloudbaseInitSetup_Stable_x64.msi Beta
https://www.cloudbase.it/downloads/CloudbaseInitSetup_Stable_x86.msi ~~~~
Additionally, the following x64 and x86 builds are automatically generated by a * (64bit) https://www.cloudbase.it/downloads/CloudbaseInitSetup_x64.msi
Jenkins job at every commit: * (32bit) https://www.cloudbase.it/downloads/CloudbaseInitSetup_x86.msi
https://www.cloudbase.it/downloads/CloudbaseInitSetup_x64.msi
https://www.cloudbase.it/downloads/CloudbaseInitSetup_x86.msi
Metadata services Got a question?
----------------- ---------------
A metadata service has the role of pulling the metadata configuration Visit http://ask.cloudbase.it/questions/
information.
Supported clouds and metadata services:
* OpenStack (HTTP)
* OpenStack (ConfigDrive)
* Amazon EC2
* CloudStack
* OpenNebula
* Ubuntu MAAS
Plugins
-------
Plugins execute actions based on the metadata obtained by the service.
cloudbaseinit.plugins.common.sethostname.SetHostNamePlugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sets the instance's hostname.
cloudbaseinit.plugins.windows.createuser.CreateUserPlugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Creates a local cloud user (if it does not already exist) and adds it to a set
of provided local groups.
The following configuration parameters control the behaviour of this
plugin.
+------------+--------------------------------+------------------+
| Option | Description | Default |
+============+================================+==================+
| *username* | Name of the cloud user | *Admin* |
+------------+--------------------------------+------------------+
| *groups* | Comma separated list of groups | *Administrators* |
+------------+--------------------------------+------------------+
cloudbaseinit.plugins.windows.setuserpassword.SetUserPasswordPlugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sets the cloud user's password. If a password has been provided in the
metadata during boot (user_data) it will be used, otherwise a random password
will be generated, encrypted with the user's SSH public key and posted to the
metadata provider (currently supported only by the OpenStack HTTP metadata
provider).
+-------------------------+-------------------------------------------------------------------------------------+---------------------------+
| Option | Description | Default |
+=========================+=====================================================================================+===========================+
| *inject_user_password* | Can be set to false to avoid the injection of the password provided in the metadata | *True* |
+-------------------------+-------------------------------------------------------------------------------------+---------------------------+
| | Can control what happens with the password at the next logon. If this option | |
| | is set to `always`, the user will be forced to change the password at the next | |
| *first_logon_behaviour* | logon. If it is set to `clear_text_injected_only`, the user will be forced to | *clear_text_injected_only*|
| | change the password only if the password is a clear text password, coming from the | |
| | metadata. The last option is `no`, when the user is never forced. | |
+-------------------------+-------------------------------------------------------------------------------------+---------------------------+
cloudbaseinit.plugins.common.networkconfig.NetworkConfigPlugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Configures static networking.
+-------------------+------------------------------+---------+
| Option | Description | Default |
+===================+==============================+=========+
| *network_adapter* | Network adapter to configure | *None* |
+-------------------+------------------------------+---------+
If *network_adapter* is not specified, the first available ethernet
adapter will be chosen if it cannot be matched with the configuration provided
in the metadata.
cloudbaseinit.plugins.common.sshpublickeys.SetUserSSHPublicKeysPlugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Creates an "authorized_keys" file in the user's home directory containing the
SSH keys provided in the metadata.
It is needed by the
*cloudbaseinit.plugins.windows.setuserpassword.SetUserPasswordPlugin* plugin.
cloudbaseinit.plugins.windows.extendvolumes.ExtendVolumesPlugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Extends automatically a disk partition to it's maximum size. This is useful
when booting images with different flavors.
cloudbaseinit.plugins.windows.winrmlistener.ConfigWinRMListenerPlugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Configures a WinRM HTTPS listener to allow remote management via WinRS or
PowerShell.
cloudbaseinit.plugins.windows.winrmcertificateauth.ConfigWinRMCertificateAuthPlugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Enables password-less authentication for remote management via WinRS or
PowerShell.
See: http://www.cloudbase.it/windows-without-passwords-in-openstack/
cloudbaseinit.plugins.common.localscripts.LocalScriptsPlugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Executes any script (e.g. Powershell, CMD, etc) located in the following path.
+----------------------+--------------------+---------+
| Option | Description | Default |
+======================+====================+=========+
| *local_scripts_path* | Local scripts path | *None* |
+----------------------+--------------------+---------+
cloudbaseinit.plugins.windows.licensing.WindowsLicensingPlugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Activates the Windows instance if the following option is True.
+--------------------+------------------+---------+
| Option | Description | Default |
+====================+==================+=========+
| *activate_windows* | Activate Windows | *False* |
+--------------------+------------------+---------+
cloudbaseinit.plugins.windows.ntpclient.NTPClientPlugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Applies NTP client info based on the DHCP server options, if available.
+-----------------------+-------------------+---------+
| Option | Description | Default |
+=======================+===================+=========+
| *ntp_use_dhcp_config* | Set NTP from DHCP | *False* |
+-----------------------+-------------------+---------+
cloudbaseinit.plugins.common.mtu.MTUPlugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sets the network interfaces MTU based on the value provided by the DHCP server
options, if available.
This is particularly useful for cases in which a lower MTU value is required
for networking (e.g. OpenStack GRE Neutron Open vSwitch configurations).
+-----------------------+-------------------+---------+
| Option | Description | Default |
+=======================+===================+=========+
| *mtu_use_dhcp_config* | Set MTU from DHCP | *True* |
+-----------------------+-------------------+---------+
cloudbaseinit.plugins.common.userdata.UserDataPlugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Executes custom scripts provided with the user_data metadata as plain text or
compressed with Gzip.
Supported formats:
Windows batch
"""""""""""""
The file is executed in a cmd.exe shell (can be changed with the COMSPEC
environment variable). The *user_data* first line must be:
rem cmd
PowerShell
""""""""""
The user_data first line must be:
#ps1_sysnative
or for a x86 PowerShell execution:
#ps1_x86
Bash
""""
A bash shell needs to be installed in the system and available in the PATH in
order to use this feature. The user_data first line must start with:
#!
e.g.:
#!/bin/bash
cloud-config
""""""""""""
Cloud-config YAML configuration as supported by cloud-init, excluding Linux
specific content. The user_data first line must be:
#cloud-config
The following cloud-config directives are supported:
* write_files
Defines a set of files which will be created on
the local filesystem. It can be a list of items or only one item,
with the following attributes:
- path
Absolute path on disk where the content should be written
- content
The content which will be written in the given file
- permissions
Integer representing file permissions
- encoding
The encoding of the data in content.
Supported encodings are: ``b64``, ``base64`` for base64-encoded
content, ``gz``, ``gzip`` for gzip encoded content, ``gz+b64``,
``gz+base64``, ``gzip+b64``, ``gzip+base64`` for base64 encoded
gzip content.
Examples::
# One item
write_files:
encoding: b64
content: NDI=
path: C:\test
permissions: '0o466'
# Multiple items
write_files:
- encoding: b64
content: NDI=
path: C:\b64
permissions: '0644'
- encoding: base64
content: NDI=
path: C:\b64_1
permissions: '0644'
- encoding: gzip
content: !!binary |
H4sIAGUfoFQC/zMxAgCIsCQyAgAAAA==
path: C:\gzip
permissions: '0644'
* set_timezone
Change the underlying timezone.
Example::
set_timezone: Asia/Tbilisi
Multi-part userdata content
"""""""""""""""""""""""""""
MIME multi-part userdata is supported. The content will ne handled based on the
content type.
text/x-shellscript
""""""""""""""""""
Any script to be executed: PowerShell, CMD, Bash or Python.
text/part-handler
"""""""""""""""""
A script that can manage other content type parts. This is used in particular
by Heat / CFN templates, although Linux specific.
text/x-cfninitdata
""""""""""""""""""
Heat / CFN content. Written to the path provided by:
+-------------------+-------------------------+-------------+
| Option | Description | Default |
+===================+=========================+=============+
| *heat_config_dir* | Heat configuration path | *C:\\cfn* |
+-------------------+-------------------------+-------------+
Example Heat Windows templates: https://github.com/openstack/heat-templates/tree/master/hot/Windows

38
cloudbaseinit/osutils/windows.py
View File

@ -1040,43 +1040,7 @@ class WindowsUtils(base.BaseOSUtils):
C:\Windows\(System32|SysWOW64|Sysnative). C:\Windows\(System32|SysWOW64|Sysnative).
Note that "Sysnative" is just an alias (doesn't really exist on disk). Note that "Sysnative" is just an alias (doesn't really exist on disk).
On 32bit OSes, the return value will be the System32 directory, More info about this can be found in documentation.
which contains 32bit programs.
On 64bit OSes, the return value may be different, depending on the
Python bits and the `sysnative` parameter. If the Python interpreter is
32bit, the return value will be System32 (containing 32bit
programs) if `sysnative` is set to False and Sysnative otherwise. But
if the Python interpreter is 64bit and `sysnative` is False, the return
value will be SysWOW64 and System32 for a True value of `sysnative`.
Why this behavior and what is the purpose of `sysnative` parameter?
On a 32bit OS the things are clear, there is one System32 directory
containing 32bit applications and that's all. On a 64bit OS, there's a
System32 directory containing 64bit applications and a compatibility
one named SysWOW64 (WindowsOnWindows) containing the 32bit version of
them. Depending on the Python interpreter's bits, the `sysnative` flag
will try to bring the appropriate version of the system directory, more
exactly, the physical System32 or SysWOW64 found on disk. On a WOW case
(32bit interpreter on 64bit OS), a return value of System32 will point
to the physical SysWOW64 directory and a return value of Sysnative,
which is consolidated by the existence of this alias, will point to the
real physical System32 directory found on disk. If the OS is still
64bit and there is no WOW case (that means the interpreter is 64bit),
the system native concept is out of discussion and each return value
will point to the physical location it intends to.
On a 32bit OS the `sysnative` parameter has no meaning, but on a 64bit
one, based on its value, it will provide a real/alias path pointing to
system native applications if set to True (64bit programs) and to
system compatibility applications if set to False (32bit programs). Its
purpose is to provide the correct system paths by taking into account
the Python interpreter bits too, because on a 32bit interpreter
version, System32 is not the same with the System32 on a 64bit
interpreter. Also, using a 64bit interpreter, the Sysnative alias will
not work, but the `sysnative` parameter will take care to return
SysWOW64 if you explicitly want 32bit applications, by setting it to
False.
""" """
if sysnative and self.check_sysnative_dir_exists(): if sysnative and self.check_sysnative_dir_exists():
return self.get_sysnative_dir() return self.get_sysnative_dir()

192
doc/Makefile Normal file
View File

@ -0,0 +1,192 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/cloudbase-init.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/cloudbase-init.qhc"
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/cloudbase-init"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/cloudbase-init"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

263
doc/make.bat Normal file
View File

@ -0,0 +1,263 @@
@ECHO OFF
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set BUILDDIR=build
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
set I18NSPHINXOPTS=%SPHINXOPTS% source
if NOT "%PAPER%" == "" (
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
)
if "%1" == "" goto help
if "%1" == "help" (
:help
echo.Please use `make ^<target^>` where ^<target^> is one of
echo. html to make standalone HTML files
echo. dirhtml to make HTML files named index.html in directories
echo. singlehtml to make a single large HTML file
echo. pickle to make pickle files
echo. json to make JSON files
echo. htmlhelp to make HTML files and a HTML help project
echo. qthelp to make HTML files and a qthelp project
echo. devhelp to make HTML files and a Devhelp project
echo. epub to make an epub
echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
echo. text to make text files
echo. man to make manual pages
echo. texinfo to make Texinfo files
echo. gettext to make PO message catalogs
echo. changes to make an overview over all changed/added/deprecated items
echo. xml to make Docutils-native XML files
echo. pseudoxml to make pseudoxml-XML files for display purposes
echo. linkcheck to check all external links for integrity
echo. doctest to run all doctests embedded in the documentation if enabled
echo. coverage to run coverage check of the documentation if enabled
goto end
)
if "%1" == "clean" (
for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
del /q /s %BUILDDIR%\*
goto end
)
REM Check if sphinx-build is available and fallback to Python version if any
%SPHINXBUILD% 2> nul
if errorlevel 9009 goto sphinx_python
goto sphinx_ok
:sphinx_python
set SPHINXBUILD=python -m sphinx.__init__
%SPHINXBUILD% 2> nul
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
:sphinx_ok
if "%1" == "html" (
%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/html.
goto end
)
if "%1" == "dirhtml" (
%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
goto end
)
if "%1" == "singlehtml" (
%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
goto end
)
if "%1" == "pickle" (
%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the pickle files.
goto end
)
if "%1" == "json" (
%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the JSON files.
goto end
)
if "%1" == "htmlhelp" (
%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run HTML Help Workshop with the ^
.hhp project file in %BUILDDIR%/htmlhelp.
goto end
)
if "%1" == "qthelp" (
%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run "qcollectiongenerator" with the ^
.qhcp project file in %BUILDDIR%/qthelp, like this:
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\cloudbase-init.qhcp
echo.To view the help file:
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\cloudbase-init.ghc
goto end
)
if "%1" == "devhelp" (
%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished.
goto end
)
if "%1" == "epub" (
%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The epub file is in %BUILDDIR%/epub.
goto end
)
if "%1" == "latex" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
if errorlevel 1 exit /b 1
echo.
echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "latexpdf" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
cd %BUILDDIR%/latex
make all-pdf
cd %~dp0
echo.
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "latexpdfja" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
cd %BUILDDIR%/latex
make all-pdf-ja
cd %~dp0
echo.
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "text" (
%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The text files are in %BUILDDIR%/text.
goto end
)
if "%1" == "man" (
%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The manual pages are in %BUILDDIR%/man.
goto end
)
if "%1" == "texinfo" (
%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
goto end
)
if "%1" == "gettext" (
%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
goto end
)
if "%1" == "changes" (
%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
if errorlevel 1 exit /b 1
echo.
echo.The overview file is in %BUILDDIR%/changes.
goto end
)
if "%1" == "linkcheck" (
%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
if errorlevel 1 exit /b 1
echo.
echo.Link check complete; look for any errors in the above output ^
or in %BUILDDIR%/linkcheck/output.txt.
goto end
)
if "%1" == "doctest" (
%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
if errorlevel 1 exit /b 1
echo.
echo.Testing of doctests in the sources finished, look at the ^
results in %BUILDDIR%/doctest/output.txt.
goto end
)
if "%1" == "coverage" (
%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
if errorlevel 1 exit /b 1
echo.
echo.Testing of coverage in the sources finished, look at the ^
results in %BUILDDIR%/coverage/python.txt.
goto end
)
if "%1" == "xml" (
%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The XML files are in %BUILDDIR%/xml.
goto end
)
if "%1" == "pseudoxml" (
%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
goto end
)
:end

288
doc/source/conf.py
View File

@ -1 +1,287 @@
# Temporary placeholder # -*- coding: utf-8 -*-
#
# cloudbase-init documentation build configuration file, created by
# sphinx-quickstart on Wed Jun 03 01:25:56 2015.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
import shlex
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'cloudbase-init'
copyright = u'2015, Cloudbase Solutions Srl'
author = u'Cloudbase Solutions Srl'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '1.0'
# The full version, including alpha/beta/rc tags.
release = '1.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'classic'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
#html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# Now only 'ja' uses this config value
#html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'cloudbase-initdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
# Latex figure (float) alignment
#'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'cloudbase-init.tex', u'cloudbase-init Documentation',
u'Cloudbase Solutions Srl', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'cloudbase-init', u'cloudbase-init Documentation',
[author], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'cloudbase-init', u'cloudbase-init Documentation',
author, 'cloudbase-init', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False

26
doc/source/index.rst Normal file
View File

@ -0,0 +1,26 @@
.. cloudbase-init documentation master file, created by
sphinx-quickstart on Wed Jun 03 01:25:56 2015.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to cloudbase-init's documentation!
==========================================
Contents:
.. toctree::
:maxdepth: 2
intro
tutorial
services
plugins
userdata
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

43
doc/source/intro.rst Normal file
View File

@ -0,0 +1,43 @@
.. _intro:
Intro
=====
The open source `project <https://github.com/stackforge/cloudbase-init>`_
**cloudbase-init** is a service conceived and
maintained by Cloudbase Solutions Srl, currently working on NT systems.
It was designed to initialize and configure guest operating systems under
`OpenStack <https://www.openstack.org/>`_,
`OpenNebula <http://opennebula.org/>`_,
`CloudStack <https://cloudstack.apache.org/>`_,
`MaaS <https://maas.ubuntu.com/>`_ and many others.
Under `Cloudbase <http://www.cloudbase.it/cloud-init-windows/>`_ page,
beta and stable installers can be found and the service itself is very easy to
configure through configuration files. It can also customize instances based
on user input like local scripts and data.
More details on how you can use this can be found under :ref:`tutorial`.
Portable cloud initialization service
-------------------------------------
The main goal of this project is to provide guest cloud initialization for
*Windows* and other operating systems.
The architecture of the project is highly flexible and allows extensions for
additional clouds and plugins.
There's no limitation in the type of supported hypervisors. This service can be
used on instances running on Hyper-V, KVM, Xen, ESXi etc.
.. _download:
Binaries
--------
The following x64 and x86 builds are automatically generated by a Jenkins
job at every commit:
* https://www.cloudbase.it/downloads/CloudbaseInitSetup_x64.msi
* https://www.cloudbase.it/downloads/CloudbaseInitSetup_x86.msi

239
doc/source/plugins.rst Normal file
View File

@ -0,0 +1,239 @@
.. _plugins:
Plugins
=======
Plugins execute actions based on the metadata obtained by the loaded service.
They are intended to actually configure your instance using data provided by
the cloud and even by the user.
Current list of supported plugins:
Setting host name
-----------------
.. class:: cloudbaseinit.plugins.common.sethostname.SetHostNamePlugin
Sets the instance's hostname. It may be truncated to 15 characters for Netbios
compatibility reasons using the option below.
Config options:
* netbios_host_name_compatibility (bool: True)
.. warning:: This may require a system restart.
Creating user
-------------
.. class:: cloudbaseinit.plugins.windows.createuser.CreateUserPlugin
Creates (or updates if existing) a new user and adds it to a
set of provided local groups. By default, it creates the user "Admin" under
"Administrators" group, but this can be changed under configuration file.
Config options:
* username (string: "Admin")
* groups (list of strings: ["Administrators"])
Setting password
----------------
.. class:: cloudbaseinit.plugins.windows.setuserpassword.SetUserPasswordPlugin
Sets the cloud user's password. If a password has been provided in the metadata
during boot it will be used, otherwise a random password will be generated,
encrypted with the user's SSH public key and posted to the metadata provider
(currently supported only by the OpenStack HTTP metadata provider).
An option called `inject_user_password` is set *True* by default to make
available the use of metadata password which is found under the "admin_pass"
field or through an URL request. If the option is set to *False* or if the
password isn't found in metadata, then an attempt of using an already set
password is done (usually a random value by the `createuser` plugin).
With `first_logon_behaviour` you can control what happens with the password at
the next logon. If this option is set to "always", the user will be forced to
change the password at the next logon. If it is set to "clear_text_injected_only",
the user will be forced to change the password only if the password is a
clear text password, coming from the metadata. The last option is "no",
when the user is never forced.
Config options:
* inject_user_password (bool: True)
* first_logon_behaviour (string: "clear_text_injected_only")
.. note:: This plugin can run multiple times (for posting the password if the
metadata service supports this).
Static networking
-----------------
.. class:: cloudbaseinit.plugins.common.networkconfig.NetworkConfigPlugin
Statically configures each network adapter for which corresponding details
are found into metadata. The details/addresses association is done using
MAC matching and if this fails, then name or interface index matching.
The basic setting is based on IPv4 addresses, but it supports IPv6 addresses
too if they are enabled and exposed to the metadata.
The purpose of this plugin is to configure network adapters, for which the
DHCP server is disabled, to have internet access and static IPs.
.. warning:: This may require a system restart.
Saving public keys
------------------
.. class:: cloudbaseinit.plugins.common.sshpublickeys.SetUserSSHPublicKeysPlugin
Creates an **authorized_keys** file in the user's home directory containing
the SSH keys provided in the metadata. It is needed by the plugin responsible
for encrypting and setting passwords.
Config options:
* username (string: "Admin")
Volume expanding
----------------
.. class:: cloudbaseinit.plugins.windows.extendvolumes.ExtendVolumesPlugin
Extends automatically a disk partition to its maximum size. This is useful
when booting images with different flavors. By default, all the volumes are
extended, but you can select specific ones by populating with their indexes the
`volumes_to_extend` option.
Config options:
* volumes_to_extend (list of integers: None)
.. note:: This plugin will run at every boot.
WinRM listener
--------------
.. class:: cloudbaseinit.plugins.windows.winrmlistener.ConfigWinRMListenerPlugin
Configures a WinRM HTTPS listener to allow remote management via
`WinRM <https://msdn.microsoft.com/en-us/library/aa384426(v=vs.85).aspx>`_
or PowerShell.
Config options:
* winrm_enable_basic_auth (bool: True)
.. note:: This plugin will run until a full and proper configuration
will take place.
.. _certificate:
WinRM certificate
-----------------
.. class:: cloudbaseinit.plugins.windows.winrmcertificateauth.ConfigWinRMCertificateAuthPlugin
Enables password-less authentication for remote management via WinRS or
PowerShell. Usually uses x509 embedded with UPN certificates.
Config options:
* username (string: "Admin")
.. note:: http://www.cloudbase.it/windows-without-passwords-in-openstack/
.. _scripts:
Scripts execution
-----------------
.. class:: cloudbaseinit.plugins.common.localscripts.LocalScriptsPlugin
Executes any script (powershell, batch, python etc.) located in the following
path indicated by `local_scripts_path` option.
More details about the supported scripts and content can be found
in :ref:`tutorial` on :ref:`file execution <execution>` subject.
Config options:
* local_scripts_path (string: None)
.. warning:: This may require a system restart.
.. note:: This plugin may run multiple times (depending on the script(s)
return code).
Licensing
---------
.. class:: cloudbaseinit.plugins.windows.licensing.WindowsLicensingPlugin
Activates the Windows instance if the `activate_windows` option is *True*.
Config options:
* activate_windows (bool: False)
Clock synchronization
---------------------
.. class:: cloudbaseinit.plugins.windows.ntpclient.NTPClientPlugin
Applies NTP client info based on the DHCP server options, if available. This
behavior is enabled only when the `ntp_use_dhcp_config` option is set
to *True* (which by default is *False*).
Config options:
* ntp_use_dhcp_config (bool: False)
.. note:: This plugin will run until the NTP client is configured.
MTU customization
-----------------
.. class:: cloudbaseinit.plugins.common.mtu.MTUPlugin
Sets the network interfaces MTU based on the value provided by the DHCP server
options, if available and enabled (by default is *True*).
This is particularly useful for cases in which a lower MTU value is required
for networking (e.g. OpenStack GRE Neutron Open vSwitch configurations).
Config options:
* mtu_use_dhcp_config (bool: True)
.. note:: This plugin will run at every boot.
User data
---------
.. class:: cloudbaseinit.plugins.common.userdata.UserDataPlugin
Executes custom scripts provided by user data metadata as plain text or
compressed with Gzip.
More details, examples and possible formats here: :ref:`userdata`.
----
Configuring selected plugins
----------------------------
By default, all plugins are executed, but a custom list of them can be
specified through the `plugins` option in the configuration file.
For more details on doing this, see :ref:`configuration <config>`
file in :ref:`tutorial`.

193
doc/source/services.rst Normal file
View File

@ -0,0 +1,193 @@
.. _services:
Services
========
A **metadata service** has the role of pulling the guest provided data
(configuration information) and exposing it to the :ref:`plugins` for a
general and basic initialization of the instance.
These sub-services can change their behavior according to custom
configuration options, if they are specified, which are documented below.
Supported metadata services (cloud specific):
.. _httpservice:
OpenStack (web API)
-------------------
.. class:: cloudbaseinit.metadata.services.httpservice.HttpService
A complete service which also supports password related capabilities and
can be usually accessed with http://169.254.169.254/ magic address, which can
also be changed using `metadata_base_url` option under the config file. A
default value of *True* for `add_metadata_private_ip_route` option is used
to add a route for the IP address to the gateway. This is needed for supplying
a bridge between different VLANs in order to get access to the web server.
Capabilities:
* instance ID
* host name
* public keys
* authentication certificates (metadata + user data)
* static network configuration addresses
* admin password
* user data
* user content (additional files)
* ability to post passwords
Config options:
* metadata_base_url (string: "http://169.254.169.254/")
* add_metadata_private_ip_route (bool: True)
.. _configdrive:
OpenStack (configuration drive)
-------------------------------
.. class:: cloudbaseinit.metadata.services.configdrive.ConfigDriveService
This is similar to the web API, but it "serves" its files locally without
requiring network access. The data is generally retrieved from a
`cdrom <https://en.wikipedia.org/wiki/ISO_9660>`_,
`vfat <https://en.wikipedia.org/wiki/File_Allocation_Table#VFAT>`_ or
*raw* disks/partitions by enabling selective lookup across different devices.
Use the `config_drive_types` option to specify which types of config drive
content the service will search for and also on which devices using the
`config_drive_locations` option.
.. warning:: *deprecated options*
Using the option:
a. `config_drive_cdrom`
b. `config_drive_raw_hhd`
c. `config_drive_vfat`
It will search for metadata:
a. in mounted optical units
b. directly in the physical disk bytes
c. by exploring the physical disk as a vfat drive; which requires
*mtools* (specified by the `mtools_path` option)
The interesting part with this service is the fact that is quite fast in
comparison with the HTTP twin.
Capabilities:
* instance ID
* host name
* public keys (search in the entire metadata)
* authentication certificates (metadata + user data)
* static network configuration addresses
* admin password
* user data
* user content (additional files)
Config options:
* config_drive_types (list: ["vfat", "iso"])
* config_drive_locations (list: ["cdrom", "hdd", "partition"])
* mtools_path (string: None)
Amazon EC2
----------
.. class:: cloudbaseinit.metadata.services.ec2service.EC2Service
This is similar to the OpenStack HTTP service but is using a different
format for URLs and is having general capabilities.
Capabilities:
* instance ID
* host name
* public keys
Config options:
* ec2_metadata_base_url (string: "http://169.254.169.254/")
* ec2_add_metadata_private_ip_route (bool: True)
.. note:: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html
CloudStack
----------
.. class:: cloudbaseinit.metadata.services.cloudstack.CloudStack
Another web-based service which usually uses "10.1.1.1" or DHCP addresses for
retrieving content.
Capabilities:
* instance ID
* host name
* public keys
* admin password (retrieval/deletion/polling)
* user data
Config options:
* cloudstack_metadata_ip (string: "10.1.1.1")
.. note:: By design, this service can update the password anytime, so it will
cause the `setuserpassword` plugin to run at every boot and
by security concerns, the password is deleted right after retrieval
and no updating will occur until a new password is available on the
server.
OpenNebula
----------
.. class:: cloudbaseinit.metadata.services.opennebulaservice.OpenNebulaService
The *OpenNebula* provider is related to configuration drive and searches for
a specific context file which holds all the available info. The provided
details are exposed as bash variables gathered in a shell script.
Capabilities:
* instance ID (not present; usually a constant is returned)
* host name
* public keys
* static network configuration addresses
* user data
Ubuntu MaaS
-----------
.. class:: cloudbaseinit.metadata.services.maasservice.MaaSHttpService
This one works with instances on bare metal and uses web requests for
retrieving the available exposed metadata. It uses
`OAuth <http://oauth.net/>`_ to secure the requests.
Capabilities:
* instance ID
* host name
* public keys
* authentication certificates (x509)
* user data
----
Configuring available services
------------------------------
Some of these classes can be specified manually in the configuration file
under `metadata_services` option. Based on this option, the service loader
will search across these providers and try to load the most suitable one.
For more details on doing this, see :ref:`configuration <config>`
file in :ref:`tutorial`.

115
doc/source/tutorial.rst Normal file
View File

@ -0,0 +1,115 @@
.. _tutorial:
Tutorial
========
First, download your desired type of installer from :ref:`here <download>`,
then install it and fill in configuration options which suits you best.
Based on the current selected *cloudbase-init* installer architecture, it'll
be available under *C:\\Program Files* or *C:\\Program Files (x86)* as
**Cloudbase Solutions\\Cloudbase-Init** directory. There, are located some
folders of interest like:
* bin - Executable files and other binaries.
* conf - Configuration files holding miscellaneous options.
* log - Here are the cloudbase-init logs.
* LocalScripts - User supplied :ref:`scripts <execution>`.
* Python - Bundle of executable and library files to support Python
scripts and core execution.
After install, cloudbase-init acts like a 2-step service which will read
metadata using :ref:`services` and will pass that to the executing
:ref:`plugins`, this way configuring all the supported things.
Depending on the platform, some plugins may request reboots.
Sysprepping
-----------
The System Preparation (Sysprep) tool prepares an installation of Windows for
duplication, auditing, and customer delivery. Duplication, also called imaging,
enables you to capture a customized Windows image that you can reuse throughout
an organization.
The Sysprep phase uses the "Unattend.xml" which implies the service to run
using the "cloudbase-init-unattend.conf" configuration file.
.. _config:
Configuration file
------------------
In the chosen installation path, under the *conf* directory, are present
two config files named "cloudbase-init.conf" and
"cloudbase-init-unattend.conf".
These can hold various config options for picking up the desired available
services and plugins ready for execution and also customizing user experience.
*Explained example of configuration file:*
.. code-block:: text
[DEFAULT]
# What user to create and in which group(s) to be put.
username=Admin
groups=Administrators
inject_user_password=true # Use password from the metadata (not random).
# Which devices to inspect for a possible configuration drive (metadata).
config_drive_raw_hhd=true
config_drive_cdrom=true
# Path to tar implementation from Ubuntu.
bsdtar_path=C:\Program Files (x86)\Cloudbase Solutions\Cloudbase-Init\bin\bsdtar.exe
# Logging debugging level.
verbose=true
debug=true
# Where to store logs.
logdir=C:\Program Files (x86)\Cloudbase Solutions\Cloudbase-Init\log\
logfile=cloudbase-init-unattend.log
default_log_levels=comtypes=INFO,suds=INFO,iso8601=WARN
logging_serial_port_settings=
# Enable MTU and NTP plugins.
mtu_use_dhcp_config=true
ntp_use_dhcp_config=true
# Where are located the user supplied scripts for execution.
local_scripts_path=C:\Program Files (x86)\Cloudbase Solutions\Cloudbase-Init\LocalScripts\
# Services that will be tested for loading until one of them succeeds.
metadata_services=cloudbaseinit.metadata.services.configdrive.ConfigDriveService,
cloudbaseinit.metadata.services.httpservice.HttpService,
cloudbaseinit.metadata.services.ec2service.EC2Service,
cloudbaseinit.metadata.services.maasservice.MaaSHttpService
# What plugins to execute.
plugins=cloudbaseinit.plugins.common.mtu.MTUPlugin,
cloudbaseinit.plugins.common.sethostname.SetHostNamePlugin
# Miscellaneous.
allow_reboot=false # allow the service to reboot the system
stop_service_on_exit=false
The "cloudbase-init-unattend.conf" configuration file is similar to the
default one and is used by the Sysprepping phase. It was designed for the
scenario where the minimum user intervention is required and it only runs
the MTU and host name plugins, leaving the image ready for further
initialization cases.
More of these explained options are available under the :ref:`services`,
:ref:`plugins` and :ref:`userdata` documentation.
.. _execution:
File execution
--------------
Cloudbase-init has the ability to execute user provided scripts, usually
found in the default path
*C:\\Program Files (x86)\\Cloudbase Solutions\\Cloudbase-Init\\LocalScripts*,
through a specific :ref:`plugin <scripts>` for doing this stuff. Depending on
the platform used, the files should be valid MZPEs, PowerShell, Python,
Batch or Bash scripts, containing the actual code. The user data plugin is
also capable of executing various script types and return code value handling.
Based on their return codes, you can instruct the system to reboot or even
re-execute the plugin on the next boot:
* 1001 - reboot and don't run the plugin again on next boot
* 1002 - don't reboot now and run the plugin again on next boot
* 1003 - reboot and run the plugin again on next boot

221
doc/source/userdata.rst Normal file
View File

@ -0,0 +1,221 @@
.. _userdata:
Userdata
========
The *userdata* is the user custom content exposed to the guest instance
by the currently deployed and running cloud infrastructure. Its purpose is
to provide additional data for the instance to customize it as much as you
need, if the cloud initialization service does support this feature.
Fortunately, *cloudbase-init* is able to interpret and use this kind of user
specific data in multiple ways. In most of the cases, the thing that indicates
of what type is the processed data is usually the **first line**.
Currently supported contents:
PEM certificate
---------------
**-----BEGIN CERTIFICATE-----**
This one should start with a PEM specific beginning header, which will
be eventually parsed by the :ref:`configuration drive <configdrive>`
and :ref:`web API <httpservice>` OpenStack services and used by the
:ref:`certificate` plugin for storing and using it.
Batch
-----
**rem cmd**
The file is executed in a *cmd.exe* shell (can be changed with the `COMSPEC`
environment variable).
PowerShell
----------
**#ps1_sysnative** (system native)
**#ps1_x86** (Windows On Windows 32bit)
Execute PowerShell scripts using the desired executable. For finding out more
about the system nativeness thing, click :ref:`here <sysnative>`.
Bash
----
**#!/bin/bash**
A bash shell needs to be installed in the system and available in the `PATH`
in order to use this feature.
Python
------
**#!/usr/bin/env python**
Python is available by default with the build itself, but also it must be in
the system `PATH`.
EC2 format
----------
There is no "first line" here, but the content should follow a XML pattern
with valid Batch/PowerShell script contents under **script** or **powershell**
enclosing tags like in this example:
.. code-block:: xml
<script>
set root=%SystemDrive%
echo ec2dir>%root%\ec2file.txt
</script>
<powershell>
$root = $env:SystemDrive
$dname = Get-Content "$root\ec2file.txt"
New-Item -path "$root\$dname" -type directory
</powershell>
.. note:: http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/UsingConfig_WinAMI.html
Cloud config
------------
**#cloud-config**
Cloud-config YAML configuration as supported by *cloud-init*, excluding Linux
specific content.
The following cloud-config directives are supported:
* write_files - Defines a set of files which will be created on the local
filesystem. It can be a list of items or only one item,
with the following attributes:
1. path - Absolute path on disk where the content should be written.
2. content - The content which will be written in the given file.
3. permissions - Integer representing file permissions.
4. encoding - The encoding of the data in content. Supported encodings
are: b64, base64 for base64-encoded content, gz,
gzip for gzip encoded content, gz+b64, gz+base64,
gzip+b64, gzip+base64 for base64 encoded gzip content.
*Examples:*
.. code-block:: xml
# One item
write_files:
encoding: b64
content: NDI=
path: C:\test
permissions: '0o466'
.. code-block:: xml
# Multiple items
write_files:
- encoding: b64
content: NDI=
path: C:\b64
permissions: '0644'
- encoding: base64
content: NDI=
path: C:\b64_1
permissions: '0644'
- encoding: gzip
content: !!binary |
H4sIAGUfoFQC/zMxAgCIsCQyAgAAAA==
path: C:\gzip
permissions: '0644'
* set_timezone - Change the underlying timezone.
*Example:*
.. code-block:: text
set_timezone: Asia/Tbilisi
* set_hostname - Override the already default set host name value. (metadata)
*Example:*
.. code-block:: text
set_hostname: newhostname
Multi-part content
------------------
MIME multi-part user data is supported. The content will ne handled based on
the content type.
* text/x-shellscript - Any script to be executed: PowerShell, Batch, Bash
or Python.
* text/part-handler - A script that can manage other content type parts.
This is used in particular by Heat / CFN templates,
although Linux specific.
* text/x-cfninitdata - Heat / CFN content. Written to the path provided by
`heat_config_dir` option which defaults to "C:\\cfn".
(examples of Heat Windows `templates`_)
----
.. _sysnative:
Sysnativeness
-------------
*When deciding which path to use for system executable files...*
On 32bit OSes, the return value will be the *System32* directory,
which contains 32bit programs.
On 64bit OSes, the return value may be different, depending on the
Python bits and the `sysnative` parameter. If the Python interpreter is
32bit, the return value will be *System32* (containing 32bit
programs) if `sysnative` is set to False and *Sysnative* otherwise. But
if the Python interpreter is 64bit and `sysnative` is False, the return
value will be *SysWOW64* and *System32* for a True value of `sysnative`.
Why this behavior and what is the purpose of `sysnative` parameter?
On a 32bit OS the things are clear, there is one *System32* directory
containing 32bit applications and that's all. On a 64bit OS, there's a
*System32* directory containing 64bit applications and a compatibility
one named *SysWOW64* (WindowsOnWindows) containing the 32bit version of
them. Depending on the Python interpreter's bits, the `sysnative` flag
will try to bring the appropriate version of the system directory, more
exactly, the physical *System32* or *SysWOW64* found on disk. On a WOW case
(32bit interpreter on 64bit OS), a return value of *System32* will point
to the physical *SysWOW64* directory and a return value of *Sysnative*,
which is consolidated by the existence of this alias, will point to the
real physical *System32* directory found on disk. If the OS is still
64bit and there is no WOW case (that means the interpreter is 64bit),
the system native concept is out of discussion and each return value
will point to the physical location it intends to.
On a 32bit OS the `sysnative` parameter has no meaning, but on a 64bit
one, based on its value, it will provide a real/alias path pointing to
system native applications if set to True (64bit programs) and to
system compatibility applications if set to False (32bit programs). Its
purpose is to provide the correct system paths by taking into account
the Python interpreter bits too, because on a 32bit interpreter
version, *System32* is not the same with the *System32* on a 64bit
interpreter. Also, using a 64bit interpreter, the *Sysnative* alias will
not work, but the `sysnative` parameter will take care to return
*SysWOW64* if you explicitly want 32bit applications, by setting it to False.
.. _templates: https://github.com/openstack/heat-templates/tree/master/hot/Windows

2
test-requirements.txt
View File

@ -2,7 +2,7 @@ hacking<0.11,>=0.10.0
coverage>=3.6 coverage>=3.6
fixtures>=0.3.14 fixtures>=0.3.14
mock>=1.0 mock>=1.0
sphinx>=1.1.2,<1.1.999 sphinx
oslosphinx oslosphinx
testtools>=0.9.32 testtools>=0.9.32
testrepository>=0.0.18 testrepository>=0.0.18