Merge lp:~ed.so/duplicity/man.page into lp:duplicity/0.6

[edso]

update paramiko links
add command parameters to synopsis
add --compare-data
some polishing
several improvements

[Kenneth Loafman (kenneth-loafman)]

Looking good!

=== modified file 'bin/duplicity.1'
--- bin/duplicity.1	2013-08-17 18:34:48 +0000
+++ bin/duplicity.1	2013-08-18 14:20:30 +0000
@@ -9,12 +9,15 @@
 duplicity \- Encrypted incremental backup to local or remote storage.
 
 .SH SYNOPSIS
+For detailed descriptions for each command see chapter
+.BR ACTIONS .
+
 .B duplicity [full|incremental]
 .I [options]
 source_directory target_url
 
 .B duplicity verify
-.I [options] [--file-to-restore <relpath>]
+.I [options] [--compare-data] [--file-to-restore <relpath>] [--time time]
 source_url target_directory
 
 .B duplicity collection-status
@@ -54,19 +57,16 @@
 Some backends also require additional components (probably available as packages for your specific platform):
 .TP
 .BR "boto backend" " (S3 Amazon Web Services, Google Cloud Storage)"
-.B boto
+.B boto version 2.0+
 - http://github.com/boto/boto
 .TP
 .BR "cloudfiles backend" " (e.g. Rackspace Open Cloud)"
 .B Cloud Files Python API
 - http://www.rackspace.com/knowledge_center/article/python-api-installation-for-cloud-files
 .TP
-.BR "OpenStack Swift backend"
-.B Python swiftclient module
-- https://github.com/openstack/python-swiftclient/
-.br
-.B Python keystoneclient module
-- https://github.com/openstack/python-keystoneclient/
+.B "dpbx backend" (Dropbox)
+.B Dropbox Python SDK
+- https://www.dropbox.com/developers/reference/sdk
 .TP
 .B "ftp backend"
 .B NcFTP Client
@@ -99,7 +99,7 @@
 .BR "ssh paramiko backend" " (enabled by default)"
 .B paramiko
 (SSH2 for python) 
-- http://www.lag.net/paramiko/
+- http://pypi.python.org/pypi/paramiko (downloads); http://github.com/paramiko/paramiko (project page)
 .br
 .B pycrypto
 (Python Cryptography Toolkit) 
@@ -109,6 +109,13 @@
 .B sftp/scp client binaries
 OpenSSH - http://www.openssh.com/
 .TP
+.BR "swift backend (OpenStack Object Storage)"
+.B Python swiftclient module
+- https://github.com/openstack/python-swiftclient/
+.br
+.B Python keystoneclient module
+- https://github.com/openstack/python-keystoneclient/
+.TP
 .B "Ubuntu One"
 .B httplib2
 (python  HTTP client library)
@@ -125,23 +132,17 @@
 .br
 (also see 
 .BR "A NOTE ON SSL CERTIFICATE VERIFICATION" ).
-.TP
-.B "dpbx backend"
-.B Dropbox Python SDK
-- https://www.dropbox.com/developers/reference/sdk
-.br
 
 .SH DESCRIPTION
-Duplicity incrementally backs up files and directory
-by encrypting tar-format volumes with GnuPG and uploading them to a
-remote (or local) file server.  See
+Duplicity incrementally backs up files and folders into
+tar-format volumes encrypted with GnuPG and places them to a
+remote (or local) storage backend.  See chapter
 .B URL FORMAT
-for a list all supported backends and how to address them.
-Because duplicity uses
-librsync, the incremental archives are space efficient and only record
-the parts of files that have changed since the last backup.  Currently
-duplicity supports deleted files, full Unix permissions, uid/gid, directories,
-symbolic links, fifos, etc., but not hard links.
+for a list of all supported backends and how to address them.
+Because duplicity uses librsync, incremental backups are space efficient 
+and only record the parts of files that have changed since the last backup.
+Currently duplicity supports deleted files, full Unix permissions, uid/gid,
+directories, symbolic links, fifos, etc., but not hard links.
 
 If you are backing up the root directory /, remember to --exclude
 /proc, or else duplicity will probably crash on the weird stuff in
@@ -156,7 +157,7 @@
 .PP
 .RE
 If the above is run repeatedly, the first will be a full backup, and
