.TH build\-openstack\-debian\-image 1
.SH NAME
build\-openstack\-debian\-image \- build a Debian image to be used with OpenStack
.SH SYNOPSIS
.B build\-openstack\-debian\-image
.B \-\-release|\-r <wheezy|jessie|stretch|buster|bullseye>
[ OPTIONS ]

.SH DESCRIPTION
.LP
The
.I 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
.B --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).

.SH "PARAMETERS"

.LP
.B \-\-release|\-r
.I wheezy|jessie|stretch|buster|bullseye
.IP

Sets the
.I release
name to be installed. Currently only 5 values a possible:
.I wheezy
or
.I jessie
or
.I stretch
or
.I buster
or
.I 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.

.SH "OPTIONS"

.LP
.B \-\-extra\-packages|\-e 
.I PACKAGE,PACKAGE,...
.IP

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

.LP
.B \-\-debootstrap\-url|\-u
.I <debootstrap\-debian\-mirror>
.IP

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

.LP
.B \-\-debootstrap\-keyring\-file|\-k
.I <path-to-keyring>
.IP

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)

.LP
.B \-\-copy\-debootstrap\-keyring\-file
.IP

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.

.LP
.B \-\-boot-manager|\-bm
.I <grub|syslinux>
.IP

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.

.LP
.B \-\-boot-type|\-bt
.I <mbr|uefi>
.IP

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.

.LP
.B \-\-architecture|\-
.I <amd64|arm64>
.IP

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.

.LP
.B \-\-sources.list\-mirror|\-s
.I <source\-list\-mirror>
.IP

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:
.I http://ftp.fr.debian.org/debian

.LP
.B \-\-minimal
.IP

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.

.LP
.B \-\-azure|\-az
.IP

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

.LP
.B \-\-image-size|\-is
.I <image\-size>
.IP

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

.LP
.B \-\-automatic-resize|\-ar
.IP

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.

.LP
.B \-\-automatic\-resize\-space|\-ars
.I <supplementary-space>
.IP

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
.B \-\-automatic-resize
isn't used, then it is useless to set this option, which will be ignored.

.LP
.B \-\-login|\-l
.I <user-login>
.IP

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

.LP
.B \-\-password|\-p
.I <root-password>
.IP

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.

.LP
.B \-\-octavia\-agent
.IP

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.

.LP
.B \-\-manila\-agent
.IP

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

.LP
.B \-\-trove\-agent
.IP

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

.LP
.B \-\-extrepo
.I <openstack-release>
.IP

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

.LP
.B \-\-kernel\-from\-backports
.I <yes/no>
.IP

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

.LP
.B \-\-editor
.I <nano,vim>
.IP

List of editors to install in image.

.LP
.B \-\-default\-editor
.I </bin/nano, /usr/bin/joe, /usr/bin/vi>
.IP 

Set default alternative editor

.LP
.B \-\-hook\-script|\-hs
.I <hook-script>
.IP

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:

.B BODI_CHROOT_PATH
path where the image is mounted

.B BODI_RELEASE
name of the Debian release that is being bootstraped

.LP
.B \-\-newer\-qemu
.IP

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

.SH EXAMPLE
.IP

.IP
Here is an example with the short parameter names:

.LP
.I 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

.IP
And the same but with long names for options:

.LP
.I 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

.SH AUTHORS

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