-.TH LIVE\-BOOT persist 2012\-04\-05 3.0~a26-1 "Debian Live Project"
+.TH LIVE\-BOOT conf 2012\-04\-09 3.0~a27-1 "Debian Live Project"
.SH NAME
-\fBlive.persist\fR \- Configuration file for persistent media in
+\fBlive-persistence.conf\fR \- Configuration file for persistence media in
live\-boot
.SH DESCRIPTION
-If live-boot probes a persistent volume with the label (or GPT name,
+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") "custom\-ov",
that volume's persistence is fully customizable through the
-\fBlive.persist\fR file stored on the root of its file system. Any such
+\fBlive-persistence.conf\fR file stored on the root of its file system. Any such
labeled volume must have such a file, or it will be ignored.
.PP
-The format of \fBlive.persist\fR allow empty lines and lines starting
+The format of \fBlive-persistence.conf\fR allow empty lines and lines starting
with a "#" (used for comments), both which will be ignored. A so
called "custom mount" has the format:
.PP
\fIDIR\fR [\fIOPTION\fR]...
.RE
.PP
-which roughly translates to "make \fIDIR\fR persistent in the way
+which roughly translates to "make \fIDIR\fR persistence in the way
described by the list of \fIOPTION\fRs".
.PP
For each custom mount \fIDIR\fR must be an absolute path that cannot
use "full-ov" persistence instead). Once activated all changes (file
deletion, creation and modification) to \fIDIR\fR on the live file
system are stored persistently into a path equivalent to \fIDIR\fR on
-the persistent media, called the source directory. The default way to
+the persistence media, called the source directory. The default way to
achieve persistence is to simply bind-mount the corresponding source
directory to \fIDIR\fR, but this can be changed through the use of
\fIOPTION\fRs.
mounts can "hide" each other. For instance, if we have the two
\fIDIR\fR: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
-\fBlive.persist\fR are ordered, or if several \fBlive.persist\fR files
-on different persistent media are used at the same time. However, it
+\fBlive-persistence.conf\fR are ordered, or if several \fBlive-persistence.conf\fR 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
must use the \fBsource\fR option (see below) to make sure that they
are stored in different source directories.
.PP
-When a source directory doesn't exist on the persistent media for a
+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
\fIDIR\fR. It will also be bootstrapped by copying the contents of the
-\fIDIR\fR into its source directory on the persistent media. The
-bootstrapping will not happen when the \fBlinkfiles\fR or \fBunion\fR
+\fIDIR\fR into its source directory on the persistence media. The
+bootstrapping will not happen when the \fBlink\fR or \fBunion\fR
options are used (see below).
.SH OPTIONS
-Custom mounts defined in \fBlive.persist\fR accept the following
+Custom mounts defined in \fBlive-persistence.conf\fR accept the following
options in a coma-separated list:
.IP "\fBsource\fR=\fIPATH\fR" 4
-When given, store the persistent changes into \fIPATH\fR on the
-persistent media. \fIPATH\fR must be a relative path (w.r.t. the
-persistent media root) that cannot contain white spaces or the
+When given, store the persistence changes into \fIPATH\fR on the
+persistence media. \fIPATH\fR must be a relative path (w.r.t. 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 persistent media root. This option is mostly
+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 \fBhome-rw\fR type of persistence).
will be in effect):
.IP "\fBbind\fR" 4
Bind-mount the source directory to \fIDIR\fR. This is the default.
-.IP "\fBlinkfiles\fR" 4
+.IP "\fBlink\fR" 4
Create the directory structure of the source directory on the
-persistent media in \fIDIR\fR and create symbolic links from the
+persistence media in \fIDIR\fR and create symbolic links from the
corresponding place in \fIDIR\fR 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 \fIDIR\fR will only
links will reappear after a reboot. To permanently add or delete a
file one must do so directly in the source directory.
.IP
-Effectively \fBlinkfiles\fR will make only files already in the source
+Effectively \fBlink\fR will make only files already in the source
directory persistent, not any other files in \fIDIR\fR. These files
must be manually added to the source directory to make use of this
option, and they will appear in \fIDIR\fR in addition to files already
persistent, not the whole directory they're in, e.g. some
configuration files in a user's home directory.
.IP "\fBunion\fR" 4
-Save the rw branch of a union on the persistent media, so only the
+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 \fIDIR\fR from
\fBunion=unionmount\fR.
.SH DIRECTORIES
-.IP "\fB/live/persistent\fR" 4
-All persistent volumes will be mounted here (in a directory
-corresponding to the device name). The \fBlive.persist\fR file can
+.IP "\fB/live/persistence\fR" 4
+All persistence volumes will be mounted here (in a directory
+corresponding to the device name). The \fBlive-persistence.conf\fR file can
easily be edited through this mount, as well as any source directories
(which is especially practical for custom mounts using the
-\fBlinkfiles\fR option).
+\fBlink\fR option).
.SH EXAMPLES
-Let's say we have a persistent volume \fIVOL\fR with the a
-\fBlive.persist\fR file containing the following four lines (numbered
+Let's say we have a persistence volume \fIVOL\fR with the a
+\fBlive-persistence.conf\fR file containing the following four lines (numbered
for ease of reference):
.TP 7
1.
-/home/user1 linkfiles,source=config-files/user1
+/home/user1 link,source=config-files/user1
.TP
2.
-/home/user2 linkfiles,source=config-files/user2
+/home/user2 link,source=config-files/user2
.TP
3.
/home
\fIVOL\fR/usr
.PP
It was necessary to set the \fBsource\fR options for 1 and 2, since
-they otherwise would become nested with 3's source, which is illegal.
+they otherwise would become nested with 3's source, which is invalid.
.PP
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,
(from c)
.PP
One could argue, though, that lines 1 and 2 in the example
-\fBlive.persist\fR file above are unnecessary since line 3 already
-would make all of /home persistent. The \fBlinkfiles\fR option is
+\fBlive-persistence.conf\fR file above are unnecessary since line 3 already
+would make all of /home persistent. The \fBlink\fR 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.
.PP
projects / live-boot-grml.git / blobdiff