LIVE-BOOT(7)

📦
version 20250815ubuntu1 · 4 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

okay bestie, buckle up 💖 this here is live-boot, brought to you by the Debian Live Project, and it lives in section 7 of the man pages. she's long, so this comes in more than one part — this is part 1, so don't you dare scroll away.

🎀 NAME 🎀

live-boot — System Boot Components. short king of a name section, we love her.

✨ DESCRIPTION ✨

okay so, live-boot is the whole girlboss squad of components that set up a live system while it's booting — specifically in early userspace, before your real system even knows what's happening. 🔥

it's a hook for initramfs-tools, and its whole job is generating an initramfs that's capable of booting live systems. like the ones made by live-helper(7). that includes Live systems ISOs, netboot tarballs, and usb stick images. all of it. 💅

at boot time it goes looking for a (read-only) medium that has a "/live" directory on it, where a root filesystem lives (usually a compressed filesystem image situation, like squashfs). if it finds one? it creates a writable environment — using aufs — and boots the system from there. iconic behaviour, honestly. 🦋

🌸 CONFIGURATION 🌸

you can configure live-boot two ways: through a boot parameter, or through a configuration file. pick your fighter.

and if you wanna set the live-boot parameters that get used by default inside a live image, go look at the --bootappend-live option over in the lb_config(1) manual page. 🫶

🧚 Kernel Parameters

real talk: live-boot stays inactive unless you passed boot=live as a kernel parameter. that's the activation phrase, it's giving spell casting ngl.

and then on top of that, there's a whole bunch more boot parameters that influence how it behaves. they're further down, keep reading. 👑

🍓 Configuration Files

