From: Arvin Schnell Date: Thu, 6 Jun 2013 12:20:05 +0000 (+0200) Subject: - converted man-pages to docbook sgml X-Git-Tag: v0.1.5~36 X-Git-Url: http://git.ipfire.org/gitweb/index.cgi?a=commitdiff_plain;h=a3aaa659be201495ef5de5ee6860b94d4178f5f1;p=thirdparty%2Fsnapper.git - converted man-pages to docbook sgml --- diff --git a/configure.ac b/configure.ac index 21671ee1..58dd8743 100644 --- a/configure.ac +++ b/configure.ac @@ -130,9 +130,9 @@ AC_OUTPUT( pam/Makefile data/Makefile doc/Makefile - doc/snapper.8:doc/snapper.8.in - doc/snapperd.8:doc/snapperd.8.in - doc/pam_snapper.8:doc/pam_snapper.8.in + doc/snapper.sgml:doc/snapper.sgml.in + doc/snapperd.sgml:doc/snapperd.sgml.in + doc/pam_snapper.sgml:doc/pam_snapper.sgml.in po/Makefile testsuite-real/Makefile testsuite-cmp/Makefile diff --git a/doc/.gitignore b/doc/.gitignore index ba04924b..bad66391 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,3 +1,8 @@ +snapper.sgml +snapperd.sgml +pam_snapper.sgml snapper.8 snapperd.8 pam_snapper.8 +manpage.links +manpage.refs diff --git a/doc/Makefile.am b/doc/Makefile.am index d0098870..d9dbdc42 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -8,7 +8,10 @@ if HAVE_PAM man_MANS += pam_snapper.8 endif +.sgml.8: .sgml + docbook2man $< + TXTS = dbus-protocol.txt -EXTRA_DIST = $(man_MANS) $(TXTS) +EXTRA_DIST = $(TXTS) diff --git a/doc/pam_snapper.8.in b/doc/pam_snapper.8.in deleted file mode 100644 index 821586ed..00000000 --- a/doc/pam_snapper.8.in +++ /dev/null @@ -1,233 +0,0 @@ -.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20) -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. \*(C+ will -.\" give a nicer C++. Capital omega is used to do unbreakable dashes and -.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, -.\" nothing in troff, for use with C<>. -.tr \(*W- -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" Escape single quotes in literal strings from groff's Unicode transform. -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.ie \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.el \{\ -. de IX -.. -.\} -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "PAM_SNAPPER 8" -.TH "PAM_SNAPPER" "8" "2013-05-23" "@VERSION@" "Filesystem Snapshot Management" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.if n .ad l -.nh -.SH "NAME" -pam_snapper \- PAM module which creates filesystem snapshots via "Snapper" -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -pam_snapper.so [debug] [homeprefix=<>] [ignoreservices=<>] [ignoreusers=<>] [rootasroot] [ignoreroot] [openonly] [closeonly] [cleanup=<>] -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -Create a snapshot at every login of a User, thus he or she always have a save starting point. -.PP -As many users do not logout for some time, it is a good idea, to enable Snapper's time based snapshots in addition. -.SH "OPTIONS" -.IX Header "OPTIONS" -.IP "debug" 4 -.IX Item "debug" -Switch on debugging in the module. -.IP "homeprefix=" 4 -.IX Item "homeprefix=" -Prefix for the name of the snapper configuration. The username will be appended to this prefix. -.Sp -Default: \*(L"home_\*(R" -.IP "ignoreservices=" 4 -.IX Item "ignoreservices=" -Default: \*(L"crond\*(R" -.IP "ignoreusers=" 4 -.IX Item "ignoreusers=" -Default: (none) -.IP "rootasroot" 4 -.IX Item "rootasroot" -Perform a snapshot using the snapper configuration \*(L"root\*(R", if the user \*(L"root\*(R" logs in. In other words: the homeprefix is not used in this case. As the snapper configuration \*(L"root\*(R" is used for the system (the root filesystem), this means that with every login of the user \*(L"root\*(R" the complete \*(L"/\*(R" filesystem will be snapshotted. This can be useful to help administrators rolling back in case their activity / configuration changes have been accidentially wrong. -.Sp -\&\*(L"rootasroot\*(R" and \*(L"ignoreroot\*(R" are mutual exclusive. -.IP "ignoreroot" 4 -.IX Item "ignoreroot" -No snapshot is taken, if the user \*(L"root\*(R" opens/closes a session. -.Sp -\&\*(L"rootasroot\*(R" and \*(L"ignoreroot\*(R" are mutual exclusive. -.IP "openonly" 4 -.IX Item "openonly" -Only create a single snapshot when opening the \s-1PAM\s0 session. -.Sp -Default: create pre\- and post-snapshots -.IP "closeonly" 4 -.IX Item "closeonly" -Only create a single snapshot when closing the \s-1PAM\s0 session. -.Sp -Default: create pre\- and post-snapshots -.IP "cleanup" 4 -.IX Item "cleanup" -Set snapper cleanup algorithm. -.Sp -Default: (none) -.SH "MODULE TYPES PROVIDED" -.IX Header "MODULE TYPES PROVIDED" -Only the module type \*(L"session\*(R" is provided. -.SH "RETURN VALUES" -.IX Header "RETURN VALUES" -.IP "\s-1PAM_SUCCESS\s0" 4 -.IX Item "PAM_SUCCESS" -pam_snapper will always return \s-1PAM_SUCCESS\s0, to not prevent users from login, in case a snapshot fails. This may change in the future -.SH "EXAMPLES" -.IX Header "EXAMPLES" -.SS "Basic usage" -.IX Subsection "Basic usage" -1. Create a btrfs subvolume for the new user, and a snapper configuration, e.g. using the tool \*(L"/usr/lib/pam_snapper/pam_snapper_useradd.sh\*(R" -.PP -2. Add the following line to /etc/pam.d/common\-session: -.PP -\&\*(L"session optional pam_snapper.so\*(R" -.SH "SEE ALSO" -.IX Header "SEE ALSO" -snapper(8), pam.conf(5), pam(8), pam_snapper_homeconvert, pam_snapper_pamconfig, pam_snapper_useradd, pam_snapper_userdel -.SH "AUTHORS and CONTRIBUTORS" -.IX Header "AUTHORS and CONTRIBUTORS" -pam-snapper was written by Matthias G. Eckermann -as part of \s-1SUSE\s0 Hackweek#9 in April 2013. -.PP -This module would not have been possible without the work of -Arvin Schnell on the snapper project. pam-snapper inherits -\&\s-1DBUS\s0 handling from \*(L"snapper_dbus_cli.c\*(R" by David Disseldorp. -.PP -The module builds on the Linux \s-1PAM\s0 stack and its -documentation, written by Thorsten Kukuk. -.SH "LICENSE" -.IX Header "LICENSE" -Copyright (c) 2013 \s-1SUSE\s0 -.PP -All Rights Reserved. -.PP -This program is free software; you can redistribute it and/or modify -it under the terms of version 2 of the \s-1GNU\s0 General Public License as -published by the Free Software Foundation. -.PP -This program is distributed in the hope that it will be useful, but -\&\s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of -\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. See the \s-1GNU\s0 -General Public License for more details. -.PP -You should have received a copy of the \s-1GNU\s0 General Public License -along with this program; if not, contact \s-1SUSE\s0. -.PP -To contact \s-1SUSE\s0 about this file by physical or electronic mail, you -may find current contact information at www.suse.com. diff --git a/doc/pam_snapper.sgml.in b/doc/pam_snapper.sgml.in new file mode 100644 index 00000000..f0966692 --- /dev/null +++ b/doc/pam_snapper.sgml.in @@ -0,0 +1,192 @@ + + + + + 2013-05-23 + + pam_snapper + 8 + 2013-05-23 + @VERSION@ + Filesystem Snapshot Management + + + pam_snapper + PAM module which creates filesystem snapshots via "Snapper" + + + + + pam_snapper.so debug + homeprefix=<> + ignoreservices=<> + ignoreusers=<> + rootasroot + ignoreroot + openonly + closeonly + cleanup=<> + + + + + DESCRIPTION + + Create a snapshot at every login of a User, thus he or she always have a save + 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. + + + + 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. + + 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. + + "rootasroot" and "ignoreroot" are mutual exclusive. + + + + ignoreroot + + 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. + + Default: create pre- and post-snapshots + + + + closeonly + + Only create a single snapshot when closing the PAM session. + + Default: create pre- and post-snapshots + + + + cleanup + + Set snapper cleanup algorithm. + + Default: (none) + + + + + + + MODULE TYPES PROVIDED + Only the module type "session" is provided. + + + + 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 + + + + + + + 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" + + 2. Add the following line to /etc/pam.d/common-session: + + "session optional pam_snapper.so" + + + + + SEE ALSO + + snapper8, + pam.conf5, + pam8, + pam_snapper_homeconvert, + pam_snapper_pamconfig, + pam_snapper_useradd, + pam_snapper_userdel + + + + + AUTHORS and CONTRIBUTORS + pam-snapper was written by Matthias G. Eckermann mge@suse.com + as part of SUSE Hackweek#9 in April 2013. + + This module would not have been possible without the work of Arvin + Schnell on the snapper project. pam-snapper inherits DBUS handling from + "snapper_dbus_cli.c" by David Disseldorp. + + The module builds on the Linux PAM stack and its documentation, + written by Thorsten Kukuk. + + + + LICENSE + Copyright (c) 2013 SUSE + + All Rights Reserved. + + This program is free software; you can redistribute it and/or modify + it under the terms of version 2 of the GNU General Public License as published + by the Free Software Foundation. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY without even the implied warranty of MERCHANTABILITY or + FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more + details. + + You should have received a copy of the GNU General Public License + along with this program; if not, contact SUSE. + + To contact SUSE about this file by physical or electronic mail, you + may find current contact information at www.suse.com. + + + diff --git a/doc/snapper.8.in b/doc/snapper.8.in deleted file mode 100644 index 081bb71a..00000000 --- a/doc/snapper.8.in +++ /dev/null @@ -1,283 +0,0 @@ -.TH "SNAPPER" "8" "2013-04-26" "@VERSION@" "Filesystem Snapshot Management" -.SH "NAME" -.LP -snapper - Command\-line program for filesystem snapshot management - -.SH "SYNTAX" -.LP -snapper [\fI\-\-global\-opts\fR] <\fBcommand\fR> [\fI\-\-command\-opts\fR] -[\fBcommand-arguments\fR] - -snapper --help - -.SH "DESCRIPTION" -.LP -Snapper is a command\-line program for filesystem snapshot management. It can -create, delete and compare snapshots and undo changes done between snapshots. -.LP -Snapper never modifies the content of snapshots. Thus snapper creates -read-only snapshots if supported by the kernel. Supported filesystems are -btrfs and ext4 as well as snapshots of LVM logical volumes with -thin-provisioning. Some filesystems might not be supported depending on your -installation. - -.SH CONCEPTS - -.SS Configurations -.LP -For each filesystem or subvolume that should be snapshotted by snapper a -configuration file is required. The complete setup can be done with the -create-config command. - -.SS Snapshots -.LP -Snapper distinguishes three types of snapshots. -.LP -\fBpre\fR - 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. -.LP -\fBpost\fR - See pre type. -.LP -\fBsingle\fR - These snapshots have no special relationship to other -snapshots. -.LP -Note that filesystem\-wise all three types are the same. - -.SS Snapshot Description und Userdata -.LP -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 -keys and values are strings. - -.SS Automatic Snapshot Creation -Next to manual snapshot creation snapshots are also created automatically. -.LP -\fBcron\-job\fR - A cron\-job creates hourly snapshots. -.LP -\fBcertain programs\fR - Certain programs like YaST and zypper create pre/post -snapshot pairs when modifying the system. - -.SS Cleanup Algorithms -.LP -Snapper provides several algorithms to cleanup old snapshots. The algorithms -are executed in a daily cron\-job. This can be configured in the corresponding -configurations files along with parameters for every algorithm. -.LP -\fBnumber\fR - Deletes old snapshots when a certain number of snapshots is -reached. -.LP -\fBtimeline\fR - Deletes old snapshots but keeps a number of hourly, daily, -monthly and yearly snapshots. -.LP -\fBempty\-pre\-post\fR - Deletes pre/post snapshot pairs with empty diffs. - -.SH "GLOBAL OPTIONS" - -.TP -.I \-q, \-\-quiet -Suppress normal output. Error messages will still be printed, though. -.TP -.I \-v, \-\-verbose -Increase verbosity. -.TP -.I \-t, \-\-table\-style -Specifies table style. Table style is identified by an integer number. -.TP -.I \-c, \-\-config -Use specified configuration instead of the default configuration. The default -configuration is named "root". -.TP -.I \-\-version -Print version and exit. - -.SH "COMMANDS" -.LP -snapper provides a number of \fBcommands\fR. Each command accepts the options -listed in the GLOBAL OPTIONS section. These options must be specified -\fIbefore\fR the command name. In addition, many commands have specific -options, which are listed in this section. These command-specific options must -be specified \fIafter\fR the name of the command and \fIbefore\fR any of the -command arguments. - -.TP -.B help -Show short help text. - -.TP -.B list-configs -List available configurations. - -.TP -.B create-config [options] -Create a new configuration for a filesystem or subvolume. For this command you -will likely need the global option \fI--config\fR, see \fBGLOBAL OPTIONS\fR and -\fBCONCEPTS\fR. -.TP -\fI\-f, \-\-fstype\fR -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. - -.TP -\fI\-t, \-\-template\fR -Name of template for the new configuration file. - -.TP -.B delete-config -Delete a configuration for a filesystem or subvolume. For this command you -will likely need to global option \fI--config\fR, see \fBGLOBAL OPTIONS\fR and -\fBCONCEPTS\fR. - -.TP -.B list [options] -List snapshots. -.TP -\fI\-t, \-\-type\fR -Selects type of snapshots to list. Possible values are all, single and pre-post. - -.TP -.B create [options] -Create a new snapshot. -.TP -\fI\-t, \-\-type\fR -Specifies the type of the new snapshot. Possible values are single, pre and post. -.TP -\fI\-\-pre\-number\fR -For post snapshots the number of the pre snapshot must be provided. -.TP -\fI\-p, \-\-print\-number\fR -Print number of the created snapshot. -.TP -\fI\-d, \-\-description\fR -Description for the snapshot. -.TP -\fI\-c, \-\-cleanup\-algorithm\fR -Set the cleanup-algorithm for the snapshot. -.TP -\fI\-u, \-\-userdata\fR -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. -.TP -\fI\-\-command\fR -Create a pre and post snapshot and run command in between. - -.TP -.B modify [options] -Modify a snapshot. -.TP -\fI\-d, \-\-description\fR -New description for snapshot. -.TP -\fI\-c, \-\-cleanup\-algorithm\fR -Set the cleanup-algorithm for the snapshot. -.TP -\fI\-u, \-\-userdata\fR -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. - -.TP -.B delete | - -Delete a snapshot or a range of snapshots. - -.TP -.B mount -Mount a snapshot. Not required for all filesystem types. - -.TP -.B umount -Unmount a snapshot. Not required for all filesystem types. - -.TP -.B status [options] .. -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. -.TP -\fI\-o, \-\-output\fR -Write output to file . - -.TP -.B diff [options] .. [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. - -.TP -.B undochange [options] .. [files] -Undo changes done between snapshot number1 and number2. -.TP -\fI\-i, \-\-input\fR -Read files for which to undo changes from file . - -.TP -.B cleanup -Run the cleanup algorithm . Currently implemented cleanup -algorithms are number, timeline and empty-pre-post. - -.TP -.B xadiff .. [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: -.IP -.B \ +:user.foo -for created attributes -.IP -.B \ -:user.bar -for removed attributes -.IP -.B -+:security.selinux -for modified attributes - -.SH "PERMISSIONS" -.LP -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. - -.SH "FILES" -.TP -.B /etc/sysconfig/snapper -Global configuration file. -.TP -.B /etc/snapper/configs -Directory containing configuration files. -.TP -.B /etc/snapper/config-templates -Directory containing configuration templates. -.TP -.B /etc/snapper/filters -Directory containing filter files. -.TP -.B /var/log/snapper.log -Logfile. Please include this file in bug reports. - -.SH "NOTES" -.LP -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. -.LP -Consistency after undochange is not guaranteed. E.g. when the creation of a -user is undone there might still exist files from that user. -.LP -Support for extended attributes is a compile-time option. - -.SH "HOMEPAGE" -.LP -http://en.opensuse.org/Portal:Snapper - -.SH "AUTHORS" -.LP -Arvin Schnell - -.SH "SEE ALSO" -.LP -btrfs(8), lvm(8), attr(5) diff --git a/doc/snapper.sgml.in b/doc/snapper.sgml.in new file mode 100644 index 00000000..303561fa --- /dev/null +++ b/doc/snapper.sgml.in @@ -0,0 +1,434 @@ + + + + + 2013-04-26 + + snapper + 8 + 2013-04-26 + @VERSION@ + Filesystem Snapshot Management + + + snapper + Command-line program for filesystem snapshot management + + + + SYNTAX + snapper [] <command> [] [command-arguments] + snapper --help + + + + DESCRIPTION + Snapper is a command-line program for filesystem snapshot management. It can + create, delete and compare snapshots and undo changes done between snapshots. + + Snapper never modifies the content of snapshots. Thus snapper creates + read-only snapshots if supported by the kernel. Supported filesystems are + btrfs and ext4 as well as snapshots of LVM logical volumes with + thin-provisioning. Some filesystems might not be supported depending on your + installation. + + + + CONCEPTS + + + Configurations + For each filesystem or subvolume that should be snapshotted by snapper a + configuration file is required. The complete setup can be done with the + create-config command. + + + + 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. + + Note that filesystem-wise all three types are the same. + + + + Snapshot Description und 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 + keys and values are strings. + + + + 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. + + + + Cleanup Algorithms + + Snapper provides several algorithms to cleanup old snapshots. The + algorithms are executed in a daily cron-job. This can be configured in the + 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. + + + + + + GLOBAL OPTIONS + + + + + Suppress normal output. Error messages will still be printed, though. + + + + + + Increase verbosity. + + + + + + Specifies table style. Table style is identified by an integer number. + + + + + + Use specified configuration instead of the default configuration. The default + configuration is named "root". + + + + + + Print version and exit. + + + + + + + + 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. + + + + 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 + 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. + + + + 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. + + + + list [options] + + List snapshots. + + + + <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> + + 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> + + 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. + + + + undochange [options] <number1>..<number2> [files] + + 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. + + + + 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 + + + for modified attributes + + + + + + + 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. + + + + FILES + + + /etc/sysconfig/snapper + + Global configuration file. + + + + /etc/snapper/configs + + Directory containing configuration files. + + + + /etc/snapper/config-templates + + Directory containing configuration templates. + + + + /etc/snapper/filters + + Directory containing filter files. + + + + /var/log/snapper.log + + Logfile. Please include this file in bug reports. + + + + + + + + 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. + + 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. + + + + HOMEPAGE + http://en.opensuse.org/Portal:Snapper + + + + AUTHORS + Arvin Schnell aschnell@suse.de + + + + SEE ALSO + + btrfs8, + lvm8, + attr5 + + + + diff --git a/doc/snapperd.8.in b/doc/snapperd.8.in deleted file mode 100644 index cd8f05a8..00000000 --- a/doc/snapperd.8.in +++ /dev/null @@ -1,24 +0,0 @@ -.TH "SNAPPERD" "8" "2012-10-15" "@VERSION@" "Filesystem Snapshot Management" -.SH "NAME" -.LP -snapperd - DBus daemon for snapper - -.SH "SYNTAX" -.LP -snapperd - -.SH "DESCRIPTION" -.LP -Snapperd is a DBus daemon for snapper and not for direct use by the user. - -.SH "HOMEPAGE" -.LP -http://en.opensuse.org/Portal:Snapper - -.SH "AUTHORS" -.LP -Arvin Schnell - -.SH "SEE ALSO" -.LP -snapper(8), dbus-daemon(1) diff --git a/doc/snapperd.sgml.in b/doc/snapperd.sgml.in new file mode 100644 index 00000000..41812be1 --- /dev/null +++ b/doc/snapperd.sgml.in @@ -0,0 +1,46 @@ + + + + + 2012-10-15 + + snapperd + 8 + 2012-10-15 + @VERSION@ + Filesystem Snapshot Management + + + snapperd + DBus daemon for snapper + + + + SYNTAX + snapperd + + + + DESCRIPTION + Snapperd is a DBus daemon for snapper and not for direct use by the user. + + + + HOMEPAGE + http://en.opensuse.org/Portal:Snapper + + + + AUTHORS + Arvin Schnell aschnell@suse.de + + + + SEE ALSO + + snapper8, + dbus-daemon1 + + + + diff --git a/snapper.spec.in b/snapper.spec.in index 56b0b466..e1f67f19 100644 --- a/snapper.spec.in +++ b/snapper.spec.in @@ -34,6 +34,11 @@ BuildRequires: libdbus-1-devel BuildRequires: libzypp(plugin:commit) %endif BuildRequires: pam-devel +%if (0%{?suse_version} && 0%{?suse_version} >= 1220) +BuildRequires: docbook-utils-minimal +%else +BuildRequires: docbook-utils +%endif Requires: libsnapper@LIBVERSION_MAJOR@ = %version Requires: diffutils %if 0%{?suse_version}