Cloud-Init Reference

Cloud-init settings

This is an overview of most of the settings available for the Openstack-relevant modules in Cloud-init.

The document is based on the offical Cloud-init documentation located here:  http://cloudinit.readthedocs.org/en/latest/index.html.

Users

If no users are defined in the cloud-configuration, a default user is created. This user is typically named "ubuntu", "fedora", "debian" depending on the system image used.

You can make some changes to this default user, by using the following values:

password

Will set the users password. If you set the string to "R" or "RANDOM", a random password will be generated and written to stdout (the console).

If the password is set, the password will automatically be expired, forcing a password change on next login. This behaviour can be changed with the "chpasswd" setting.

SSH by default does not allow password authentication. This behaviour can be changed with the "ssh_pwauth" setting.

chpasswd

Use this to set multiple users passwords. Will also toggle password expiry.

chpasswd:
  list: |
    user1:password1
    user2:RANDOM
  expire: True

or

chpasswd: { expire: False }

Using the "users:" stanza, we can create local users on the system. An example:

users:
  - name: baffle
    gecos: Dag Stenstad
    shell: /bin/bash
    lock-passwd: false
    sudo: ALL=(ALL) NOPASSWD:ALL
    passwd: $6$fakepassword$TJ3Z7gk7z.DUSGRvCYTuBLJYYDUvApTdK0DxmYV0exnOpadcL/jCChjbBnOoUm6OeU6oBXC55UAoWW5dG/rQD.
    ssh-authorized-keys:
      - ssh-dss  AAAAB3NzaC1kc3MAAACBAIcAsIg3VXaz2kvG+yuM9Iy2A8eHNW3rI5DApPKT0jRNVi5Brt6gnaJf5z1cJd4adun9tMMCEQqwrf+9L/8Pk/N5QwnXj8rKLHLQCPa1fh3WsdPVhS8xOImlbvP2rM/tQCvMm++WoZbv50v39A+7yRgZy2IGO8VtJ+4jjYYgCmKPAAAAFQDwWhJpMiAxUqhnhrWNtIYxYUxrLQAAAIB1vMFx9CrUxoAw/DVAKJpgq/mfcUVj67W35aRmN33tynADfAvEKOPkP0uWOAK61/CxV7TmcgBKnJr843ZHpoDrkLrBL5ifkCLWsvsdw+ECNhqXzacHRuQekFS1Z3t7NuPcz67kpaEiZGFw3MreRedjrmukIy+H9tpr3KnZ6fyW1QAAAIA9N2rw++CinGJvjvGrIZe2SZMtJBRb0fAXzHqpPqNuNs/Q2P72hcvfBgkYu+vrghuIYJs3GIxVVbIW3d2WZwgZwbYuJqdn5VcPjEYEz/Gq9A3gBvIcJKbNwrlbbbOe1VRLnKM3o6EoHmke0Y2oDHQI+ADAWcyubt7W581G8kwnRg== baffle@deathstar

The following values can be used:

name

The users login name.

gecos

The users real name, or a complete GECOS field; The typical format for the GECOS field is a comma-delimited list with this order:

1. User's full name (or application name, if the account is for a program)
2. Building and room number or contact person
3. Office telephone number
4. Any other contact information (pager number, fax, etc.)

homedir

Set to the local path you want to use for the users home directory.

Default: Defaults to /home/<name>.

default

If defined it will create the default user defined for the operating system and inject the public key set during launch.

Default: If the "users" section is defined, the default user will not be created. If there is no "users" section in the configuration, the default user will be created.

primary-group

Defines the primary group.

Default: A new group is created, named after the user.

groups

Additional groups to add the user to.

Default: Defaults to none, no additional groups are added.

selinux-user

The SELinux user for the user's login, such as "staff_u".

Default: The system will select the default SELinux user.

lock-passwd

Lock the password to disable password login. If you require a password for sudo access, this must be set to false.

Default: True

inactive

Set the user as inactive.

Default: False

passwd

A salted password hash to set as the password for the user.

You can generate a safe hash using the mkpasswd command:

mkpasswd --method=SHA-512 --rounds=4096

Please note that allowing password based logins is a security risk.

no-create-home

Do not create a home directory.

Default: False

no-user-group

When set to true, do not create a group named after the user.

Default: False

no-log-init

When set to true, do not initialize lastlog and faillog database.

Default: False

ssh-import-id

Import SSH keys by ID from launchpad.net.

ssh-authorized-keys

Add keys to the users .ssh/authorized_keys file.

This is a list, entries must be prefixed with "-".

sudo

Set to the sudo string you want to use for this user.

Example without password authentication:

ALL=(ALL) NOPASSWD:ALL

Example without password authentication:

ALL=(ALL) ALL

If you want multiple rules, use a list:

      - ALL=(ALL) NOPASSWD:/bin/mysql
      - ALL=(ALL) ALL

Default: No sudo rules are added, the user can not elevate resources unless there is a systemwide policy.

Groups

