From 315900ea66904606c7a5d92cf46d590fa00b12a6 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 8 Apr 2012 19:38:47 +0200 Subject: Renaming live.persist to live-persistence.conf. --- manpages/de/live-boot.de.7 | 21 ++-- manpages/de/live-persistence.conf.de.5 | 211 +++++++++++++++++++++++++++++++++ manpages/de/live.persist.5.de.persist | 209 -------------------------------- 3 files changed, 224 insertions(+), 217 deletions(-) create mode 100644 manpages/de/live-persistence.conf.de.5 delete mode 100644 manpages/de/live.persist.5.de.persist (limited to 'manpages/de') diff --git a/manpages/de/live-boot.de.7 b/manpages/de/live-boot.de.7 index 85cd150..27ad650 100644 --- a/manpages/de/live-boot.de.7 +++ b/manpages/de/live-boot.de.7 @@ -95,6 +95,10 @@ Target Lun 0 Path=,Type=fileio,IOMode=ro # If you want to boot multiple machines you might want to look at tuning some parameters like # Wthreads or MaxConnections +.IP \fBfindiso\fP=\fI/PATH/TO/IMAGE\fP 4 +Look for the specified ISO file on all disks where it usually looks for the +\&.squashfs file (so you don't have to know the device name as in +fromiso=....). .IP \fBfromiso\fP=\fI/PATH/TO/IMAGE\fP 4 Allows to use a filesystem from within an iso image that's available on live\-media. @@ -177,12 +181,13 @@ live\-boot will probe devices for persistence media. These can be partitions (with the correct GPT name), filesystems (with the correct label) or image/archive files (with the correct file name). Overlays are labeled/named either "full\-ov", which will be mounted on /, or "custom\-ov", which can be -completely customized (see \fIlive.persist\fP(5)); snapshots are labeled/named -either "live\-sn" or "home\-sn" and will be extracted into / or /home, -respectively (see \fIlive\-snapshot\fP(1) for more information). The order these -are handled are: full\-ov, custom\-ov, live\-sn, home\-sn. Overlay image files -and snapshot archive files have extensions which determines their filesystem -or archive type, e.g. "custom\-ov.ext4" and "\home\-sn.squashfs". +completely customized (see \fIlive\-persistence.conf\fP(5)); snapshots are +labeled/named either "live\-sn" or "home\-sn" and will be extracted into / or +/home, respectively (see \fIlive\-snapshot\fP(1) for more information). The +order these are handled are: full\-ov, custom\-ov, live\-sn, home\-sn. Overlay +image files and snapshot archive files have extensions which determines +their filesystem or archive type, e.g. "custom\-ov.ext4" and +"\home\-sn.squashfs". .IP "\fBpersistence\-encryption\fP=\fITYPE1\fP,\fITYPE2\fP ... \fITYPEn\fP" 4 This option determines which types of encryption that we allow to be used when probing devices for persistence media. If "none" is in the list, we @@ -276,12 +281,12 @@ directory with a tmpfs on the original path. .IP \fB/etc/live/boot.d/*.conf\fP 4 .IP \fBlive/boot.conf\fP 4 .IP \fBlive/boot.d/*.conf\fP 4 -.IP \fBlive.persist\fP 4 +.IP \fBlive\-persistence.conf\fP 4 .SH "SEE ALSO" \fIlive\-snapshot\fP(1) .PP -\fIlive.persist\fP(5) +\fIlive\-persistence.conf\fP(5) .PP \fIlive\-build\fP(7) .PP diff --git a/manpages/de/live-persistence.conf.de.5 b/manpages/de/live-persistence.conf.de.5 new file mode 100644 index 0000000..73b45be --- /dev/null +++ b/manpages/de/live-persistence.conf.de.5 @@ -0,0 +1,211 @@ +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH LIVE\-BOOT conf 2012\-04\-08 3.0~a26\-1 "Debian Live Project" + +.SH NAME +\fBlive\-persistence.conf\fP \- Configuration file for persistence media in +live\-boot + +.SH DESCRIPTION +If live\-boot probes a persistence 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\-persistence.conf\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\-persistence.conf\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 persistence 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 persistence 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\-persistence.conf\fP are ordered, or if +several \fBlive\-persistence.conf\fP files on different persistence 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 persistence 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 persistence 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\-persistence.conf\fP accept the following +options in a coma\-separated list: +.IP \fBsource\fP=\fIPATH\fP 4 +When given, store the persistence changes into \fIPATH\fP on the persistence +media. \fIPATH\fP must be a relative path (w.r.t. the persistence media root) +that cannot contain white spaces or the special . or .. path components, +with the exception that it can be just . which means the persistence 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 persistence +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 persistence 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/persistence\fP 4 +All persistence volumes will be mounted here (in a directory corresponding +to the device name). The \fBlive\-persistence.conf\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 persistence volume \fIVOL\fP with the a +\fBlive\-persistence.conf\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 invalid. +.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\-persistence.conf\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. diff --git a/manpages/de/live.persist.5.de.persist b/manpages/de/live.persist.5.de.persist deleted file mode 100644 index e7a09f9..0000000 --- a/manpages/de/live.persist.5.de.persist +++ /dev/null @@ -1,209 +0,0 @@ -.\"******************************************************************* -.\" -.\" This file was generated with po4a. Translate the source file. -.\" -.\"******************************************************************* -.TH LIVE\-BOOT persist 2012\-04\-08 3.0~a26\-1 "Debian Live Project" - -.SH NAME -\fBlive.persist\fP \- Configuration file for persistence media in live\-boot - -.SH DESCRIPTION -If live\-boot probes a persistence 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 persistence 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 persistence 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 persistence 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 persistence 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 persistence 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 persistence changes into \fIPATH\fP on the persistence -media. \fIPATH\fP must be a relative path (w.r.t. the persistence media root) -that cannot contain white spaces or the special . or .. path components, -with the exception that it can be just . which means the persistence 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 persistence -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 persistence 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/persistence\fP 4 -All persistence 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 persistence 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 invalid. -.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. -- cgit v1.2.3