-subsequent ones will be incremental.  To force a full backup, use the
+subsequent ones will be incremental. To force a full backup, use the
 .I full
 action:
 .PP
@@ -164,6 +165,14 @@
 duplicity full /home/me sftp://[e-mail]/some_dir
 .PP
 .RE
+or enforcing a full every other time via 
+.I --full-if-older-than <time>
+, e.g. a full every month:
+.PP
+.RS
+duplicity --full-if-older-than 1M /home/me sftp://[e-mail]/some_dir
+.PP
+.RE
 Now suppose we accidentally delete /home/me and want to restore it
 the way it was at the time of last backup:
 .PP
@@ -179,8 +188,7 @@
 duplicity -t 3D --file-to-restore Mail/article sftp://[e-mail]/some_dir /home/me/restored_file
 .PP
 .RE
-The following command compares the files we backed up, so see what has
-changed since then:
+The following command compares the latest backup with the current files:
 .PP
 .RS
 duplicity verify sftp://[e-mail]/some_dir /home/me
@@ -213,6 +221,7 @@
 
 .SH ACTIONS
 Duplicity knows action commands, which can be finetuned with options.
+.br
 The actions for backup (full,incr) and restoration (restore) can as well be
 left out as duplicity detects in what mode it should switch to by the order
 of target URL and local folder. If the target URL comes before the local folder
@@ -221,24 +230,47 @@
 .br
 If a backup is in order and old signatures can be found duplicity automatically
 performs an incremental backup.
+.PP
+.B Note:
+The following explanations explain some but
+.B not
+all options that can be used in connection with that action command.
+Consult the OPTIONS section for more detailed informations.
 
 .TP
-.B full
+.BI "full " "<folder> <url>"
 Perform a full backup. A new backup chain is started even if
 signatures are available for an incremental backup.
 
 .TP
-.BR incr
+.BI "incr " "<folder> <url>"
 If this is requested an incremental backup will be performed.
 Duplicity will abort if no old signatures can be found.
 
 .TP
-.B collection-status
+.BI "verify " "[--compare-data] [--time <time>] [--file-to-restore <relpath>] <url> <folder>"
+Verify compares the backup contents with the source folder.
+duplicity will exit with a non-zero error level if any files are different.
+On verbosity level info (4) or higher, a message for each file that has
+changed will be logged.
+.br
+The 
+.I --file-to-restore
+option restricts verify to that file or folder.
+The 
+.I --time
+option allows to select a backup to verify against.
+The
+.I --compare-data
+option enables data comparison (see below).
+
+.TP
+.BI "collection-status " "<url>"
 Summarize the status of the backup repository by printing the chains
 and sets found, and the number of volumes in each.
 
 .TP
-.BI "list-current-files " "[--time <time>]"
+.BI "list-current-files " "[--time <time>] <url>"
 Lists the files contained in the most current backup or backup at time.
 The information will be extracted from the signature files, not the archive data
 itself. Thus the whole archive does not have to be downloaded, but on
@@ -246,15 +278,7 @@
 command will not detect it.
 
 .TP
-.BI "verify " "[--file-to-restore <relpath>]"
-Enter verify mode instead of restore.  If the --file-to-restore option
-is given, restrict verify to that file or directory.  duplicity will
-exit with a non-zero error level if any files are different.  On
-verbosity level 4 or higher, log a message for each file that has
-changed.
-
-.TP
-.BI "restore " "[--file-to-restore <relpath>] [--time <time>]"
+.BI "restore " "[--file-to-restore <relpath>] [--time <time>] <url> <target_folder>"
 You can restore the full monty or selected folders/files from a specific time.
 Use the relative path as it is printed by
 .BR list-current-files .
@@ -262,7 +286,7 @@
 comes before the local folder.
 
 .TP
-.BI "remove-older-than " time
+.BI "remove-older-than " "<time> [--force] <url>"
 Delete all backup sets older than the given time.  Old backup sets
 will not be deleted if backup sets newer than
 .I time
@@ -271,10 +295,10 @@
 section for more information.  Note, this action cannot be combined
 with backup or other actions, such as cleanup.  Note also that
 .I --force
-will be needed to delete the files rather than just list them.
+will be needed to delete the files instead of just listing them.
 
 .TP
