diskimage-builder Documentation

diskimage-builder Documentation

Release 1.20.1.dev11

OpenStack

October 06, 2016

Contents

1

2

Code

Communication

3 Table of Contents

3.1

User Guide

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.2

3.3

3.4

Developer Documentation

Elements

Copyright

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10

20

7

7

56

3

5

i

ii

diskimage-builder Documentation, Release 1.20.1.dev11

diskimage-builder is a tool for automatically building customized operating-system images for use in clouds and other environments.

It includes support for building images based on many major distributions and can produce cloud-images in all common formats ( qcow2 , vhd , raw , etc), bare metal file-system images and ram-disk images. These images are composed from the many included elements ; ments for even further customization.

diskimage-builder acts as a framework to easily add your own elediskimage-builder is used extensively by the TripleO project and within OpenStack Infrastructure .

Contents 1

diskimage-builder Documentation, Release 1.20.1.dev11

2 Contents

Release notes for the latest and previous versions are available at:

• http://docs.openstack.org/releasenotes/diskimage-builder/

The code is available at:

• https://git.openstack.org/cgit/openstack/diskimage-builder/

CHAPTER

1

Code

3

diskimage-builder Documentation, Release 1.20.1.dev11

4 Chapter 1. Code

CHAPTER

2

Communication

Communication among the diskimage-builder developers happens on IRC in #openstack-dib on freenode and on the openstack-dev mailing list ( [email protected]

).

5

diskimage-builder Documentation, Release 1.20.1.dev11

6 Chapter 2. Communication

CHAPTER

3

Table of Contents

3.1 User Guide

3.1.1 Supported Distributions

Distributions which are supported as a build host:

• Centos 6, 7

• Debian 8 (“jessie”)

• Fedora 20, 21, 22

• RHEL 6, 7

• Ubuntu 14.04 (“trusty”)

• Gentoo

Distributions which are supported as a target for an image:

• Centos 6, 7

• Debian 8 (“jessie”)

• Fedora 20, 21, 22

• RHEL 6, 7

• Ubuntu 12.04 (“precise”), 14.04 (“trusty”)

• Gentoo

3.1.2 Installation

Diskimage-builder can either be run directly out of the source repository or installed via pip. If you plan on doing development on diskimage-builder or the elements then we recommend you run the tool out of the source repository as this installation requires minimal extra effort and does not require an extra install step for your changes to take effect.

Once installed, you will be able to diskimage-builder repository.

build images

using disk-image-create and the elements included in the main

7

diskimage-builder Documentation, Release 1.20.1.dev11

Requirements

Most image formats require the qemu-img tool which is provided by the qemu-utils package on Ubuntu/Debian or the qemu package on Fedora/RHEL/opensuse/Gentoo.

Some image formats, such as VHD, may require additional tools. Please see the disk-image-create help output for more information.

Individual elements can also have additional dependencies for the build host. It is recommended you check the documentation for each element you are using to determine if there are any additional dependencies. Of particular note is the need for the dev-python/pyyaml package on Gentoo hosts.

Source Installation

Clone the diskimage-builder and dib-utils repositories locally: git clone https://git.openstack.org/openstack/diskimage-builder git clone https://git.openstack.org/openstack/dib-utils

Add the bin dirs to your path: export PATH=$PATH:$(pwd)/diskimage-builder/bin:$(pwd)/dib-utils/bin

Pip Installation

Installing via pip is as simple as: pip install diskimage-builder

3.1.3 Building An Image

Now that you have diskimage-builder properly

installed

you can get started by building your first disk image.

VM Image

Our first image is going to be a bootable vm image using one of the standard supported distribution

elements

(Ubuntu or Fedora).

The following command will start our image build (distro must be either ‘ubuntu’ or ‘fedora’): disk image create < distro > vm

This will create a qcow2 file ‘image.qcow2’ which can then be booted.

Elements

It is important to note that we are passing in a list of

elements

to disk-image-create in our above command. Elements are how we decide what goes into our image and what modifications will be performed.

Some elements provide a root filesystem, such as the ubuntu or fedora element in our example above, which other elements modify to create our image. At least one of these ‘distro elements’ must be specified when performing an image build. It’s worth pointing out that there are many distro elements (you can even create your own), and even multiples for some of the distros. This is because there are often multiple ways to install a distro which are very

8 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

different. For example: One distro element might use a cloud image while another uses a package installation tool to build a root filesystem for the same distro.

Other elements modify our image in some way. The ‘vm’ element in our example above ensures that our image has a bootloader properly installed. This is only needed for certain use cases and certain output formats and therefore it is not performed by default.

Output Formats

By default a qcow2 image is created by the disk-image-create command. Other output formats may be specified using the -t <format> argument. Multiple output formats can also be specified by comma separation. The supported output formats are:

• qcow2

• tar

• vhd

• docker

• raw

Filesystem Caveat

By default, disk-image-create uses a 4k byte-to-inode ratio when creating the filesystem in the image. This allows large ‘whole-system’ images to utilize several TB disks without exhausting inodes. In contrast, when creating images intended for tenant instances, this ratio consumes more disk space than an end-user would expect (e.g. a 50GB root disk has 47GB avail.). If the image is intended to run within a tens to hundrededs of gigabyte disk, setting the byte-toinode ratio to the ext4 default of 16k will allow for more usable space on the instance. The default can be overridden by passing –mkfs-options like this: disk-image-create --mkfs-options '-i 16384' <distro> vm

Speedups

If you have 4GB of available physical RAM (as reported by /proc/meminfo MemTotal), or more, diskimage-builder will create a tmpfs mount to build the image in. This will improve image build time by building it in RAM. By default, the tmpfs file system uses 50% of the available RAM. Therefore, the RAM should be at least the double of the minimum tmpfs size required. For larger images, when no sufficient amount of RAM is available, tmpfs can be disabled completely by passing –no-tmpfs to disk-image-create. ramdisk-image-create builds a regular image and then within that image creates ramdisk. If tmpfs is not used, you will need enough room in /tmp to store two uncompressed cloud images. If tmpfs is used, you would still need /tmp space for one uncompressed cloud image and about 20% of that image for working files.

3.1.4 Install Types

Install types permit elements to be installed from different sources, such as git repositories, distribution packages, or pip. The default install type is ‘source’ but it can be modified on the disk-image-create command line via the

–install-type option. For example you can set:

–install-type=package

3.1. User Guide 9

diskimage-builder Documentation, Release 1.20.1.dev11

to enable package installs by default. Alternately, you can also set DIB_DEFAULT_INSTALLTYPE.

Many elements expose different install types. The different implementations live under <install-dir-prefix>-<installtype>-install directories under an element’s install.d. The base element enables the chosen install type by symlinking the correct hook scripts under install.d directly.

<install-dir-prefix> can be a string of alphanumeric and ‘-‘ characters, but typically corresponds to the element name.

For example, the nova element would provide: nova/install.d/nova-package-install/74-nova nova/install.d/nova-source-install/74-nova

The following symlink would be created for the package install type: install.d/74-nova -> nova-package-install/74-nova

Or, for the source install type: install.d/74-nova -> nova-source-install/74-nova

All other scripts that exist under install.d for an element will be executed as normal. This allows common install code to live in a script under install.d.

To set the install type for an element define an environment variable DIB_INSTALLTYPE_<install_dir_prefx> . Note that if you used variable.

characters in your install directory prefix, those need to be replaced with _ in the environment

For example, to enable the package install type for the set of nova elements that use nova define the following: as the install type prefix, export DIB_INSTALLTYPE_nova=package

3.2 Developer Documentation

This documentation explains how to get started with creating your own disk-image-builder elements as well as some high level concepts for element creation.

3.2.1 Quickstart

To get started developing with diskimage-builder

, install to a virtualenv

:

$ mkdir dib

$ cd dib

$ virtualenv env

$ source env/bin/activate

$ git clone https://git.openstack.org/openstack/diskimage-builder

$ cd diskimage-builder

$ pip install -e .

You can now simply use disk-image-create to start building images and testing your changes. When you are done editing, use git review to submit changes to the upstream gerrit.

Design

Images are built using a chroot and bind mounted /proc /sys and /dev. The goal of the image building process is to produce blank slate machines that have all the necessary bits to fulfill a specific purpose in the running of an OpenStack cloud: e.g. a nova-compute node. Images produce either a filesystem image with a label of cloudimg-rootfs, or can be customised to produce whole disk images (but will still contain a filesystem labelled cloudimg-rootfs). Once the file

10 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

system tree is assembled a loopback device with filesystem (or partition table and file system) is created and the tree copied into it. The file system created is an ext4 filesystem just large enough to hold the file system tree and can be resized up to 1PB in size.

To produce the smallest image the utility fstrim is used. When deleting a file the space is simply marked as free on the disk, the file is still there until it is overwritten. fstrim informs the underlying disk to drop those bytes the end result of which is like writting zeros over those sectors. The same effect could be achieved by creating a large file full of zeros and removing that file, however that method is far more IO intensive.

An element is a particular set of code that alters how the image is built, or runs within the chroot to prepare the image.

E.g. the local-config element copies in the http proxy and ssh keys of the user running the image build process into the image, whereas the vm element makes the image build a regular VM image with partition table and installed grub boot sector. The mellanox element adds support for mellanox infiniband hardware to both the deploy ramdisk and the built images.

Images must specify a base distribution image element. Currently base distribution elements exist for fedora, rhel, ubuntu, debian and opensuse. Other distributions may be added in future, the infrastructure deliberately makes few assumptions about the exact operating system in use. The base image has opensshd running (a new key generated on first boot) and accepts keys via the cloud metadata service, loading them into the distribution specific default user account.

The goal of a built image is to have any global configuration ready to roll, but nothing that ties it to a specific cloud instance: images should be able to be dropped into a test cloud and validated, and then deployed into a production cloud (usually via bare metal nova) for production use. As such, the image contents can be modelled as three distinct portions:

• global content: the actual code, kernel, always-applicable config (like disabling password authentication to sshd).

• metadata / config management provided configuration: user ssh keys, network address and routes, configuration management server location and public key, credentials to access other servers in the cloud. These are typically refreshed on every boot.

• persistent state: sshd server key, database contents, swift storage areas, nova instance disk images, disk image cache. These would typically be stored on a dedicated partition and not overwritten when re-deploying the image.

The goal of the image building tools is to create machine images that contain the correct global content and are ready for ‘last-mile’ configuration by the nova metadata API, after which a configuration management system can take over

(until the next deploy, when it all starts over from scratch).

Components

disk-image-create [-a i386|amd64|armhf] -o filename {element} [{element} ...]

Create an image of element {element}, optionally mixing in other elements. Element dependencies are automatically included. Support for other architectures depends on your environment being able to run binaries of that platform. For instance, to enable armhf on Ubuntu install the qemu-user-static package.

The default output format from disk-image-create is qcow2. To instead output a tarball pass in “-t tar”.

This tarball could then be used as an image for a linux container(see docs/docker.md).

ramdisk-image-create -o filename {element} [{element} ...]

Create a kernel+ ramdisk pair for running maintenance on bare metal machines (deployment, inventory, burnin etc).

To generate kernel+ramdisk pair for use with nova-baremetal, use:

3.2. Developer Documentation 11

diskimage-builder Documentation, Release 1.20.1.dev11

ramdisk-image-create -o deploy.ramdisk deploy-baremetal

To generate kernel+ramdisk pair for use with ironic, use: ramdisk-image-create -o deploy.ramdisk deploy-ironic element-info

Extract information about elements.

tests/run_functests.sh

This runs a set of functional tests for diskimage-builder.

elements can be found in the top level elements directory.

Invocation

The scripts can generally just be run. Options can be set on the command line or by exporting variables to override those present in lib/img-defaults. -h to get help.

The image building scripts expect to be able to invoke commands with sudo, so if you want them to run noninteractively, you should either run them as root, with sudo -E, or allow your build user to run any sudo command without password.

Using the variable

ELEMENTS_PATH will allow to specify multiple elements locations. It is a colon (:) separated path list, and it will work in a first path/element found, first served approach. The included elements tree is used when no path is supplied, and is added to the end of the path if a path is supplied.

By default, the image building scripts will not overwrite existing disk images, allowing you to compare the newly built image with the existing one. To change that behaviour, set the variable

OVERWRITE_OLD_IMAGE to any value that isn’t

0

. If this value is zero then any existing image will be moved before the new image is written to the destination.

Setting the variable

DIB_SHOW_IMAGE_USAGE will print out a summarised disk-usage report for the final image of files and directories over 10MiB in size. Setting

DIB_SHOW_IMAGE_USAGE_FULL will show all files and directories. These settings can be useful additions to the logs in automated build situations where debugging image-growth may be important.

