| 1 |
.TH LIVE\-BOOT 5 2015\-09\-22 5.0~a5-1 "Debian Live Project" |
| 2 |
|
| 3 |
.SH NAME |
| 4 |
\fBpersistence.conf\fR \- Configuration file for persistence media in |
| 5 |
live\-boot |
| 6 |
|
| 7 |
.SH DESCRIPTION |
| 8 |
If live-boot probes a persistence volume with the label (or GPT name, |
| 9 |
or file name, but from now on we will just say "label") "persistence", |
| 10 |
that volume's persistence is fully customizable through the |
| 11 |
\fBpersistence.conf\fR file stored on the root of its file system. Any such |
| 12 |
labeled volume must have such a file, or it will be ignored. |
| 13 |
.PP |
| 14 |
The format of \fBpersistence.conf\fR allows empty lines and lines starting |
| 15 |
with a "#" (used for comments), both which will be ignored. A so |
| 16 |
called "custom mount" has the format: |
| 17 |
.PP |
| 18 |
.RS |
| 19 |
\fIDIR\fR [\fIOPTION\fR]... |
| 20 |
.RE |
| 21 |
.PP |
| 22 |
which roughly translates to "make \fIDIR\fR persistence in the way |
| 23 |
described by the list of \fIOPTION\fRs". |
| 24 |
.PP |
| 25 |
For each custom mount \fIDIR\fR must be an absolute path that cannot |
| 26 |
contain white spaces or the special . and .. path components, and |
| 27 |
cannot be /live (or any of its sub-directories). |
| 28 |
Once activated all changes (file |
| 29 |
deletion, creation and modification) to \fIDIR\fR on the live file |
| 30 |
system are stored persistently into a path equivalent to \fIDIR\fR on |
| 31 |
the persistence media, called the source directory. The default way to |
| 32 |
achieve persistence is to simply bind-mount the corresponding source |
| 33 |
directory to \fIDIR\fR, but this can be changed through the use of |
| 34 |
\fIOPTION\fRs. |
| 35 |
.PP |
| 36 |
All custom mounts will be done in an order so that no two custom |
| 37 |
mounts can "hide" each other. For instance, if we have the two |
| 38 |
\fIDIR\fR:s /a and /a/b it would always be the case that /a is mounted |
| 39 |
first, then /a/b. This remains true no matter how the lines in |
| 40 |
\fBpersistence.conf\fR are ordered, or if several \fBpersistence.conf\fR files |
| 41 |
on different persistence media are used at the same time. However, it |
| 42 |
is forbidden for custom mounts to have their source directory inside |
| 43 |
the source directory of another custom mount, so the source |
| 44 |
directories that are auto-created by live-boot does not support |
| 45 |
"nested" mounts like /a and /a/b on the same media. In this case you |
| 46 |
must use the \fBsource\fR option (see below) to make sure that they |
| 47 |
are stored in different source directories. |
| 48 |
.PP |
| 49 |
When a source directory doesn't exist on the persistence media for a |
| 50 |
certain custom mount, it will be created automatically, and |
| 51 |
permissions and ownership will be optimistically set according to |
| 52 |
\fIDIR\fR. It will also be bootstrapped by copying the contents of the |
| 53 |
\fIDIR\fR into its source directory on the persistence media. The |
| 54 |
bootstrapping will not happen when the \fBlink\fR or \fBunion\fR |
| 55 |
options are used (see below). |
| 56 |
|
| 57 |
.SH OPTIONS |
| 58 |
Custom mounts defined in \fBpersistence.conf\fR accept the following |
| 59 |
options in a comma-separated list: |
| 60 |
.IP "\fBsource\fR=\fIPATH\fR" 4 |
| 61 |
When given, store the persistence changes into \fIPATH\fR on the |
| 62 |
persistence media. \fIPATH\fR must be a relative path (with respect to the |
| 63 |
persistence media root) that cannot contain white spaces or the |
| 64 |
special . or .. path components, with the exception that it can be |
| 65 |
just . which means the persistence media root. This option is mostly |
| 66 |
relevant if you want to nest custom mounts, which otherwise would |
| 67 |
cause errors, or if you want to make the whole media root available |
| 68 |
(similar to the now deprecated \fBhome-rw\fR type of persistence). |
| 69 |
.PP |
| 70 |
The following options are mutually exclusive (only the last given one |
| 71 |
will be in effect): |
| 72 |
.IP "\fBbind\fR" 4 |
| 73 |
Bind-mount the source directory to \fIDIR\fR. This is the default. |
| 74 |
.IP "\fBlink\fR" 4 |
| 75 |
Create the directory structure of the source directory on the |
| 76 |
persistence media in \fIDIR\fR and create symbolic links from the |
| 77 |
corresponding place in \fIDIR\fR to each file in the source directory. |
| 78 |
Existing files or directories with the same name as any link will be |
| 79 |
overwritten. Note that deleting the links in \fIDIR\fR will only |
| 80 |
remove the link, not the corresponding file in the source; removed |
| 81 |
links will reappear after a reboot. To permanently add or delete a |
| 82 |
file one must do so directly in the source directory. |
| 83 |
.IP |
| 84 |
Effectively \fBlink\fR will make only files already in the source |
| 85 |
directory persistent, not any other files in \fIDIR\fR. These files |
| 86 |
must be manually added to the source directory to make use of this |
| 87 |
option, and they will appear in \fIDIR\fR in addition to files already |
| 88 |
there. This option is useful when only certain files need to be |
| 89 |
persistent, not the whole directory they're in, e.g. some |
| 90 |
configuration files in a user's home directory. |
| 91 |
.IP "\fBunion\fR" 4 |
| 92 |
Save the rw branch of a union on the persistence media, so only the |
| 93 |
changes are stored persistently. This can potentially reduce disk |
| 94 |
usage compared to bind-mounts, and will not hide files added to the |
| 95 |
read-only media. One caveat is that the union will use \fIDIR\fR from |
| 96 |
the image's read-only file system, not the real file system root, so |
| 97 |
files created after boot (e.g. by live-config) will not appear in the |
| 98 |
union. This option will use the union file system specified by |
| 99 |
live-boot's \fBunion\fR boot parameter. |
| 100 |
|
| 101 |
.SH DIRECTORIES |
| 102 |
.IP "\fB/live/persistence\fR" 4 |
| 103 |
All persistence volumes will be mounted here (in a directory |
| 104 |
corresponding to the device name). The \fBpersistence.conf\fR file can |
| 105 |
easily be edited through this mount, as well as any source directories |
| 106 |
(which is especially practical for custom mounts using the |
| 107 |
\fBlink\fR option). |
| 108 |
|
| 109 |
.SH EXAMPLES |
| 110 |
|
| 111 |
Let's say we have a persistence volume \fIVOL\fR with the a |
| 112 |
\fBpersistence.conf\fR file containing the following four lines (numbered |
| 113 |
for ease of reference): |
| 114 |
.TP 7 |
| 115 |
1. |
| 116 |
/home/user1 link,source=config-files/user1 |
| 117 |
.TP |
| 118 |
2. |
| 119 |
/home/user2 link,source=config-files/user2 |
| 120 |
.TP |
| 121 |
3. |
| 122 |
/home |
| 123 |
.TP |
| 124 |
4. |
| 125 |
/usr union |
| 126 |
.PP |
| 127 |
The corresponding source directories are: |
| 128 |
.TP 7 |
| 129 |
1. |
| 130 |
\fIVOL\fR/config-files/user1 (but it would be \fIVOL\fR/home/user1 |
| 131 |
without the \fBsource\fR option) |
| 132 |
.TP |
| 133 |
2. |
| 134 |
\fIVOL\fR/config-files/user2 (but it would be \fIVOL\fR/home/user2 |
| 135 |
without the \fBsource\fR option) |
| 136 |
.TP |
| 137 |
3. |
| 138 |
\fIVOL\fR/home |
| 139 |
.TP |
| 140 |
4. |
| 141 |
\fIVOL\fR/usr |
| 142 |
.PP |
| 143 |
It was necessary to set the \fBsource\fR options for 1 and 2, since |
| 144 |
they otherwise would become nested with 3's source, which is invalid. |
| 145 |
.PP |
| 146 |
Line 3 will be taken care of before line 1 and 2 in order to prevent |
| 147 |
custom mounts 1 and 2 from being hidden by 3. When line 3 is handled, |
| 148 |
\fIVOL\fR/home is simply bind-mounted on /home. To illustrate what |
| 149 |
happens for lines 1 and 2, let's say that the following files exist: |
| 150 |
.TP 7 |
| 151 |
a. |
| 152 |
\fIVOL\fR/config-files/user1/.emacs |
| 153 |
.TP |
| 154 |
b. |
| 155 |
\fIVOL\fR/config-files/user2/.bashrc |
| 156 |
.TP |
| 157 |
c. |
| 158 |
\fIVOL\fR/config-files/user2/.ssh/config |
| 159 |
.PP |
| 160 |
Then the following links and directories will be created: |
| 161 |
.TP 7 |
| 162 |
Link: |
| 163 |
/home/user1/.emacs -> \fIVOL\fR/config-files/user1/.emacs (from a) |
| 164 |
.TP |
| 165 |
Link: |
| 166 |
/home/user2/.bashrc -> \fIVOL\fR/config-files/user2/.bashrc (from b) |
| 167 |
.TP |
| 168 |
Dir: |
| 169 |
/home/user2/.ssh (from c) |
| 170 |
.TP |
| 171 |
Link: |
| 172 |
/home/user2/.ssh/config -> \fIVOL\fR/config-files/user2/.ssh/config |
| 173 |
(from c) |
| 174 |
.PP |
| 175 |
One could argue, though, that lines 1 and 2 in the example |
| 176 |
\fBpersistence.conf\fR file above are unnecessary since line 3 already |
| 177 |
would make all of /home persistent. The \fBlink\fR option is |
| 178 |
intended for situations where you don't want a complete directory to |
| 179 |
be persistent, only certain files in it or its sub-directories. |
| 180 |
.PP |
| 181 |
Line 4 can be mounted at any time since its \fIDIR\fR (and source |
| 182 |
directory) is completely disjoint from all the other custom |
| 183 |
mounts. When mounted, \fIVOL\fR/usr will be the rw branch due to the |
| 184 |
\fBunion\fR option, and will only contain the difference compared to |
| 185 |
the underlying read-only file system. Hence packages could be |
| 186 |
installed into /usr with great space-wise efficiency compared to |
| 187 |
bind-mounts, since in the latter case all of /usr would have to be |
| 188 |
copied into \fIVOL\fR/usr during the initial bootstrap. |
| 189 |
|
| 190 |
.SH SEE ALSO |
| 191 |
\fIlive\-boot\fR(7) |
| 192 |
.PP |
| 193 |
\fIlive\-build\fR(7) |
| 194 |
.PP |
| 195 |
\fIlive\-config\fR(7) |
| 196 |
.PP |
| 197 |
\fIlive\-tools\fR(7) |
| 198 |
|
| 199 |
.SH HOMEPAGE |
| 200 |
More information about live\-boot and the Debian Live project can be found on the homepage at <\fIhttps://wiki.debian.org/DebianLive\fR> and in the manual at <\fIhttps://live-team.pages.debian.net/live-manual/\fR>. |
| 201 |
|
| 202 |
.SH BUGS |
| 203 |
Bugs can be reported by submitting a bugreport for the live\-boot package in the Bug Tracking System at <\fIhttp://bugs.debian.org/\fR> or by writing a mail to the Debian Live mailing list at <\[email protected]\fR>. |
| 204 |
|
| 205 |
.SH AUTHOR |
| 206 |
live\-boot was originally written by Daniel Baumann <\[email protected]\fR>. Since 2016 development has been continued by the Debian Live team. |