a48c33e280
Document plugins, metadata services, configuration file, how the project is supposed to work and some user related usecases. Change-Id: I184a9409a9e9173c346f0ab149cb7d78ed87e0b3
116 lines
4.7 KiB
ReStructuredText
116 lines
4.7 KiB
ReStructuredText
.. _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
|