LIVE-BOOT(conf) Debian Live Project LIVE-BOOT(conf)
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 persis‐
tence.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 sys‐
tem are stored persistently into a path equivalent to DIR on the per‐
sistence 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 coma-separated list:
source=PATH
When given, store the persistence changes into PATH on the persis‐
tence media. PATH must be a relative path (with respect to the per‐
sistence media root) that cannot contain white spaces or the spe‐
cial . 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 persis‐
tence).
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 per‐
sistence media in DIR and create symbolic links from the corre‐
sponding place in DIR to each file in the source directory. Exist‐
ing 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 direc‐
tory 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 persis‐
tent, 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, but is not supported with
union=unionmount.
DIRECTORIES
/live/persistence
All persistence volumes will be mounted here (in a directory corre‐
sponding 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 refer‐
ence):
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 oth‐
erwise 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 persis‐
tence.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 cer‐
tain 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 sys‐
tem. 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 <http://live.debian.net/> and in the manual at
<http://live.debian.net/manual/>.
BUGS
Bugs can be reported by submitting a bugreport for the live-boot pack‐
age in the Debian Bug Tracking System at <https://bugs.debian.org/> or
by writing a mail to the Debian Live mailing list at <debian-
[email protected]>.
AUTHOR
persistence.conf was written by anonym <[email protected]> for the
Debian project.
3.0.1-1 2013-02-14 LIVE-BOOT(conf)