Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Correcting left-over in author section of live.persist manpage.
- Loading branch information
1 parent
d15a400
commit a39a167
Showing
13 changed files
with
1,389 additions
and
123 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,210 @@ | ||
.\"******************************************************************* | ||
.\" | ||
.\" This file was generated with po4a. Translate the source file. | ||
.\" | ||
.\"******************************************************************* | ||
.TH LIVE\-BOOT persist 05.04.2012 3.0~a25\-1 "Debian Live Projekt" | ||
|
||
.SH NAME | ||
\fBlive.persist\fP \- Configuration file for persistent media in live\-boot | ||
|
||
.SH BESCHREIBUNG | ||
If live\-boot probes a persistent 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\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.persist\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 persistent 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 persistent 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.persist\fP are ordered, or if several | ||
\fBlive.persist\fP files on different persistent 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 persistent 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 persistent media. The bootstrapping will not happen when the | ||
\fBlinkfiles\fP or \fBunion\fP options are used (see below). | ||
|
||
.SH OPTIONEN | ||
Custom mounts defined in \fBlive.persist\fP accept the following options in a | ||
coma\-separated list: | ||
.IP \fBsource\fP=\fIPATH\fP 4 | ||
When given, store the persistent changes into \fIPATH\fP on the persistent | ||
media. \fIPATH\fP must be a relative path (w.r.t. the persistent 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 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 \fBlinkfiles\fP 4 | ||
Create the directory structure of the source directory on the persistent | ||
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 \fBlinkfiles\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 persistent 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/persistent\fP 4 | ||
All persistent volumes will be mounted here (in a directory corresponding to | ||
the device name). The \fBlive.persist\fP file can easily be edited through this | ||
mount, as well as any source directories (which is especially practical for | ||
custom mounts using the \fBlinkfiles\fP option). | ||
|
||
.SH EXAMPLES | ||
|
||
Let's say we have a persistent volume \fIVOL\fP with the a \fBlive.persist\fP file | ||
containing the following four lines (numbered for ease of reference): | ||
.TP 7 | ||
1. | ||
/home/user1 linkfiles,source=config\-files/user1 | ||
.TP | ||
2. | ||
/home/user2 linkfiles,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 illegal. | ||
.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.persist\fP | ||
file above are unnecessary since line 3 already would make all of /home | ||
persistent. The \fBlinkfiles\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 "SIEHE AUCH" | ||
\fIlive\-boot\fP(7) | ||
.PP | ||
\fIlive\-build\fP(7) | ||
.PP | ||
\fIlive\-config\fP(7) | ||
.PP | ||
\fIlive\-tools\fP(7) | ||
|
||
.SH HOMEPAGE | ||
Weitere Informationen ueber live\-boot und das Debian Live Projekt koennen | ||
auf der Homepage unter <\fIhttp://live.debian.net/\fP> und im Handbuch | ||
unter <\fIhttp://live.debian.net/manual/\fP> gefunden werden. | ||
|
||
.SH FEHLER | ||
Fehler koennen durch Einreichen eines Fehlerberichtes fuer das live\-boot | ||
Paket im Debian Bug Tracking System unter | ||
<\fIhttp://bugs.debian.org/\fP> oder durch Senden einer E\-Mail an die | ||
Debian Live Mailing Liste unter <\fIdebian\-live@lists.debian.org\fP> | ||
(englischsprachig) mitgeteilt werden. | ||
|
||
.SH AUTOR | ||
live.persist was written by anonym <\fIanonym@lavabit.com\fP> for the | ||
Debian project. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.