Provided by: live-boot-doc_20220505_all bug

NAME

       persistence.conf - Configuration file for persistence media in live-boot

DESCRIPTION

       If  live-boot  probes  a persistence volume with the label (or GPT name, or file name, but
       from now on we will just say "label") "persistence", that volume's  persistence  is  fully
       customizable  through the persistence.conf file stored on the root of its file system. Any
       such labeled volume must have such a file, or it will be ignored.

       The format of persistence.conf allows empty lines and lines starting with a "#" (used  for
       comments), both which will be 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".

       For each custom mount DIR must be an absolute path that cannot contain white spaces or the
       special  .  and  ..  path components, and 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, 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.

       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.  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. However, 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 does  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 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. 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

       live-boot(7)

       live-build(7)

       live-config(7)

       live-tools(7)

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.