blast

Blast is the boring linux automatic setup tool. The name is supposed to be an innuendo to YaST, but well... I suppose it sounded better in my head ;-)

Blast can be used to build Debian system images for various targets including Raspberry Pi, live-media, and regular system installations. It is based on GNU Make and debootstrap. It will setup wireless networking, SSH access, and user accounts and it includes modules for preseeding various software configuration options. All configuration options for a system image can be set within a single make file.

Deployment

There is no real installation proces involved, because blast is just a bunch of Make files. To use it you have to check out the source repository:

~$ git clone https://git.plutz.net/git/blast

Depending on what systems you want to build you may also need some additional tools to run blast. Here is the debian packages you should install on the host system:

• make - GNU make, the script interpreter
• debootstrap - used for bootstrapping debian installations
• qemu-user-static, binfmt-support - needed for running raspberry pi arm binaries during raspi installation
• btrfs-tools - recommended because it allows quick reuse of cached root environments. You should also build on a btrfs filesystem. Using btrfs is not required though (unless you are building a subvol target).
• squashfs-tools - required for building squash and iso targets (live CDs)
• fdisk, dosfstools - for building disk images and setting up boot partiotion (uses sfdisk and mkfs.fat)
• xorriso - used in conjunction with grub-mkrescue to create live images
• grub-pc-bin, grub-efi-amd64-bin, grub-efi-ia32-bin - grub bootloader payloads for various image types
• syslinux - optional, required for image and disk targets
• openssl - required for writing encrypted default passwords

Usage

A host configuration is written as a Make file. The repository contains a file named config.example to get you started. The main Makefile should not be edited. Once you have set up a system configuration, e.g. host.mk you can start the build process by running

~$ sudo make config=host.mk

The build process needs to be run as root user. This is because we will set up and mount disk images, use debootstrap, chroot into the system environment etc. Employ security measures at your discretion.

Config options

Options that can be used in the make file are:

Choosing the target: iso= subvol= squash= raspi= image=

By setting one, and only one of the following options, you can choose a system type:

• iso=[filename].iso

  will build a hybrid live image that can be written to CD, DVD or USB Media. The image is bootable via Legacy PC boot, 32bit EFI, and 64bit EFI. It will boot when burned to cdrom (El-Torito boot standard), as well as from HDD-like media like USB thumbdrives, external HDD, or internal HDDs. If you want the image to be bootable on 32bit PCs, ARCH must be set to i386 (see below).

• raspi=[filename].img

  will build a raspberry pi image from raspbian and debian repos. The image can be written to an SD-Card to be run directly on a Raspberry Pi. This is very useful for environments where you don't want to attach a keyboard and screen to your Raspi, because the image can include a network configuration (including WPA2 wireless) and login credentials.

• subvol=[directory]

  will build a system installation into a btrfs subvolume. The directory path must not previously exist and the path must point to a btrfs filesystem. In this mode a bootloader will not be installed. You will need to install one manually after the installation. Obviously the filesystem needs to be prepared beforehand. This is still useful to set automatic config options, preseed user accounts, install software from a list, etc.

• squash=[filename].squash

  will build a squashfs image. Squashfs is a compressed file system, that is used on live media. If you want to build a cd image you may want to use the iso= target instead (which will also contain a squashfs image). The bare squash image can be used in PXE environments. In this case you need to provide the bootloader, pxe environment, etc.. yourself.]

• image=[filename].img

  will build a HDD image for deployment on PCs. It will install Bootloaders for 32bit EFI (grub), 64bit EFI (grub) and Legacy PC boot (syslinux). The way the bootloader is deployed is not well integrated into debian and it may break when the system is updated. This installation mode is not well tested and may not work as expected.

• disk=/dev/sdX

  Dangerous! Use only in developer environments! This works similarly to the image= target but will install a system directly to a hard disk. It will set up a clean partition table and erase all data on the disk in the process. The development is neglecteda, and it may not work as expected. Be careful when using it!

imagesize=...

Only applies when building a raspi= or image= target. This defaults to 1GB. The image should be large enough to fit all the software you want to install. The image does not need to fill your target medium, and should in fact be no larger than necessary. You can use the autoresize module (see below) to expand an installation to fill its available disk space once the medium is booted for the first time.

ARCH=...

