Ubuntu Manpage: build-openstack-debian-image - build a Debian image to be used with OpenStack

name
synopsis
description
parameters
options
example
authors

oracular (1) build-openstack-debian-image.1.gz

Provided by: openstack-debian-images_1.84_amd64

NAME

       build-openstack-debian-image - build a Debian image to be used with OpenStack

SYNOPSIS

       build-openstack-debian-image --release|-r <wheezy|jessie|stretch|buster|bullseye> [ OPTIONS ]

DESCRIPTION

       The build-openstack-debian-image shell script will build a Debian image which can be used in an OpenStack
       IaaS cloud. The resulting (Qcow2 and raw images) contains initramfs-growroot so that the  root  partition
       will  be  resized (during the initramfs phase, before mouting anything) to match the flavor selected when
       using "nova boot". Later on during the boot process, cloud-init will resize the root partition on the fly
       (resize is performed when the partition is already mounted read-write, since recent kernel allow that for
       ext3).

       Cloud-init is setup to use an Ec2 metadata server, which is what OpenStack is compatible with. A "debian"
       (configurable  with the use of the --login option) user will be used to receive the ssh key from the user
       data blob.  This user is setup without a password (eg: adduser --disabled-password).  Once logged as this
       "debian"  user  in  your  new  virtual  machine, you can "sudo" to root from that user, without needing a
       password. The root password is "password" by default, and ssh into the root user  without  using  an  ssh
       keypair is disabled by default (PermitRootLogin without-password is set in /etc/ssh/sshd_config).

PARAMETERS

       --release|-r wheezy|jessie|stretch|buster|bullseye

              Sets  the  release  name  to be installed. Currently only 5 values a possible: wheezy or jessie or
              stretch or buster or bullseye.

              At the time of writing, bullseye is only here to prepare the future, and will not  work  until  it
              effectively becomes the new testing.

OPTIONS

--extra-packages|-e PACKAGE,PACKAGE,...

Select the PACKAGE you want to add to the image default is: bash-
completion,joe,most,screen,less,vim,bzip2 Note that this list of extra packages isn't used if you
use the --minimal option.

--debootstrap-url|-u <debootstrap-debian-mirror>

Select the URL of the Debian mirror to use to perform the debootstrap. For example:
http://ftp.fr.debian.org/debian

--debootstrap-keyring-file|-k <path-to-keyring>

Use the specified keyring file, and not the official debian archive keyring, when verifying
packages. This is useful when using an unofficial package repository (e.g. a self-hosted aptly)

--copy-debootstrap-keyring-file

Copy the keyring file specified by --debootstrap-keyring-file into /etc/apt/trusted.gpg.d and
/usr/share/keyrings in the generated image. Note that the prefered way to install and manage a
keyring is to install it as a package using --extra-packages.

--boot-manager|-bm <grub|syslinux>

Select what type of boot manager to use inside the image. The default is Grub, but you can as well
decide to use syslinux if you prefer.

--boot-type|-bt <mbr|uefi>

Select how to boot the image: using legacy MBR-style (aka BIOS or CSM) boot, or UEFI. The default
is mbr. Selecting uefi requires the use of Grub as the boot manager, and will set up an extra EFI
System Partition inside the image to support UEFI boot.

--architecture|- <amd64|arm64>

Select the architecture to target for the output image. This will not cross build for that
architecture, but will pick the right architecture-specific components. Supported options are
"amd64" and "arm64"; "amd64" is default.

--sources.list-mirror|-s <source-list-mirror>

URL to use when building the sources.list inside the chroot. If this option is omitted, then the
global httpredir.debian.org redirector is used. For example, you can use:
http://ftp.fr.debian.org/debian

--minimal

Without this option, the following packages will also be installed: bash-completion (and
/etc/bash.bashrc will be setup to use bash-completion), joe (the text editor), most, GNU screen,
less and vim. If you believe that more things should be added in the non-minimal image,
suggestions are welcome.

--azure|-az

Build an image for the Microsoft Azure cloud. Note that this option is incompatible with the
--automatic-resize|-ar option, which will be ignored.

--image-size|-is <image-size>

Select the image size (default to 2 GBytes if this option is omitted). Only useful if you need to
use a custom script hook (see below).

--automatic-resize|-ar

Reduce the image to the minimum HDD size possible. The partition of the image will be first
shrinked with resize2fs -M, then the space it takes will be used to do a 2nd resize2fs adding a
bit of extra space for the operating system to write runtime data (see below). Since this option
takes a lot of time, it is disabled by default.

--automatic-resize-space|-ars <supplementary-space>

Size of the supplementary space added to the partition after it is resized to the minimum. If this
option is omitted, then 50G is used. If --automatic-resize isn't used, then it is useless to set
this option, which will be ignored.

--login|-l <user-login>

Change the login name (default to debian) for the user created by Cloud-Init.

--password|-p <root-password>

Defines a default root password for your image. This option is dangerous, first because it will
show the root password to the user of the computer building the image if using "ps", then also
because it is best to not set a default root password at all if possible. However, this option is
still there, because sometimes, you need to be able to debug your image, and login through the web
console of horizon. In a production environment, do not use this option.

--octavia-agent

Install the Octavia agent in order to build an Octavia Amphorae image, that will be used for HA
proxy based Load Balancer as a Service.

--manila-agent

Install the Manila agent in order to build OpenStack Manila share image.

--trove-agent

Install the Trove agent in order to build the OpenStack Trove image.

--extrepo <openstack-release>

Setup the OpenStack extrepo repository. This is mainly useful when the --octavia-agent option is
use, so the unofficial OpenStack backports repositories can be used to setup the agent.

--kernel-from-backports <yes/no>

If set to yes, install the kernel from official Debian backports.

--editor <nano,vim>

List of editors to install in image.

--default-editor </bin/nano, /usr/bin/joe, /usr/bin/vi>

Set default alternative editor

--hook-script|-hs <hook-script>

If you wish to further customize the generated cloud image, you can use a hook script. When
called, build-openstack-debian-image will fill up some BODI_* environment variable for the hook
script to use as per below:

BODI_CHROOT_PATH path where the image is mounted

BODI_RELEASE name of the Debian release that is being bootstraped

--newer-qemu

Do not use the -o compat=0.10 option when converting to raw, and also, use -p -W -m 8 (ie: multi-
thread + progress indicator convert).

EXAMPLE

              Here is an example with the short parameter names:

       build-openstack-debian-image  -u http://ftp.fr.debian.org/debian -s http://ftp.fr.debian.org/debian -is 5
       -e libapache2-mod-php5 -hs ~/customize-my-image -ar -ars 100

              And the same but with long names for options:

       build-openstack-debian-image  --debootstrap-url   http://ftp.fr.debian.org/debian   --sources.list-mirror
       http://ftp.fr.debian.org/debian   --image-size   5   --extra-packages  libapache2-mod-php5  --hook-script
       ~/customize-my-image --automatic-resize --automatic-resize-space 100

AUTHORS

       build-openstack-debian-image has been written by Thomas  Goirand  <zigo@debian.org>,  with  contributions
       from Mehdi Abaakouk <sileht@sileht.net>.

                                                                                 build-openstack-debian-image(1)