Caches and offline mode

Since retrieving and transforming operating system image files, git repositories, Python or Ruby packages, and so on can be a significant overhead, we cache many of the inputs to the build process.

The cache location is read from image-builder for caching.

DIB_IMAGE_CACHE

.

Developing Elements

describes the interface within disk-

When invoking disk-image-builder, the --offline option will instruct disk-image-builder to not refresh cached resources. Alternatively you can set DIB_OFFLINE=1 .

Note that we don’t maintain operating system package caches, instead depending on your local infrastructure (e.g.

Squid cache, or an APT or Yum proxy) to facilitate caching of that layer, so you need to arrange independently for offline mode. For more information about setting up a squid proxy, consult the TripleO documentation .

Base images

These are cached by the standard elements -

fedora ,

redhat-common ,

ubuntu ,

debian

and

opensuse .

12 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

source-repositories

Git repositories and tarballs obtained via the

source-repositories

element will be cached.

C and C++ compilation

Ccache is configured by the

base

element. Any compilation that honours ccache will be cached.

PyPI

The

pypi

element will bind mount a PyPI mirror from the cache dir and configure pip and easy-install to use it.

Developing Elements

Conform to the following conventions:

• Use the environment for overridable defaults, prefixing environment variable names with

DIB_

. For example:

DIB_MYDEFAULT = ${ DIB_MYDEFAULT

:-

default }

If you do not use the sanitised.

DIB prefix you may find that your overrides are discarded as the build environment is

• Consider that your element co-exists with many others and try to guard against undefined behaviours. Some examples:

– Two elements use the source-repositories element, but use the same filename for the source-repositories config file. Files such as these (and indeed the scripts in the various .d directories

listed below ) should be

named such that they are unique. If they are not unique, when the combined tree is created by disk-imagebuilder for injecting into the build environment, one of the files will be overwritten.

– Two elements copy different scripts into

/usr/local/bin with the same name. If they both use set

-e and cp -n then the conflict will be caught and cause the build to fail.

• If your element mounts anything into the image build tree (

$TMP_BUILD_DIR

) then it will be automatically unmounted when the build tree is unmounted - and not remounted into the filesystem image - if the mount point is needed again, your element will need to remount it at that point.

• If caching is required, elements should use a location under $DIB_IMAGE_CACHE .

• Elements should allow for remote data to be cached. When

$DIB_OFFLINE is set, this cached data should be used if possible. See the

Global image-build variables

section of this document for more information.

• Elements in the upstream diskimage-builder elements should not create executables which run before 10- or after

90- in any of the phases if possible. This is to give downstream elements the ability to easily make executables which run after our upstream ones.

Phase Subdirectories

Make as many of the following subdirectories as you need, depending on what part of the process you need to customise. The subdirectories are executed in the order given here. Scripts within the subdirectories should be named with a two-digit numeric prefix, and are executed in numeric order.

3.2. Developer Documentation 13

diskimage-builder Documentation, Release 1.20.1.dev11

Only files which are marked executable (+x) will be run, so other files can be stored in these directories if needed. As a convention, we try to only store executable scripts in the phase subdirectories and store data files elsewhere in the element.

The phases are:

1.

root.d

2.

extra-data.d

3.

pre-install.d

4.

install.d

5.

post-install.d

6.

block-device.d

7.

finalise.d

8.

cleanup.d

root.d

Create or adapt the initial root filesystem content. This is where alternative distribution support is added, or customisations such as building on an existing image.

Only one element can use this at a time unless particular care is taken not to blindly overwrite but instead to adapt the context extracted by other elements.

• runs: outside chroot

• inputs:

$ARCH=i386|amd64|armhf

$TARGET_ROOT=/path/to/target/workarea

extra-data.d

Pull in extra data from the host environment that hooks may need during image creation.

This should copy any data (such as SSH keys, http proxy settings and the like) somewhere under

$TMP_HOOKS_PATH

.

• runs: outside chroot

• inputs: $TMP_HOOKS_PATH

• outputs: None

pre-install.d

repositories.

Run code in the chroot before customisation or packages are installed. A good place to add apt

• runs: in chroot

install.d

Runs after pre-install.d

in the chroot. This is a good place to install packages, chain into configuration management tools or do other image specific operations.

• runs: in chroot

post-install.d

Run code in the chroot. This is a good place to perform tasks you want to handle after the

OS/application install but before the first boot of the image. Some examples of use would be:

Run chkconfig to disable unneeded services

Clean the cache left by the package manager to reduce the size of the image.

• runs: in chroot

block-device.d

Customise the block device that the image will be made on (for example to make partitions).

Runs after the target tree has been fully populated but before the cleanup.d

phase runs.

14 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

• runs: outside chroot

• inputs:

$IMAGE_BLOCK_DEVICE={path}

$TARGET_ROOT={path}

• outputs:

$IMAGE_BLOCK_DEVICE={path}

finalise.d

Perform final tuning of the root filesystem. Runs in a chroot after the root filesystem content has been copied into the mounted filesystem: this is an appropriate place to reset SELinux metadata, install grub bootloaders and so on.

Because this happens inside the final image, it is important to limit operations here to only those necessary to affect the filesystem metadata and image itself. For most operations, post-install.d

is preferred.

• runs: in chroot

cleanup.d

Perform cleanup of the root filesystem content. For instance, temporary settings to use the image build environment HTTP proxy are removed here in the dpkg element.

• runs: outside chroot

• inputs:

$ARCH=i386|amd64|armhf

$TARGET_ROOT=/path/to/target/workarea

Other Subdirectories

Elements may have other subdirectories that are processed by specific elements rather than the diskimage-builder tools themselves.

One example of this is the bin directory. The rpm-distro ,

dpkg

and

opensuse

elements install all files found in the bin directory into

/usr/local/bin within the image as executable files.

Environment Variables

To set environment variables for other hooks, add a file to your element environment.d

.

This directory contains bash script snippets that are sourced before running scripts in each phase.

DIB exposes an internal

$IMAGE_ELEMENT variable which provides elements access to the full set of elements that are included in the image build. This can be used to process local in-element files across all the elements ( pkg-map for example).

Dependencies

Each element can use the following files to define or affect dependencies:

element-deps

A plain text, newline separated list of elements which will be added to the list of elements built into the image at image creation time.

element-provides

A plain text, newline separated list of elements which are provided by this element. These elements will be excluded from elements built into the image at image creation time.

For example if element A depends on element B and element C includes element B in its element-provides file and A and C are included when building an image, then B is not used.

3.2. Developer Documentation 15

diskimage-builder Documentation, Release 1.20.1.dev11

Operating system elements

Some elements define the base structure for an operating system – for example, the opensuse element builds a base openSUSE system. Such elements have more requirements than the other elements:

• they must have operating-system tem”.

in their element-provides, so this indicates they are an “operating sys-

• they must export the

DISTRO_NAME environment variable with the name of the distribution built, using an environment.d script. For example, the opensuse element exports

DISTRO_NAME=opensuse

.

Ramdisk Elements

Ramdisk elements support the following files in their element directories:

binary-deps.d

Text files listing executables required to be fed into the ramdisk. These need to be present in

$PATH in the build chroot (i.e. need to be installed by your elements as described above).

init.d

POSIX shell script fragments that will be appended to the default script executed as the ramdisk is booted

(

/init

).

ramdisk-install.d

Called to copy files into the ramdisk. The variable

$TMP_MOUNT_PATH points to the root of the tree that will be packed into the ramdisk.

udev.d

udev rules files that will be copied into the ramdisk.

Element coding standard

• lines should not include trailing whitespace.

• there should be no hard tabs in the file.

• indents are 4 spaces, and all indentation should be some multiple of them.

• do and then keywords should be on the same line as the if, while or for conditions.

Global image-build variables

DIB_OFFLINE

This is always set. When not empty, any operations that perform remote data access should avoid it if possible. If not possible the operation should still be attempted as the user may have an external cache able to keep the operation functional.

DIB_IMAGE_ROOT_FS_UUID

This contains the UUID of the root filesystem, when diskimage-builder is building a disk image. This works only for ext filesystems.

DIB_IMAGE_CACHE

Path to where

~/.cache/image_create

.

cached inputs to the build process are stored.

Defaults to

Structure of an element

The above-mentioned global content can be further broken down in a way that encourages composition of elements and reusability of their components. One possible approach to this would be to label elements as either a “driver”, “service”, or “config” element. Below are some examples.

• Driver-specific elements should only contain the necessary bits for that driver:

16 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

elements/ driver-mellanox/ init install.d/

10-mlx

- modprobe line

- package installation

• An element that installs and configures Nova might be a bit more complex, containing several scripts across several phases: elements/ service-nova/ source-repository-nova - register a source repository pre-install.d/

- add a PPA 50-my-ppa install.d/

10-user

50-my-pack

60-nova

- common Nova user accts

- install packages from my PPA

- install nova and some dependencies

• In the general case, configuration should probably be handled either by the meta-data service (eg, o-r-c) or via normal CM tools (eg, salt). That being said, it may occasionally be desirable to create a set of elements which express a distinct configuration of the same software components.

In this way, depending on the hardware and in which availability zone it is to be deployed, an image would be composed of:

• zero or more driver-elements

• one or more service-elements

• zero or more config-elements

It should be noted that this is merely a naming convention to assist in managing elements. Diskimage-builder is not, and should not be, functionally dependent upon specific element names.

diskimage-builder has the ability to retrieve source code for an element and place it into a directory on the target image during the extra-data phase. The default location/branch can then be overridden by the process running diskimagebuilder, making it possible to use the same element to track more then one branch of a git repository or to get source for a local cache. See

source-repositories

for more information.

Debugging elements The build-time environment and command line arguments are captured by the and written to /etc/dib_environment and /etc/dib_arguments inside the image.

base

element

Export break to drop to a shell during the image build. Break points can be set either before or after any of the hook points by exporting “break=[before|after]-hook-name”. Multiple break points can be specified as a comma-delimited string. Some examples:

• break=before-block-device-size will break before the block device size hooks are called.

• break=before-pre-install will break before the pre-install hooks.

• break=after-error will break after an error during an in target hookpoint.

Images are built such that the Linux kernel is instructed not to switch into graphical consoles (i.e. it will not activate

KMS). This maximises compatibility with remote console interception hardware, such as HP’s iLO. However, you will typically only see kernel messages on the console - init daemons (e.g. upstart) will usually be instructed to output to a serial console so nova’s console-log command can function. There is an element in the tripleo-image-elements repository called “remove-serial-console” which will force all boot messages to appear on the main console.

3.2. Developer Documentation 17

diskimage-builder Documentation, Release 1.20.1.dev11

Ramdisk images can be debugged at run-time by passing troubleshoot as a kernel command line argument, or by pressing “t” when an error is reached. This will spawn a shell on the console (this can be extremely useful when network interfaces or disks are not detected correctly).

Testing Elements An element can have functional tests encapsulated inside the element itself. The tests can be written either as shell or python unit tests.

shell In order to create a test case, follow these steps:

• Create a directory called test-elements inside your element.

• Inside the test-elements directory, create a directory with the name of your test case. The test case directory should have the same structure as an element. For example: elements / apt sources / test elements / test case 1

• Assert state during each of the element build phases you would like to test. You can exit 1 to indicate a failure.

• To exit early and indicate a success, touch a file

/tmp/dib-test-should-fail in the image chroot, then exit 1.

Tests are run with tools/run_functests.sh

. Running run_functests.sh -l will show available tests

(the example above would be called apt-sources/test-case-1

, for example). Specify your test (or a series of tests as separate arguments) on the command line to run it. If it should not be run as part of the default CI run, you can submit a change with it added to DEFAULT_SKIP_TESTS in that file.

python To run functional tests locally, install and start docker, then use the following tox command: tox efunc

Note that running functional tests requires sudo rights, thus you may be asked for your password.

To run functional tests for one element, append its name to the command: tox -efunc ironic-agent

Additionally, elements can be tested using python unittests. To create a a python test:

• Create a directory called tests in the element directory.

• Create an empty file called __init__.py

to make it into a python package.

• Create your test files as test\whatever.py

, using regular python test code.

To run all the tests use testr testr run

. To run just some tests provide one or more regex filters - tests matching any of them are run testr run apt-proxy

.

Third party elements Additional elements can be incorporated by setting were building tripleo-images, the variable would be set like:

ELEMENTS_PATH

, for example if one export ELEMENTS_PATH = tripleo-image-elements/elements disk-image-create rhel7 cinder-api

Linting

You should always run bin/dib-lint over your elements. It will warn you of common issues.

18 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

sudo Using sudo of the host system.