-.BI "remove-all-but-n-full " count
+.BI "remove-all-but-n-full " "<count> [--force] <url>"
 Delete all backups sets that are older than the count:th last full
 backup (in other words, keep the last
 .I count
@@ -283,26 +307,26 @@
 must be larger than zero. A value of 1 means that only the single most
 recent backup chain will be kept.  Note that
 .I --force
-will be needed to delete the files rather than just list them.
+will be needed to delete the files instead of just listing them.
 
 .TP
-.BI "remove-all-inc-of-but-n-full " count
+.BI "remove-all-inc-of-but-n-full " "<count> [--force] <url>"
 Delete incremental sets of all backups sets that are older than the count:th last full
 backup (in other words, keep only old full backups and not their increments).
 .I count
 must be larger than zero. A value of 1 means that only the single most
 recent backup chain will be kept intact.  Note that
 .I --force
-will be needed to delete the files rather than just list them.
+will be needed to delete the files instead of just listing them.
 
 .TP
-.B cleanup
+.BI "cleanup " "[--force] [--extra-clean] <url>"
 Delete the extraneous duplicity files on the given backend.
 Non-duplicity files, or files in complete data sets will not be
 deleted.  This should only be necessary after a duplicity session
 fails or is aborted prematurely.  Note that
 .I --force
-will be needed to delete the files rather than just list them.
+will be needed to delete the files instead of just listing them.
 
 .SH OPTIONS
 
@@ -374,6 +398,11 @@
 enough storage space is required to store two volumes.
 
 .TP
+.B --compare-data
+Enable data comparison of regular files on action verify.
+This is disabled by default for performance reasons.
+
+.TP
 .BI "--dry-run "
 Calculate what would be done, but do not perform any backend actions
 
@@ -670,7 +699,7 @@
 option). Default is to prompt the status each 3 seconds.
 
 .TP
-.BI "--rename " "orig new"
+.BI "--rename " "<original path> <new path>"
 Treats the path
 .I orig
 in the backup as if it were the path
@@ -943,7 +972,7 @@
 it is permitted however.
 Consider setting the environment variable 
 .B FTP_PASSWORD 
-instead, which is used by most, if not all backends, regardless of its name.
+instead, which is used by most, if not all backends, regardless of it's name.
 .PP
 In protocols that support it, the path may be preceded by a single
 slash, '/path', to represent a relative path to the target home directory,
@@ -958,6 +987,13 @@
 See also
 .B "A NOTE ON CLOUD FILES ACCESS"
 .PP
+.BI Dropbox
+.br
+dpbx:///some_dir
+.br
+Make sure to read
+.BR "A NOTE ON DROPBOX ACCESS" " first!"
+.PP
 file://[relative|/absolute]/local/path
 .PP
 ftp[s]://user[:password]@other.host[:port]/some_dir
@@ -1005,7 +1041,7 @@
 swift://container_name
 .br
 See also
-.B "A NOTE ON OPENSTACK SWIFT ACCESS"
+.B "A NOTE ON SWIFT (OPENSTACK OBJECT STORAGE) ACCESS"
 .PP
 tahoe://alias/directory
 .PP
@@ -1018,25 +1054,7 @@
 See also
 .BI "A NOTE ON UBUNTU ONE"
 .PP
-webdav[s]://user[:password]@other.host/some_dir
-.PP
-.BI Dropbox
-.br
-dpbx:///some_dir
-.br
-.IP 1.
-"some_dir" must already exist in the Dropbox Application folder for
-this application, like "Apps/Duplicity/some_dir".
-.IP 2.
-The first run of the backend must be ineractive!
-It will print the URL that you need to open in the browser to obtain
-OAuth token for the application. The token will be saved in the file
-$HOME/.dropbox.token_store.txt and used in the future runs.
-.IP 3.
-When using Dropbox for storage, be aware that all files, including the
-ones in the Apps folder, will be synced to all connected computers.
-You may prefer to use a separate Dropbox account specially for the
-backups, and not connect any computers to that account.
+webdav[s]://user[:password]@other.host[:port]/some_dir
 .RE
 
 .SH TIME FORMATS
@@ -1172,21 +1190,26 @@
 The
 .B --exclude
 pattern option matches a file if:
-.IP 1.
+.PP
+.B 1.
 .I pattern
 can be expanded into the file's filename, or
-.IP 2.
+.br
+.B 2.
 the file is inside a directory matched by the option.
 .PP
 Conversely, the 
 .B "--include " 
 pattern matches a file if:
