+++ /dev/null
-.TH LIVE\-BOOT conf 2012\-04\-09 3.0~a27-1 "Debian Live Project"
-
-.SH NAME
-\fBlive-persistence.conf\fR \- Configuration file for persistence media in
-live\-boot
-
-.SH 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") "custom\-ov",
-that volume's persistence is fully customizable through the
-\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-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
-.RS
-\fIDIR\fR [\fIOPTION\fR]...
-.RE
-.PP
-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
-contain white spaces or the special . and .. path components, and
-cannot be /live (or any of its sub-directories), or / (for the latter,
-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 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.
-.PP
-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
-\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-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
-"nested" mounts like /a and /a/b on the same media. In this case you
-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 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 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-persistence.conf\fR accept the following
-options in a coma-separated list:
-.IP "\fBsource\fR=\fIPATH\fR" 4
-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 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).
-.PP
-The following options are mutually exclusive (only the last given one
-will be in effect):
-.IP "\fBbind\fR" 4
-Bind-mount the source directory to \fIDIR\fR. This is the default.
-.IP "\fBlink\fR" 4
-Create the directory structure of the source directory on 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
-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.
-.IP
-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
-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.
-.IP "\fBunion\fR" 4
-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
-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 \fBunion\fR boot parameter, but is not supported with
-\fBunion=unionmount\fR.
-
-.SH DIRECTORIES
-.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
-\fBlink\fR option).
-
-.SH EXAMPLES
-
-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 link,source=config-files/user1
-.TP
-2.
-/home/user2 link,source=config-files/user2
-.TP
-3.
-/home
-.TP
-4.
-/usr union
-.PP
-The corresponding source directories are:
-.TP 7
-1.
-\fIVOL\fR/config-files/user1 (but it would be \fIVOL\fR/home/user1
-without the \fBsource\fR option)
-.TP
-2.
-\fIVOL\fR/config-files/user2 (but it would be \fIVOL\fR/home/user2
-without the \fBsource\fR option)
-.TP
-3.
-\fIVOL\fR/home
-.TP
-4.
-\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 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,
-\fIVOL\fR/home is simply bind-mounted on /home. To illustrate what
-happens for lines 1 and 2, let's say that the following files exist:
-.TP 7
-a.
-\fIVOL\fR/config-files/user1/.emacs
-.TP
-b.
-\fIVOL\fR/config-files/user2/.bashrc
-.TP
-c.
-\fIVOL\fR/config-files/user2/.ssh/config
-.PP
-Then the following links and directories will be created:
-.TP 7
-Link:
-/home/user1/.emacs -> \fIVOL\fR/config-files/user1/.emacs (from a)
-.TP
-Link:
-/home/user2/.bashrc -> \fIVOL\fR/config-files/user2/.bashrc (from b)
-.TP
-Dir:
-/homea/user2/.ssh (from c)
-.TP
-Link:
-/home/user2/.ssh/config -> \fIVOL\fR/config-files/user2/.ssh/config
-(from c)
-.PP
-One could argue, though, that lines 1 and 2 in the example
-\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
-Line 4 can be mounted at any time since its \fIDIR\fR (and source
-directory) is completely disjoint from all the other custom
-mounts. When mounted, \fIVOL\fR/usr will be the rw branch due to the
-\fBunion\fR 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 \fIVOL\fR/usr during the initial bootstrap.
-
-.SH SEE ALSO
-\fIlive\-boot\fR(7)
-.PP
-\fIlive\-build\fR(7)
-.PP
-\fIlive\-config\fR(7)
-.PP
-\fIlive\-tools\fR(7)
-
-.SH HOMEPAGE
-More information about live\-boot and the Debian Live project can be
-found on the homepage at <\fIhttp://live.debian.net/\fR> and in the
-manual at <\fIhttp://live.debian.net/manual/\fR>.
-
-.SH BUGS
-Bugs can be reported by submitting a bugreport for the live\-boot
-package in the Debian Bug Tracking System at
-<\fIhttp://bugs.debian.org/\fR> or by writing a mail to the Debian
-Live mailing list at <\fIdebian-live@lists.debian.org\fR>.
-
-.SH AUTHOR
-live\.persist was written by anonym <\fIanonym@lavabit.com\fR> for the
-Debian project.
projects / live-boot-grml.git / blobdiff