outside the chroot environment can cause breakout issues where you accidentally modify parts dib-lint will warn if it sees sudo calls that do not use the path arguments given to elements running outside the chroot.

To disable the error for a call you know is safe, add

# dib-lint: safe_sudo to the end of the sudo command line. To disable the check for an entire file, add

# dib-lint: disable=safe_sudo

dib-lint

dib-lint provides a way to check for common errors in diskimage-builder elements.

To use it, simply run the dib-lint script in a directory containing an elements directory. The checks will be run against every file found under elements .

The following is a list of what is currently caught by dib-lint:

• executable: Ensure any files that begin with #! are executable

• indent: Ensure that all source code is using an indent of four spaces

• element-deps ordering: Ensure all element-deps files are alphabetized

• /bin/bash: Ensure all scripts are using bash explicitly

• sete: Ensure all scripts are set -e

• setu: Ensure all scripts are set -u

• setpipefail: Ensure all scripts are set -o pipefail

• dibdebugtrace: Ensure all scripts respect the DIB_DEBUG_TRACE variable

• tabindent: Ensure no tabs are used for indentation

• newline: Ensure that every file ends with a newline

• mddocs: Ensure that only markdown-formatted documentation is used

• yaml validation: Ensure that any yaml files in the repo have valid syntax

Some of the checks can be omitted, either for an entire project or for an individual file. Project exclusions go in tox.ini, using the following section format:

[dib-lint] ignore=sete setpipefail

This will cause the set -e and set -o pipefail checks to be ignored.

File-specific exclusions are specified as a comment in the relevant file, using the following format:

# dib-lint: disable=sete setpipefail

This will exclude the same tests, but only for the file in which the comment appears.

Only some of the checks can be disabled. The ones available for exclusion are:

• executable

• indent

• sete

3.2. Developer Documentation 19

diskimage-builder Documentation, Release 1.20.1.dev11

• setu

• setpipefail

• dibdebugtrace

• tabindent

• newline

• mddocs

Stable Interfaces

diskimage-builder and the elements provide several ‘stable’ interfaces for both developers and users which we aim to preserve during a major version release. These interfaces consist of:

The names and arguments of the executable scripts included with diskimage-builder in the bin directory will remain stable.

The environment variables that diskimage-builder provides for elements to use will remain stable.

The environment variables documented in each element and the values accepted by these environment variables will remain stable.

Required environment variables for an element will not be added.

Support for build or target distributions will not be removed.

3.3 Elements

Elements are found in the subdirectory elements. Each element is in a directory named after the element itself.

Elements should have a README.rst in the root of the element directory describing what it is for.

3.3.1 apt-conf

This element overrides the default apt.conf for APT based systems.

Environment Variables

DIB_APT_CONF:

Required No

Default None

Description To override DIB_APT_CONF take effect at build time and run time.

, set it to the path to your apt.conf. The new apt.conf will

Example

DIB_APT_CONF=/etc/apt/apt.conf

20 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

3.3.2 apt-preferences

This element generates the APT preferences file based on the provided manifest provided by the

manifests

element.

The APT preferences file can be used to control which versions of packages will be selected for installation. APT uses a priority system to make this determination. For more information about APT preferences, see the apt_preferences(5) man page.

Environment Variables

DIB_DPKG_MANIFEST:

Required No

Default None

Description The manifest file to generate the APT preferences file from.

Example

DIB\_DPKG\_MANIFEST=~/image.d/dib-manifests/dib-manifest-dpkg-image

3.3.3 apt-sources

Specify an apt sources.list file which is used during image building and then remains on the image when it is run.

Environment Variables

DIB_APT_SOURCES

Required

No

Default

None (Does not replace sources.list file)

Description Path to a file on the build host which is used in place of

/etc/apt/sources.list

Example

DIB_APT_SOURCES=/etc/apt/sources.list

the build host.

will use the same sources.list as

3.3.4 architecture-emulation-binaries

This element enables execution for different architectures

When building an image for an architecture that the host machine can not execute, we need to chroot into the image to execute code, and if the host architecture does not match, we need to emulate the instructions.

This element does the following:

• copies the binary file into chroot /usr/bin environment. Binary file is chosen based on host architecture and image architecture the user is trying to build.

If an image we are building for an architecture is not the host architecture, install tools provided by qemu-userstatic (which needs to be installed) to allow us to run commands inside the building image.

This is tested on amd64/i386 architecture to build armhf and arm64 ubuntu cloud images.

3.3. Elements 21

diskimage-builder Documentation, Release 1.20.1.dev11

3.3.5 baremetal

This is the baremetal (IE: real hardware) element.

Does the following:

• extracts the kernel and initial ramdisk of the built image.

Optional parameters:

• DIB_BAREMETAL_KERNEL_PATTERN and DIB_BAREMETAL_INITRD_PATTERN may be supplied to specify which kernel files are preferred; this can be of use when using custom kernels that don’t fit the standard naming patterns. Both variables must be provided in order for them to have any effect.

3.3.6 base

This is the base element.

Almost all users will want to include this in their disk image build, as it includes a lot of useful functionality.

The DIB_CLOUD_INIT_ETC_HOSTS

/etc/hosts : environment variable can be used to customize cloud-init’s management of

• If the variable is set to something, write that value as cloud-init’s manage_etc_hosts.

• If the variable is set to an empty string, don’t create manage_etc_hosts setting (cloud-init will use its default value).

• If the variable is not set, use “localhost” for now. Later, not setting the variable will mean using cloud-init’s default. (To preserve diskimage-builder’s current default behavior in the future, set the variable to “localhost” explicitly.)

Notes:

• If you are getting warnings during the build about your locale being missing, consider installing/generating the relevant locale. This may be as simple as having language-pack-XX installed in the pre-install stage

• This element ensures /tmp/ccache will be available in the chroot during the root, extra-data, pre-install, install and post-install stages. /tmp/ccache is unavailable during block-device, finalise and cleanup stages as it will have been automatically unmounted by then.

3.3.7 bootloader

Installs grub[2] on boot partition on the system. In case GRUB2 is not available in the system, a fallback to Extlinux will happen. It’s also possible to enforce the use of Extlinux by exporting a DIB_EXTLINUX variable to the environment.

3.3.8 cache-url

A helper script to download images into a local cache.

3.3.9 centos-minimal

Create a minimal image based on CentOS 7.

Use of this element will require ‘yum’ and ‘yum-utils’ to be installed on Ubuntu and Debian. Nothing additional is needed on Fedora or CentOS.

22 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

The DIB_OFFLINE or more specific pre-cached root filesystem tarball.

DIB_YUMCHROOT_USE_CACHE variables can be set to prefer the use of a

By default, DIB_YUM_MINIMAL_CREATE_INTERFACES scripts/ifcfg-eth[0|1] scripts to enable DHCP on the eth0 & is set to enable the creation of eth1

/etc/sysconfig/networkinterfaces. If you do not have these interfaces, or if you are using something else to setup the network such as cloud-init, glean or network-manager, you would want to set this to

0

.

3.3.10 centos

Use Centos 6 cloud images as the baseline for built disk images.

For further details see the redhat-common README.

3.3.11 centos7

Use Centos 7 cloud images as the baseline for built disk images.

For further details see the redhat-common README.

DIB_DISTRIBUTION_MIRROR:

Required No

Default

None

Description

To use a CentOS Yum mirror, set this variable to the mirror URL before running bin/disk-image-create. This URL should point to the directory containing the

5/6/7 directories.

Example

DIB_DISTRIBUTION_MIRROR=http://amirror.com/centos

3.3.12 cleanup-kernel-initrd

Remove unused kernel/initrd from the image.

3.3.13 cloud-init-datasources

Configures cloud-init to only use an explicit list of data sources.

Cloud-init contains a growing collection of data source modules and most are enabled by default. This causes cloudinit to query each data source on first boot. This can cause delays or even boot problems depending on your environment.

Including this element without setting DIB_CLOUD_INIT_DATASOURCES will cause image builds to fail.

Environment Variables

DIB_CLOUD_INIT_DATASOURCES

Required Yes

Default None

Description A comma-separated list of valid data sources to limit the data sources that will be queried for metadata on first boot.

3.3. Elements 23

diskimage-builder Documentation, Release 1.20.1.dev11

Example

DIB_CLOUD_INIT_DATASOURCES="Ec2" will enable only the Ec2 data source.

Example

DIB_CLOUD_INIT_DATASOURCES="Ec2, ConfigDrive, OpenStack" enable the Ec2, ConfigDrive and OpenStack data sources.

will

3.3.14 cloud-init-disable-resizefs

The cloud-init resizefs module can be extremely slow and will also unwittingly create a root filesystem that cannot be booted by grub if the underlying partition is too big. This removes it from cloud.cfg, putting the onus for resizing on the user post-boot.

3.3.15 cloud-init-nocloud

Configures cloud-init to only use on-disk metadata/userdata sources. This will avoid a boot delay of 2 minutes while polling for cloud data sources such as the EC2 metadata service.

Empty on-disk sources are created in /var/lib/cloud/seed/nocloud/.

3.3.16 cloud-init

Install’s and enables cloud-init for systems that don’t come with it pre-installed

Currently only supports Gentoo.

3.3.17 debian-minimal

Create a minimal image based on Debian. We default to unstable but

Debian.

DIB_RELEASE can be set to any series of

There are two ways to configure apt-sources:

1. Using the standard way of defining the default, backports, updates and security repositories is the default. In this case you can overwrite the two environment variables to adapt the behavior: DIB_DISTRIBUTION_MIRROR : the mirror to use default: http://ftp.us.debian.org/debian

DIB_DEBIAN_COMPONENTS : (default) main be e.g.

main,contrib,non-free .

a comma separated list of components. For Debian this can

Note it is not recommended to use http://httpredir.debian.org/ for DIB_DISTRIBUTION_MIRROR unreliable it is. Be sure to select a mirror from the official mirror list: due to how https://www.debian.org/mirror/list

By default only bootstrap main component is used. If DIB_DEBIAN_COMPONENTS element has been set, that list of components will be used instead.

(comma separated) from the de-

Backports, updates and security are included unless

DIB_RELEASE is unstable

.

2. Complete configuration given in the variable DIB_APT_SOURCES_CONF . Each line contains exactly one entry for the sources.list.d directory. The first word must be the logical name (which is used as file name with .list

automatically appended), followed by a colon : , followed by the complete repository specification. Example:

DIB_APT_SOURCES_CONF=

“default:deb http://10.0.0.10/ stretch main contrib security main contrib” mysecurity:deb http://10.0.0.10/ stretch-

24 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

If necessary, a custom apt keyring and debootstrap script can be supplied to the

DIB_APT_KEYRING and DIB_DEBIAN_DEBOOTSTRAP_SCRIPT debootstrap command via respectively. Both options require the use of absolute rather than relative paths.

Use of this element will also require the tool ‘debootstrap’ to be available on your system. It should be available on

Ubuntu, Debian, and Fedora. It is also recommended that the ‘debian-keyring’ package be installed.

The

DIB_OFFLINE or more specific

DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE use of a pre-cached root filesystem tarball.

variables can be set to prefer the

The DIB_DEBOOTSTRAP_EXTRA_ARGS environment variable may be used to pass extra arguments to the debootstrap command used to create the base filesystem image.

If –keyring is is used in

DIB_DEBOOTSTRAP_EXTRA_ARGS , it will override DIB_APT_KEYRING if that is used as well.

For further information about DIB_DEBIAN_DEBOOTSTRAP_SCRIPT , DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE and DIB_DEBOOTSTRAP_EXTRA_ARGS please consult “README.rst” of the debootstrap element.

Note on ARM systems

Because there is not a one-to-one mapping of ARCH to a kernel package, if you are building an image for ARM on debian, you need to specify which kernel you want in the environment variable DIB_ARM_KERNEL . For instance, if you want the linux-image-mx5 package installed, set DIB_ARM_KERNEL to mx5 .

3.3.18 debian-systemd

You may want to use systemd list.

instead of the classic sysv init system. In this case, include this element in your element

3.3.19 debian-upstart

By default Debian will use sysvinit for booting. If you want to experiment with Upstart, or have need of it due to a need for upstart jobs, this element will build the image with upstart as the init system.

3.3.20 debian

Create an image based on Debian. We default to unstable but DIB_RELEASE is mapped to any series of Debian.

Note that the default Debian series is unstable , and the default mirrors for Debian can be problematic for unstable .

Because apt does not handle changing Packages files well across multiple out of sync mirrors, it is recommended that you choose a single mirror of debian, and pass it in via DIB_DISTRIBUTION_MIRROR .

If necessary, a custom apt keyring and debootstrap script can be supplied to the