-.IP 1.
+.PP
+.B 1.
 .I pattern
 can be expanded into the file's filename, or
-.IP 2.
+.br
+.B 2.
 the file is inside a directory matched by the option, or
-.IP 3.
+.br
+.B 3.
 the file is a directory which contains a file matched by the option.
 .PP
 For example,
@@ -1231,7 +1254,8 @@
 interpreted similarly to the way
 .I extended shell patterns
 are, with a few exceptions:
-.IP 1.
+.PP
+.B 1.
 Globbing patterns like
 .BR * ,
 .BR ** ,
@@ -1239,10 +1263,12 @@
 and
 .B [...]
 are not expanded.
-.IP 2.
+.br
+.B 2.
 Include patterns do not match files in a directory that is included.
 So /usr/local in an include file will not match /usr/local/doc.
-.IP 3.
+.br
+.B 3.
 Lines starting with "+ " are interpreted as include directives, even
 if found in a filelist referenced by
 .BR --exclude-filelist .
@@ -1343,32 +1369,20 @@
 .I must 
 be set in order to use other cloud files providers.
 
-.SH A NOTE ON OPENSTACK SWIFT ACCESS
-
-Swift is the OpenStack Object Storage service.
-
-The backend requires python-switclient to be installed on the system.
-python-keystoneclient is also needed to use OpenStack's Keystone Identity service.
-See 
-.B REQUIREMENTS 
-above.
-
-It uses four environment variables for authentification:
-.BR SWIFT_USERNAME " (required),"
-.BR SWIFT_PASSWORD " (required),"
-.BR SWIFT_AUTHURL " (required),"
-.BR SWIFT_TENANTNAME " (optional, the tenant can be included in the username)"
-
-If the user was previously authenticated, the following environment
-variables can be used instead:
-.BR SWIFT_PREAUTHURL " (required),"
-.BR SWIFT_PREAUTHTOKEN " (required)"
-
-If
-.B SWIFT_AUTHVERSION
-is unspecified, it will default to version 1.
-
-
+.SH A NOTE ON DROPBOX ACCESS
+.IP 1.
+"some_dir" must already exist in the Dropbox Application folder for
+this application, like "Apps/Duplicity/some_dir".
+.IP 2.
+The first run of the backend must be ineractive!
+It will print the URL that you need to open in the browser to obtain
+OAuth token for the application. The token will be saved in the file
+$HOME/.dropbox.token_store.txt and used in the future runs.
+.IP 3.
+When using Dropbox for storage, be aware that all files, including the
+ones in the Apps folder, will be synced to all connected computers.
+You may prefer to use a separate Dropbox account specially for the
+backups, and not connect any computers to that account.
 
 .SH A NOTE ON EUROPEAN S3 BUCKETS
 Amazon S3 provides the ability to choose the location of a bucket upon
@@ -1529,7 +1543,31 @@
 .B --ssl-no-check-certificate
 option to disable certificate verification alltogether, in case some ssl library 
 is missing or verification is not wanted. Use it with care, as even with self signed 
-servers manually providing the private ca certificate is definitely the safer option. 
+servers manually providing the private ca certificate is definitely the safer option.
+
+.SH A NOTE ON SWIFT (OPENSTACK OBJECT STORAGE) ACCESS
+Swift is the OpenStack Object Storage service.
+.br
+The backend requires python-switclient to be installed on the system.
+python-keystoneclient is also needed to use OpenStack's Keystone Identity service.
+See 
+.B REQUIREMENTS 
+above.
+
+It uses four environment variables for authentification:
+.BR SWIFT_USERNAME " (required),"
+.BR SWIFT_PASSWORD " (required),"
+.BR SWIFT_AUTHURL " (required),"
+.BR SWIFT_TENANTNAME " (optional, the tenant can be included in the username)"
+
+If the user was previously authenticated, the following environment
+variables can be used instead:
+.BR SWIFT_PREAUTHURL " (required),"
+.BR SWIFT_PREAUTHTOKEN " (required)"
+
+If
+.B SWIFT_AUTHVERSION
+is unspecified, it will default to version 1.
 
 .SH A NOTE ON SYMMETRIC ENCRYPTION AND SIGNING
 Signing and symmetrically encrypt at the same time with the gpg binary on the