From: Arvin Schnell Date: Mon, 10 Jun 2013 16:23:21 +0000 (+0200) Subject: - improved man-pages format X-Git-Tag: v0.1.5~24 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=f81169a2f9e6fca2ebb20ebbdc8e229bae411623;p=thirdparty%2Fsnapper.git - improved man-pages format --- diff --git a/doc/pam_snapper.xml.in b/doc/pam_snapper.xml.in index 5b404db8..7e253fd8 100644 --- a/doc/pam_snapper.xml.in +++ b/doc/pam_snapper.xml.in @@ -1,3 +1,4 @@ + @@ -8,13 +9,13 @@ pam_snapper 8 2013-05-23 - @VERSION@ + @VERSION@ Filesystem Snapshot Management pam_snapper - PAM module which creates filesystem snapshots via "Snapper" + PAM module which creates filesystem snapshots via "snapper" @@ -39,67 +40,78 @@ starting point. As many users do not logout for some time, it is a good idea, to - enable Snapper's time based snapshots in addition. + enable snapper's time based snapshots in addition. OPTIONS - + - debug + Switch on debugging in the module. - homeprefix=<prefix> + - Prefix for the name of the snapper configuration. The username will be appended to this prefix. + Prefix for the name of the snapper configuration. The username + will be appended to this prefix. Default: "home_" - ignoreservices=<comma separated list of services> + Default: "crond" - ignoreusers=<comma separated list of users> + Default: (none) - rootasroot + - Perform a snapshot using the snapper configuration "root", if the user "root" logs in. In other words: the homeprefix is not used in this case. As the snapper configuration "root" is used for the system (the root filesystem), this means that with every login of the user "root" the complete "/" filesystem will be snapshotted. This can be useful to help administrators rolling back in case their activity / configuration changes have been accidentially wrong. + Perform a snapshot using the snapper configuration "root", if + the user "root" logs in. In other words: the homeprefix is not used + in this case. As the snapper configuration "root" is used for the + system (the root filesystem), this means that with every login of + the user "root" the complete "/" filesystem will be + snapshotted. This can be useful to help administrators rolling back + in case their activity / configuration changes have been + accidentally wrong. "rootasroot" and "ignoreroot" are mutual exclusive. - ignoreroot + - No snapshot is taken, if the user "root" opens/closes a session. + No snapshot is taken, if the user "root" opens/closes a + session. "rootasroot" and "ignoreroot" are mutual exclusive. - openonly + - Only create a single snapshot when opening the PAM session. + Only create a single snapshot when opening the PAM + session. Default: create pre- and post-snapshots - closeonly + - Only create a single snapshot when closing the PAM session. + Only create a single snapshot when closing the PAM + session. Default: create pre- and post-snapshots - cleanup + Set snapper cleanup algorithm. Default: (none) @@ -115,12 +127,13 @@ RETURN VALUES - + PAM_SUCCESS - pam_snapper will always return PAM_SUCCESS, to not prevent users from login, in case a - snapshot fails. This may change in the future + pam_snapper will always return PAM_SUCCESS, to not prevent + users from login, in case a snapshot fails. This may change in the + future. @@ -129,12 +142,20 @@ EXAMPLES - Basic usage - 1. Create a btrfs subvolume for the new user, and a snapper configuration, e.g. using the tool "/usr/lib/pam_snapper/pam_snapper_useradd.sh" + + Basic usage - 2. Add the following line to /etc/pam.d/common-session: - - "session optional pam_snapper.so" + + + Create a btrfs subvolume for the new user, and a snapper + configuration, e.g. using the tool + /usr/lib/pam_snapper/pam_snapper_useradd.sh. + + + Add the following line to /etc/pam.d/common-session: + "session optional pam_snapper.so" + + @@ -151,8 +172,8 @@ - - AUTHORS and CONTRIBUTORS + + AUTHORS pam-snapper was written by Matthias G. Eckermann mge@suse.com as part of SUSE Hackweek#9 in April 2013. diff --git a/doc/snapper.xml.in b/doc/snapper.xml.in index dfd66464..81839f29 100644 --- a/doc/snapper.xml.in +++ b/doc/snapper.xml.in @@ -1,3 +1,4 @@ + @@ -8,7 +9,7 @@ snapper 8 2013-04-26 - @VERSION@ + @VERSION@ Filesystem Snapshot Management @@ -56,20 +57,33 @@ Snapshots Snapper distinguishes three types of snapshots. - pre - Pre snapshots should always have a corresponding post - snapshot. The intention of pre/post shotshot pairs is to snapshot the - filesystem before and after a modification. - - post - See pre type. - - single - These snapshots have no special relationship to other - snapshots. - + + + pre + + Pre snapshots should always have a corresponding post + snapshot. The intention of pre/post snapshot pairs is to snapshot the + filesystem before and after a modification. + + + + post + + See pre type. + + + + single + + These snapshots have no special relationship to other snapshots. + + + Note that filesystem-wise all three types are the same. - - Snapshot Description und Userdata + + Snapshot Description and Userdata With each snapshot a description and some userdata can be associated. The description is a string. The userdata is a list of key-value pairs where the @@ -79,11 +93,15 @@ Automatic Snapshot Creation Next to manual snapshot creation snapshots are also created automatically. - - cron-job - A cron-job creates hourly snapshots. - - certain programs - Certain programs like YaST and zypper create pre/post - snapshot pairs when modifying the system. + + + A cron-job creates hourly snapshots. + + + Certain programs like YaST and zypper create pre/post + snapshot pairs when modifying the system. + + @@ -94,20 +112,34 @@ corresponding configurations files along with parameters for every algorithm. - number - Deletes old snapshots when a - certain number of snapshots is reached. - - timeline - Deletes old snapshots but - keeps a number of hourly, daily, monthly and yearly snapshots. - - empty-pre-post - Deletes pre/post snapshot pairs with empty diffs. + + + number + + Deletes old snapshots when a certain number of snapshots is reached. + + + + timeline + + Deletes old snapshots but keeps a number of hourly, daily, + monthly and yearly snapshots. + + + + empty-pre-post + + Deletes pre/post snapshot pairs with empty diffs. + + + GLOBAL OPTIONS - + @@ -127,7 +159,7 @@ - + Use specified configuration instead of the default configuration. The default configuration is named "root". @@ -145,220 +177,262 @@ COMMANDS - snapper provides a number of commands. Each command accepts the options - listed in the GLOBAL OPTIONS section. These options must be specified - before the command name. In addition, many commands have specific - options, which are listed in this section. These command-specific options must - be specified after the name of the command and before any of the - command arguments. - - + + snapper provides a number of commands. Each + command accepts the options listed in the GLOBAL OPTIONS section. These options must + be specified before the command name. In addition, + many commands have specific options, which are listed in this + section. These command-specific options must be specified + after the name of the command and + before any of the command arguments. + + + - help + Show short help text. + - list-configs + List available configurations. + - create-config [options] <subvolume> + Create a new configuration for a filesystem or subvolume. For this command you - will likely need the global option , see GLOBAL OPTIONS and + will likely need the global option , see + GLOBAL OPTIONS and CONCEPTS. - - - - <fstype> - - Manually set filesystem type. Supported values are btrfs, ext4 and lvm. For - lvm snapper uses LVM thin-provisioned snapshots. The filesystem type on top of - LVM must be provided in parentheses, e.g. lvm(xfs). - Without this option snapper tries to detect the filesystem. - - - - <name> - - Name of template for the new configuration file. + + + fstype + + Manually set filesystem type. Supported values are btrfs, ext4 and lvm. For + lvm snapper uses LVM thin-provisioned snapshots. The filesystem type on top of + LVM must be provided in parentheses, e.g. lvm(xfs). + Without this option snapper tries to detect the filesystem. + + + + name + + Name of template for the new configuration file. + + + + - delete-config + - Delete a configuration for a filesystem or subvolume. For this command you - will likely need to global option , see GLOBAL OPTIONS and - CONCEPTS. + Delete a configuration for a filesystem or subvolume. For this + command you will likely need to global option + , see GLOBAL + OPTIONS and CONCEPTS. + - list [options] + List snapshots. + + + type + + Selects type of snapshots to list. Possible values are + all, single and pre-post. + + + + - <type> - - Selects type of snapshots to list. Possible values are all, single and pre-post. - - - - create [options] + Create a new snapshot. - - - - <type> - - Specifies the type of the new snapshot. Possible values are single, pre and post. - - - - <number> - - For post snapshots the number of the pre snapshot must be provided. - - - - - - Print number of the created snapshot. - - - - <description> - - Description for the snapshot. - - - - <cleanup-algorithm> - - Set the cleanup-algorithm for the snapshot. - - - - <userdata> - - Set userdata for the snapshot. The key-value pairs must be seperated by comma - and the key and value must be seperated by an equal sign, - e.g. requestid=42,user=arthur. - - - - <command> - - Create a pre and post snapshot and run command in between. - - - - modify [options] <number> + + + type + + Specifies the type of the new snapshot. Possible values + are single, pre and post. + + + + number + + For post snapshots the number of the pre snapshot must + be provided. + + + + + + Print number of the created snapshot. + + + + description + + Description for the snapshot. + + + + cleanup-algorithm + + Set the cleanup-algorithm for the snapshot. + + + + userdata + + Set userdata for the snapshot. The key-value pairs must + be separated by comma and the key and value must be separated + by an equal sign, e.g. requestid=42,user=arthur. + + + + command + + Create a pre and post snapshot and run command in between. + + + + + + + + Modify a snapshot. - - - - <description> - - New description for snapshot. - - - - <cleanup-algorithm> - - Set the cleanup-algorithm for the snapshot. - - - - <userdata> - - Set userdata for the snapshot. The key-value pairs must be seperated by comma - and the key and value must be seperated by an equal sign, - e.g. requestid=42,user=arthur. - - - - delete <number> | <number1>-<number2> + + + description + + New description for snapshot. + + + + cleanup-algorithm + + Set the cleanup-algorithm for the snapshot. + + + + userdata + + Set userdata for the snapshot. The key-value pairs must + be separated by comma and the key and value must be separated + by an equal sign, e.g. requestid=42,user=arthur. + + + + + + + + Delete a snapshot or a range of snapshots. + - mount <number> + Mount a snapshot. Not required for all filesystem types. + - umount <number> + Unmount a snapshot. Not required for all filesystem types. + - status [options] <number1>..<number2> - - Compare the snapshots number1 and number2. This will show a list of files and - directories that have been created, modified or deleted in the time between - the two snapshots have been made. - - - - <file> - - Write output to file <file>. - - - - diff [options] <number1>..<number2> [files] + - Compare the snapshots number1 and number2. This will show a diff of the - content of files and directories that have been created, modified or deleted - in the time between the two snapshots have been made. + Compare the snapshots number1 and + number2. This will show a list of files + and directories that have been created, modified or deleted in the + time between the two snapshots have been made. + + + file + + Write output to file file. + + + + - undochange [options] <number1>..<number2> [files] + - Undo changes done between snapshot number1 and number2. + Compare the snapshots number1 and + number2. This will show a diff of the + content of files and directories that have been created, modified or + deleted in the time between the two snapshots have been made. + - <file> + - Read files for which to undo changes from file <file>. + Undo changes done between snapshot number1 and number2. + + + file + + Read files for which to undo changes from file file. + + + + - cleanup <cleanup-algorithm> + - Run the cleanup algorithm <cleanup-algorithm>. Currently implemented cleanup - algorithms are number, timeline and empty-pre-post. + Run the cleanup algorithm + cleanup-algorithm. Currently implemented + cleanup algorithms are number, timeline and empty-pre-post. + - xadiff <number1>..<number2> [files] + - Compare the extended attributes. This command will genereate a report - describing the modifications that have taken place in time between the - snapshots number1 and number2 have been made. See example below: - - +:user.foo - for created attributes - -:user.bar - for removed attributes + Compare the extended attributes between snapshot + number1 and + number2. See examples below: - - for modified attributes + + + +:user.foo for created attributes + + + -:user.bar for removed attributes + + + -+:security.selinux for modified attributes + + @@ -366,16 +440,16 @@ PERMISSIONS - Non-root users can be allowed to use a configuration by setting ALLOW_USERS or - ALLOW_GROUPS in the config file. For all operations to work the user must also - be able to read and access the .snapshots directory inside the - subvolume. The .snapshots directory must be owned by root and must not be - writable by anybody else. + Non-root users can be allowed to use a configuration by setting + ALLOW_USERS or ALLOW_GROUPS in the config file. For all operations to work the + user must also be able to read and access the .snapshots + directory inside the subvolume. The .snapshots directory + must be owned by root and must not be writable by anybody else. FILES - + /etc/sysconfig/snapper @@ -411,12 +485,13 @@ NOTES - There is no mechanism to ensure consistency of the files while a snapshot it - made. E.g. the files of a database can be inconsistence while the database is - running. + There is no mechanism to ensure consistency of the files while a + snapshot it made. E.g. the files of a database can be inconsistence while + the database is running. - Consistency after undochange is not guaranteed. E.g. when the creation of a - user is undone there might still exist files from that user. + Consistency after undochange is not guaranteed. E.g. when the + creation of a user is undone there might still exist files from that + user. Support for extended attributes is a compile-time option. diff --git a/doc/snapperd.xml.in b/doc/snapperd.xml.in index 7520738b..e92f4ccc 100644 --- a/doc/snapperd.xml.in +++ b/doc/snapperd.xml.in @@ -1,3 +1,4 @@ + @@ -8,7 +9,7 @@ snapperd 8 2012-10-15 - @VERSION@ + @VERSION@ Filesystem Snapshot Management