DIB_APT_KEYRING and DIB_DEBIAN_DEBOOTSTRAP_SCRIPT debootstrap command via respectively. Both options require the use of absolute rather than relative paths.

Use of this element will also require the tool ‘debootstrap’ to be available on your system. It should be available on

Ubuntu, Debian, and Fedora.

The DIB_OFFLINE or more specific DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE variables can be set to prefer the use of a pre-cached root filesystem tarball.

The DIB_DEBOOTSTRAP_EXTRA_ARGS environment variable may be used to pass extra arguments to the debootstrap command used to create the base filesystem image.

If –keyring is is used in

DIB_DEBOOTSTRAP_EXTRA_ARGS , it will override DIB_APT_KEYRING if that is used as well.

3.3. Elements 25

diskimage-builder Documentation, Release 1.20.1.dev11

For further information about DIB_DEBIAN_DEBOOTSTRAP_SCRIPT , DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE and DIB_DEBOOTSTRAP_EXTRA_ARGS please consult “README.rst” of the debootstrap element.

Note on ARM systems

Because there is not a one-to-one mapping of ARCH to a kernel package, if you are building an image for ARM on debian, you need to specify which kernel you want in the environment variable DIB_ARM_KERNEL . For instance, if you want the linux-image-mx5 package installed, set DIB_ARM_KERNEL to mx5 .

3.3.21 debootstrap

Base element for creating minimal debian-based images.

This element is incomplete by itself, you’ll want to use the debian-minimal or ubuntu-minimal elements to get an actual base image.

If necessary, a custom apt keyring and debootstrap script can be supplied to the

DIB_APT_KEYRING and DIB_DEBIAN_DEBOOTSTRAP_SCRIPT debootstrap command via respectively. Both options require the use of absolute rather than relative paths.

Use of this element will also require the tool ‘debootstrap’ to be available on your system. It should be available on

Ubuntu, Debian, and Fedora.

The DIB_OFFLINE or more specific DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE variables can be set to prefer the use of a pre-cached root filesystem tarball. Setting DIB_OFFLINE may cause other element to use cached data, while

DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE only functions in the debootstrap element.

The

DIB_DEBOOTSTRAP_EXTRA_ARGS environment variable may be used to pass extra arguments to the debootstrap command used to create the base filesystem image.

If –keyring is is used in

DIB_DEBOOTSTRAP_EXTRA_ARGS , it will override DIB_APT_KEYRING if that is used as well.

The DIB_DEBOOTSTRAP_CACHE variable can be used to cache the created root filesystem. By default this is 0

(disabled) and any other value enables this. If run in offline mode then the most recently cached rootfs is used instead of being built.

The DIB_DEBOOTSTRAP_DEFAULT_LOCALE environment variable may be used to configure the default locale of the base image. It defaults to C.UTF-8.

Note on ARM systems

Because there is not a one-to-one mapping of ARCH to a kernel package, if you are building an image for ARM on debian, you need to specify which kernel you want in the environment variable DIB_ARM_KERNEL . For instance, if you want the linux-image-mx5 package installed, set DIB_ARM_KERNEL to mx5 .

3.3.22 deploy-baremetal

A ramdisk that will expose the machine primary disk over iSCSI and reboot once baremetal-deploy-helper signals it is finished.

3.3.23 deploy-ironic

A ramdisk that will expose the machine primary disk over iSCSI and reboot once Ironic signals it is finished.

26 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

Warning:

This element is deprecated. Please use the ironic-agent element instead.

3.3.24 deploy-kexec

Boots into the new image once baremetal-deploy-helper signals it is finished by downloading the kernel and ramdisk via tftp, and using the kexec utilities.

3.3.25 deploy-targetcli

Use targetcli for the deploy ramdisk

Provides the necessary scripts and dependencies to use targetcli for exporting the iscsi target in the deploy ramdisk.

Implemented as a dracut module, so will only work with dracut-based ramdisks.

3.3.26 deploy-tgtadm

Use tgtadm and tgtd for the deploy ramdisk

Provides the necessary scripts and dependencies to use tgtadm and tgtd for exporting the iscsi target in the deploy ramdisk.

Will only work with the standard (not dracut) ramdisk.

3.3.27 deploy

Temporary element to include deploy-baremetal from the name deploy whilst renaming the element.

3.3.28 devuser

Creates a user that is useful for development / debugging. The following environment variables can be useful for configuration:

Environment Variables

DIB_DEV_USER_USERNAME

Required No

Default devuser

Description Username for the created user.

DIB_DEV_USER_SHELL

Required No

Default

System default (The useradd default is used)

Description

Full path for the shell of the user. This is passed to useradd using the -s parameter. Note that this does not install the (possibly) required shell package.

DIB_DEV_USER_PWDLESS_SUDO

3.3. Elements 27

diskimage-builder Documentation, Release 1.20.1.dev11

Required No

Default No

Description

Enable passwordless sudo for the user.

DIB_DEV_USER_AUTHORIZED_KEYS

Required No

Default $HOME/.ssh/id_{rsa,dsa}.pub

Description Path to a file to copy into this users’ .ssh/authorized_keys If this is not specified then an attempt is made to use a the building user’s public key. To disable this behavior specify an invalid path for this variable (such as /dev/null).

DIB_DEV_USER_PASSWORD

Required No

Default Password is disabled

Description

Set the default password for this user. This is a fairly insecure method of setting the password and is not advised.

3.3.29 dhcp-all-interfaces

Autodetect network interfaces during boot and configure them for DHCP

The rationale for this is that we are likely to require multiple network interfaces for use cases such as baremetal and there is no way to know ahead of time which one is which, so we will simply run a DHCP client on all interfaces with real MAC addresses (except lo) that are visible on the first boot.

On non-Gentoo based distributions the script /usr/local/sbin/dhcp-all-interfaces.sh will be called early in each boot and will scan available network interfaces and ensure they are configured properly before networking services are started.

On Gentoo based distributions we will install the dhcpcd package and ensure the service starts at boot. This service automatically sets up all interfaces found via dhcp and/or dhcpv6 (or SLAAC).

3.3.30 dib-init-system

Installs a script (dib-init-system) which outputs the type of init system in use on the target image. Also sets an environment variable DIB_INIT_SYSTEM to this value.

Any files placed in a init-scripts/INIT_SYSTEM priate directory if

INIT_SYSTEM is in use on the host.

directory inside the element will be copied into the appro-

Environment Variables

DIB_INIT_SYSTEM

Description image.

One of upstart, systemd, or sysv depending on the init system in use for the target

28 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

3.3.31 dib-python

Adds a symlink to /usr/local/bin/dib-python which points at either a python2 or python3 executable. This is useful for creating #! lines for scripts that are compatible with both python2 and python3.

This does not install a python if one does not exist, and instead fails.

3.3.32 dkms

This is the dkms (Dynamic Kernel Module System) element.

Some distributions such as Fedora and Ubuntu include DKMS in their packaging. In these distros, it is reasonable to include dkms. Other RHEL based derivatives do not include DKMS, so those distros should not use the DKMS element.

3.3.33 docker

Base element for creating images from docker containers.

This element is incomplete by itself, you’ll want to add additional elements, such as dpkg or yum to get richer features.

At its heart, this element simply exports a root tarball from a named docker container so that other diskimage-builder elements can build on top of it.

The variables DISTRO_NAME and DIB_RELEASE will be used to decide which docker image to pull, and are required for most other elements. Additionally, the DIB_DOCKER_IMAGE environment variable can be set in addition to

DISTRO_NAME and DIB_RELEASE if a different docker image is desired.

3.3.34 dpkg

Provide dpkg specific image building glue.

The ubuntu element needs customisations at the start and end of the image build process that do not apply to RPM distributions, such as using the host machine HTTP proxy when installing packages. These customisations live here, where they can be used by any dpkg based element.

The dpkg specific version of install-packages is also kept here.

Environment Variables

DIB_APT_KEYS

Required No

Default None

Description If an extra or updated apt key is needed then define

DIB_ADD_APT_KEYS with the path to a folder. Any key files inside will be added to the key ring before any apt-get commands take place.

Example

DIB_APT_KEYS=/etc/apt/trusted.gpg.d

DIB_APT_LOCAL_CACHE

Required No

Default 1

3.3. Elements 29

diskimage-builder Documentation, Release 1.20.1.dev11

Description in

By default the

$DIB_IMAGE_CACHE/apt/$DISTRO_NAME

/var/cache/apt/archives directory is mounted to cache the .deb files downloaded during the image creation.

Use this variable if you wish to disable the internal cache of the

/var/cache/apt/archives directory

Example

DIB_APT_LOCAL_CACHE=0 will disable internal caching.

DIB_DISABLE_APT_CLEANUP

Required No

Default 0

Description At the end of a dib run we clean the apt cache to keep the image size as small as possible. Use this variable to prevent cleaning the apt cache at the end of a dib run.

Example

DIB_DISABLE_APT_CLEANUP=1 will disable cleanup.

3.3.35 dracut-network

Extends dracut and build an initramfs with network support.

3.3.36 dracut-ramdisk

Build Dracut-based ramdisks

This is an alternative to the

Busybox.

ramdisk element that uses Dracut to provide the base system functionality instead of

For elements that need additional drivers in the ramdisk image, a dracut-drivers.d feature is included that works in a similar fashion to the binary-deps.d feature. The element needing to add drivers should create a dracut-drivers.d

directory and populate it with a single file listing all of the kernel modules it needs added to the ramdisk. Comments are not supported in this file. Note that these modules must be installed in the chroot first.

By default, the virtio, virtio_net, and virtio_blk modules are included so that ramdisks are able to function properly in a virtualized environment.

3.3.37 dynamic-login

This element insert a helper script in the image that allows users to dynamically configure credentials at boot time.

This is specially useful for troubleshooting.

Troubleshooting an image can be quite hard, specially if you can not get a prompt you can enter commands to find out what went wrong. By default, the images (specially ramdisks) doesn’t have any SSH key or password for any user. Of course one could use the devuser element to generate an image with SSH keys and user/password in the image but that would be a massive security hole and very it’s discouraged to run in production with a ramdisk like that.

This element allows the operator to inject a SSH key and/or change the root password dynamically when the image boots. Two kernel command line parameters are used to do it: sshkey

Description

If the operator append sshkey=”$PUBLIC_SSH_KEY” to the kernel command line on boot, the helper script will append this key to the root user authorized_keys.

rootpwd

30 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

Description If the operator append rootpwd=”$ENCRYPTED_PASSWORD” to the kernel command line on boot, the helper script will set the root password to the one specified by this option.

Note that this password must be encrypted

. Encrypted passwords can be generated using the openssl command, e.g: openssl passwd -1 .

Note: The value of these parameters must be quoted , e.g: sshkey=”ssh-rsa BBBA1NBzaC1yc2E ...”

Warning:

Some base operational systems might require selinux to be in permissive or disabled mode so that you can log in the image. This can be achieved by building the image with the diskimage-builder or by passing selinux=0 selinux-permissive element for in the kernel command line. RHEL/CentOS are examples of OSs which this is true.

3.3.38 element-manifest

Writes a manifest file that is the full list of elements that were used to build the image. The file path can be overriden by setting $DIB_ELEMENT_MANIFEST_PATH, and defaults to /etc/dib-manifests/element-manifest.

3.3.39 enable-serial-console

Start getty on active serial consoles.

With ILO and other remote admin environments, having a serial console can be useful for debugging and troubleshooting.

For upstart: If ttyS1 exists, getty will run on that, otherwise on ttyS0.

For systemd: We dynamically start a getty on any active serial port via udev rules.

3.3.40 epel

This element installs the Extra Packages for Enterprise Linux (EPEL) repository GPG key as well as configuration for yum.

DIB_EPEL_MIRROR:

Required No

Default None

Description

To use a EPEL Yum mirror, set this variable to the mirror URL before running bin/diskimage-create. This URL should point to the directory containing the 5/6/7 directories.

Example

DIB\_EPEL\_MIRROR=http://dl.fedoraproject.org/pub/epel

3.3.41 fedora-minimal

Create a minimal image based on Fedora.

Use of this element will require ‘yum’ and ‘yum-utils’ to be installed on Ubuntu and Debian. Nothing additional is needed on Fedora or CentOS. The element will need python-lzma everywhere.

Due to a bug in the released version of urlgrabber, on many systems an installation of urlgrabber from git is required.

The git repository can be found here: http://yum.baseurl.org/gitweb?p=urlgrabber.git;a=summary

3.3. Elements 31

diskimage-builder Documentation, Release 1.20.1.dev11

The DIB_OFFLINE or more specific pre-cached root filesystem tarball.

