Plugins

Plugins execute actions based on the metadata obtained by the loaded service. They are intended to configure the instance using data provided by the underlying cloud and by the user who created the instance. There are three stages for the plugins’ execution:

1. The PRE_NETWORKING stage (for setting up the network, before doing any valid web request.

2. The PRE_METADATA_DISCOVERY stage (additional configuration before the metadata service discovery).

3. The default MAIN stage, which holds the rest of the plugins which are (re)executed according to their saved status. The metadata service loaded needs to provide an instance id for the plugins to be able to have a saved status. If the metadata service cannot provide an instance id, the plugins state from the MAIN stage cannot be saved, and therefore, all plugins will be executed at every boot.

Note that the plugins from the two stages are executed each time the cloudbase-init service starts (those plugins do not have saved status).

Just before the MAIN stage, the metadata service can report to the cloud service that the provision started. After the MAIN stage ended, the metadata service can report to the cloud service that the provisioning completed successfully or failed.


Configuring selected plugins

By default, only a subset of plugins is executed. The plugins are:

[DEFAULT]
plugins = cloudbaseinit.plugins.common.mtu.MTUPlugin, cloudbaseinit.plugins.windows.ntpclient.NTPClientPlugin, cloudbaseinit.plugins.common.sethostname.SetHostNamePlugin, cloudbaseinit.plugins.windows.createuser.CreateUserPlugin, cloudbaseinit.plugins.common.networkconfig.NetworkConfigPlugin, cloudbaseinit.plugins.windows.licensing.WindowsLicensingPlugin, cloudbaseinit.plugins.common.sshpublickeys.SetUserSSHPublicKeysPlugin, cloudbaseinit.plugins.windows.extendvolumes.ExtendVolumesPlugin, cloudbaseinit.plugins.common.userdata.UserDataPlugin, cloudbaseinit.plugins.common.setuserpassword.SetUserPasswordPlugin, cloudbaseinit.plugins.windows.winrmlistener.ConfigWinRMListenerPlugin, cloudbaseinit.plugins.windows.winrmcertificateauth.ConfigWinRMCertificateAuthPlugin, cloudbaseinit.plugins.common.localscripts.LocalScriptsPlugin

A custom list of plugins can be specified through the plugins option in the configuration file.

For more details on doing this, see configuration file in Tutorial.


Setting hostname (MAIN)

class cloudbaseinit.plugins.common.sethostname.SetHostNamePlugin

Sets the instance hostname. The hostname gets truncated to 15 characters for Netbios compatibility reasons if netbios_host_name_compatibility is set.

Config options:

  • netbios_host_name_compatibility (bool: True)

Notes:

  • Requires support in the metadata service.

  • May require a system restart.

Creating user (MAIN)

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 in the configuration file.

A random user password is set for the user. The password length is by default set to 20 and can be customized using the user_password_length configuration option.

If rename_admin_user is set to True, the user Administrator is renamed to the username config value or to the metadata service provided value.

Config options:

  • username (string: “Admin”)

  • groups (list of strings: [“Administrators”])

  • user_password_length (int: 20)

  • rename_admin_user (bool: false)

Notes:

  • The metadata service can provide the username. If the metadata service provides the admin username, it will override the username configuration value.

Setting password (MAIN)

class cloudbaseinit.plugins.common.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.

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 CreateUserPlugin 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 to change the password.

Config options:

  • username (string: “Admin”)

  • inject_user_password (bool: True)

  • first_logon_behaviour (string: “clear_text_injected_only”)

  • user_password_length (int: 20)

Notes:

  • The metadata service may provide the username. If the metadata service provides the admin username, it will override the username configuration value.

  • May run at every boot to (re)set and post the password if the metadata service supports this behaviour.

Static networking (MAIN)

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.

NIC teaming (bonding) is supported and uses NetLBFO implementation.

Notes:

  • Requires support in the metadata service.

  • May require a system restart.

Saving public keys (MAIN)

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”)

Notes:

  • Requires support in the metadata service. The metadata service provides the SSH public keys.

  • The metadata service can provide the username. If the metadata service provides the admin username, it will override the username configuration value.

Volume expanding (MAIN)

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)

Notes:

  • Runs at every boot.

WinRM listener (MAIN)

class cloudbaseinit.plugins.windows.winrmlistener.ConfigWinRMListenerPlugin

Configures a WinRM HTTPS listener to allow remote management via WinRM or PowerShell.

If winrm_enable_basic_auth is set to True, it enables basic authentication (authentication using username and password) for the WinRM listeners.

If winrm_configure_http_listener is set to True, the WinRM http listener will also be enabled.

Config options:

  • winrm_enable_basic_auth (bool: True)

  • winrm_configure_https_listener (bool: True)

  • winrm_configure_http_listener (bool: False)

Notes:
  • The metadata service can provide the listeners configuration (protocol and certificate thumbprint).

  • May run at every boot. If the WinRM Windows service does not exist, it will run at the next boot.

WinRM certificate (MAIN)

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”)

Notes

  • Requires support in the metadata service. The metadata service must provide the certificate metadata. The admin user password needs to be present, either from the metadata, either as shared data set by running CreateUserPlugin or SetUserPasswordPlugin. The metadata service can provide the username. If the metadata service provides the admin username, it will override the username configuration value.

  • How to use this feature: http://www.cloudbase.it/windows-without-passwords-in-openstack/

Local Scripts execution (MAIN)

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 Tutorial on file execution subject.

Config options:

  • local_scripts_path (string: None)

