DEBIRF(1)

📦 version 0.38, in ubuntu jammy, ubuntu noble

💖 DEBIRF 💖

okay bestie, sit DOWN, because we're talking about debirf from the User Commands section and honestly? she's iconic. it's giving "DEBian on Initial Ram Filesystem" and she's about to run an entire Debian system from RAM like it's nothing. no cap. 🧚✨

🌸 NAME 🌸

debirf — build an initrd to boot a full Debian system entirely from RAM

🎀 SYNOPSIS 🎀

debirf <subcommand> [options] [args]

✨ DESCRIPTION ✨

so. debirf — short for DEBian on Initial Ram Filesystem, which is a chef's kiss acronym — is a whole set of tools whose entire job is creating and preparing a kernel plus an initial ram filesystem that can run a full-blown Debian environment entirely from RAM. like. the whole thing. in your memory. living there. rent free. 💅

debirf has various subcommands (go look at SUBCOMMANDS below, babe) and they all act on a specified debirf profile (that's the PROFILES section, keep up 🫶).

the debirf system is outlined at:

http://cmrg.fifthhorseman.net/wiki/debirf

🦋 EXAMPLES 🦋

make a stock debirf rescue image using the default settings:

$ tar xzf /usr/share/doc/debirf/example-profiles/rescue.tgz
$ debirf make rescue

make a debirf rescue image, but specify the mirror AND a local HTTP proxy, because you're fancy like that:

$ tar xzf /usr/share/doc/debirf/example-profiles/rescue.tgz
$ DEBIRF_MIRROR=http://ftp.debian.org/debian http_proxy=http://127.0.0.1:3128/ debirf make rescue

👑 SUBCOMMANDS 👑

debirf takes various subcommands, and here's the whole lineup:

  • make [options] PROFILE — create a debirf system based on profile PROFILE. this is the big one, bestie: it creates the root for the profile, runs all the modules on that root, and then generates the kernel image (peep KERNEL) and the debirf initramfs. this subcommand takes various options too (see OPTIONS). multitasking queen. 👑
  • enter PROFILE — chroot into the root of profile PROFILE, with the full profile environment. it's giving "step inside, make yourself at home".
  • makeiso PROFILE — create a bootable CD-ROM image from the kernel and initramfs in PROFILE. this needs a bootloader to be available, no bootloader no party. if grub-mkrescue (in the grub-common package on debian) is available, it will be used. otherwise, isolinux is used if it's available. you can use the DEBIRF_ISO_BOOTLOADER environment variable to specify a preference manually (see below, i got you 💜).
  • help — output a brief usage summary. short, sweet, to the point.

💅 OPTIONS 💅

heads up, these are for the make subcommand only. nobody else gets them.
  • -c, --check-vars — check variables before make
  • -n, --new — create new root, even if old one exists
  • -o, --overwrite — debootstrap on top of old root if it exists
  • -s, --skip — skip debootstrap step altogether if old root exists
  • -r, --root-build — use real chroot to build instead of fakechroot (requires superuser privileges or CAP_SYS_CHROOT)
  • -w, --no-warning — skip superuser warning
  • -i, --initrd-only — remake initramfs from existing root (skip debootstrap and module stages)
  • -k, --kernel-deb=KERNEL — install KERNEL .deb, instead of default kernel

🌈 PROFILES 🌈

a debirf profile is a directory containing a debirf.conf config file and a modules sub-directory (see MODULES). that's it. that's the profile. simple, clean, main character energy.

🍓 PACKAGE INCLUDES/EXCLUDES 🍓

if the profile directory includes a packages file, it is interpreted as a list of packages to include/exclude during the debootstrap stage. packages should be specified one per line, with a + prefix to indicate inclusion during debootstrap, or a - prefix to indicate exclusion. yes bestie, one per line. we're organized in this house.

🧚 MODULES 🧚

modules are used to configure the debirf system, and can be used to extend the capabilities of debirf. modules are bash shell scripts that are executed in alpha-numeric order by run-parts in a chroot in the debirf root during the module stage of the debirf build. the module stage is right after the debirf debootstrap stage, and right before the initramfs archive is created. all shell variables beginning with "DEBIRF_", including those defined in the debirf.conf file, are available to the modules. so like, share the wealth, yk? 💜

modules may specify packages to be included/excluded during the debootstrap stage with special #DEBIRF_PACKAGE> comments anywhere in the module. lines beginning with #DEBIRF_PACKAGE>+ specify packages to include, and lines beginning with #DEBIRF_PACKAGE>- indicate packages to exclude. only ONE package should be specified per comment line (no spaces, i'm serious). so for instance, the lines:

#DEBIRF_PACKAGE>+emacs
#DEBIRF_PACKAGE>+ed
#DEBIRF_PACKAGE>-nano

would include the packages emacs and ed, and would exclude the package nano. (rip nano, you served your purpose 🫡)

NOTE: some modules are more important to the proper functioning of debirf than others, and the ordering of modules is important. some modules may depend on certain other modules having already been, or not yet been, run. for instance, the module that cleans the debirf apt cache (z1_clean_root) should be the last module run at the end of the module stage. do not skip this note. do not pass go. do not collect $200. 🚨

⭐ KERNEL ⭐

the debirf install-kernel module will try to pick the most up-to-date kernel for the suite you are installing (versions 2.6 only), with the arch determined by the kernel running on the host build system. she picks the freshest one, periodt.

💖 FUNCTIONS 💖

a set of pre-defined bash shell functions are available to the modules to fasciliate configuring the debirf system (yes, "fasciliate", it's in the original and we respect it 😌):

  • debirf_exec <command> — execute <command> within debirf root (DEBIRF_ROOT) with chroot.
  • msg <message> — output a message to standard out during the build process.
  • failure <message> <exit-code> — cause debirf script to fail with <exit-code>, and <message> to stderr.
  • debirf_info_sh <message> — write one line of sh code to the debirf.info file on the debirf root.
  • debirf_info_comment <message> — write one line of comment to the debirf.info file on the debirf root.

🎀 ENVIRONMENT 🎀

the following environment variables are used by debirf (and yes, every single one of them matters):

  • DEBIRF_LABEL — debirf label (default: debirf)
  • DEBIRF_BUILDD — where to build the debirf (default: ./)
  • DEBIRF_ARCH — architecture to build (default is the architecture of the build machine)
  • DEBIRF_SUITE — suite to build from (default determined from lsb_release, otherwise "sid")
  • DEBIRF_DISTRO — distro for suite (default determined from lsb_release, otherwise "debian")
  • DEBIRF_MIRROR — mirror to pull suite (default determined by DEBIRF_DISTRO)
  • DEBIRF_KEYRING — keyring to verify debootstrap (default determined by DEBIRF_DISTRO)
  • DEBIRF_KERNEL_FLAVOR — the flavor of kernel debirf should install. supply everything from a typical debian package name after the version number. e.g. 486, vserver-686-bigmem, openvz-amd64. (default chosen based on currently-running kernel)
  • DEBIRF_ISO_BOOTLOADER — whether to use "grub" or "isolinux" as the El Torito bootloader for debirf makeiso. if not specified, "grub" is the default.

🦋 FILES 🦋

  • $DEBIRF_PROFILE/debirf.conf — debirf profile configuration file. contains values for the various debirf environment variables (see ENVIRONMENT). variables specified in the debirf.conf override those specified on the command line. yes, the config file wins the argument. queen behavior. 👑
  • $DEBIRF_ROOT/etc/debirf/debirf.info — file that stores various information about the debirf build. this is a bash-sourceable file.

🌸 AUTHOR 🌸

written by Jameson Rollins and Daniel Kahn Gillmor. legends, honestly.

💀 BUGS 💀

debirf does not work as a non-privileged user across different versions of libc. in particular, this means that you probably won't be able to build an image from a different version of the operating system than you're using without building as root. (see http://bugs.debian.org/650242)

bestie this one is real. if you try to be cute about it as a normal user across libc versions, it will not be cute back. build as root or perish. 😭

please report bugs in debirf via the debian BTS: http://bugs.debian.org/

Copyright © 2007-2011 Jameson Rollins and Daniel Kahn Gillmor

this is free software. you may redistribute copies of it under the terms of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. there is NO WARRANTY, to the extent permitted by law. (no warranty, no promises, no refunds, that's the deal 💅)

🌈 SEE ALSO 🌈

/usr/share/doc/debirf/README, debootstrap(8), fakechroot(1)

and that's the whole vibe, bestie 💖 this was debirf version 0.32, dating all the way back to Dec 2011 — a true vintage icon, still serving. go build something that lives entirely in RAM. slay. ✨🎀🦋

📦 where this page comes from