One of the architectures available in the debian repos. Default is amd64, which is usually what you want. If you are builing a Raspberry Pi target it is always armhf, regardless of what you choose. The most common case where you need to change this would be when builing for i386. If the target platform is incompatible with your host playform, you will need one of the qemu-*-static binaries to run the installation. qemu-arm-static will be used automatically when builing for Raspberry Pi.

release=...

The Debian release you want to install. Still defaults to stretch, so you may want to change this. There is currently a bug in the Debian package scripts for buster, which requires you to restart the make process after the first crash. The Debian installer will crash during the udev installation, once it realises that it runs in a change root environment. If you start blast a second time, it will deploy a workaround and continue the installation. This is a bug in the Debian udev installer scripts. Debian bullseye and sid are not thoroughly tested but should work as well.

packages+=...

Probably the most important option. Takes a list of debian packages you want to install within the system image. This will be added to a list of default packages, and packages installed by various modules. Package names may be separated by whitespace or comma. You can write this list packages = but I recommand using the packages += syntax so you can prepare multiple lines which will be appended to one another.

modules=

Comma separated list of modules from the modules/ directory. Modules can contain configuration and setup commands for various use cases. Including a module may enable addisional options for the make file. See the modules documentation below.

hostname=

The hostname of the target system. A machine will request this as network name and display it in various places like the login dialog, shell prompt, etc. Set this to something you recognize. Use blast, live, or raspi if you cannot think of anything better. You can choose computer names among names from Movies, TV Shows, Rock Bands, Chemical Elements, Greek deities, Spices, Countries, etc. It is up to you.

rootpass=

The root password for the system. If you leave this unset, the root user may not login via password. Other methods of login will still be available. You can use this if you are lazy, but of course the password will appear in plain text in the configuration file. The root password will be automatically hashed using the openssl utility. Note that in the default Debian configuration the root password cannot be used to login via SSH.

rootkey=[filename]

A more secure way of providing root credentials. This is a filename of a ssh public key without the .pub file ending. If the file does not exist a key pair will be generated, with the private key in the given file, and the public key in corresponding .pub file. The public key will be deployed to the target system to provide root login.

users=...

Comma separated list of user names. A regular (unpriviliged) user account will be created for each user name. The login password will be empty by default. This enables users to login by just pressing the enter key, when prompted for a password. Users can (and should!) set their own password after logging in for the first time. When building a grephical desktop system I recommend including the usermode package, so that users have a graphical tool for changing their login password. Note that SSH refuses to accept empty login passwords in the default configuration.

wifi= wifipass=

Default wifi network and password. If the password is omitted, the system will try to connect to an unencrypted wifi network. With the password set, it will try to connect to a WPA/WPA2 encrypted network. WEP is not supported. The network configuration will be applied using the ifupdown and wireless-tools. Beware that, if the network-manager is installed it may interfere with these settings.

timezone=

Default time zone, e.g. Europe/Berlin. Defaults to UTC if not set.

locales=

Comma separated list of locales, which will be included. The first will be used as the default locale. E.g. de_DE.UTF-8

keyboard=

default keyboard layout, e.g. German, defaults to US, if not set.

Modules

Modules can contain configuration and setup commands for various use cases. Including a module may enable addisional options for the make file. Modules are enabled by through the modules= option.

approx

Perform the installation from an Apt-proxy. After the installation is completed the clients apt configuration will be reset to use the regular debian sources. Adds the option approx=.

• Example

  approx=http://localhost:9000/debian

autoresize

Adds a script that will resize the clients root file system during the first boot. Useful for RaspberryPi SD-card images.

live

...to be written

nodm

Sets up nodm as a login manager, i.e. enable autologin.

Options:

• nodm_user=

  User that will be logged in at startup

• code.webui=

  URL of a web interface. If this option is set, nodm will not start a desktop environment, but will launch a chromium web browser in fullscreen mode pointing to this domain. Useful for embedded devices.

xfce

Recommended for desktop environments. Sets up a default XFCE desktop environment with a preconfigured desktop bar at the bottom of the screen, consistent theme settings across GTK / QT applications, etc.

gimp

Regular Gimp installation with some UI presets like single window mode, etc.

display_wsLCD4

Include and enable driver for Waveshare 4 inch touch display (480x320, connected via GPIO). May work with 3.5inch variant as well.

display_ws5inch

Include and enable driver for Waveshare 5 inch touch display (800x420, connected via HDMI).