Using the "groups:" stanza, we can create local groups on the system. Groups are created before users, and you use a YAML list to define the additional groups, alternatively with a list of users to be added.

Create the group "magicians":

groups:
  - magicians

Create the group "magicians" with "gandalf" and "harryp" as members.

groups:
  - magicians:
    - gandalf
    - harryp

Note: We've had some issues with this during testing.

Filesystems and partitions

# resize_rootfs should the / filesytem be resized on first boot # this allows you to launch an instance with a larger disk / partition # and have the instance automatically grow / to accomoddate it # set to 'False' to disable # by default, the resizefs is done early in boot, and blocks # if resize_rootfs is set to 'noblock', then it will be run in parallel resize_rootfs: True # set up mount points # 'mounts' contains a list of lists # the inner list are entries for an /etc/fstab line # ie : [ fs_spec, fs_file, fs_vfstype, fs_mntops, fs-freq, fs_passno ] # # default: # mounts: # - [ ephemeral0, /mnt ] # - [ swap, none, swap, sw, 0, 0 ] # # in order to remove a previously listed mount (ie, one from defaults) # list only the fs_spec. For example, to override the default, of # mounting swap: # - [ swap ] # or # - [ swap, null ] # # - if a device does not exist at the time, an entry will still be # written to /etc/fstab. # - '/dev' can be ommitted for device names that begin with: xvd, sd, hd, vd # - if an entry does not have all 6 fields, they will be filled in # with values from 'mount_default_fields' below. # # Note, that you should set 'nobootwait' (see man fstab) for volumes that may # not be attached at instance boot (or reboot) # mounts: - [ ephemeral0, /mnt, auto, "defaults,noexec" ] - [ sdc, /opt/data ] - [ xvdh, /opt/data, "auto", "defaults,nobootwait", "0", "0" ] - [ dd, /dev/zero ] # mount_default_fields # These values are used to fill in any entries in 'mounts' that are not # complete. This must be an array, and must have 7 fields. mount_default_fields: [ None, None, "auto", "defaults,nobootwait", "0", "2" ]

Timezone and locale

# timezone: set the timezone for this instance # the value of 'timezone' must exist in /usr/share/zoneinfo timezone: US/Eastern # set the locale to a given locale # default: en_US.UTF-8 locale: en_US.UTF-8 # render template default-locale.tmpl to locale_configfile locale_configfile: /etc/default/locale

Writing out arbitrary files

The "write_files" module of cloud-init can write files anywhere into the filesystem. Files can be Base64 encoded or gzip compressed.

The following values can be used:

path

Complete path and filename of the file to write. Example:

    path: /root/awesome.txt

encoding

What kind of encoding, if any, is used for the content of the file.

Valid values are:

• b64 - Base64 encoded file.
• gzip - Gzip compressed file.
• gz+b64 - Gzip compressed Base64 encoded file

Note: Encoding a file is optional, if it is undefined the default is that the file content is not encoded or compressed.

content

The content of the file.

A one-line text document:

    content: Hello world!

A multiline text document:

    content: |
      #!/bin/bash
      echo "Hello world!"
      exit 0

A binary file:

    content: !!binary |
        f0VMRgIBAQAAAAAAAAAAAAIAPgABAAAAwARAAAAAAABAAAAAAAAAAJAVAAAAAAAAAAAAAEAAOAAI
        AEAAHgAdAAYAAAAFAAAAQAAAAAAAAABAAEAAAAAAAEAAQAAAAAAAwAEAAAAAAADAAQAAAAAAAAgA
        AAAAAAAAAwAAAAQAAAAAAgAAAAAAAAACQAAAAAAAAAJAAAAAAAAcAAAAAAAAABwAAAAAAAAAAQAA

owner

The owner and group of the file. Example:

    owner: root:root

permissions

Unix file permissions for the file.

A more complete example:

write_files:
  - path: /etc/sysconfig/selinux
    encoding: b64
    content: CiMgVGhpcyBmaWxlIGNvbnRyb2xzIHRoZSBzdGF0ZSBvZiBTRUxpbnV4...
    owner: root:root
    permissions: '0644'
  - path: /etc/issue.net
    content: |
        Welcome to our new superserver!

        Please remember to close the door behind you.
  - path: /bin/arch
    content: !!binary |
        f0VMRgIBAQAAAAAAAAAAAAIAPgABAAAAwARAAAAAAABAAAAAAAAAAJAVAAAAAAAAAAAAAEAAOAAI
        AEAAHgAdAAYAAAAFAAAAQAAAAAAAAABAAEAAAAAAAEAAQAAAAAAAwAEAAAAAAADAAQAAAAAAAAgA
        AAAAAAAAAwAAAAQAAAAAAgAAAAAAAAACQAAAAAAAAAJAAAAAAAAcAAAAAAAAABwAAAAAAAAAAQAA
        ....
    permissions: '0555'
