1a28d39c72
Check if the configuration value of bsdtar_path does exist as a path before trying to execute the binary. Updated the tutorial reference of bsdtar to FreeBSD instead of Ubuntu. Change-Id: Ieba5da2f330aa11c40cce6c2ae9de40155f33b07
115 lines
4.8 KiB
ReStructuredText
115 lines
4.8 KiB
ReStructuredText
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 FreeBSD: https://www.freebsd.org/cgi/man.cgi?tar(1).
|
|
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.
|
|
|
|
A complete list of config options can be found at :ref:`config_list`.
|
|
|
|
.. _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 it. Depending on
|
|
the platform used, the files should be valid PowerShell, Python, Batch or Bash scripts.
|
|
The userdata can be also a PEM certificate, in a cloud-config format or a MIME content.
|
|
The user data plugin is capable of executing various script types and exit code value handling.
|
|
|
|
Based on their exit 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
|