manpages/de/live.persist.5.de.persist

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