manpages/en/persistence.conf.5

   1 .TH LIVE\-BOOT conf 2013\-01\-02 4.0~a4-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 coma-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, but is not supported with
 100 \fBunion=unionmount\fR.
 101
 102 .SH DIRECTORIES
 103 .IP "\fB/live/persistence\fR" 4
 104 All persistence volumes will be mounted here (in a directory
 105 corresponding to the device name). The \fBpersistence.conf\fR file can
 106 easily be edited through this mount, as well as any source directories
 107 (which is especially practical for custom mounts using the
 108 \fBlink\fR option).
 109
 110 .SH EXAMPLES
 111
 112 Let's say we have a persistence volume \fIVOL\fR with the a
 113 \fBpersistence.conf\fR file containing the following four lines (numbered
 114 for ease of reference):
 115 .TP 7
 116 1.
 117 /home/user1 link,source=config-files/user1
 118 .TP
 119 2.
 120 /home/user2 link,source=config-files/user2
 121 .TP
 122 3.
 123 /home
 124 .TP
 125 4.
 126 /usr union
 127 .PP
 128 The corresponding source directories are:
 129 .TP 7
 130 1.
 131 \fIVOL\fR/config-files/user1 (but it would be \fIVOL\fR/home/user1
 132 without the \fBsource\fR option)
 133 .TP
 134 2.
 135 \fIVOL\fR/config-files/user2 (but it would be \fIVOL\fR/home/user2
 136 without the \fBsource\fR option)
 137 .TP
 138 3.
 139 \fIVOL\fR/home
 140 .TP
 141 4.
 142 \fIVOL\fR/usr
 143 .PP
 144 It was necessary to set the \fBsource\fR options for 1 and 2, since
 145 they otherwise would become nested with 3's source, which is invalid.
 146 .PP
 147 Line 3 will be taken care of before line 1 and 2 in order to prevent
 148 custom mounts 1 and 2 from being hidden by 3. When line 3 is handled,
 149 \fIVOL\fR/home is simply bind-mounted on /home. To illustrate what
 150 happens for lines 1 and 2, let's say that the following files exist:
 151 .TP 7
 152 a.
 153 \fIVOL\fR/config-files/user1/.emacs
 154 .TP
 155 b.
 156 \fIVOL\fR/config-files/user2/.bashrc
 157 .TP
 158 c.
 159 \fIVOL\fR/config-files/user2/.ssh/config
 160 .PP
 161 Then the following links and directories will be created:
 162 .TP 7
 163 Link:
 164 /home/user1/.emacs -> \fIVOL\fR/config-files/user1/.emacs (from a)
 165 .TP
 166 Link:
 167 /home/user2/.bashrc -> \fIVOL\fR/config-files/user2/.bashrc (from b)
 168 .TP
 169 Dir:
 170 /homea/user2/.ssh (from c)
 171 .TP
 172 Link:
 173 /home/user2/.ssh/config -> \fIVOL\fR/config-files/user2/.ssh/config
 174 (from c)
 175 .PP
 176 One could argue, though, that lines 1 and 2 in the example
 177 \fBpersistence.conf\fR file above are unnecessary since line 3 already
 178 would make all of /home persistent. The \fBlink\fR option is
 179 intended for situations where you don't want a complete directory to
 180 be persistent, only certain files in it or its sub-directories.
 181 .PP
 182 Line 4 can be mounted at any time since its \fIDIR\fR (and source
 183 directory) is completely disjoint from all the other custom
 184 mounts. When mounted, \fIVOL\fR/usr will be the rw branch due to the
 185 \fBunion\fR option, and will only contain the difference compared to
 186 the underlying read-only file system. Hence packages could be
 187 installed into /usr with great space-wise efficiency compared to
 188 bind-mounts, since in the latter case all of /usr would have to be
 189 copied into \fIVOL\fR/usr during the initial bootstrap.
 190
 191 .SH SEE ALSO
 192 \fIlive\-boot\fR(7)
 193 .PP
 194 \fIlive\-build\fR(7)
 195 .PP
 196 \fIlive\-config\fR(7)
 197 .PP
 198 \fIlive\-tools\fR(7)
 199
 200 .SH HOMEPAGE
 201 More information about live\-boot and the Debian Live project can be
 202 found on the homepage at <\fIhttp://live.debian.net/\fR> and in the
 203 manual at <\fIhttp://live.debian.net/manual/\fR>.
 204
 205 .SH BUGS
 206 Bugs can be reported by submitting a bugreport for the live\-boot
 207 package in the Debian Bug Tracking System at
 208 <\fIhttp://bugs.debian.org/\fR> or by writing a mail to the Debian
 209 Live mailing list at <\fIdebian-live@lists.debian.org\fR>.
 210
 211 .SH AUTHOR
 212 persistence.conf was written by anonym <\fIanonym@lavabit.com\fR> for the
 213 Debian project.