-   path: /usr/bin/helloworld
    encoding: gzip
    content: !!binary |
        H4sIAIDb/U8C/1NW1E/KzNMvzuBKTc7IV8hIzcnJVyjPL8pJ4QIA6N+MVxsAAAA=
    permissions: '0755'

Packages and Repositories

Install additional software, add additional package repositories and set up what mirror to use.

Packages

Install packages on first boot. You can also specify a specific verison. Example:

packages:
  - byobu
  - pwgen
  - [xfsprogs, 3.1.9ubuntu2]

You can also ensure that the system is up-to-date by forcing an upgrade at first boot:

package_upgrade: true

To allow the instance to reboot after package install/update, add:

package_reboot_if_required: true

APT repositories

Configure repositories for apt-based distributions like Ubuntu and Debian.

The following values can be used:

apt_mirror

Wich mirror to use for package updates. Example:

apt_mirror: http://no.archive.ubuntu.com/ubuntu/

apt_mirror_search

Search a list for available mirrors. Select the first one that resolves via DNS. Example:

apt_mirror_search:
 - http://local-mirror.mydomain/ubuntu/
 - http://no.archive.ubuntu.com/ubuntu/

apt_mirror_search_dns

Search for DNS-names "-mirror" in each of the FQDN, localdomain or domains in /etc/resolv.conf.

Default: false

apt_sources

Adds additional APT sources to the conifguration.

Expects a list of sources, with "source" and "key" keys.

Example:

apt_sources:
  - source: "deb http://apt.opscode.com/ $RELEASE-0.10 main"
    key: |
      -----BEGIN PGP PUBLIC KEY BLOCK-----
      Version: GnuPG v1.4.9 (GNU/Linux)

      mQGiBEppC7QRBADfsOkZU6KZK+YmKw4wev5mjKJEkVGlus+NxW8wItX5sGa6kdUu
      twAyj7Yr92rF+ICFEP3gGU6+lGo0Nve7KxkN/1W7/m3G4zuk+ccIKmjp8KS3qn99
      dxy64vcji9jIllVa+XXOGIp0G8GEaj7mbkixL/bMeGfdMlv8Gf2XPpp9vwCgn/GC
      JKacfnw7MpLKUHOYSlb//JsEAJqao3ViNfav83jJKEkD8cf59Y8xKia5OpZqTK5W
      ShVnNWS3U5IVQk10ZDH97Qn/YrK387H4CyhLE9mxPXs/ul18ioiaars/q2MEKU2I
      XKfV21eMLO9LYd6Ny/Kqj8o5WQK2J6+NAhSwvthZcIEphcFignIuobP+B5wNFQpe
      DbKfA/0WvN2OwFeWRcmmd3Hz7nHTpcnSF+4QX6yHRF/5BgxkG6IqBIACQbzPn6Hm
      sMtm/SVf11izmDqSsQptCrOZILfLX/mE+YOl+CwWSHhl+YsFts1WOuh1EhQD26aO
      Z84HuHV5HFRWjDLw9LriltBVQcXbpfSrRP5bdr7Wh8vhqJTPjrQnT3BzY29kZSBQ
      YWNrYWdlcyA8cGFja2FnZXNAb3BzY29kZS5jb20+iGAEExECACAFAkppC7QCGwMG
      CwkIBwMCBBUCCAMEFgIDAQIeAQIXgAAKCRApQKupg++Caj8sAKCOXmdG36gWji/K
      +o+XtBfvdMnFYQCfTCEWxRy2BnzLoBBFCjDSK6sJqCu5Ag0ESmkLtBAIAIO2SwlR
      lU5i6gTOp42RHWW7/pmW78CwUqJnYqnXROrt3h9F9xrsGkH0Fh1FRtsnncgzIhvh
      DLQnRHnkXm0ws0jV0PF74ttoUT6BLAUsFi2SPP1zYNJ9H9fhhK/pjijtAcQwdgxu
      wwNJ5xCEscBZCjhSRXm0d30bK1o49Cow8ZIbHtnXVP41c9QWOzX/LaGZsKQZnaMx
      EzDk8dyyctR2f03vRSVyTFGgdpUcpbr9eTFVgikCa6ODEBv+0BnCH6yGTXwBid9g
      w0o1e/2DviKUWCC+AlAUOubLmOIGFBuI4UR+rux9affbHcLIOTiKQXv79lW3P7W8
      AAfniSQKfPWXrrcAAwUH/2XBqD4Uxhbs25HDUUiM/m6Gnlj6EsStg8n0nMggLhuN
      QmPfoNByMPUqvA7sULyfr6xCYzbzRNxABHSpf85FzGQ29RF4xsA4vOOU8RDIYQ9X
      Q8NqqR6pydprRFqWe47hsAN7BoYuhWqTtOLSBmnAnzTR5pURoqcquWYiiEavZixJ
      3ZRAq/HMGioJEtMFrvsZjGXuzef7f0ytfR1zYeLVWnL9Bd32CueBlI7dhYwkFe+V
      Ep5jWOCj02C1wHcwt+uIRDJV6TdtbIiBYAdOMPk15+VBdweBXwMuYXr76+A7VeDL
      zIhi7tKFo6WiwjKZq0dzctsJJjtIfr4K4vbiD9Ojg1iISQQYEQIACQUCSmkLtAIb
      DAAKCRApQKupg++CauISAJ9CxYPOKhOxalBnVTLeNUkAHGg2gACeIsbobtaD4ZHG
      0GLl8EkfA8uhluM=
      =zKAm
      -----END PGP PUBLIC KEY BLOCK-----

