bionic (5) persistence.conf.5.gz

Provided by: open-infrastructure-system-boot_20161101-lts2-1_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:   /homea/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  Live  Systems  project  can  be  found  on  the  homepage  at
       <http://live-systems.org/> and in the manual at <http://live-systems.org/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  Live  Systems  mailing  list  at   <debian-
       live@lists.debian.org>.

AUTHOR

       live-boot was written by Daniel Baumann <mail@daniel-baumann.ch>.