DIB_YUMCHROOT_USE_CACHE variables can be set to prefer the use of a

This element sets the DIB_RELEASE var to ‘fedora’. The release of fedora to be installed can be controlled through the DIB_RELEASE variable, which defaults to ‘21’.

3.3.42 fedora

Use Fedora cloud images as the baseline for built disk images. For further details see the redhat-common README.

Environment Variables

DIB_DISTRIBUTION_MIRROR:

Required No

Default None

Description To use a Fedora Yum mirror, set this variable to the mirror URL before running bin/disk-image-create.

This URL should point to the directory containing the releases/updates/development and extras directories.

Example

DIB\_DISTRIBUTION\_MIRROR=http://download.fedoraproject.org/pub/fedora/linux

3.3.43 Gentoo

Use a Gentoo cloud image as the baseline for built disk images. The images are located in profile specific sub directories: http://distfiles.gentoo.org/releases/amd64/autobuilds/

As of this writing, only x86_64 images are available.

Notes:

• There are very frequently new automated builds that include changes that happen during the product maintenance. The download directories contain an unversioned name and a versioned name. The unversioned name will always point to the latest image, but will frequently change its content. The versioned one will never change content, but will frequently be deleted and replaced by a newer build with a higher version-release number.

• In order to run the package-installs element you will need to make sure dev-python/pyyaml host.

is installed on the

• In order to run the vm element you will need to make sure sys-block/parted is installed on the host.

• Other profiles can be used by exporting GENTOO_PROFILE with a valid profile. A list of valid profiles follows: default/linux/amd64/13.0

default/linux/amd64/13.0/no-multilib hardened/linux/amd64/no-multilib hardened/linux/amd64

• You can set the GENTOO_PORTAGE_CLEANUP environment variable to true (or anything other than False) to clean up portage from the system and get the image size smaller.

3.3.44 growroot

Grow the root partition on first boot.

This is only supported on:

32 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

• ubuntu trusty or later

• gentoo

• fedora & centos

3.3.45 grub2

This image installs grub2 bootloader on the image, that’s necessary for the local boot feature in Ironic to work. This is being made a separated element because usually images have grub2 removed for space reasons and also because they are going to boot from network (PXE boot).

3.3.46 hpdsa

This is the hpdsa element.

This element enables the ‘hpdsa’ driver to be included in the ramdisk when invoked during ramdisk/image creation.

This driver is required for deploying the HP Proliant Servers Gen9 with Dynamic Smart Array Controllers.

Note: This element supports only Ubuntu image/ramdisk to be updated with the hpdsa driver. It installs hp certificate from https://downloads.linux.hp.com/SDR/hpPublicKey2048_key1.pub

. Since HP has released this currently only for trusty, It has been restricted to work only for trusty.

3.3.47 hwburnin

A hardware test ramdisk - exercises the machine RAM and exercises the hard disks

3.3.48 hwdiscovery

A ramdisk to report the hardware of a machine to an inventory service.

This will collect up some basic information about the hardware it boots on:

• CPU cores

• RAM

• Disk

• NIC mac address

This information will then be collated into a JSON document, base64 encoded and passed, via HTTP POST, to a URL that you must specify on the kernel commandline, thus:

HW_DISCOVERY_URL=http://1.2.3.4:56/hw_script.asp

This is currently fairly fragile as there can be a huge variability in the number of disks/NICs in servers and how they are configured.

If other elements wish to inject data into the hardware discovery data, they can - they should be specified before hwdiscovery to the image building script, and they should contain something like this in their init fragment:

_vendor_hwdiscovery_data=”$_vendor_hwdiscovery_data “some vendor key” : “some data you care about”,

“some other vendor key” : “some other data you care about”,”

3.3. Elements 33

diskimage-builder Documentation, Release 1.20.1.dev11

Note that you are essentially feeding JSON into the main hwdiscovery JSON.

This will allow any number of vendor specific hwdiscovery elements to chain together their JSON fragments and maintain consistency.

3.3.49 ilo

Ramdisk support for applying HP iLO firmware.

The firmware files are copied in via an extra-data hook: the variable DIB_ILO_FIRMWARE_PATH specifies a directory, and every file in that directory will be unpacked into a same-named directory in the ramdisk (using –unpack=...).

If the path is not specified, a diagnostic is output but no error is triggered.

During ramdisk init every found firmware installer will be executed using –silent –log=log The log is displayed after the firmware has executed.

If the firmware exits with status 0 (ok), status 2 (same or older version) or 4 (ilo not detected) a diagnostic message is logged and init proceeds.

Any other status code is treated as an error.

3.3.50 install-bin

Add any files in an element’s bin directory to /usr/local/bin in the created image with permissions 0755.

3.3.51 install-static

Copy static files into the built image.

The contents of any static/ subdirs of elements will be installed into these images at build time using rsync

-lCr

. So to install a file

/etc/boo

, include static/etc/boo in your element.

Note: This installs all files with owner and group of root.

3.3.52 install-types

Enable install-types support for elements.

Install types permit elements to be installed from different sources, such as git repositories, distribution packages, or pip. The default install type is ‘source’ but it can be modified on the disk-image-create command line via the

–install-type option. For example you can set:

–install-type=package to enable package installs by default. Alternately, you can also set DIB_DEFAULT_INSTALLTYPE.

Many elements expose different install types. The different implementations live under <install-dir-prefix>-<installtype>-install directories under an element’s install.d. The base element enables the chosen install type by symlinking the correct hook scripts under install.d directly.

<install-dir-prefix> can be a string of alphanumeric and ‘-‘ characters, but typically corresponds to the element name.

For example, the nova element would provide: nova/install.d/nova-package-install/74-nova nova/install.d/nova-source-install/74-nova

The following symlink would be created for the package install type: install.d/74-nova -> nova-package-install/74-nova

34 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

Or, for the source install type: install.d/74-nova -> nova-source-install/74-nova

All other scripts that exist under install.d for an element will be executed as normal. This allows common install code to live in a script under install.d.

Environment Variables

DIB_INSTALLTYPE_<install_dir_prefix>

Required No

Default source

Description

Set the install type for the dir prefix. ‘-‘ characters can be replaced with a ‘_’.

Example

DIB_INSTALLTYPE_simple_init=repo to be repo.

Sets the simple-init element install type

3.3.53 ironic-agent

Builds a ramdisk with ironic-python-agent. More information can be found at: https://git.openstack.org/cgit/openstack/ironic-python-agent/

Beyond installing the ironic-python-agent, this element does the following:

• Installs the dhcp-all-interfaces available network interfaces.

so the node, upon booting, attempts to obtain an IP address on all

• Disables the iptables service on SysV and systemd based systems.

• Disables the ufw service on Upstart based systems.

• Installs packages required for the operation of the ironic-python-agent:: hdparm util-linux genisoimage qemu-utils parted

• When installing from source, python-dev and gcc are also installed in order to support source based installation of ironic-python-agent and its dependencies.

• Install the certificate if any, which is set to the environment variable

DIB_IPA_CERT for validating the authenticity by ironic-python-agent. The certificate can be self-signed certificate or CA certificate.

This element outputs three files:

• $IMAGE-NAME.initramfs

: The deploy ramdisk file containing the ironic-python-agent (IPA) service.

$IMAGE-NAME.kernel

: The kernel binary file.

$IMAGE-NAME.vmlinuz

: A hard link pointing to the

$IMAGE-NAME.kernel

file; this is just a backward compatibility layer, please do not rely on this file.

Note: The package based install currently only enables the service when using the systemd init system. This can easily be changed if there is an agent package which includes upstart or sysv packaging.

Note: Using the ramdisk will require at least 1.5GB of ram

3.3. Elements 35

diskimage-builder Documentation, Release 1.20.1.dev11

3.3.54 ironic-discoverd-ramdisk

Warning: This element is deprecated. Please use the ironic-agent element instead.

ironic-inspector [1] is a project for conducting hardware properties discovery via booting a special ramdisk and interrogating hardware from within it.

This ramdisk collects hardware information from the machine it’s booted on and posts it to the URL provided via kernel argument ‘discoverd_callback_url’.

The hardware information collected by the ramdisk are:

• BMC IP address (may be required for associating with existing node in Ironic)

• CPU count and architecture

• Memory amount in MiB

• Hard drive size in GiB

• IP and mac addresses for all NICs except the loopback

The machine is halted at the end of the process.

[1] https://pypi.python.org/pypi/ironic-inspector

3.3.55 iso

Generates a bootable ISO image from the kernel/ramdisk generated by the elements baremetal

, ironic-agent or ramdisk

. It uses isolinux to boot on BIOS machines and grub to boot on EFI machines.

This element has been tested on the following distro(s): * ubuntu * fedora * debian

NOTE : For other distros, please

/usr/lib/syslinux/isolinux.bin

.

make sure the isolinux.bin

file exists at

baremetal element

When used with baremetal element, this generates a bootable ISO image named booting the generated kernel and ramdisk.

<image-name>-boot.iso

It also automatically appends kernel command-line argument

‘root=UUID=<uuid-of-the-root-partition>’. Any more kernel command-line arguments required may be provided by specifying them in

DIB_BOOT_ISO_KERNEL_CMDLINE_ARGS

.

NOTE : It uses pre-built efiboot.img by default to work for UEFI machines. This is because of a bug in latest version of grub[1]. The user may choose to avoid using pre-built binary and build efiboot.img on their own machine by setting the environment variable DIB_UEFI_ISO_BUILD_EFIBOOT to 1 (this might work only on certain versions of grub).

The current efiboot.img was generated by the method build_efiboot_img() in 100-build-iso on Ubuntu 13.10 with grub

2.00-19ubuntu2.1.

ramdisk element

When used with ramdisk element, this generates a bootable ISO image named

<image-name>.iso

booting the generated kernel and ramdisk. It also automatically appends kernel command-line argument ‘boot_method=vmedia’ which is required for Ironic drivers iscsi_ilo

.

36 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

ironic-agent element

When used with ironic-agent element, this generates a bootable ISO image named

<image-name>.iso

which boots the agent kernel and agent ramdisk.

REFERENCES

[1] https://bugs.launchpad.net/ubuntu/+source/grub2/+bug/1378658

3.3.56 local-config

Copies local user settings such as .ssh/authorized_keys and $http_proxy into the image.

Environment Variables

DIB_LOCAL_CONFIG_USERNAME

Required No

Default root

Description Username used when installing .ssh/authorized_keys.

3.3.57 manifests

Copy any manifests generated into the build area post-image creation

This element should be a dependency of any element that writes a manifest into the DIB_MANIFEST_IMAGE_DIR , which defaults to /etc/dib-manifests . This is created in extra-data.d rather than pre-install.d to allow the sourcerepositories element to make use of it

The manifests are copied to manifests being available as

DIB_MANIFEST_SAVE_DIR

, which defaults to

${IMAGE_NAME}.d/dib-manifests by default

${IMAGE_NAME}.d/

, resulting in the

3.3.58 mellanox

Force support for mellanox hardware

3.3.59 modprobe-blacklist

Blacklist specific modules using modprobe.d/blacklist.conf.

In order to use set DIB_MODPROBE_BLACKLIST to the name of your module. To disable multiple modules you can set DIB_MODPROBE_BLACKLIST to a list of string separated by spaces.

Example: export DIB_MODPROBE_BLACKLIST=”igb”

3.3. Elements 37

diskimage-builder Documentation, Release 1.20.1.dev11

3.3.60 no-final-image

This is a noop element which can be used to indicate to diskimage-builder that it should not bother creating a final image out of the generated filesystem. It is useful in cases where an element handles all of the image building itself, such as ironic-agent or Docker images. In those cases the final image normally generated by diskimage-builder is not the desired output, so there’s no reason to spend time creating it.

Elements that wish to behave this way should include this element in their element-deps file.

3.3.61 oat-client

This element installs oat-client on the image, that’s necessary for trusted boot feature in Ironic to work.

Intel TXT will measure BIOS, Option Rom and Kernel/Ramdisk during trusted boot, the oat-client will securely fetch the hash values from TPM.

Note: This element only works on Fedora.

Put fedora-oat.repo

into /etc/yum.repos.d/ : export DIB_YUM_REPO_CONF=/etc/yum.repos.d/fedora-oat.repo

Note: OAT Repo is lack of a GPG signature check on packages, https://github.com/OpenAttestation/OpenAttestation/issues/26 which can be tracked on:

3.3.62 opensuse

Use an openSUSE cloud image as the baseline for built disk images. The images are located in distribution specific sub directories under http://download.opensuse.org/repositories/Cloud:/Images:/