Debian Debconf

You can set debconf-answers in the same way as you set them using a debian preseed-file or using debconf-set-selections. Example:

debconf_selections: |     # Need to perserve newlines
        # Force debconf priority to critical.
        debconf debconf/priority select critical

        # Override default frontend to readline, but allow user to select.
        debconf debconf/frontend select readline
        debconf debconf/frontend seen false

YUM repositories

Configure additional repositories for yum-based distributions like RHEL, CentOS and Fedora.

Start the confguration with the following stanza:

yum_repos:

Add configuration under this.

The following values can be used:

name

A human readable string describing the repository.

baseurl

The URL where the repository is located.

enabled

If the repository should be marked as enabled.

failovermethod

Either 'roundrobin' or 'priority'.

'roundrobin' randomly selects a URL out of the list of URLs to start with and proceeds through each of them as it encounters a failure contacting the host.

'priority' starts from the first baseurl listed and reads through them sequentially.

gpgcheck

Whether or not a GPG signature check should be performed on the packages in the repository.

gpgkey

A URL pointing to the ASCII-armored GPG key file for the repository.

This option is used if yum needs a public key to verify a package and the required key hasn't been imported into the RPM database. If this option is set, yum will automatically import the key from the specified URL.

A more complete example:

yum_repos:
    epel-testing:
        baseurl: http://download.fedoraproject.org/pub/epel/testing/5/$basearch
        enabled: true
        failovermethod: priority
        gpgcheck: true
        gpgkey: file:///etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL
        name: Extra Packages for Enterprise Linux 5 - Testing

Read the documentation for yum.conf for more details and additional options. Most options used in yum.conf can also be used here.

Automation and Configuration Management

Puppet

To automatically configure puppet, define the following stanza:

puppet:
  conf:

Every key present in the conf object will be added to to puppet.conf except the "ca_cert".

[name]
subkey=value

This configuration:

puppet:
  conf:
    agent:
      server: "puppetmaster.example.org"
      certname: "%i.%f"
    ca_cert: |
      -----BEGIN CERTIFICATE-----
      MIICCTCCAXKgAwIBAgIBATANBgkqhkiG9w0BAQUFADANMQswCQYDVQQDDAJjYTAe
      Fw0xMDAyMTUxNzI5MjFaFw0xNTAyMTQxNzI5MjFaMA0xCzAJBgNVBAMMAmNhMIGf
      MA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCu7Q40sm47/E1Pf+r8AYb/V/FWGPgc
      b014OmNoX7dgCxTDvps/h8Vw555PdAFsW5+QhsGr31IJNI3kSYprFQcYf7A8tNWu
      1MASW2CfaEiOEi9F1R3R4Qlz4ix+iNoHiUDTjazw/tZwEdxaQXQVLwgTGRwVa+aA
      qbutJKi93MILLwIDAQABo3kwdzA4BglghkgBhvhCAQ0EKxYpUHVwcGV0IFJ1Ynkv
      T3BlblNTTCBHZW5lcmF0ZWQgQ2VydGlmaWNhdGUwDwYDVR0TAQH/BAUwAwEB/zAd
      BgNVHQ4EFgQUu4+jHB+GYE5Vxo+ol1OAhevspjAwCwYDVR0PBAQDAgEGMA0GCSqG
      SIb3DQEBBQUAA4GBAH/rxlUIjwNb3n7TXJcDJ6MMHUlwjr03BDJXKb34Ulndkpaf
      +GAlzPXWa7bO908M9I8RnPfvtKnteLbvgTK+h+zX1XCty+S2EQWk29i2AdoqOTxb
      hppiGMp0tT5Havu4aceCXiy2crVcudj3NFciy8X66SoECemW9UYDCb9T5D0d
      -----END CERTIFICATE-----

Will result in this puppet.conf:

[puppetd]
server=puppetmaster.example.org
certname=i-0123456.ip-X-Y-Z.cloud.internal

The puppmaster ca certificate will be available in /var/lib/puppet/ssl/certs/ca.pem

"certname" supports substitutions at runtime; %i is the instanceid, %f is the FQDN of the instance.

Chef

To automatically configure chef, define the following stanza:

chef:

And then configure the following values under this key:

install_type

Can be set to "gems", "packages" or "omnibus".

"packages" installs Chef using the package system, "gems" installs Chef using ruby gems and "omnibus" installs using the OpsChef installer system.

omnibus_url

