manpages/de/persistence.conf.de.5

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