For example, the images of openSUSE 13.2 can be found here: http://download.opensuse.org/repositories/Cloud:/Images:/openSUSE_13.2/images/

These images should be considered experimental. There are curently only x86_64 images.

Environment Variables

DIB_RELEASE

Required No

Default 13.1

Description Set the desired openSUSE release.

DIB_CLOUD_IMAGES

Required

No

Default http://download.opensuse.org/repositories/Cloud:/Images :/(openSUSE|Leap)_${DIB_RELEASE}

Description Set the desired URL to fetch the images from.

38 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

Notes:

• There are very frequently new automated builds that include changes that happen during the product maintenance. The download directories contain an unversioned name and a versioned name. The unversioned name will always point to the latest image, but will frequently change its content. The versioned one will never change content, but will frequently be deleted and replaced by a newer build with a higher version-release number.

3.3.63 package-installs

The package-installs element allows for a declarative method of installing and uninstalling packages for an image build. This is done by creating a package-installs.yaml or package-installs.json file in the element directory.

In order to work on Gentoo hosts you will need to manually install dev-python/pyyaml .

example package-installs.yaml

libxml2: grub2: phase: pre-install.d

networkmanager: uninstall: True os-collect-config: installtype: source linux-image-amd64: arch: amd64 dmidecode: not-arch: ppc64, ppc64le lshw: arch: ppc64, ppc64le example package-installs.json

{

"libxml2"

:

null

,

"grub2"

: {

"phase"

: "pre-install.d" },

"networkmanager"

: {

"uninstall"

:

true

}

"os-collect-config"

}

: {

"installtype"

: "source" }

Setting phase, uninstall, or installtype properties for a package overrides the following default values: phase: install.d

uninstall: False installtype: * (Install package for all installtypes) arch: * (Install package for all architectures)

Setting the installtype property causes the package only to be installed if the specified installtype would be used for the element. See the diskimage-builder docs for more information on installtypes.

The arch property is a comma-separated list of architectures to install for. The not-arch is a comma-separated list of architectures the package should be excluded from. Either arch or not-arch can be given for one package - not both. See documentation about the ARCH variable for more information.

DEPRECATED: Adding a file under your elements pre-install.d, install.d, or post-install.d directories called packageinstalls-<element-name> will cause the list of packages in that file to be installed at the beginning of the respective phase. If the package name in the file starts with a “-”, then that package will be removed at the end of the install.d

phase.

3.3. Elements 39

diskimage-builder Documentation, Release 1.20.1.dev11

Using post-install.d for cleanup

Package removal is done in post-install.d at level 95. If you a running cleanup functions before this, you need to be careful not to clean out any temporary files relied upon by this element. For this reason, generally post-install cleanup functions should occupy the higher levels between 96 and 99.

3.3.64 partitioning-sfdisk

Sets up a partitioned disk using sfdisk, according to user needs.

Environment Variables

DIB_PARTITIONING_SFDISK_SCHEMA : Required: Yes : Default: 2048„L *

0 0; 0 0; 0 0;

: Description: A multi-line string specifying

‘‘

DIB_PARTITIONING_SFDISK_SCHEMA=” a disk schema in sectors.

2048,10000,L * 10248„L 0 0; ” will create two partitions on disk, first one will be bootable.

: Example:

3.3.65 pip-and-virtualenv

This element installs pip and virtualenv in the image. If the package installtype is used then these programs are installed from distribution packages. If the source installtype is used these programs are installed from get-pip.py and pip (respectively).

To install pip and virtualenv from package: export DIB_INSTALLTYPE_pip_and_virtualenv=package

3.3.66 pip-cache

# Use a cache for pip

Using a download cache speeds up image builds.

Including this element in an image build causes $HOME/.cache/image-create/pip to be bind mounted as /tmp/pip inside the image build chroot. The $PIP_DOWNLOAD_CACHE environment variable is then defined as /tmp/pip, which causes pip to cache all downloads to the defined location.

Note that pip and its use of $PIP_DOWNLOAD_CACHE is not concurrency safe. Running multiple instances of diskimage-builder concurrently can cause issues. Therefore, it is advised to only have one instance of diskimagebuilder that includes the pip-cache element running at a time.

The pip concurrency issue is being tracked upstream at https://github.com/pypa/pip/issues/1141

3.3.67 pkg-map

Map package names to distro specific packages.

Provides the following:

• bin/pkg-map:

40 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

usage: pkg-map [-h] [--element ELEMENT] [--distro DISTRO]

Translate package name to distro specific name.

optional arguments:

-h, --help

--element ELEMENT

--distro DISTRO

--release RELEASE show this help message and exit

The element (namespace) to use for translation.

The distro name to use for translation. Defaults to

DISTRO_NAME

The release to use for translation.

DIB_RELEASE

Defaults to

• Any element may create its own pkg-map JSON config file using the one of 4 sections for the release/distro/family/ and or default. The family is set automatically within pkg-map based on the supplied distro name. Families include:

– redhat: includes centos, fedora, and rhel distros

– debian: includes debian and ubuntu distros

– suse: includes the opensuse distro

The release is a specification of distro; i.e. the distro and release must mach for a translation.

The most specific section takes priority.

An empty package list can be provided.

Example for Nova and Glance (NOTE: using fictitious package names for Fedora and package mapping for suse family to provide a good example!)

Example format:

{

}

"release" : {

"fedora" : {

"23" : {

"nova_package" :

}

}

"foo" "bar"

},

"distro" : {

"fedora" : {

"nova_package" : "openstack-compute" ,

"glance_package" : "openstack-image"

},

}

"family" : {

"redhat" : {

},

"nova_package" : "openstack-nova" ,

"glance_package" : "openstack-glance"

"suse" : {

"nova_package" : ""

},

}

"default" : {

"nova_package" : "nova" ,

"glance_package" : "glance"

}

3.3. Elements 41

diskimage-builder Documentation, Release 1.20.1.dev11

Example commands using this format: pkg-map –element nova-compute –distro fedora nova_package

Returns: openstack-compute pkg-map –element nova-compute –distro rhel nova_package

Returns: openstack-nova pkg-map –element nova-compute –distro ubuntu nova_package

Returns: nova pkg-map –element nova-compute –distro opensuse nova_package

Returns:

• This output can be used to filter what other tools actually install (install-packages can be modified to use this for example)

• Individual pkg-map files live within each element. For example if you are created an Apache element your pkg-map JSON file should be created at elements/apache/pkg-map.

3.3.68 posix

• This element installs packages to ensure that the resulting image has binaries necessary to meet the requirements of POSIX, laid out in the following URL:

– http://pubs.opengroup.org/onlinepubs/9699919799/idx/utilities.html

• This has been tested to work on Ubuntu, Debian, and CentOS, although should work on Red Hat Enterprise

Linux.

• To add support for other distros please consult the URL for binaries, then add the providing packages to pkgmap.

3.3.69 proliant-tools

• This element can be used when building ironic-agent ramdisk. It enables ironic-agent ramdisk to do in-band cleaning operations specific to HP ProLiant hardware.

• Works with ubuntu and fedora distributions (on which ironic-agent element is supported).

• Currently the following utilities are installed:

– proliantutils - This module registers an ironic-python-agent hardware manager for HP ProLiant hardware, which implements in-band cleaning steps. The latest version of proliantutils available is installed.

This python module is released with Apache license.

– HP Smart Storage Administrator (HP SSA) CLI for Linux 64-bit rently installed version is 2.30. Newer version of hpssacli

- This utility is used by proliantutils library above for doing in-band RAID configuration on HP ProLiant hardware. Curwhen available, may be installed to the ramdisk by using the environment variable

DIB_HPSSACLI_URL

.

DIB_HPSSACLI_URL should contain the HTTP(S) URL for downloading the RPM package for hpssacli utility. Availability of newer versions can be in the Revision History in the above link. This utility is closed source and is released with

HP End User License Agreement – Enterprise Version .

42 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

3.3.70 pypi

Inject a PyPI mirror

Use a custom PyPI mirror to build images. The default is to bind mount one from ~/.cache/image-create/pypi/mirror into the build environment as mirror URL file:///tmp/pypi. The element temporarily overwrites /root/.pip.conf and

.pydistutils.cfg to use it.

When online, the official pypi.python.org pypi index is supplied as an extra-url, so uncached dependencies will still be available. When offline, only the mirror is used - be warned that a stale mirror will cause build failures. To disable the pypi.python.org index without using –offline (e.g. when working behind a corporate firewall that prohibits pypi.python.org) set DIB_NO_PYPI_PIP to any non-empty value.

To use an arbitrary mirror set DIB_PYPI_MIRROR_URL=http[s]://somevalue/

Additional mirrors can be added by exporting DIB_PYPI_MIRROR_URL_1=... etc. Only the one mirror can be used by easy-install, but since wheels need to be in the first mirror to be used, the last listed mirror is used as the pydistutils index. NB: The sort order for these variables is a simple string sort - if you have more than 9 additional mirrors, some care will be needed.

You can also set the number of retries that occur on failure by setting the DIB_PIP_RETRIES environment variable.

If setting fallback pip mirrors you typically want to set this to 0 to prevent the need to fail multiple times before falling back.

A typical use of this element is thus: export DIB_PYPI_MIRROR_URL=http://site/pypi/Ubuntu-13.10 export DIB_PYPI_MIRROR_URL_1=http://site/pypi/ export DIB_PYPI_MIRROR_URL_2=file:///tmp/pypi export

DIB_PIP_RETRIES=0