The URL to download the installer, if install_type is "omnibus".

force_install

If set to "true", run the installer even if chef-client appears to allready be installed.

server_url

The URL of the chef-server. Example:

  server_url: "https://chef.yourorg.com:4000"

node_name

The name of the node, defaults to the instance-id if not present.

environment

The name of the environment, defaults to "_default" if not present.

validation_name

The validation client name, defaults to "chef-validator" if not present. Typically set if using hosted chef.

validation_key

The PEM encoded certificate of the validation key. Example:

  validation_key: |
      -----BEGIN RSA PRIVATE KEY-----
      YOUR-ORGS-VALIDATION-KEY-HERE
      -----END RSA PRIVATE KEY-----

run_list

An list for the first boot json. Example:

  run_list:
   - "recipe[apache2]"
   - "role[db]"

initial_attributes

Initial attributes used by the cookbooks. Example:

  initial_attributes:
    apache:
      prefork:
        maxclients: 100
      keepalive: "off"

output

Capture all subprocess output into a logfile, useful for troubleshooting cloud-init issues. Example:

  output: {all: '| tee -a /var/log/cloud-init-output.log'}

A complete configuration might look like this:

chef:
  install_type: "omnibus"
  force_install: false
  server_url: "https://chef.yourorg.com:4000"
  node_name: "server01"
  environment: "production"
  validation_name: "yourorg-validator"
  validation_key: |
     -----BEGIN RSA PRIVATE KEY-----
     YOUR-ORGS-VALIDATION-KEY-HERE
     -----END RSA PRIVATE KEY-----
  run_list:
    - "recipe[apache2]"
    - "role[db]"
  initial_attributes:
    apache:
      prefork:
        maxclients: 100
      keepalive: "off"
  omnibus_url: "https://www.opscode.com/chef/install.sh"
  output: {all: '| tee -a /var/log/cloud-init-output.log'}

SaltStack

To automatically configure SaltStacks salt-minion, define the "salt_minion"-stanza:

salt-minion:

This will automatically install the salt-minion package from the configured software repositories.

You can then use the "conf" key to configure the configuration: def handle(name, cfg, cloud, log, _args): # If there isn't a salt key in the configuration don't do anything if 'salt_minion' not in cfg: log.debug(("Skipping module named %s," " no 'salt_minion' key in configuration"), name) return salt_cfg = cfg['salt_minion'] # Start by installing the salt package ... cloud.distro.install_packages(('salt-minion',)) # Ensure we can configure files at the right dir config_dir = salt_cfg.get("config_dir", '/etc/salt') util.ensure_dir(config_dir) # ... and then update the salt configuration if 'conf' in salt_cfg: # Add all sections from the conf object to /etc/salt/minion minion_config = os.path.join(config_dir, 'minion') minion_data = util.yaml_dumps(salt_cfg.get('conf')) util.write_file(minion_config, minion_data) # ... copy the key pair if specified if 'public_key' in salt_cfg and 'private_key' in salt_cfg: pki_dir = salt_cfg.get('pki_dir', '/etc/salt/pki') with util.umask(077): util.ensure_dir(pki_dir) pub_name = os.path.join(pki_dir, 'minion.pub') pem_name = os.path.join(pki_dir, 'minion.pem') util.write_file(pub_name, salt_cfg['public_key']) util.write_file(pem_name, salt_cfg['private_key']) # restart salt-minion. 'service' will start even if not started. if it # was started, it needs to be restarted for config change. util.subp(['service', 'salt-minion', 'restart'], capture=False)

Configure trusted CA certificates

By using the "ca-certs:" stanza, you can configure the trusted CA certificates system-wide for SSL/TLS trust establishment when the instance boots for the first time. An example configuration:

ca-certs:
  trusted:
  - |
   -----BEGIN CERTIFICATE-----
   YOUR-ORGS-TRUSTED-CA-CERT-HERE
   -----END CERTIFICATE-----
  - |
   -----BEGIN CERTIFICATE-----
   YOUR-ORGS-TRUSTED-CA-CERT-HERE
   -----END CERTIFICATE-----

The following values can be used:

trusted

A list with PEM files of all the certificates you trust, typically used to insert your own organizations certificate.

remove-defaults

Remove all default trusted CA-certificates that are normally shipped with the operating system.

DNS and name-resolution

Hostname

These settings control how /etc/hostname is set.

hostname

Set the hostname on the instance to the supplied value.

Default:Hostname as returned by the metadata service.

preserve_hostname

When set to "false", update the hostname on boot, except if it is manually set by the user.

When set to "true", never update /etc/hostname.

Default: false

fqdn

Set the fully qualified domain name on the instance to the supplied value.

Default: FQDN as returned by the metadata service.

Hosts

These settings control how /etc/hosts is managed.

manage_etc_hosts

When set to "false", Cloud-init will not modify /etc/hosts at all.

When set to "true" or "template", /etc/hosts will be rewritten from /etc/cloud/templates/hosts.tmpl on every boot.

