--- /dev/null
+.\"*******************************************************************
+.\"
+.\" This file was generated with po4a. Translate the source file.
+.\"
+.\"*******************************************************************
+.TH LIVE\-BOOT conf 2012\-04\-09 3.0~a27\-1 "Debian Live Project"
+
+.SH NAME
+\fBlive\-persistence.conf\fP \- 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\fP 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\fP 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\fP [\fIOPTION\fP]...
+.RE
+.PP
+which roughly translates to "make \fIDIR\fP persistence in the way described by
+the list of \fIOPTION\fPs".
+.PP
+For each custom mount \fIDIR\fP 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\fP on the live file system are stored persistently
+into a path equivalent to \fIDIR\fP 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\fP, but this can be changed
+through the use of \fIOPTION\fPs.
+.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\fP: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\fP are ordered, or if
+several \fBlive\-persistence.conf\fP 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\fP 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\fP. It will also be
+bootstrapped by copying the contents of the \fIDIR\fP into its source directory
+on the persistence media. The bootstrapping will not happen when the \fBlink\fP
+or \fBunion\fP options are used (see below).
+
+.SH OPTIONS
+Custom mounts defined in \fBlive\-persistence.conf\fP accept the following
+options in a coma\-separated list:
+.IP \fBsource\fP=\fIPATH\fP 4
+When given, store the persistence changes into \fIPATH\fP on the persistence
+media. \fIPATH\fP 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\fP type of
+persistence).
+.PP
+The following options are mutually exclusive (only the last given one will
+be in effect):
+.IP \fBbind\fP 4
+Bind\-mount the source directory to \fIDIR\fP. This is the default.
+.IP \fBlink\fP 4
+Create the directory structure of the source directory on the persistence
+media in \fIDIR\fP and create symbolic links from the corresponding place in
+\fIDIR\fP 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\fP 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\fP will make only files already in the source directory
+persistent, not any other files in \fIDIR\fP. These files must be manually
+added to the source directory to make use of this option, and they will
+appear in \fIDIR\fP 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\fP 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\fP 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\fP boot parameter, but is not
+supported with \fBunion=unionmount\fP.
+
+.SH DIRECTORIES
+.IP \fB/live/persistence\fP 4
+All persistence volumes will be mounted here (in a directory corresponding
+to the device name). The \fBlive\-persistence.conf\fP file can easily be edited
+through this mount, as well as any source directories (which is especially
+practical for custom mounts using the \fBlink\fP option).
+
+.SH EXAMPLES
+
+Let's say we have a persistence volume \fIVOL\fP with the a
+\fBlive\-persistence.conf\fP 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\fP/config\-files/user1 (but it would be \fIVOL\fP/home/user1 without the
+\fBsource\fP option)
+.TP
+2.
+\fIVOL\fP/config\-files/user2 (but it would be \fIVOL\fP/home/user2 without the
+\fBsource\fP option)
+.TP
+3.
+\fIVOL\fP/home
+.TP
+4.
+\fIVOL\fP/usr
+.PP
+It was necessary to set the \fBsource\fP 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\fP/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\fP/config\-files/user1/.emacs
+.TP
+b.
+\fIVOL\fP/config\-files/user2/.bashrc
+.TP
+c.
+\fIVOL\fP/config\-files/user2/.ssh/config
+.PP
+Then the following links and directories will be created:
+.TP 7
+Link:
+/home/user1/.emacs \-> \fIVOL\fP/config\-files/user1/.emacs (from a)
+.TP
+Link:
+/home/user2/.bashrc \-> \fIVOL\fP/config\-files/user2/.bashrc (from b)
+.TP
+Dir:
+/homea/user2/.ssh (from c)
+.TP
+Link:
+/home/user2/.ssh/config \-> \fIVOL\fP/config\-files/user2/.ssh/config (from
+c)
+.PP
+One could argue, though, that lines 1 and 2 in the example
+\fBlive\-persistence.conf\fP file above are unnecessary since line 3 already
+would make all of /home persistent. The \fBlink\fP 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\fP (and source directory) is
+completely disjoint from all the other custom mounts. When mounted,
+\fIVOL\fP/usr will be the rw branch due to the \fBunion\fP 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\fP/usr during the initial bootstrap.
+
+.SH "SEE ALSO"
+\fIlive\-boot\fP(7)
+.PP
+\fIlive\-build\fP(7)
+.PP
+\fIlive\-config\fP(7)
+.PP
+\fIlive\-tools\fP(7)
+
+.SH HOMEPAGE
+More information about live\-boot and the Debian Live project can be found on
+the homepage at <\fIhttp://live.debian.net/\fP> and in the manual at
+<\fIhttp://live.debian.net/manual/\fP>.
+
+.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/\fP> or by
+writing a mail to the Debian Live mailing list at
+<\fIdebian\-live@lists.debian.org\fP>.
+
+.SH AUTHOR
+live.persist was written by anonym <\fIanonym@lavabit.com\fP> for the
+Debian project.
projects / live-boot-grml.git / blobdiff