Package: image-bootstrap
Table of ContentsAboutHistoryExample runSpeeding things upUsing RAM instead of HDD/SSDApt-Cacher NG -- a cache specific to Debian/UbuntuPolipo -- a generic HTTP cachehaveged -- an entropy generatorDebian packageUsage (--helpoutput)Hints on using image-bootstrap within a pipeKnown limitationsInstalling Debian wheezy to loop devicesInstalling to partition block devicesAboutWelcome to the home ofimage-bootstrap(and its little brotherdirectory-bootstrap).image-bootstrapis a command line tool to generate bootable virtual machine images
and write them to a givenblock device.Linux distributions supported byimage-bootstrapcurrently include:
Arch, Debian, Gentoo, Ubuntu.When passing the--openstackparameter, images areprepared for use with OpenStack.directory-bootstrapis a command line tool to install non-Debian Linux distributions
into a givendirectory(similar todebootstrapfor Debian/Ubuntu).Distributions supported bydirectory-bootstrapcurrently include:
Alpine Linux, Arch Linux, CentOS (up to 7.x), Gentoo, and Void Linux.Historyimage-bootstrapstarted out as a re-write ofgrml-debootstrap.
Primarily, it can be used to create Debian/Ubuntu or Arch images ready to be launched as a virtual machine.In comparision to grml-debootstrap, by nowimage-bootstrapinstalls to block devices only,supports several approaches to installing GRUB 2.x, or extlinux, or no bootloader at all,does not leak the host's hostname into the resulting image,supports passing the root password off the command-line
(and the eyes of other users and shell history),supports using a custom/etc/resolv.conffile
(e.g. to not leak your home router model name from/etc/resolv.confinto the image),has support for installing Arch Linux, Gentoo and Ubuntu (besides Debian),is able to createOpenStack images,is written in Python rather than Bash/mksh, andhas more friendly terminal output.directory-bootstrapcame into life with the arrival of support for Arch Linux.
Support for Gentoo followed, after.
Support for Void Linux and CentOS chroots came into live during 34c3, December 2017.
Support for Alpine Linux chroots came into in March 2018.Example runThe following is a complete demo of installing Debian jessie to LVM volume/dev/vg/lvand launching the resulting image using KVM.#${EDITOR}root_password.txt#sudoimage-bootstrap--hostnamejessiedebian\--password-fileroot_password.txt/dev/vg/lv_                          __             __      __(_)_ _  ___ ____ ____  ___ / /  ___  ___  / /____ / /________ ____/ /  ' \/ _ `/ _ `/ -_)/__// _ \/ _ \/ _ \/ __(_-</ __/ __/ _ `/ _ \/_/_/_/_/\_,_/\_, /\__/    /_.__/\___/\___/\__/___/\__/_/  \_,_/ .__//___/                      v0.9.1 :: 2015-07-11  /_/Software libre licensed under AGPL v3 or later.Brought to you by Sebastian Pipping <sebastian@pipping.org>.Please report bugs at https://github.com/hartwork/image-bootstrap.  Thank you!Selected approach "chroot-grub2-drive" for bootloader installation.Checking for blkid... /sbin/blkidChecking for chmod... /bin/chmodChecking for chroot... /usr/sbin/chrootChecking for cp... /bin/cpChecking for debootstrap... /usr/sbin/debootstrapChecking for find... /usr/bin/findChecking for kpartx... /sbin/kpartxChecking for mkdir... /bin/mkdirChecking for mkfs.ext4... /sbin/mkfs.ext4Checking for mount... /bin/mountChecking for parted... /sbin/partedChecking for partprobe... /sbin/partprobeChecking for rm... /bin/rmChecking for rmdir... /bin/rmdirChecking for sed... /bin/sedChecking for tune2fs... /sbin/tune2fsChecking for umount... /bin/umountChecking for uname... /bin/unameChecking for unshare... /usr/bin/unshareChecking for known unsupported architecture/machine combination...Checking if "/dev/vg/lv" is a block device...Reading root password from file "/home/user1/root_password.txt"...Unsharing Linux namespaces (mount, UTS/hostname)...Partitioning "/dev/vg/lv"...Activating partition devices...Creating file system on "/dev/mapper/vg-lvp1"...Creating directory "/mnt/tmpFczeFl"...Mounting partitions...Creating directory "/mnt/tmpFczeFl/etc"...Writing file "/mnt/tmpFczeFl/etc/hostname"...Writing file "/mnt/tmpFczeFl/etc/resolv.conf" (based on file "/etc/resolv.conf")...Bootstrapping Debian "jessie" into "/mnt/tmpFczeFl"...Writing file "/mnt/tmpFczeFl/etc/hostname"...Writing file "/mnt/tmpFczeFl/etc/resolv.conf" (based on file "/etc/resolv.conf")...Writing file "/mnt/tmpFczeFl/etc/fstab"...Writing file "/mnt/tmpFczeFl/etc/network/interfaces"...Running pre-chroot scripts...Mounting non-disk file systems...Setting root password...Writing device map to "/mnt/tmpFczeFl/boot/grub/device.map" (mapping "(hd9999)" to "/dev/dm-8")...Installing bootloader to device "/dev/vg/lv" (actually "/dev/dm-8", approach "chroot-grub2-drive")...Generating GRUB configuration...Post-processing GRUB config...Generating initramfs...Unmounting non-disk file systems...Cleaning chroot apt cache...Running post-chroot scripts...Unmounting partitions...Removing directory "/mnt/tmpFczeFl"...Deactivating partition devices...Done.#sudokvm-hda/dev/vg/lvWithout--color never, the output above is actually in color.Speeding things upUsing RAM instead of HDD/SSDIf you runimage-bootstraprepeatedly and have enough RAM, you may want to
create images on RAM storage rather than on disk.  I use a setup witha loop device (to have a block device)over a sparse file (to save space)in a tmpfs mount (to use RAM).For example (assuming you have /tmp in RAM already):#sudomount-oremout,size=6g/tmp#truncate--size3g/tmp/disk3g#LOOP_DEVICE="$(losetup--show-f/tmp/disk3g)"#image-bootstrap....arch..."${LOOP_DEVICE}"#qemu-imgconvert-p-fraw-Oqcow2"${LOOP_DEVICE}"/var/lib/arch-$(date-I).qcow2#losetup-d"${LOOP_DEVICE}"#rm/tmp/disk3gApt-Cacher NG -- a cache specific to Debian/UbuntuWhen creating multiple images,
a local instance ofApt-Cacher NGand
passing--mirror http://localhost:3142/debiantoimage-bootstrapmay come in handy.Polipo -- a generic HTTP cacheFor a distribution-agnostic cache, usingPolipocan greatly speed up consecutive runs.
Invokeimage-bootstrapwith#http_proxy=http://127.0.0.1:8123/image-bootstrap...when using Polipo with default port configuration.haveged -- an entropy generatorDuring image creation, cryptographic keys may need to be generated, e.g.
for the OpenSSH server, at least temporarily.  As key generation relies
on availability of entropy, image creation may take longer in environments that
are slow at adding to the entropy pool.
To speed things up, runninghavegedat the host systemcouldbe an option, especially since all keys should be deleted
from images, eventually. Otherwise, there is a risk of ending up with multiple
systems having the same key allowing for attacks.
I am unsure of the quality of entropy that haveged produces.  Use is at your own risk.Debian packageAs long asimage-bootstrapas not availableinDebian, you can
make animage-bootstrapDebian package yourself easily from Git as follows:#gitclonehttps://github.com/hartwork/image-bootstrap.gitCloning into 'image-bootstrap'...[..]#make-Cimage-bootstrap/deb[..]#ls*.debimage-bootstrap_0.9.1_all.deb#sudodpkg-iimage-bootstrap_0.9.1_all.deb[..]Usage (--helpoutput)In general, the usage is:image-bootstrap [..] DISTRIBUTION [..] DEVICEorimage-bootstrap --hostname NAME [DISTRO_AGNOSTIC] DISTRIBUTION [DISTRO_SPECIFIC] DEVICEin a bit more detail.A dump of the current--helpoutput would be:#image-bootstrap--helpusage: image-bootstrap [-h] [--version] [--color {never,always,auto}][--debug] [--quiet] [--verbose] [--arch ARCHITECTURE][--bootloader {auto,chroot-grub2-device,chroot-grub2-drive,host-extlinux,host-grub2-device,host-grub2-drive,none}][--bootloader-force] [--hostname NAME] [--openstack][--password PASSWORD | --password-file FILE][--resolv-conf FILE] [--disk-id ID][--first-partition-uuid UUID] [--machine-id ID][--scripts-pre DIRECTORY] [--scripts-chroot DIRECTORY][--scripts-post DIRECTORY] [--grub2-install COMMAND][--cache-dir DIRECTORY]DISTRIBUTION ... DEVICECommand line tool for creating bootable virtual machine imagespositional arguments:DEVICE                block device to install tooptional arguments:-h, --help            show this help message and exit--version             show program's version number and exittext output configuration:--color {never,always,auto}toggle output color (default: auto)--debug               enable debugging--quiet               limit output to error messages--verbose             increase verbositymachine configuration:--arch ARCHITECTURE   architecture (e.g. amd64)--bootloader {auto,chroot-grub2-device,chroot-grub2-drive,host-extlinux,host-grub2-device,host-grub2-drive,none}approach to take during bootloader installation(default: auto)--bootloader-force    apply more force when installing bootloader (default:disabled)--hostname NAME       hostname to set (default: "machine")--openstack           prepare for use with OpenStack (default: disabled)--password PASSWORD   root password to set (default: password log-indisabled)--password-file FILE  file to read root password from (default: passwordlog-in disabled)--resolv-conf FILE    file to copy nameserver entries from (default:/etc/resolv.conf)--disk-id ID          specific disk identifier to apply, e.g. 0x12345678--first-partition-uuid UUIDspecific UUID to apply to first partition, e.g.c1b9d5a2-f162-11cf-9ece-0020afc76f16--machine-id ID       specific machine identifier to apply, e.g.c1b9d5a2f16211cf9ece0020afc76f16script integration:--scripts-pre DIRECTORYscripts to run prior to chrooting phase, inalphabetical order--scripts-chroot DIRECTORYscripts to run during chrooting phase, in alphabeticalorder--scripts-post DIRECTORYscripts to run after chrooting phase, in alphabeticalordercommand names:--grub2-install COMMANDoverride grub2-install commandgeneral configuration:--cache-dir DIRECTORYdirectory to use for downloads (default:/var/cache/directory-bootstrap/)subcommands (choice of distribution):Run "image-bootstrap DISTRIBUTION --help" for details on options specific to that distribution.DISTRIBUTION          choice of distribution, pick from:arch                Arch Linuxdebian              Debian GNU/Linuxgentoo              Gentooubuntu              Ubuntu_                          __             __      __(_)_ _  ___ ____ ____  ___ / /  ___  ___  / /____ / /________ ____/ /  ' \/ _ `/ _ `/ -_)/__// _ \/ _ \/ _ \/ __(_-</ __/ __/ _ `/ _ \/_/_/_/_/\_,_/\_, /\__/    /_.__/\___/\___/\__/___/\__/_/  \_,_/ .__//___/                      v2.0.0 :: 2020-02-28  /_/Software libre licensed under AGPL v3 or later.Brought to you by Sebastian Pipping <sebastian@pipping.org>.Please report bugs at https://github.com/hartwork/image-bootstrap.  Thank you!To show options specific to Debian, run ..#image-bootstrapdebian--helpusage: image-bootstrap debian [-h] [--debootstrap COMMAND] [--release RELEASE][--mirror URL] [--debootstrap-opt OPTION]optional arguments:-h, --help            show this help message and exit--release RELEASE     specify Debian release (default: jessie)--mirror URL          specify Debian mirror to use (e.g.http://localhost:3142/debian for a local instance ofapt-cacher-ng; default:http://httpredir.debian.org/debian)--debootstrap-opt OPTIONoption to pass to debootstrap, in addition; can bepassed several times; use with --debootstrap-opt=...syntax, i.e. with "="command names:--debootstrap COMMANDoverride debootstrap commandHints on using image-bootstrap within a pipeIf you want to runimage-bootstrapin a pipe to capture its output to bothstdout/stderrto a single log file, be sure to runimage-bootstrapin
unbuffered mode, e.g.:python -u image-bootstrap [OPTIONS] 2>&1 | tee my.logThe default shebang generated by python setuptools does not use-u. It's also
not easily possible to have it pass-usince theenvcommand does allow for
for passing command parameters only in fairly recent versions. As a consequence,stdout/stderrwon't be synchronized and error output you see in a log file
will not exactly correspond to preceding/succeeding output onstdout. (Seeissue #71for more details.)Moreover, if you're using Bash and you need to keep track ofimage-bootstrap's exit code, be sure to runset -o pipefailprior to
invokingimage-bootstrap.
(Please see thePipelinessection of theGNU Bash Reference Manualfor more details.)Known limitationsInstalling Debianwheezyto loop devicesGRUB 1.99 has trouble installing to loop devices.
As a result, usingimage-bootstrapto install e.g. Debianwheezyto a loop device
requires. bootloader approachhost-grub2-deviceorhost-grub2-driveand. a more recent version of GRUB 2.x on the system runningimage-bootstrap.Installing to partition block devicesLinux does not like partitions in partitions much.
It can be tricked using device mapper, though.This is how to install to a partition using another partition as a temporary target.
The temporary target mustbe 2 GiB in space or more (to hold the whole distribution) andsmaller or equal than the actualy target (for the later copy to work).#dmsetupcreatedm-linear-vda4--table"0$(blockdev--getsz/dev/vda4)linear /dev/vda4 0"#image-bootstrap--openstackarch/dev/mapper/dm-linear-vda4#partprobe/dev/mapper/dm-linear-vda4#pv/dev/mapper/dm-linear-vda4p1>/dev/vda2#dmsetupremovedm-linear-vda4p1#dmsetupremovedm-linear-vda4(/dev/vda2is the real target,/dev/vda4the temporary one.)There are other ways to achieve the same.