The strings '$hostname' and '$fqdn' are replaced in the template with the appropriate values.

To make modifications persistant across a reboot, you must make modificatoins to /etc/cloud/templates/hosts.tmpl

When set to "localhost", Cloud-init will set the hostname and fqdn of the instance in /etc/hosts for the 127.0.1.1 entry. It will not modify other entries.

Default: false

Note: This value should be set to "localhost" or "true" in your configuration to set a proper FQDN and hostname in /etc/hosts at installation time.

Configure resolv.conf

manage-resolv-conf

When set to "false", ignore this module.

When set to "true", override the default setup of resolv.conf, and configure it using the template below.

manage-resolv-conf: true
resolv_conf:
  nameservers: ['8.8.4.4', '8.8.8.8']
  searchdomains:
    - foo.example.com
    - bar.example.com
  domain: example.com
  options:
    rotate: true
    timeout: 1

Note: Currently this feature only works on Fedora, RHEL and SLES.

SSH

ssh_pwauth

If set to "true", enables password-based SSH logins.

Default: false

ssh_svcname

The name of the SSH service, used with "service restart". Defaults to "ssh".

ssh_deletekeys

When set to "true", existing ssh keys will be deleted on first boot on a per-instance basis.

This should always be set on public images.

ssh_genkeytypes

A list of the ssh key types that should be generated. These are passed to 'ssh-keygen -t'

ssh_genkeytypes: ['rsa', 'dsa', 'ecdsa']

ssh_fp_console_blacklist ssh_key_console_blacklist

Configuration of ssh keys output to console.

A list of key types (first token of a /etc/ssh/ssh_key_*.pub file) that should be skipped when outputting key fingerprints and keys to the console respectively.

ssh_import_id

Import SSH keys by ID from launchpad.net.

This is a string or list of IDs to be imported. Example:

ssh_import_id: [baffle, hpotter]

ssh_authorized_keys

A list of public SSH keys that will be added to the default user, or the first user defined in the users-section. Example:

ssh_authorized_keys:
  - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAGEA3FSyQwBI6Z+nCSjUUk8EEAnnkhXlukKoUPND/RRClWz2s5TCzIkd3Ou5+Cyz71X0XmazM3l5WgeErvtIwQMyT1KjNoMhoJMrJnWqQPOt5Q8zWd9qG7PBl9+eiH5qV7NZ mykey@host
  - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA3I7VUf2l5gSn5uavROsc5HRDpZdQueUq5ozemNSj8T7enqKHOEaFoU2VoPgGEWC9RyzSQVeyD6s7APMcE82EtmW4skVEgEGSbDc1pvxzxtchBj78hJP6Cf5TCMFSXw+Fz5rF1dR23QDbN1mkHs7adr8GW4kSWqU7Q7NDwfIrJJtO7Hi42GyXtvEONHbiRPOe8stqUly7MvUoN+5kfjBM8Qqpfl2+FNhTYWpMfYdPUnE7u536WqzFmsaqJctz3gBxH9Ex7dFtrxR4qiqEr9Qtlu3xGn7Bw07/+i1D+ey3ONkZLN+LQ714cgj8fRS4Hj29SCmXp5Kt5/82cD/VN3NtHw== smoser@brickies

ssh_keys

Install pre-generated SSH private keys on the instance instead of generating a random key. Supports 'rsa', 'dsa' and 'ecdsa'. Example:

