os-builder/docs/config.md

Config

build.sh sources the file config in the current working directory at startup. It can also be specified explicitly:

sudo ./build.sh -c build_amd64

Variables

Core

• IMG_NAME (Default: vesperos-$RELEASE-$ARCH)

  Base name for output files.

• RELEASE (Default: trixie)

  Debian release to build against.

• ARCH (Default: arm64)

  Target architecture. One of: arm64, armhf, amd64.

Directories

• WORK_DIR (Default: $BASE_DIR/work)

  Where stage rootfs directories are built. Should be on a Linux filesystem — NTFS will not work.

• DEPLOY_DIR (Default: $BASE_DIR/deploy)

  Where finished images and archives are placed.

Network / SSH

• ENABLE_SSH (Default: 0)

  Set to 1 to enable the SSH server in the built image.

• PUBKEY_SSH_FIRST_USER (Default: unset)

  If set, written to ~/.ssh/authorized_keys for the first user.

• PUBKEY_ONLY_SSH (Default: 0)

  Set to 1 to disable password auth and require public key auth for SSH.

• APT_PROXY (Default: unset)

  Apt proxy URL (e.g. http://192.168.1.1:3142). Not included in the final image.

• TEMP_REPO (Default: unset)

  Additional temporary apt repo used only during the build. Supports RELEASE substitution.

Locale / Keyboard

• LOCALE_DEFAULT (Default: en_US.UTF-8)

• KEYBOARD_KEYMAP (Default: en)

• KEYBOARD_LAYOUT (Default: English (US))

• TIMEZONE_DEFAULT (Default: America/Los Angeles)

Cloud-init

• ENABLE_CLOUD_INIT (Default: 1)

  Set to 1 to install and configure cloud-init. On RPi, seed files go to /boot/firmware/. On amd64, they go to /var/lib/cloud/seed/nocloud/.

Other

• USE_QEMU (Default: 0)

  Set to 1 to produce a QEMU-compatible image (adds -qemu suffix).

• SETFCAP (Default: unset)

  Set to 1 to preserve Linux capabilities in the rootfs. Only needed for NFS or capability-sensitive deployments.

• STAGE_LIST (Default: stage*)

  Override the list of stages to run. Example: "stage0 stage1 mystage stage2".

• EXPORTS (Default: unset)

  Space-separated list of stage:type pairs declaring what to export and from which stage. Supported types: squashfs, img, noobs. Example:

  EXPORTS="stage3:squashfs"
  EXPORTS="stage3:squashfs stage2:img"
  

Live boot (squashfs only)

• LIVEBOOT (Default: 0)

  Set to 1 to produce a second -live squashfs alongside the raw one. Installs live-boot, configures GDM autologin, and rebuilds the initramfs. Only applies to amd64.

• LIVE_USERNAME (Default: vesperos)

• LIVE_USER_FULLNAME (Default: Live User)

• LIVE_USER_PASSWORD (Default: vesperos)

NOOBS

• NOOBS_NAME — Display name shown in the NOOBS menu.

• NOOBS_DESCRIPTION — Short description shown in the NOOBS menu.

  Both must be set in the config when using noobs in EXPORTS.

Example Config Files

amd64 with live boot

ARCH='amd64'
EXPORTS="stage3:squashfs"
DEPLOY_COMPRESSION="none"
LIVEBOOT=1
LIVE_USERNAME="vesper"
LIVE_USER_PASSWORD="vesper"

Raspberry Pi (arm64)

ARCH='arm64'
EXPORTS="stage3:squashfs"
DEPLOY_COMPRESSION="none"
ENABLE_CLOUD_INIT=1