Atom feed of this document

 Config drive


OpenStack can be configured to write metadata to a special configuration drive that will be attached to the instance when it boots. The instance can retrieve any information that would normally be available through the metadata service by mounting this disk and reading files from it.

One use case for the config drive is to pass networking configuration (e.g., IP address, netmask, gateway) when DHCP is not being used to assign IP addresses to instances. The instance's IP configuration can be transmitted using the config drive, which can be mounted and accessed before the instance's network settings have been configured.

The config drive can be used by any guest operating system that is capable of mounting an ISO9660 or VFAT file system. This functionality should be available on all modern operating systems.

In addition, an image that has been built with a recent version of the cloud-init package will be able to automatically access metadata passed via config drive. The current version of cloud-init as of this writing (0.7.1) has been confirmed to work with Ubuntu, as well as Fedora-based images such as RHEL.

If an image does not have the cloud-init package installed, the image must be customized to run a script that mounts the config drive on boot, reads the data from the drive, and takes appropriate action such as adding the public key to an account. See below for details on how data is organized on the config drive.


To use config drive, the genisoimage program must be installed on each compute host. In the Ubuntu packages, it is not installed by default (see bug #1165174). Make sure you install this program on each compute host before attempting to use config drive, or an instance will not boot properly.


If you use Xen with a config drive, disable the agent through the xenapi_disable_agent configuration parameter.

 Enabling the config drive

To enable the config drive, pass the --config-drive=true parameter when calling nova boot. Here is a complex example that enables the config drive as well as passing user data, two files, and two key/value metadata pairs, all of which will be accessible from the config drive as described below.

$ nova boot --config-drive=true --image my-image-name --key-name mykey --flavor 1 --user-data ./my-user-data.txt myinstance --file /etc/network/interfaces=/home/myuser/instance-interfaces --file known_hosts=/home/myuser/.ssh/known_hosts --meta role=webservers --meta essential=false

You can also configure the Compute service to always create a config drive by setting the following option in /etc/nova/nova.conf:


As of this writing, there is no mechanism for an administrator to disable use of the config drive if a user passes the --config-drive=true flag to the nova boot command.

 Accessing the config drive from inside an instance

The config drive will have a volume label of config-2. If your guest OS supports accessing disk by label, you should be able to mount the config drive as the /dev/disk/by-label/config-2 device. For example:

# mkdir -p /mnt/config
# mount /dev/disk/by-label/config-2 /mnt/config


The cirros 0.3.0 test image does not have support for the config drive. Support will be added in version 0.3.1.

If your guest operating system does not use udev, then the /dev/disk/by-label directory will not be present. The blkid command can be used to identify the block device that corresponds to the config drive. For example, when booting the cirros image with the m1.tiny flavor, the device will be /dev/vdb:

# blkid -t LABEL="config-2" -odevice

Once identified, the device can then be mounted:

# mkdir -p /mnt/config
# mount /dev/vdb /mnt/config

 Contents of the config drive

The files that will be present in the config drive will vary depending on the arguments that were passed to nova boot. Based on the example above, the contents of the config drive would be:


 Guidelines for accessing config drive data

Do not rely on the presence of the EC2 metadata present in the config drive (i.e., files under the ec2 directory), as this content may be removed in a future release.

When creating images that access config drive data, if there are multiple directories under the openstack directory, always select the highest API version by date that your consumer supports. For example, if your guest image can support versions 2012-03-05, 2012-08-05, 2013-04-13. It is best to try 2013-04-13 first and fall back to an earlier version if it 2013-04-13 isn't present.

 Format of OpenStack metadata

Here is an example of the contents of openstack/2012-08-10/meta_data.json, openstack/latest/meta_data.json (these two files are identical), formatted to improve readability:

    "availability_zone": "nova",
    "files": [
            "content_path": "/content/0000",
            "path": "/etc/network/interfaces"
            "content_path": "/content/0001",
            "path": "known_hosts"
    "hostname": "test.novalocal",
    "launch_index": 0,
    "name": "test",
    "meta": {
            "role": "webservers"
            "essential": "false"
    "public_keys": {
        "mykey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDBqUfVvCSez0/Wfpd8dLLgZXV9GtXQ7hnMN+Z0OWQUyebVEHey1CXuin0uY1cAJMhUq8j98SiW+cU0sU4J3x5l2+xi1bodDm1BtFWVeLIOQINpfV1n8fKjHB+ynPpe1F6tMDvrFGUlJs44t30BrujMXBe8Rq44cCk6wqyjATA3rQ== Generated by Nova\n"
    "uuid": "83679162-1378-4288-a2d4-70e13ec132aa"

Note the effect of the --file /etc/network/interfaces=/home/myuser/instance-interfaces argument passed to the original nova boot command. The contents of this file are contained in the file openstack/content/0000 file on the config drive, and the path is specified as /etc/network/interfaces in the meta_data.json file.

 Format of EC2 metadata

Here is an example of the contents of ec2/2009-04-04/meta-data.json, latest/meta-data.json (these two files are identical) formatted to improve readbility:

    "ami-id": "ami-00000001",
    "ami-launch-index": 0,
    "ami-manifest-path": "FIXME",
    "block-device-mapping": {
        "ami": "sda1",
        "ephemeral0": "sda2",
        "root": "/dev/sda1",
        "swap": "sda3"
    "hostname": "test.novalocal",
    "instance-action": "none",
    "instance-id": "i-00000001",
    "instance-type": "m1.tiny",
    "kernel-id": "aki-00000002",
    "local-hostname": "test.novalocal",
    "local-ipv4": null,
    "placement": {
        "availability-zone": "nova"
    "public-hostname": "test.novalocal",
    "public-ipv4": "",
    "public-keys": {
        "0": {
            "openssh-key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDBqUfVvCSez0/Wfpd8dLLgZXV9GtXQ7hnMN+Z0OWQUyebVEHey1CXuin0uY1cAJMhUq8j98SiW+cU0sU4J3x5l2+xi1bodDm1BtFWVeLIOQINpfV1n8fKjHB+ynPpe1F6tMDvrFGUlJs44t30BrujMXBe8Rq44cCk6wqyjATA3rQ== Generated by Nova\n"
    "ramdisk-id": "ari-00000003",
    "reservation-id": "r-7lfps8wj",
    "security-groups": [

 User data

The files openstack/2012-08-10/user_data, openstack/latest/user_data, ec2/2009-04-04/user-data, and ec2/latest/user-data, will only be present if the --user-data flag was passed to nova boot and will contain the contents of the user data file passed as the argument.

 Format of the config drive

The default format of the config drive as an ISO 9660 filesystem. To explicitly specify the ISO 9660 format, add the following line to /etc/nova/nova.conf:


For legacy reasons, the config drive can be configured to use VFAT format instead of ISO 9660. It is unlikely that you would require VFAT format, since ISO 9660 is widely supported across operating systems. However, if you wish to use the VFAT format, add the following line to /etc/nova/nova.conf instead:


If VFAT is chosen, the config drive will be 64MB in size.

 Configuration Reference

The following table contains all options for config drive.

Table 8.2. Description of configuration options for configdrive
Configuration option=Default value (Type) Description
config_drive_cdrom=False (BoolOpt)Attaches the Config Drive image as a cdrom drive instead of a disk drive
config_drive_format=iso9660 (StrOpt)Config drive format. One of iso9660 (default) or vfat
config_drive_inject_password=False (BoolOpt)Sets the admin password in the config drive image
config_drive_skip_versions=1.0 2007-01-19 2007-03-01 2007-08-29 2007-10-10 2007-12-15 2008-02-01 2008-09-01 (StrOpt)List of metadata versions to skip placing into the config drive
config_drive_tempdir=None (StrOpt)Where to put temporary files associated with config drive creation
force_config_drive=None (StrOpt)Set to force injection to take place on a config drive (if set, valid options are: always)
mkisofs_cmd=genisoimage (StrOpt)Name and optionally path of the tool used for ISO image creation

Log a bug against this page

loading table of contents...