ssh_keys:
  rsa_private: |
    -----BEGIN RSA PRIVATE KEY-----
    MIIBxwIBAAJhAKD0YSHy73nUgysO13XsJmd4fHiFyQ+00R7VVu2iV9Qcon2LZS/x
    1cydPZ4pQpfjEha6WxZ6o8ci/Ea/w0n+0HGPwaxlEG2Z9inNtj3pgFrYcRztfECb
    1j6HCibZbAzYtwIBIwJgO8h72WjcmvcpZ8OvHSvTwAguO2TkR6mPgHsgSaKy6GJo
    PUJnaZRWuba/HX0KGyhz19nPzLpzG5f0fYahlMJAyc13FV7K6kMBPXTRR6FxgHEg
    L0MPC7cdqAwOVNcPY6A7AjEA1bNaIjOzFN2sfZX0j7OMhQuc4zP7r80zaGc5oy6W
    p58hRAncFKEvnEq2CeL3vtuZAjEAwNBHpbNsBYTRPCHM7rZuG/iBtwp8Rxhc9I5w
    ixvzMgi+HpGLWzUIBS+P/XhekIjPAjA285rVmEP+DR255Ls65QbgYhJmTzIXQ2T9
    luLvcmFBC6l35Uc4gTgg4ALsmXLn71MCMGMpSWspEvuGInayTCL+vEjmNBT+FAdO
    W7D4zCpI43jRS9U06JVOeSc9CDk2lwiA3wIwCTB/6uc8Cq85D9YqpM10FuHjKpnP
    REPPOyrAspdeOAV+6VKRavstea7+2DZmSUgE
    -----END RSA PRIVATE KEY-----

  rsa_public: ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAGEAoPRhIfLvedSDKw7XdewmZ3h8eIXJD7TRHtVW7aJX1ByifYtlL/HVzJ09nilCl+MSFrpbFnqjxyL8Rr/DSf7QcY/BrGUQbZn2Kc22PemAWthxHO18QJvWPocKJtlsDNi3 smoser@localhost

  dsa_private: |
    -----BEGIN DSA PRIVATE KEY-----
    MIIBuwIBAAKBgQDP2HLu7pTExL89USyM0264RCyWX/CMLmukxX0Jdbm29ax8FBJT
    pLrO8TIXVY5rPAJm1dTHnpuyJhOvU9G7M8tPUABtzSJh4GVSHlwaCfycwcpLv9TX
    DgWIpSj+6EiHCyaRlB1/CBp9RiaB+10QcFbm+lapuET+/Au6vSDp9IRtlQIVAIMR
    8KucvUYbOEI+yv+5LW9u3z/BAoGBAI0q6JP+JvJmwZFaeCMMVxXUbqiSko/P1lsa
    LNNBHZ5/8MOUIm8rB2FC6ziidfueJpqTMqeQmSAlEBCwnwreUnGfRrKoJpyPNENY
    d15MG6N5J+z81sEcHFeprryZ+D3Ge9VjPq3Tf3NhKKwCDQ0240aPezbnjPeFm4mH
    bYxxcZ9GAoGAXmLIFSQgiAPu459rCKxT46tHJtM0QfnNiEnQLbFluefZ/yiI4DI3
    8UzTCOXLhUA7ybmZha+D/csj15Y9/BNFuO7unzVhikCQV9DTeXX46pG4s1o23JKC
    /QaYWNMZ7kTRv+wWow9MhGiVdML4ZN4XnifuO5krqAybngIy66PMEoQCFEIsKKWv
    99iziAH0KBMVbxy03Trz
    -----END DSA PRIVATE KEY-----

  dsa_public: ssh-dss AAAAB3NzaC1kc3MAAACBAM/Ycu7ulMTEvz1RLIzTbrhELJZf8Iwua6TFfQl1ubb1rHwUElOkus7xMhdVjms8AmbV1Meem7ImE69T0bszy09QAG3NImHgZVIeXBoJ/JzByku/1NcOBYilKP7oSIcLJpGUHX8IGn1GJoH7XRBwVub6Vqm4RP78C7q9IOn0hG2VAAAAFQCDEfCrnL1GGzhCPsr/uS1vbt8/wQAAAIEAjSrok/4m8mbBkVp4IwxXFdRuqJKSj8/WWxos00Ednn/ww5QibysHYULrOKJ1+54mmpMyp5CZICUQELCfCt5ScZ9GsqgmnI80Q1h3Xkwbo3kn7PzWwRwcV6muvJn4PcZ71WM+rdN/c2EorAINDTbjRo97NueM94WbiYdtjHFxn0YAAACAXmLIFSQgiAPu459rCKxT46tHJtM0QfnNiEnQLbFluefZ/yiI4DI38UzTCOXLhUA7ybmZha+D/csj15Y9/BNFuO7unzVhikCQV9DTeXX46pG4s1o23JKC/QaYWNMZ7kTRv+wWow9MhGiVdML4ZN4XnifuO5krqAybngIy66PMEoQ= smoser@localhost

disable_root

Disable ssh access as root.

If you want to be able to ssh in to the system as the root user rather than as the default/configured user, then you must set this to false.

Default: true

disable_root_opts

The value of this variable will prefix the respective key in /root/.ssh/authorized_keys if "disable_root" is true.

See 'man authorized_keys' for more information on what you can do here.

The string '$USER' will be replaced with the username of the default user. Example:

disable_root_opts: no-port-forwarding,no-agent-forwarding,no-X11-forwarding,command="echo 'Please login as the user \"$USER\" rather than the user \"root\".';echo;sleep 10"

Execute commands

If you want to run commands during boot, use the "runcmd", "bootcmd" or "cloud-init-boot-per" option.

"runcmd" will run late in the boot process, at about the same runlevel as "rc.local".

"bootcmd" will run very early in the boot process, only slightly after a "boothook" would run. It will be run every boot.

# run commands
# default: none
# runcmd contains a list of either lists or a string
# each item will be executed in order at rc.local like level with
# output to the console
# - if the item is a list, the items will be properly executed as if
#   passed to execve(3) (with the first arg as the command).
# - if the item is a string, it will be simply written to the file and
#   will be interpreted by 'sh'
#
# Note, that the list has to be proper yaml, so you have to escape
# any characters yaml would eat (':' can be problematic)

Logging

