diff --git a/README.rst b/README.rst index 077dc384..7f0aa053 100644 --- a/README.rst +++ b/README.rst @@ -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 -Windows and other operating systems. +* Author: Cloudbase Solutions Srl +* 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 -additional clouds and plugins. +* Documentation: http://cloudbase-init.readthedocs.org/en/latest/ +* 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 -https://www.cloudbase.it/downloads/CloudbaseInitSetup_Stable_x86.msi +Beta +~~~~ -Additionally, the following x64 and x86 builds are automatically generated by a -Jenkins job at every commit: +* (64bit) https://www.cloudbase.it/downloads/CloudbaseInitSetup_x64.msi +* (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 -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 +Visit http://ask.cloudbase.it/questions/ diff --git a/cloudbaseinit/osutils/windows.py b/cloudbaseinit/osutils/windows.py index c0afbb73..9cd0e01b 100644 --- a/cloudbaseinit/osutils/windows.py +++ b/cloudbaseinit/osutils/windows.py @@ -1040,43 +1040,7 @@ class WindowsUtils(base.BaseOSUtils): C:\Windows\(System32|SysWOW64|Sysnative). Note that "Sysnative" is just an alias (doesn't really exist on disk). - 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. + More info about this can be found in documentation. """ if sysnative and self.check_sysnative_dir_exists(): return self.get_sysnative_dir() diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..7faf91f1 --- /dev/null +++ b/doc/Makefile @@ -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 ' where 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." diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 00000000..f11307ad --- /dev/null +++ b/doc/make.bat @@ -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 ^` where ^ 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 diff --git a/doc/source/conf.py b/doc/source/conf.py index 1610bf42..3a9714bf 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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 +# " v 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 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 diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..e46020d4 --- /dev/null +++ b/doc/source/index.rst @@ -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` diff --git a/doc/source/intro.rst b/doc/source/intro.rst new file mode 100644 index 00000000..ea7a8239 --- /dev/null +++ b/doc/source/intro.rst @@ -0,0 +1,43 @@ +.. _intro: + +Intro +===== + +The open source `project `_ +**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 `_, +`OpenNebula `_, +`CloudStack `_, +`MaaS `_ and many others. +Under `Cloudbase `_ 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 diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst new file mode 100644 index 00000000..42d52d9a --- /dev/null +++ b/doc/source/plugins.rst @@ -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 `_ +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 ` 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 ` +file in :ref:`tutorial`. diff --git a/doc/source/services.rst b/doc/source/services.rst new file mode 100644 index 00000000..426171ad --- /dev/null +++ b/doc/source/services.rst @@ -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 `_, +`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 `_ 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 ` +file in :ref:`tutorial`. diff --git a/doc/source/tutorial.rst b/doc/source/tutorial.rst new file mode 100644 index 00000000..6bc012b0 --- /dev/null +++ b/doc/source/tutorial.rst @@ -0,0 +1,115 @@ +.. _tutorial: + +Tutorial +======== + +First, download your desired type of installer from :ref:`here `, +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 `. + * 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 ` 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 diff --git a/doc/source/userdata.rst b/doc/source/userdata.rst new file mode 100644 index 00000000..b1220e4b --- /dev/null +++ b/doc/source/userdata.rst @@ -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 ` +and :ref:`web API ` 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 `. + + +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 + + + + + $root = $env:SystemDrive + $dname = Get-Content "$root\ec2file.txt" + New-Item -path "$root\$dname" -type directory + + +.. 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 diff --git a/test-requirements.txt b/test-requirements.txt index b6a2bb0c..b4862ae8 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -2,7 +2,7 @@ hacking<0.11,>=0.10.0 coverage>=3.6 fixtures>=0.3.14 mock>=1.0 -sphinx>=1.1.2,<1.1.999 +sphinx oslosphinx testtools>=0.9.32 testrepository>=0.0.18