LIVE-BOOT(5)

📦
version 20250815ubuntu1 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

okay bestie, sit down, hydrate, because this one is the live-boot(5) page from the Debian Live Project — manual section 5, all about persistence.conf. it's giving "tiny config file, enormous consequences" and honestly? obsessed. 💖

✨ NAME ✨

persistence.conf — the configuration file for persistence media in live-boot 🎀

💫 DESCRIPTION 💫

okay so here's the vibe: if live-boot probes a persistence volume whose label is persistence, then that volume's persistence is fully customizable through the persistence.conf file stored on the root of its file system. 🦋

quick sidebar, because words matter: when we say "label" we mean the label, or the GPT name, or the file name — but from now on we're just gonna say "label", okay? iykyk.

and it's not a suggestion: any such labeled volume must have such a file, or it will be ignored. no file, no persistence, no conversation. 💀

📝 the format (it's lowkey chill)

The format of persistence.conf allows empty lines and lines starting with a # (those are used for comments), and both of those get ignored. 😌

A so called "custom mount" has the format:

DIR [OPTION]...

which roughly translates to "make DIR persistence in the way described by the list of OPTIONs". 🫶

🚨 the rules for DIR

For each custom mount, DIR must be an absolute path, and:

  • it cannot contain white spaces or the special . and .. path components
  • it cannot be /live (or any of its sub-directories)

Once activated, all changes (file deletion, creation and modification) to DIR on the live file system are stored persistently into a path equivalent to DIR on the persistence media — and that path is called the source directory. ✨

The default way to achieve persistence is to simply bind-mount the corresponding source directory to DIR, but this can be changed through the use of OPTIONs. 💅

👑 mount order, because chaos is not allowed here

All custom mounts will be done in an order so that no two custom mounts can "hide" each other. For instance, if we have the two DIR:s /a and /a/b, it would always be the case that /a is mounted first, then /a/b. And this remains true no matter how the lines in persistence.conf are ordered, or if several persistence.conf files on different persistence media are used at the same time. main character scheduling energy, periodt.

However — and this is the part where it gets real — it is forbidden for custom mounts to have their source directory inside the source directory of another custom mount. So the source directories that are auto-created by live-boot do not support "nested" mounts like /a and /a/b on the same media. In this case you must use the source option (see below) to make sure that they are stored in different source directories. 🙈

🌱 when the source directory doesn't exist yet

When a source directory doesn't exist on the persistence media for a certain custom mount, it will be created automatically, and permissions and ownership will be optimistically set according to DIR. It will also be bootstrapped by copying the contents of the DIR into its source directory on the persistence media. 🌸

heads up bestie: the bootstrapping will not happen when the link or union options are used (see below).

💅 OPTIONS 💅

Custom mounts defined in persistence.conf accept the following options in a comma-separated list:

  • source=PATH — when given, store the persistence changes into PATH on the persistence media. PATH must be a relative path (with respect to the persistence media root) that cannot contain white spaces or the special . or .. path components, with the exception that it can be just ., which means the persistence media root. This option is mostly relevant if you want to nest custom mounts, which otherwise would cause errors, or if you want to make the whole media root available (similar to the now deprecated home-rw type of persistence).

The following options are mutually exclusive — only the last given one will be in effect:

  • bind — bind-mount the source directory to DIR. This is the default. 🫡
  • link — create the directory structure of the source directory on the persistence media in DIR and create symbolic links from the corresponding place in DIR to each file in the source directory. Existing files or directories with the same name as any link will be overwritten. Note that deleting the links in DIR will only remove the link, not the corresponding file in the source; removed links will reappear after a reboot. To permanently add or delete a file one must do so directly in the source directory. 😭

Effectively link will make only files already in the source directory persistent, not any other files in DIR. These files must be manually added to the source directory to make use of this option, and they will appear in DIR in addition to files already there. This option is useful when only certain files need to be persistent, not the whole directory they're in, e.g. some configuration files in a user's home directory. 🎀

  • union — save the rw branch of a union on the persistence media, so only the changes are stored persistently. This can potentially reduce disk usage compared to bind-mounts, and will not hide files added to the read-only media. One caveat is that the union will use DIR from the image's read-only file system, not the real file system root, so files created after boot (e.g. by live-config) will not appear in the union. This option will use the union file system specified by live-boot's union boot parameter. 🔥

📂 DIRECTORIES 📂

  • /live/persistence — all persistence volumes will be mounted here (in a directory corresponding to the device name). The persistence.conf file can easily be edited through this mount, as well as any source directories (which is especially practical for custom mounts using the link option). ✨

🌈 EXAMPLES 🌈

Let's say we have a persistence volume VOL with the a persistence.conf file containing the following four lines (numbered for ease of reference):

  1. /home/user1 link,source=config-files/user1
  2. /home/user2 link,source=config-files/user2
  3. /home
  4. /usr union

The corresponding source directories are:

  1. VOL/config-files/user1 (but it would be VOL/home/user1 without the source option)
  2. VOL/config-files/user2 (but it would be VOL/home/user2 without the source option)
  3. VOL/home
  4. VOL/usr

It was necessary to set the source options for 1 and 2, since they otherwise would become nested with 3's source, which is invalid. 🚫

Line 3 will be taken care of before line 1 and 2 in order to prevent custom mounts 1 and 2 from being hidden by 3. When line 3 is handled, VOL/home is simply bind-mounted on /home. To illustrate what happens for lines 1 and 2, let's say that the following files exist:

a. VOL/config-files/user1/.emacs

b. VOL/config-files/user2/.bashrc

c. VOL/config-files/user2/.ssh/config

Then the following links and directories will be created:

  • Link: /home/user1/.emacs -> VOL/config-files/user1/.emacs (from a)
  • Link: /home/user2/.bashrc -> VOL/config-files/user2/.bashrc (from b)
  • Dir: /home/user2/.ssh (from c)
  • Link: /home/user2/.ssh/config -> VOL/config-files/user2/.ssh/config (from c)

One could argue, though, that lines 1 and 2 in the example persistence.conf file above are unnecessary since line 3 already would make all of /home persistent. The link option is intended for situations where you don't want a complete directory to be persistent, only certain files in it or its sub-directories. 💅

Line 4 can be mounted at any time since its DIR (and source directory) is completely disjoint from all the other custom mounts. When mounted, VOL/usr will be the rw branch due to the union option, and will only contain the difference compared to the underlying read-only file system. Hence packages could be installed into /usr with great space-wise efficiency compared to bind-mounts, since in the latter case all of /usr would have to be copied into VOL/usr during the initial bootstrap. 👑

👀 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 💀

Bugs can be reported by submitting a bugreport for the live-boot package in the Bug Tracking System at <http://bugs.debian.org/> or by writing 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. 💜

okay that's the whole page, you ate that. this one came from the Debian Live Project, version 5.0~a5-1, dated 2015-09-22 — and yes, it's still LIVE-BOOT(5) in the footer because legends never change their section number. byeee bestie, go be persistent 💖✨

📦 where this page comes from