Notes:

  • May require a system restart.

  • May run at every boot. It depends on the exit codes of the scripts.

Licensing (MAIN)

class cloudbaseinit.plugins.windows.licensing.WindowsLicensingPlugin

Activates the Windows instance if the activate_windows option is True. If set_kms_product_key or set_avma_product_key are set, it will use that KMS or AVMA product key in Windows.

If kms_host is set, it will set the provided host as the KMS licensing server.

Config options:

  • activate_windows (bool: False)

  • set_kms_product_key (bool: False)

  • set_avma_product_key (bool: False)

  • kms_host (string: None)

  • log_licensing_info (bool: True)

Notes:

  • The metadata service can provide the KMS host, overriding the configuration option kms_host. The metadata service can provide the avma_product_key, overriding the configuration option set_avma_product_key.

Clock synchronization (PRE_NETWORKING)

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).

If real_time_clock_utc is set to True, it will set the real time clock to use universal time. If set to False, it will set the real time clock to use the local time.

Config options:

  • ntp_use_dhcp_config (bool: False)

  • real_time_clock_utc (bool: False)

  • ntp_enable_service (bool: True)

Notes:

  • May require a reboot.

  • May run at every boot.

MTU customization (PRE_METADATA_DISCOVERY)

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)

Notes:

  • Runs at every boot.

User data (MAIN)

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: Userdata.

Trim Config (MAIN)

class cloudbaseinit.plugins.common.trim.TrimConfigPlugin

Enables or disables TRIM delete notifications for the underlying storage device.

Config options:

  • trim_enabled (bool: False)

San Policy Config (MAIN)

class cloudbaseinit.plugins.windows.sanpolicy.SANPolicyPlugin

If not None, the SAN policy is set to the given value of the configuration option san_policy. The possible values are: OnlineAll, OfflineAll or OfflineShared.

Config options:

  • san_policy (string: None)

RDP Settings Config (MAIN)

class cloudbaseinit.plugins.windows.rdp.RDPSettingsPlugin

Sets the registry key KeepAliveEnable, to enable or disable the RDP keep alive functionality.

Config options:

  • rdp_set_keepalive (bool: False)

RDP Post Certificate Thumbprint (MAIN)

class cloudbaseinit.plugins.windows.rdp.RDPPostCertificateThumbprintPlugin

Posts the RDP certificate thumbprint to the metadata service endpoint.

Notes:

  • Requires support in the metadata service. The metadata service should expose an HTTP endpoint where the certificate thumbprint can be posted.

Page Files (MAIN)

class cloudbaseinit.plugins.windows.pagefiles.PageFilesPlugin

Sets custom page files according to the config options.

Config options:

  • page_file_volume_labels (array: [])

  • page_file_volume_mount_points (array: [])

Notes:

  • May require a reboot. If the page file is configured, a reboot is required.

  • Runs at every boot.

Display Idle Timeout Config (MAIN)

class cloudbaseinit.plugins.windows.displayidletimeout.DisplayIdleTimeoutConfigPlugin

Sets the idle timeout, in seconds, before powering off the display. Set 0 to leave the display always on.

Config options:

  • display_idle_timeout (int: 0)

Boot Status Policy Config (MAIN)

class cloudbaseinit.plugins.windows.bootconfig.BootStatusPolicyPlugin

Sets the Windows BCD boot status policy according to the config option. When set, the only possible value for bcd_boot_status_policy is ignoreallfailures.

Config options:

  • bcd_boot_status_policy (string: None)

BCD Config (MAIN)

class cloudbaseinit.plugins.windows.bootconfig.BCDConfigPlugin

A unique disk ID is needed to avoid disk signature collisions. This plugin resets the boot disk id and enables auto-recovery in the BCD store.

Config options:

  • set_unique_boot_disk_id (bool: False)

  • bcd_enable_auto_recovery (bool: False)

Ephemeral Disk Config (MAIN)

class cloudbaseinit.plugins.common.ephemeraldisk.EphemeralDiskPlugin

Sets the ephemeral disk data loss warning file. On public clouds like Azure, the ephemeral disk should contain a read only file with data loss warning text, that warns the user to not use the ephemeral disk as a persistent storage disk.

Config options:

  • ephemeral_disk_volume_label (string: None)

  • ephemeral_disk_volume_mount_point (string: None)

  • ephemeral_disk_data_loss_warning_path (string: None)

Notes:

  • Requires support in the metadata service. The metadata service should provide the disk data loss warning text.

Windows Auto Updates (MAIN)

class cloudbaseinit.plugins.windows.updates.WindowsAutoUpdatesPlugin

Enables automatic Windows updates based on the user configuration or the metadata service information. The metadata service setting takes priority over the configuration option.

Config options:

  • enable_automatic_updates (bool: False)

Notes:

  • If the metadata service provides the information needed to enable the automatic updates, it will override the enable_automatic_updates configuration value.

Server Certificates (MAIN)

class cloudbaseinit.plugins.windows.certificates.ServerCertificatesPlugin

Imports X509 certificates into the desired store location. The metadata service provides the certificate and key in a PFX archive, their store location and store name.

Notes:

  • Requires support in the metadata service.

Azure Guest Agent (MAIN)

class cloudbaseinit.plugins.windows.azureguestagent.AzureGuestAgentPlugin

Installs Azure Guest agent, which is required for the Azure cloud platform.

Notes:

  • Requires support in the metadata service. Azure metadata service should provide the agent package provisioning data.