[devpi-server]( https://git.openstack.org/cgit/openstack-infra/pypi-mirro://pypi.python.org/pypi/devpi-server ) can be useful in making a partial PyPI mirror suitable for building images. For instance:

• pip install -U devpi

• devpi-server quickstart

• devpi use http://machinename:3141

• Re-export your variables to point at the new mirror: export DIB_PYPI_MIRROR_URL=http://machinename:3141/

DIB_PYPI__MIRROR_URL_1 unset DIB_PYPI__MIRROR_URL_2 unset

The next time packages are installed, they’ll be cached on the local devpi server; subsequent runs pointed at the same mirror will use the local cache if the upstream can’t be contacted.

Note that this process only has the server running temporarily; see [Quickstart: Permanent install on server/laptop]( http://doc.devpi.net/latest/quickstart-server.html

) guide from the devpi developers for more information on a more permanent setup.

3.3.71 ramdisk-base

Shared functionality required by all of the different ramdisk elements.

3.3.72 ramdisk

This is the ramdisk element.

Almost any user building a ramdisk will want to include this in their build, as it triggers many of the vital functionality from the basic diskimage-builder libraries (such as init script aggregation, busybox population, etc).

3.3. Elements 43

diskimage-builder Documentation, Release 1.20.1.dev11

An example of when one might want to use this toolchain to build a ramdisk would be the initial deployment of baremetal nodes in a TripleO setup. Various tools and scripts need to be injected into a ramdisk that will fetch and apply a machine image to local disks. That tooling/scripting customisation can be easily applied in a repeatable and automatable way, using this element.

NOTE: ramdisks require 1GB minimum memory on the machines they are booting.

See the top-level README.md of the project, for more information about the mechanisms available to a ramdisk element.

3.3.73 rax-nova-agent

Images for Rackspace Cloud currently require nova-agent to get networking information.

Many of the things here are adapted from: https://developer.rackspace.com/blog/bootstrap-your-qcow-images-for-the-rackspace-public-cloud/

3.3.74 redhat-common

Image installation steps common to RHEL, CentOS, and Fedora.

Requirements:

If used to build an image form a cloud image compress with xz (the default in centos), this element uses “unxz” to decompress the image. Depending on your distro you may need to install either the xz or xz-utils package.

Environment Variables

DIB_LOCAL_IMAGE

Required No

Default None

Description

Use the local path of a qcow2 cloud image. This is useful in that you can use a customized or previously built cloud image from diskimage-builder as input. The cloud image does not have to have been built by diskimage-builder. It should be a full disk image, not just a filesystem image.

Example

DIB_LOCAL_IMAGE=rhel-guest-image-7.1-20150224.0.x86_64.qcow2

DIB_DISABLE_KERNEL_CLEANUP

Required No

Default 0

Description Specify if kernel needs to be cleaned up or not. When set to true, the bits that cleanup old kernels will not be executed.

Example DIB_DISABLE_KERNEL_CLEANUP=1

3.3.75 rhel-common

This element contains the common installation steps between RHEL os releases.

44 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

RHEL Registration

This element provides functionality for registering RHEL images during the image build process with the disk-imagecreate script from diskimage-builder. The RHEL image will register itself with either the hosted Red Hat Customer

Portal or Satellite to enable software installation from official repositories. After the end of the image creation process, the image will unregister itself so an entitlement will not be decremented from the account.

SECURITY WARNING:

While the image building workflow will allow you to register with a username and password combination, that feature is deprecated in the boot process via Heat as it will expose your username and password in clear text for anyone that has rights to run heat stack-show. A compromised username and password can be used to login to the Red Hat

Customer Portal or an instance of Satellite. An activation key can only be used for registration purposes using the subscription-manager command line tool and is considered a lower security risk.

IMPORTANT NOTE:

The 00-rhsm script is specific to RHEL6. If you use the REG_ variables to use with RHEL7, you do not need to set any DIB_RHSM variables. The scripts named with “rhel-registration” have not been developed or tested for RHEL6.

For information on building RHEL6 images, please see the rhel element README.

Environment Variables For Image Creation

The following environment variables are used for registering a RHEL instance with either the Red Hat Customer Portal or Satellite 6.

#### REG_ACTIVATION_KEY Attaches existing subscriptions as part of the registration process. The subscriptions are pre-assigned by a vendor or by a systems administrator using Subscription Asset Manager.

#### REG_AUTO_ATTACH Automatically attaches the best-matched compatible subscription. This is good for automated setup operations, since the system can be configured in a single step.

#### REG_BASE_URL Gives the hostname of the content delivery server to use to receive updates. Both Customer

Portal Subscription Management and Subscription Asset Manager use Red Hat’s hosted content delivery services, with the URL https://cdn.redhat.com

. Since Satellite 6 hosts its own content, the URL must be used for systems registered with Satellite 6.

#### REG_ENVIRONMENT Registers the system to an environment within an organization.

#### REG_FORCE Registers the system even if it is already registered. Normally, any register operations will fail if the machine is already registered.

#### REG_HALT_UNREGISTER At the end of the image build process, the element runs a cleanup script that will unregister it from the system it registered with. There are some cases when building an image where you may want to stop this from happening so you can verify the registration or to build a one off-image where the boot-time registration will not be enabled. Set this value to ‘1’ to stop the unregistration process.

#### REG_MACHINE_NAME Sets the name of the system to be registered. This defaults to be the same as the hostname.

#### REG_METHOD Sets the method of registration. Use “portal” to register a system with the Red Hat Customer

Portal. Use “satellite” to register a system with Red Hat Satellite 6. Use “disable” to skip the registration process.

#### REG_ORG Gives the organization to which to join the system.

#### REG_POOL_ID The pool ID is listed with the product subscription information, which is available from running the list subcommand of subscription-manager.

3.3. Elements 45

diskimage-builder Documentation, Release 1.20.1.dev11

#### REG_PASSWORD Gives the password for the user account.

#### REG_RELEASE Sets the operating system minor release to use for subscriptions for the system. Products and updates are limited to that specific minor release version. This is used only used with the REG_AUTO_ATTACH option. Possible values for this include 5Server, 5.7, 5.8, 5.9, 5.10, 6.1,...6.6, 7.0. It will change over time as new releases come out. There are also variants 6Server, 6Client, 6Workstation, 7Server, etc.

#### REG_REPOS A single string representing a list of repository names separated by a comma (No spaces). Each of the repositories in this string are enabled through subscription manager. Once you’ve attached a subscription, you can find available repositories by running subscription-manager repos –list.

#### REG_SERVER_URL Gives the hostname of the subscription service to use. The default is for Customer Portal Subscription Management, subscription.rhn.redhat.com. If this option is not used, the system is registered with

Customer Portal Subscription Management.

#### REG_SERVICE_LEVEL Sets the service level to use for subscriptions on that machine. This is only used with the REG_AUTO_ATTACH option.

#### REG_USER Gives the content server user account name.

#### REG_TYPE Sets what type of consumer is being registered. The default is system, which is applicable to both physical systems and virtual guests. Other types include hypervisor for virtual hosts, person, domain, rhui, and candlepin for some subscription management applications.

Image Build Registration Examples

To register with Satellite 6, a common example would be to set the following variables:

REG_SAT_URL=’ http://my-sat06.server.org

‘ REG_ORG=’tripleo’ REG_ENV=’Library’ REG_USER=’tripleo’

REG_PASSWORD=’tripleo’ REG_METHOD=satellite

To register with the Red Hat Customer Portal, a common example would be to set the following variables:

REG_REPOS=’rhel-7-server-optional-rpms,rhel-7-server-extras-rpms’

REG_USER=’tripleo’ REG_PASSWORD=’tripleo’ REG_METHOD=portal

REG_AUTO_ATTACH=true

Configuration

Heat metadata can be used to configure the rhel-common element.

rh_registration: activation_key: # Attaches existing subscriptions as part of the registration # process. The subscriptions are pre-assigned by a vendor or by # a systems administrator using Subscription

Asset Manager.

auto_attach: ‘true’

# Automatically attaches the best-matched compatible subscription. # This is good for automated setup operations, since the system can # be configured in a single step.

base_url:

# Gives the hostname of the content delivery server to use to # receive updates. Both

Customer Portal Subscription Management # and Subscription Asset Manager use Red Hat’s hosted content # delivery services, with the URL https://cdn.redhat.com

. Since # Satellite 6 hosts its own content, the URL must be used for # systems registered with Satellite 6.

environment: # Registers the system to an environment within an organization.

force: # Registers the system even if it is already registered. Normally, # any register operations will fail if the machine is already # registered.

machine_name: the hostname.

# Sets the name of the system to be registered. This defaults to be # the same as

46 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

org: # Gives the organization to which to join the system.

password: # DEPRECATED # Gives the password for the user account.

release:

# Sets the operating system minor release to use for subscriptions # for the system. Products and updates are limited to that specific # minor release version. This is only used with the auto_attach # option.

repos: # A single string representing a list of repository names separated by a # comma (No spaces).

Each of the repositories in this string are enabled # through subscription manager.

satellite_url: # The url of the Satellite instance to register with. Required for # Satellite registration.

server_url: # Gives the hostname of the subscription service to use. The default # is for Customer

Portal Subscription Management, # subscription.rhn.redhat.com. If this option is not used, the system # is registered with Customer Portal Subscription Management.

service_level: # Sets the service level to use for subscriptions on that machine. # This is only used with the auto_attach option.

user: # DEPRECATED # Gives the content server user account name.

type:

# Sets what type of consumer is being registered. The default is # “system”, which is applicable to both physical systems and virtual # guests. Other types include “hypervisor” for virtual hosts, # “person”, “domain”, “rhui”, and “candlepin” for some subscription # management applications.

method: # Sets the method of registration. Use “portal” to register a # system with the Red Hat

Customer Portal. Use “satellite” to # register a system with Red Hat Satellite 6. Use “disable” to # skip the registration process.

Configuration Registration Examples

To register with Satellite 6, a common example would be to use the following metadata:

{

"rh_registration" :{

"satellite_url" : "http://my-sat06.server.org" ,

"org" : "tripleo" ,

"environment" : "Library" ,

"activation_key" : "my-key-SQQkh4" ,

"method" : "satellite" ,

"repos" : "rhel-ha-for-rhel-7-server-rpms"

}

}

To register with the Red Hat Customer Portal, a common example would be to use the following metadata:

{

"rh_registration" :{

"repos" : "rhel-7-server-optional-rpms,rhel-7-server-extras-rpms" ,

"auto_attach" :true,

"activation_key"

"org" : "5643002"

:

,

"my-key-SQQkh4" ,

"method" : "portal"

}

}

3.3. Elements 47

diskimage-builder Documentation, Release 1.20.1.dev11

3.3.76 rhel

# Overrides:

## General * Downloading the Red Hat Enterprise Linux cloud image requires a valid Red Hat

Network login and a subscription to Red Hat Enterprise Linux 6 Server product.

* diskimagebuilder does not integrate directly with RHN, so a manual download is required.

https://rhn.redhat.com/rhn/software/channel/downloads/Download.do?cid=16952

Please visit to download the qcow2 file. * Set

DIB_CLOUD_IMAGES to “file:///download_path” * Overriding of DIB_RELEASE is necessary when a new version of the RHEL qcow2 image is available and the default image has not yet been updated in diskimage-builder.

## Red Hat Subscription Manager (RHSM)

Certificate-based Red Hat Subscription Management (RHSM) is the default registration type.

• Set DIB_RHSM_USER and DIB_RHSM_PASSWORD to register the system with RHSM during the image building process. This will apply the associated Red Hat Enterprise Linux Server subscription so the latest package updates can be applied. At the end of the image building process, the system will be unregistered from

RHSM.

• Set DIB_RHSM_POOL to a subscription pool if you do not want the system to use the –auto-attach feature of subscription-manager .

• Set DIB_RHSM_REPOS to a space-separated list of Red Hat repositories to enable.

## Red Hat Network (RHN)

Set DIB_REG_TYPE=rhn for Red Hat Network (RHN classic) registration. The image building process will register the system to RHN and apply the associated Red Hat Enterprise Linux Server subscription so the latest package updates can be applied. At the end of the image building process, the system will be unregistered from RHN.

• For RHN username/password authentication set DIB_RHSM_USER and DIB_RHSM_PASSWORD. To use a

Satellite server activation key set DIB_SAT_KEY. If adding RHN channels username and password must be set.

• When registering to Satellite set DIB_SAT_URL to the Satellite server URL and DIB_SAT_CERT_RPM_URL to the Satellite certificate.

• Set DIB_RHN_CHANNELS to a space-separated list of RHN channels

DIB_RHN_CHANNELS=rhel-x86_64-server-6 rhel-x86_64-server-6-rhscl-1 .

to add.

Example:

RHN username/password is required for this.

3.3.77 rhel7

Use RHEL 7 cloud images as the baseline for built disk images.

Because RHEL 7 base images are not publicly available, it is necessary to first download the RHEL 7 cloud image from the Red Hat Customer Portal and pass the path to the resulting file to disk-image-create as the

DIB_LOCAL_IMAGE environment variable.

The cloud image can be found at (login required):

7/7.1/x86_64/product-downloads https://access.redhat.com/downloads/content/69/ver=/rhel—

Then before running the image build, define DIB_LOCAL_IMAGE (replace the file name with the one downloaded, if it differs from the example): export DIB_LOCAL_IMAGE=rhel-guest-image-7.1-20150224.0.x86_64.qcow2

The downloaded file will then be used as the basis for any subsequent image builds.

For further details about building RHEL 7 images, see the rhel-common and redhat-common element README files.

48 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

Environment Variables

DIB_LOCAL_IMAGE

Required Yes

Default None

Description The RHEL 7 base image you have downloaded. See the element description above for more details.

Example

DIB_LOCAL_IMAGE=/tmp/rhel7-cloud.qcow2

3.3.78 runtime-ssh-host-keys

An element to generate SSH host keys on first boot.

Since ssh key generation is not yet common to all operating systems, we need to create a DIB element to manage this.

We force the removal of the SSH host keys, then add init scripts to generate them on first boot.

This element currently supports Debian and Ubuntu (both systemd and upstart).

3.3.79 select-boot-kernel-initrd

A helper script to get the kernel and initrd image.

It uses the function select_boot_kernel_initrd from the library img-functions to find the newest kernel and ramdisk in the image, and returns them as a concatenated string separating the values with a colon (:).

3.3.80 selinux-permissive

Puts selinux into permissive mode by writing SELINUX=permissive to /etc/selinux/config

Enable this element when debugging selinux issues.

3.3.81 serial-console

This element is now deprecated please use enable-serial-console instead

3.3.82 simple-init

Basic network and system configuration that can’t be done until boot

Unfortunately, as much as we’d like to bake it in to an image, we can’t know in advance how many network devices will be present, nor if DHCP is present in the host cloud. Additionally, in environments where cloud-init is not used, there are a couple of small things, like mounting config-drive and pulling ssh keys from it, that need to be done at boot time.

3.3. Elements 49

diskimage-builder Documentation, Release 1.20.1.dev11

Autodetect network interfaces during boot and configure them

The rationale for this is that we are likely to require multiple network interfaces for use cases such as baremetal and there is no way to know ahead of time which one is which, so we will simply run a DHCP client on all interfaces with real MAC addresses (except lo) that are visible on the first boot.

The script /usr/local/sbin/simple-init.sh

will be called early in each boot and will scan available network interfaces and ensure they are configured properly before networking services are started.

Processing startup information from config-drive

On most systems, the DHCP approach desribed above is fine. But in some clouds, such as Rackspace Public cloud, there is no DHCP. Instead, there is static network config via config-drive .

simple-init will happily call glean which will do nothing if static network information is not there.

Finally, glean will handle ssh-keypair-injection from config drive if cloud-init is not installed.

Chosing glean installation source

By default glean is installed using pip using the latest release on pypi. It is also possible to install glean from a specified git repository location. This is useful for debugging and testing new glean changes for example. To do this you need to set these variables:

DIB_INSTALLTYPE_simple_init=repo

DIB_REPOLOCATION_glean=/path/to/glean/repo

DIB_REPOREF_glean=name_of_git_ref

For example to test glean change 364516 do: git clone https://git.openstack.org/openstack-infra/glean /tmp/glean cd /tmp/glean git review -d 364516 git checkout -b my-test-ref

Then set your DIB env vars like this before running DIB:

DIB_INSTALLTYPE_simple_init=repo

DIB_REPOLOCATION_glean=/tmp/glean

DIB_REPOREF_glean=my-test-ref

3.3.83 source-repositories

With this element other elements can register their installation source by placing their details in the file source-repository-*

.

source-repository-* file format

The plain text file format is space separated and has four mandatory fields optionally followed by fields which are type dependent:

<name> <type> <destination> <location> [<ref>]

name

Identifier for the source repository. Should match the file suffix.

type

Format of the source. Either git

, tar

, package or file

.

50 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

destination

Base path to place sources.

location

Resource to fetch sources from. For git the location is cloned. For tar it is extracted.

ref

(optional). Meaning depends on the

type

: file : unused/ignored.

git : a git reference to fetch. A value of “

*

” prunes and fetches all heads and tags. Defaults to specified.

master if not

tar

:

.

” extracts the entire contents of the tarball.

*

” extracts the contents within all its subdirectories.

A subdirectory path may be used to extract only its contents.

A specific file path within the archive is not supported .

The lines in the source-repository scripts are eval’d, so they may contain environment variables.

The package type indicates the element should install from packages onto the root filesystem of the image build during the install.d

phase. If the element provides an <element-name>-package-install directory, symlinks will be created for those scripts instead.

git and tar are treated as source installs. If the element provides an <element-name>-source-install directory under it’s install.d

image build.

hook directory, symlinks to the scripts in that directory will be created under install.d

for the

For example, the nova element would provide: nova / install .

d / nova package install / 74 nova nova / install .

d / nova source install / 74 nova source-repositories will create the following symlink for the package install type: install.d/74-nova -> nova-package-install/74-nova

Or, for the source install type: install.d/74-nova -> nova-source-install/74-nova

All other scripts that exist under install.d

for an element will be executed as normal. This allows common install code to live in a script outside of <element-name>-package-install or <element-name>-source-install.

If multiple elements register a source location with the same <destination> then source-repositories will exit with an error. Care should therefore be taken to only use elements together that download source to different locations.

The repository paths built into the image are stored in etc/dib-source-repositories, one repository per line. This permits later review of the repositories (by users or by other elements).

The repository names and types are written to an environment.d hook script at 01-source-repositories-environment.

This allows later hook scripts during the install.d phase to know which install type to use for the element.

An example of an element “custom-element” that wants to retrieve the ironic source from git and pbr from a tarball would be:

Element file: elements/custom-element/source-repository-ironic : ironic git /usr/local/ironic git://git.openstack.org/openstack/ironic.git

File : elements/custom-element/source-repository-pbr : pbr tar /usr/local/pbr http://tarballs.openstack.org/pbr/pbr-master.tar.gz .

diskimage-builder will then retrieve the sources specified and place them at the directory

<destination>

.

3.3. Elements 51

diskimage-builder Documentation, Release 1.20.1.dev11

Override per source

A number of environment variables can be set by the process calling diskimage-builder which can change the details registered by the element, these are:

DIB_REPOTYPE_<name>

: change the registered type

DIB_REPOLOCATION_<name>

: change the registered location

DIB_REPOREF_<name>

: change the registered reference

For example if you would like diskimage-builder to get ironic from a local mirror you would override the

<location> field and could set:

DIB_REPOLOCATION_ironic = git://localgitserver/ironic.git

As you can see above, the <name> of the repo is used in several bash variables. In order to make this syntactically feasible, any characters not in the set [A-Za-z0-9_] will be converted to _

For instance, a repository

“DIB_REPOTYPE_diskimage_builder” named “diskimage-builder” would set a variable called

Alternatively if you would like to use the keystone element and build an image with keystone from a stable branch stable/grizzly then you would set:

DIB_REPOREF_keystone = stable/grizzly

If you wish to build an image using code from a Gerrit review, you can set

DIB_REPOLOCATION_<name> and

DIB_REPOREF_<name> to the values given by Gerrit in the fetch/pull section of a review. For example, setting up

Nova with change 61972 at patchset 8:

DIB_REPOLOCATION_nova = https://review.openstack.org/openstack/nova

DIB_REPOREF_nova = refs/changes/72/61972/8

Alternate behaviors

Override git remote

The base url for all git repositories can be set by use of:

DIB_GITREPOBASE

So setting

DIB_GITREPOBASE=https://github.com/ http://git.openstack.org/openstack/nova.git

will result in use of the tory instead.

when the repo location is https://github.com/openstack/nova.git

set to reposi-

Disable external fetches

When doing image builds in environments where external resources are not allowed, it is possible to disable fetching of all source repositories by including an element in the image that sets

NO_SOURCE_REPOSITORIES=1 in an environment.d

script.

3.3.84 stable-interface-names

Does the following:

52 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

• Enables stable network interface naming (em1, em2, etc) by installing the biosdevname and removes any symlinks which may disable udev rules, etc.

3.3.85 svc-map

Map service names to distro specific services.

Provides the following:

• bin/svc-map usage: svc-map [-h] SERVICE

Translate service name to distro specific name.

optional arguments:

-h, --help show this help message and exit

• Any element may create its own svc-map YAML config file using the one of 3 sections for the distro/family/ and or default. The family is set automatically within svc-map based on the supplied distro name. Families include:

– redhat: includes centos, fedora, and rhel distros

– debian: includes debian and ubuntu distros

– suse: includes the opensuse distro

The most specific section takes priority. Example for Nova and Glance (NOTE: default is using the common value for redhat and suse families)

The key used for the service name should always be the same name used for the source installation of the service.

The svc-map script will check for the source name against systemd and upstart and return that name if it exists instead of the mapped name.

Example format for Nova: nova-api: default: openstack-nova-api debian: nova-api nova-cert: default: openstack-nova-cert debian: nova-cert nova-compute: default: openstack-nova-compute debian: nova-compute nova-conductor: default: openstack-nova-conductor debian: nova-conductor nova-consoleauth: default: openstack-nova-console debian: nova-console

Example format for Glance: glance-api: debian: glance-api default: openstack-glance-api glance-reg: debian: glance-reg default: openstack-glance-registry

3.3. Elements 53

diskimage-builder Documentation, Release 1.20.1.dev11

If the distro is of the debian family the combined services file would be: nova-cert: nova-cert nova-compute: nova-compute glance-api: glance-api nova-conductor: nova-conductor nova-api: nova-api glance-reg: glance-reg nova-consoleauth: nova-console

If the distro is of the suse or redhat families the combined services file would be: nova-cert: openstack-nova-cert nova-compute: openstack-nova-compute glance-reg: openstack-glance-registry nova-conductor: openstack-nova-conductor glance-api: openstack-glance-api nova-consoleauth: openstack-nova-console nova-api: openstack-nova-api

Example commands using this format: svc-map nova-compute

Returns: openstack-nova-compute svc-map nova-compute

Returns: openstack-nova-compute svc-map nova-compute

Returns: nova-compute

• This output can be used to filter what other tools actually install (install-services can be modified to use this for example)

• If you pass more than one service argument, the result for each service is printed on its own line.

• Individual svc-map files live within each element. For example if you have created an Apache element your svc-map YAML file should be created at elements/apache/svc-map.

3.3.86 uboot

Perform kernel/initrd post-processing for UBoot.

This element helps post-process the kernel/initrd for use with uboot. It works with ramdisk images as well as user images.

This element needs u-boot-tools to be installed on the host.

The load address and entry point for UBoot kernel can be specified as shown in the example below.

Example: export UBOOT_KERNEL_ADDR=0x80000 export UBOOT_KERNEL_EP=0x80000

3.3.87 ubuntu-core

Use Ubuntu Core cloud images as the baseline for built disk images.

Overrides:

54 Chapter 3. Table of Contents

diskimage-builder Documentation, Release 1.20.1.dev11

• To use a non-default URL for downloading base Ubuntu cloud images, use the environment variable

DIB_CLOUD_IMAGES

• To download a non-default release of Ubuntu cloud images, use the environment variable DIB_RELEASE

• To use different mirrors rather than the default of archive.ubuntu.com and security.ubuntu.com, use the environment variable DIB_DISTRIBUTION_MIRROR

3.3.88 ubuntu-minimal

Note: The ubuntu element is likely what you want unless you really know you want this one for some reason. The ubuntu element gets a lot more testing coverage and use.

Create a minimal image based on Ubuntu. We default to trusty but DIB_RELEASE is mapped to any series of Ubuntu.

If necessary, a custom apt keyring and debootstrap script can be supplied to the

DIB_APT_KEYRING and

DIB_DEBIAN_DEBOOTSTRAP_SCRIPT debootstrap command via respectively. Both options require the use of absolute rather than relative paths.

Use of this element will also require the tool ‘debootstrap’ to be available on your system. It should be available on

Ubuntu, Debian, and Fedora.

The DIB_OFFLINE or more specific DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE variables can be set to prefer the use of a pre-cached root filesystem tarball.

The DIB_DEBOOTSTRAP_EXTRA_ARGS environment variable may be used to pass extra arguments to the debootstrap command used to create the base filesystem image.

If –keyring is is used in

DIB_DEBOOTSTRAP_EXTRA_ARGS , it will override DIB_APT_KEYRING if that is used as well.

For further information about DIB_DEBIAN_DEBOOTSTRAP_SCRIPT , DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE and DIB_DEBOOTSTRAP_EXTRA_ARGS please consult “README.rst” of the debootstrap element.

3.3.89 ubuntu

Use Ubuntu cloud images as the baseline for built disk images.

Overrides:

• To use a non-default URL for downloading base Ubuntu cloud images, use the environment variable

DIB_CLOUD_IMAGES

• To download a non-default release of Ubuntu cloud images, use the environment variable DIB_RELEASE. This element will export the DIB_RELEASE variable.

• To use different mirrors rather than the default of archive.ubuntu.com and security.ubuntu.com, use the environment variable DIB_DISTRIBUTION_MIRROR

3.3.90 vm

Sets up a partitioned disk (rather than building just one filesystem with no partition table).

3.3.91 yum-minimal

Base element for creating minimal yum-based images.

This element is incomplete by itself, you’ll want to use the centos-minimal or fedora-minimal elements to get an actual base image.

3.3. Elements 55

diskimage-builder Documentation, Release 1.20.1.dev11

Use of this element will require ‘yum’ and ‘yum-utils’ to be installed on Ubuntu and Debian. Nothing additional is needed on Fedora or CentOS.

The DIB_OFFLINE or more specific pre-cached root filesystem tarball.

DIB_YUMCHROOT_USE_CACHE variables can be set to prefer the use of a

If you wish to have DHCP networking setup for eth0 & eth1 via /etc/sysconfig/network-config scripts/ifcfg-eth[0|1], set the environment variable

DIB_YUM_MINIMAL_CREATE_INTERFACES to

1

.

3.3.92 yum

Provide yum specific image building glue.

RHEL/Fedora/CentOS and other yum based distributions need specific yum customizations.

Customizations include caching of downloaded yum packages outside of the build chroot so that they can be reused by subsequent image builds. The cache increases image building speed when building multiple images, especially on slow connections. This is more effective than using an HTTP proxy as a yum cache since the same rpm from different mirrors is often requested.

Custom yum repository configurations can also be applied by defining DIB_YUM_REPO_CONF to a space separated list of repo configuration files. The files will be copied to /etc/yum.repos.d/ during the image build, and then removed at the end of the build. Each repo file should be named differently to avoid a filename collision.

3.3.93 zypper

This element provides some customizations for zypper based distributions like SLES and openSUSE. It works in a very similar way as the yum element does for yum based distributions.

Zypper is reconfigured so that it keeps downloaded packages cached outside of the build chroot so that they can be reused by subsequent image builds. The cache increases image building speed when building multiple images, especially on slow connections. This is more effective than using an HTTP proxy for caching packages since the download servers will often redirect clients to different mirrors.

3.4 Copyright

Copyright 2012 Hewlett-Packard Development Company, L.P.

Copyright (c) 2012 NTT DOCOMO, INC.

All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an

“AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the

License for the specific language governing permissions and limitations under the License.

56 Chapter 3. Table of Contents

Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement

Table of contents