build-open...bian-image(1)

🎀 NAME 🎀

build-openstack-debian-image — bestie, it builds a Debian image that you can use with OpenStack. That's it, that's the job. ✨

Oh also, hi, this is the section 1 page from the General Commands Manual, and the command is literally called build-openstack-debian-image. 💅

---

🌸 SYNOPSIS 🌸

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

---

🦋 DESCRIPTION 🦋

Okay so the build-openstack-debian-image shell script builds you a Debian image that you can use in an OpenStack IaaS cloud. Iconic. The resulting images (Qcow2 and raw) contain initramfs-growroot, so the root partition gets resized — during the initramfs phase, before mounting anything — to match the flavor you picked when you use "nova boot". Then later on during the boot process, cloud-init resizes the root partition on the fly. (That resize happens while the partition is already mounted read-write, since recent kernels allow that for ext3. slay.)

Cloud-init is set up to use an Ec2 metadata server, which is what OpenStack is compatible with. A "debian" user (you can change this with the --login option) is the one who receives the ssh key from the user data blob. This user is set up without a password (like, adduser --disabled-password energy). Once you're logged in as this "debian" user on your brand new virtual machine, you can "sudo" to root from that user, no password needed. The root password is "password" by default, and ssh-ing into the root user without 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. Right now only 5 values are possible: wheezy or jessie or stretch or buster or bullseye.

Not me warning you about this one: 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,... — pick the PACKAGE(s) you wanna add to the image. The default is: bash-completion,joe,most,screen,less,vim,bzip2. Heads up though: this list of extra packages isn't used if you use the --minimal option. 🙈
• --debootstrap-url, -u <debootstrap-debian-mirror> — choose the URL of the Debian mirror used to perform the debootstrap. For example: http://ftp.fr.debian.org/debian
• --debootstrap-keyring-file, -k <path-to-keyring> — use the keyring file you specify here, and not the official debian archive keyring, when verifying packages. Super useful when you're using an unofficial package repository (e.g. a self-hosted aptly).
• --copy-debootstrap-keyring-file — copies the keyring file you specified with --debootstrap-keyring-file into /etc/apt/trusted.gpg.d and /usr/share/keyrings in the generated image. Note that the preferred way to install and manage a keyring is to install it as a package using --extra-packages. 🗝️
• --boot-manager, -bm <grub|syslinux> — choose what type of boot manager to use inside the image. The default is Grub, but you can also decide to use syslinux if you prefer.
• --boot-type, -bt <mbr|uefi> — choose 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> — choose the architecture to target for the output image. This will not cross build for that architecture, it'll just pick the right architecture-specific components. Supported options are "amd64" and "arm64"; "amd64" is the default.
• --sources.list-mirror, -s <source-list-mirror> — the URL to use when building the sources.list inside the chroot. If you omit this option, 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 set up 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> — choose the image size (defaults 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 first be 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> — the size of the supplementary space added to the partition after it's 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 is debian) for the user created by Cloud-Init.
• --password, -p <root-password> — defines a default root password for your image.

⚠️ Bestie, this option is dangerous. First because it will show the root password to the user of the computer building the image if using "ps", and then also because it's 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> — set up the OpenStack extrepo repository. This is mainly useful when the --octavia-agent option is used, so the unofficial OpenStack backports repositories can be used to set up 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 the image.
• --default-editor </bin/nano, /usr/bin/joe, /usr/bin/vi> — set the 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 variables 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's 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 thing 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>. Absolute legends, no cap. 💜

---

And that's the whole page, bestie! 🎀 This was build-open...bian-image(1) from the General Commands Manual — go build something cute. 🦋🌸✨