/
live.persist.5.de.persist
209 lines (199 loc) · 8.52 KB
/
live.persist.5.de.persist
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH LIVE\-BOOT persist 2012\-04\-05 3.0~a26\-1 "Debian Live Project"
.SH NAME
\fBlive.persist\fP \- Configuration file for persistent media in live\-boot
.SH DESCRIPTION
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 OPTIONS
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 "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.