manpages/de/live-persistence.conf.de.5

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