# add entries to rsyslog configuration
# The first occurance of a given filename will truncate. 
# subsequent entries will append.
# if value is a scalar, its content is assumed to be 'content', and the
# default filename is used.
# if filename is not provided, it will default to 'rsylog_filename'
# if filename does not start with a '/', it will be put in 'rsyslog_dir'
# rsyslog_dir default: /etc/rsyslog.d
# rsyslog_filename default: 20-cloud-config.conf
rsyslog:
 - ':syslogtag, isequal, "[CLOUDINIT]" /var/log/cloud-foo.log'
 - content: "*.*   @@192.0.2.1:10514"
 - filename: 01-examplecom.conf
   content: "*.*   @@syslogd.example.com"

# def_log_file and syslog_fix_perms work together
# if 
# - logging is set to go to a log file 'L' both with and without syslog
# - and 'L' does not exist
# - and syslog is configured to write to 'L'
# then 'L' will be initially created with root:root ownership (during
# cloud-init), and then at cloud-config time (when syslog is available)
# the syslog daemon will be unable to write to the file.
# 
# to remedy this situation, 'def_log_file' can be set to a filename
# and syslog_fix_perms to a string containing ":"
#
# the default values are '/var/log/cloud-init.log' and 'syslog:adm'
# the value of 'def_log_file' should match what is configured in logging
# if either is empty, then no change of ownership will be done
def_log_file: /var/log/my-logging-file.log
syslog_fix_perms: syslog:root

Cloud-init setup

Configure the setup of cloud-init, overriding the defaults.

unverified_modules

Many of the cloud-init modules specify a list of supported operating systems, ensuring that the module only runs on verified systems.

To override this behaviour, you can add a list of modules that should be run anyway. The default list is empty. Example:

unverified_modules: ['apt-update-upgrade']

cloud_config_modules

This setting is used to override what modules are loaded by cloud-init, and their frequency.

This is an array of arrays or strings.

If the item is a string, then it is read as a module name.

If the item is an array it must be in the form:

name, frequency, arguments

"name" must be a python-file in the CloudConfig/ module directory named "cc_<name>.py".

"frequency" can be set to "once-per-instance" to only run the module during initial creation or "always" to run the module on every boot.

"arguments" is arguments to the module.

The default list of modules are:

cloud_config_modules:
  - mounts
  - ssh
  - apt-update-upgrade
  - puppet
  - updates-check
  - disable-ec2-metadata
  - runcmd

An example of a modified list:

cloud_config_modules:
  - mounts
  - ssh-import-id
  - ssh
  - grub-dpkg
  - [ apt-update-upgrade, always ]
  - puppet
  - updates-check
  - disable-ec2-metadata
  - runcmd
  - byobu

manual_cache_clean

By default, the link from /var/lib/cloud/instance to the specific instance in /var/lib/cloud/instances/ is removed on every boot. The cloud-init code then searches for a DataSource on every boot.

If your DataSource will not be present on every boot, then you can set this option to 'True', and maintain (remove) that link before the image will be booted as a new instance.

Default: false

output

Configure where output from the various stages of cloud-init will be saved. This is a dict with the following entries:

• "init": Where to send the output of cloud-init.
• "config": Where to send the output of cloud-config.
• "final": Where to send the output of cloud-config-final.
• "all": Where to send the output of all the cloud-stages.

Each entry in the dict can be a string, list or dict.

• If the entry is a string, it refers to stdout and stderr.
• If the entry is a list, entry 0 is stdout, entry 1 is stderr.
• if the entry is a dict, it is expected to have 'output' and 'error' fields.

Default: Write to console only.

The special entry "&1" for an error means "same location as stdout".

An example:

output:
 init: "> /var/log/my-cloud-init.log"
 config: [ ">> /tmp/foo.out", "> /tmp/foo.err" ]
 final:
   output: "| tee /tmp/final.stdout | tee /tmp/bar.stdout"
   error: "&1"

Finishing up

Actions to perform when finishing the installation.

final_message

The message written by cloud-final when the system has finished its first boot.

Default: cloud-init boot finished at $TIMESTAMP. Up $UPTIME seconds

Example:

final_message: "The system is finally up, after $UPTIME seconds"

phone_home

If this dictionary is present, then the phone_home cloud-config module will post specified data back to the given url.

An example:

phone_home:
 url: http://my.example.com/$INSTANCE_ID/
 post: [ pub_key_dsa, pub_key_rsa, pub_key_ecdsa, instance_id ]
 tries: 10

power_state

This can be used to make the system shutdown, reboot or halt after boot is finished.

This same thing can be acheived by user-data scripts or by runcmd by simply invoking 'shutdown'.

Doing it this way ensures that cloud-init is entirely finished with modules that would be executed, and avoids any error/log messages that may go to the console as a result of system services like syslog being taken down while cloud-init is running.

Options:

"delay" is how long to delay the shutdown. Same format as the "shutdown" command. The default is 'now'. Other format accepted is +m (m in minutes).

"mode" must be one of 'poweroff', 'halt', 'reboot'.

"message" is provided as the message argument to 'shutdown'.

An example:

power_state:
 delay: 30
 mode: poweroff
 message: Bye Bye