live-boot can also be configured (but not activated — important distinction, bestie) through configuration files. those files can go in either:

  • the root filesystem itself: /etc/live/boot.conf, /etc/live/boot/*
  • or on the live media: live/boot.conf, live/boot/*

and here's the thing — these environment variables can only be set in the configuration files. nowhere else. so write them down:

  • DISABLE_CDROM=[true|false] — turns off support for booting from CD-ROMs. if you set it to true, mkinitramfs will build an initramfs without the kernel modules for reading CD-ROMs. bye bye cd-rom modules 💀
  • DISABLE_DM_VERITY=[true|false] — turns off support for dm-verity. set it to true and mkinitramfs builds an initramfs without the kernel module dm-verity and some other dm modules. also, the default mount binary gets used instead of the util-linux one. plot twist.
  • DISABLE_FAT=[true|false] — turns off support for booting from FAT file systems. set it to true and mkinitramfs builds an initramfs without the kernel module vfat and some nls_* modules.
  • DISABLE_EXFAT=[true|false] — turns off support for booting from exFAT file systems. set it to true and mkinitramfs builds an initramfs without the kernel module exfat.
  • DISABLE_FUSE=[true|false] — turns off support for booting from FUSE-based file systems. set it to true and mkinitramfs builds an initramfs without the kernel module fuse and without the file systems that depend on it (like curlftpfs and httpfs2). they're a package deal, sorry.
  • DISABLE_NTFS=[true|false] — turns off support for booting from NTFS file systems. set it to true and mkinitramfs builds an initramfs without the kernel module ntfs.
  • DISABLE_USB=[true|false] — turns off support for booting from USB devices. set it to true and mkinitramfs builds an initramfs without the kernel module sd_mod.
  • MINIMAL=[true|false] — builds a minimal initramfs. set it to true and mkinitramfs builds an initramfs without some udev scripts and without rsync. girl went on a diet.
  • PERSISTENCE_FSCK=[true|false] — runs fsck on the persistence filesystem at boot. it'll attempt to repair errors. the execution log gets saved in /var/log/live/fsck.log. receipts kept, always. 📝
  • FSCKFIX=[true|false] — if PERSISTENCE_FSCK or forcefsck are set, this passes -y to fsck so it stops asking you questions interactively and just assumes yes to all queries. no more standing there like "😭 do I say yes??" — she's confident now.

💅 OPTIONS 💅

live-boot currently features the following parameters. (yes, this is the long part. we're getting through it together, hold my hand 🫶)

  • access=ACCESS — sets the accessibility level for physically or visually impaired users. ACCESS has to be one of v1, v2, v3, m1, or m2. so: v1 = lesser visual impairment, v2 = moderate visual impairment, v3 = blindness, m1 = minor motor difficulties, m2 = moderate motor difficulties. accessibility is main character energy fr. ✨
  • console=TTY,SPEED — sets the default console used with the "live-getty" option. example: console=ttyS0,115200
  • debug — makes the initramfs boot process more verbose. use it like: debug=1. warning though: if you set debug without giving it a value, the messages may not be shown. so give her a value, bestie. 💀
  • fetch=URL
  • httpfs=URL — both fetch and httpfs are another form of netboot: downloading a squashfs image from a given URL. the difference, ok: the fetch method copies the image into RAM, and the httpfs method uses FUSE and httpfs2 to mount the image in place. copying to RAM needs more memory and might take forever for big images — but it's more likely to actually work correctly, because it doesn't need networking afterwards, and the system runs faster once booted since it doesn't have to keep contacting the server anymore. tradeoffs, babe.

also, because of current limitations in busybox's wget and DNS resolution, an URL cannot contain a hostname — it has to be an IP address only. so:

Not working: http://example.com/path/to/your_filesystem.squashfs
Working: http://1.2.3.4/path/to/your_filesystem.squashfs

and also note that because of this, it's currently not possible to fetch an image from a name-based virtualhost of an httpd if that virtualhost is sharing the IP address with the main httpd instance. 🙈

oh and — you can also use the live ISO image in place of the squashfs image. options, we love options.

  • iscsi=server-ip[,server-port];target-name — boot from an iSCSI target that has an ISO or disk live image as one of its LUNs. the target you specified gets searched for a LUN that looks like a live medium. and if you're using the iscsitarget software iSCSI target solution, your ietd.conf might look like this:
# The target-name you specify in the iscsi= parameter
Target <target-name>
  Lun 0 Path=<path-to-your-live-image.iso>,Type=fileio,IOMode=ro
  # If you want to boot multiple machines you might want to look at tuning some parameters like
  # Wthreads or MaxConnections
  • findiso=/PATH/TO/IMAGE — looks for the specified ISO file on all the disks where it would usually look for the .squashfs file. so basically you don't have to know the device name like you would with fromiso=.... she'll find it for you. 🔍
  • forcefsck — runs fsck on the persistence filesystem at boot. it will attempt to repair errors. the execution log is saved in /var/log/live/fsck.log.
  • fromiso=/PATH/TO/IMAGE — uses a filesystem from within an ISO image that's available on the live-media. the first part of the argument should be the block device where the image is stored, followed by the path and filename — for example fromiso=/dev/sda1/live/image.iso.

alternatively, you can use it to boot from an ISO embedded into an initrd, like fromiso=/live/image.iso.

  • ignore_uuid — don't check whether any UUID embedded in the initramfs matches the discovered medium. heads up: live-boot can be told to generate a UUID by setting LIVE_GENERATE_UUID=1 when building the initramfs.
  • verify-checksums — if specified, an MD5 sum gets calculated on the live media during boot and compared to the value found in md5sum.txt, which lives in the root directory of the live media. trust but verify, periodt. ✅
  • ip=[DEVICE]:[CLIENT_IP]:[NETMASK]:[GATEWAY_IP]:[NAMESERVER], [,[DEVICE]:[CLIENT_IP]:[NETMASK]:[GATEWAY_IP]:[NAMESERVER]] — lets you specify the name(s) and options of the interface(s) that should be configured at boot time. don't specify this if you want to use dhcp (that's the default). heads up: this is gonna change in a future release to mimic the official kernel boot param specification, e.g. ip=10.0.0.1::10.0.0.254:255.255.255.0::eth0,:::::eth1:dhcp.
  • ip=[frommedia] — if this variable is set, dhcp and static configuration are just skipped, and the system will use the (must be) media-preconfigured /etc/network/interfaces instead.
  • {live-media|bootfrom}=DEVICE — if you specify one of these two equivalent forms, live-boot will first try to find this device for the "/live" directory, where the read-only root filesystem should live. if it doesn't find anything usable there, the normal scan for block devices happens instead.

and instead of specifying an actual device name, you can use the keyword removable to limit the search of acceptable live media to removable type only. also note: if you wanna restrict the media even further, to usb mass storage only, there's the removable-usb keyword for that. 💅

  • live-media-offset=BYTES — this way you can tell live-boot that your image starts at offset BYTES in the device you specified above (or the autodiscovered one). this is useful for hiding the live system ISO or image inside another ISO or image, to create "clean" images. sneaky 🕵️
  • live-media-path=PATH — sets the path to the live filesystem on the medium. by default it's set to /live, and you should not change that unless you've customized your media accordingly. don't touch unless you know, bestie.
  • live-media-timeout=SECONDS — sets the timeout, in seconds, for the device specified by "live-media=" to become ready before giving up. she's patient, but not that patient.
  • module=NAME — instead of using the default optional file "filesystem.module" (see below), a different file can be specified without the .module extension. it should be placed in the "/live" directory of the live medium.
  • netboot[=nfs|cifs] — tells live-boot to perform a network mount. the parameter "nfsroot=" (with optional "nfsopts=") should specify where the root filesystem is located. with no args, it'll try cifs first, and if that fails, nfs. fallback queen. 👑
  • nfsopts= — lets you specify custom nfs options.
  • nofastboot — disables the default disabling of filesystem checks in /etc/fstab. so if you have static filesystems on your harddisk and you want them checked at boot time, use this parameter — otherwise they get skipped.
  • nopersistence — disables the "persistence" feature. useful if the bootloader (like syslinux) was installed with persistence enabled and you're like "no thank you 💀".
  • noeject — don't prompt to eject the live medium.
  • ramdisk-size — defines a custom ramdisk size (it's the -o size option of tmpfs mount). by default, there's no ramdisk size set, so the default of mount applies (currently 50% of available RAM). note: this option currently has no effect when booting with toram. 🙈
  • overlay-size=SIZE — the size of the tmpfs mount (used for the upperdir union root mount), in bytes, rounded up to entire pages. this option accepts a suffix % to limit the instance to that percentage of your physical RAM, or a suffix k, m or g for Ki, Mi, Gi (binary kilo (kibi), binary mega (mebi) and binary giga (gibi)). by default, 50% of available RAM gets used.
  • swap=true — enables usage of local swap partitions.

okay bestie that's part 1 down and honestly? we ate. there's more of this page still coming, so keep scrolling, don't leave me hanging 🫶💖

  • persistence — okay so this one is the moment live-boot goes snooping through your devices looking for persistence media 💅. It's checking for three flavors: partitions (with the correct GPT name), filesystems (with the correct label), or image files (with the correct file name). Overlays get labeled/named "persistence" (go peep persistence.conf(5) for the deets). Overlay image files are named "persistence". that's it, that's the vibe.
  • persistence-encryption=TYPE1,TYPE2 ... TYPEn — this decides which types of encryption are allowed while probing devices for persistence media. "none" in the list = unencrypted media is fine 🫶. "luks" in the list = LUKS-encrypted media is allowed. "lukslabel" in the list = we check whether the container holds the label "persistence" before trying to open it. Whenever a device with encrypted media gets probed, the user gets prompted for the passphrase (yes bestie, you will be typing it). The default value is "none".
  • persistence-media={removable|removable-usb} — use the keyword 'removable' and live-boot will try to find persistence partitions on removable media only 💾. Wanna get even tighter and restrict it to USB mass storage only? Use the 'removable-usb' keyword.
  • persistence-method=TYPE1,TYPE2 ... TYPEn — this determines which types of persistence media we allow. Put "overlay" in the list and we consider overlays (i.e. "live-rw" and "home-rw"). The default is "overlay".
  • persistence-path=PATH — live-boot will look for persistency files in the root directory of a partition. With this parameter, the path can be configured so you can have multiple directories on the same partition to store persistency files. organized ✨
  • persistence-read-only — filesystem changes are not saved back to persistence media. Specifically: overlays and netboot NFS mounts are mounted read-only.
  • persistence-storage=TYPE1,TYPE2 ... TYPEn — this determines which types of persistence storage to consider when probing for persistence media. "filesystem" in the list = filesystems with matching labels will be used; "file" in the list = all filesystems get probed for archives and image files with matching filenames. The default is "file,filesystem".
  • persistence-label=LABEL1,LABEL2 ... LABELn — live-boot will use the names in this list (instead of "persistence") when searching for persistent storage. Each LABEL can be a valid filename, partition label, or GPT name. The default is "persistence".
  • noeject — makes live-boot reboot without attempting to eject the media and without asking the user to remove the boot media. no awkward "please remove the disc" moment 🎀.
  • showmounts — this parameter makes live-boot show the ro filesystems (mostly compressed) on "/" over in "/lib/live". Not enabled by default, because it could lead to problems with applications like "mono" which store binary paths on installation. so like. leave it alone unless you know 🧚.
  • silent — boot with the normal quiet parameter and live-boot hides most messages of its own. Add silent on top and it hides all of them. humble and quiet, love that 🦋.
  • todisk=DEVICE — add this and live-boot will try to copy the entire read-only media to the specified device before mounting the root filesystem. Heads up: it probably needs a lot of free space 🫠. Subsequent boots should then skip this step and just specify the "live-media=DEVICE" boot parameter with the same DEVICE used this time.
  • toram — add this and live-boot will try to copy the whole read-only media to the computer's RAM before mounting the root filesystem. This could need a lot of ram, according to the space used by the read-only media. throwing it all in memory, main character energy honestly 🌈.
  • union=overlay|aufs — by default live-boot uses overlay. With this parameter you can switch to aufs.
  • dm-verity-root-hash=IMAGE:ROOTHASH,IMAGE2:ROOTHASH2 ... IMAGEn:ROOTHASHn — explicitly specify a dm-verity root hash for an IMAGE. Full path needs to be specified 🔍. Hashes for multiple images can be comma separated specified.
  • dm-verity-enforce-roothash-signature — enforces that the root hash has to be checked against a signature. no shortcuts 🫡.
  • dm-verity-oncorruption=ignore|panic|restart — sets the regarding action for the kernel if corruption occurs on a dm-verity device.

🦋 dm-verity Support 🦋

live-boot has support for dm-verity backed root file systems, which allows for error detection (and correction) in the underlying image ✨.

If, for an image, a file ending with .verity is found in the same directory as the image, live-boot attempts to mount that image with dm-verity support. For a given device with dm-verity support, a root hash must be specified — either in a file ending with .roothash or with the kernel command-line option dm-verity-root-hash. If a file ending with .roothash.p7s is found, it's used for signature checking in dm-verity. If signature checking should be enforced, the kernel command-line option dm-verity-enforce-roothash-signature must be set.

Forward error detection gets enabled if a file ending with .fec and one with .fec.roots containing the number of roots are found 💅.

Example file structure:

/live/filesystem.squashfs
/live/filesystem.squashfs.verity
/live/filesystem.squashfs.fec
/live/filesystem.squashfs.fec.roots
/live/filesystem.squashfs.roothash
/live/filesystem.squashfs.roothash.p7s

✨ FILES (old) ✨

yk, the legacy lineup, still chilling here:

  • /etc/live.conf — some variables can be configured via this config file (inside the live system).
  • live/filesystem.module — this optional file (inside the live media) contains a list of white-space or carriage-return-separated file names corresponding to disk images in the "/live" directory. If this file exists, only images listed here will be merged into the root aufs, and they'll be loaded in the order listed here. The first entry in this file will be the "lowest" point in the aufs, and the last file in this list will be on the "top" of the aufs, directly below /overlay. Without this file, any images in the "/live" directory are loaded in alphanumeric order.

💜 FILES 💜

  • /etc/live/boot.conf
  • /etc/live/boot/*
  • live/boot.conf
  • live/boot/*
  • persistence.conf

👑 SEE ALSO 👑

🌸 HOMEPAGE 🌸

More information about live-boot and the Debian Live project can be found on the homepage at https://wiki.debian.org/DebianLive and in the manual at https://live-team.pages.debian.net/live-manual/ 🫶.

🍓 BUGS 🍓

Found a bug? No gatekeeping, report it bestie: submit a bugreport for the live-boot package in the Bug Tracking System at http://bugs.debian.org/, or write a mail to the Debian Live mailing list at debian-live@lists.debian.org 💌.

💖 AUTHOR 💖

live-boot was originally written by Daniel Baumann <mail@daniel-baumann.ch>. Since 2016, development has been continued by the Debian Live team. iconic lineage, no cap 👑.

and that's a wrap on the whole page, bestie 💅 this edition is 5.0~a5-1, dated 2015-09-22, and it lives under the name LIVE-BOOT(7) — go forth and boot responsibly 🌈✨

📦 where this page comes from