Skip to main content

ENVIRONMENT VARIABLES

This reference covers the host-tool tacklebox builder, its embedded live baseline, and the QEMU smoke-test script. Build settings below do not configure purebuild or the browser builder; those use their own command-line or JavaScript options. Kernel arguments have their own section, because a shell variable that you export does not change the boot command line.

Host build settings​

Set these in the environment of the tacklebox process. With sudo, put the assignments after sudo so they reach the builder:

sudo env TBOX_CUSTOMIZE_COMMIT_TIMEOUT=1800 TBOX_CUSTOMIZE_CAPS=NET_ADMIN \
tacklebox build fixtures/iso-2env.json --iso out.iso
VariableAppliesTypeDefaultEffect and example value
TBOX_CUSTOMIZE_TIMEOUTBuild: live customizationNonnegative integer seconds0Bounds the script container with Podman's --timeout; 0 disables the inner deadline. Example: 1800. Invalid or negative values use the default.
TBOX_CUSTOMIZE_COMMIT_TIMEOUTBuild: customization commitNonnegative integer seconds600Bounds the subsequent podman commit; 0 disables this inner deadline. Example: 1800 for large writable layers. Invalid or negative values use the default.
TBOX_CUSTOMIZE_CAPSBuild: live customizationComma-separated capability namesNo extrasAdds --cap-add entries alongside the fixed SYS_ADMIN capability. Example: NET_ADMIN for Flatpak sandbox loopback setup. Whitespace and empty entries are ignored; Podman validates names.
TBOX_CUSTOMIZE_NETWORKBuild: customization and Remora preparationString: Podman network modePodman's defaultPasses --network to the container. Example: host when the default bridge cannot reach package servers.
TBOX_FLATPAK_PREINSTALLBuild: live baselineString switch1 inside the baselineOnly 0 skips the image's declared Flatpak preinstall.d step; other values allow it when Flatpak and declarations exist. Example: 0. Forwarded from the host into the customization container.
SUPERISO_COMPRESSIONBuild: squashfsString switchRecipe compression, otherwise fastExact value release forces release compression quality over the recipe. For zstd this selects level 15 and 1 MiB blocks instead of level 3 and 128 KiB blocks. Other values leave the recipe choice unchanged. Example: release.
TACKLEBOX_SQUASHFS_COMPRESSORBuild: squashfs, including offline storesString enumRecipe shared_store.compressor, otherwise zstdValid values zstd, xz, gzip, lz4, lzo override the recipe. Invalid values are ignored. Example: xz for a kernel without squashfs zstd support.
TACKLEBOX_OFFLINE_COPY_TIMEOUTBuild: offline image copyPositive integer seconds1800Bounds skopeo copy into the embedded store. Example: 3600. Invalid values fail the overlay-store copy; the VFS-store path falls back to the default. Zero does not disable the deadline.
TACKLEBOX_CONTEXTBuild/install: container commands; testsString enumRoot context when effective UID is 0root keeps container commands in the current context; user enables the legacy drop to SUDO_USER when set and not root. Other values use the UID default. Example: user when deliberately using the invoking user's image store. This setting does not grant privileges.

Customization runs only when the environment has live_customize scripts; the embedded baseline runs before those scripts. The script-container timeout and commit timeout are separate, and any outer job deadline still applies. Tacklebox keeps a cache of customization results: if you change only a variable, the build can reuse an existing derived image. The cache key includes TBOX_FLATPAK_PREINSTALL. See live customization.

Standard host variables also affect storage and subprocesses:

VariableAppliesTypeDefaultEffect and example value
TMPDIRBuild: temporary files and offline-store runrootsDirectory pathSystem temporary directory; /tmp for offline runrootsRedirects scratch space. Example: /var/tmp/tbox. Keep it short: Podman runroot paths have a 50-character limit.
SUDO_USERBuild/installUsernameSet by sudo, otherwise unsetIdentifies the original user for legacy user-context commands and ISO output ownership. Normally let sudo set it. Example: alice.
PATHBuild/installColon-separated directoriesInheritedLocates host tools; preserved when dropping to SUDO_USER. Example: /usr/local/bin:/usr/bin:/bin.
XDG_RUNTIME_DIRBuild/install subprocessesDirectory pathContainer tool's defaultPreserved across the user-context drop. Example: /run/user/1000.
XDG_DATA_HOMEBuild/install subprocessesDirectory pathContainer tool's defaultPreserved across the user-context drop for intentional storage redirection. Example: /var/tmp/alice-data.
CONTAINERS_STORAGE_CONFBuild/install subprocessesFile pathContainer tool's defaultPreserved across the user-context drop to select container storage configuration. Example: /home/alice/storage.conf.

Sources: customization, compression, offline stores, container context.

Settings inside the live image​

The embedded baseline reads these at build time, not at boot. The host builder does not forward TBOX_LIVE_USER or TBOX_DESKTOP. Set them in the source image's container environment (for example, a Containerfile ENV instruction). If you export them in a recipe script, the baseline has already run and does not see them.

VariableTypeDefaultEffectExample in a Containerfile
TBOX_LIVE_USERUsername stringliveuserSelects the passwordless live user and autologin account; a new account uses UID 1000.ENV TBOX_LIVE_USER=demo
TBOX_DESKTOPDesktop stringDetect KDE, niri, cosmic, or XFCE session files; otherwise GNOMEOverrides desktop detection for display-manager/autologin setup. Use gnome, kde, niri, cosmic, or xfce.ENV TBOX_DESKTOP=kde

Boot settings are kernel arguments​

TBOX_LIVE_OVERLAY_SIZE is not a supported environment variable in the current builder or initramfs. Use tacklebox.live.overlay.size=<MiB> on the kernel command line. Generated host-tool live ISO entries specify 8192 (8 GiB); the dracut module also defaults to 8192 when the argument is absent.

Kernel argumentTypeDefault / generated valueEffect and example
rootRoot selector stringGenerated for the mediaLive ISO: root=tbox:CDLABEL=TBOX_ISO selects the ISO by label; block media uses root=LABEL=TBOX_STORE.
tacklebox.live.dirRelative directoryLiveOSDirectory containing live squashfs files, e.g. tacklebox.live.dir=LiveOS.
tacklebox.live.squashimgFilenameModule fallback rootfs.sfs; builder selects per layoutSelects the root squashfs, e.g. tacklebox.live.squashimg=alpha.rootfs.sfs.
tacklebox.live.overlay.sizeInteger MiB8192Sizes the tmpfs for writable live overlay data, e.g. tacklebox.live.overlay.size=4096.
tacklebox.live.deltaFilenameUnsetAdds a delta squashfs as an overlay lower layer, e.g. tacklebox.live.delta=beta.delta.sfs. Generated for non-base delta environments.
tacklebox.rootRelative subtree pathGenerated for block and combined layouts; otherwise unsetPivots to the selected environment, e.g. tacklebox.root=tbox-install/alpha on block media or tacklebox.root=alpha for a combined ISO.
tacklebox.persistDevice selectorLABEL=TBOX_PERSIST for persistent block entries; otherwise unsetEnables shared home persistence, e.g. tacklebox.persist=LABEL=TBOX_PERSIST.
tacklebox.envEnvironment ID stringSelected live ISO environmentIdentifies the environment in the command line and serial log, e.g. tacklebox.env=alpha.

For a one-off overlay-size change, edit the existing argument in the boot menu entry before boot. Do not add a second argument with a different value. Recipes can supply additional kargs; see the user guide and the boot architecture. Generated arguments come from kernelcmdline; tbox-live-root.sh reads the live mount settings.

Boot smoke tests​

VariableAppliesTypeDefaultEffect / example
QEMU_LOGTest: scripts/test-boot.shFile pathqemu-boot.logSerial log destination. Use a separate filename for each boot: QEMU_LOG=alpha.log scripts/test-boot.sh out.iso 300.

The test timeout is the script's second positional argument (seconds), not an environment variable. See test-boot.sh.