duplicity-team team mailing list archive

[edso <edgar.soldin@xxxxxx>]

edso has proposed merging lp:~ed.so/duplicity/manpage into lp:duplicity.

Requested reviews:
  duplicity-team (duplicity-team)

For more details, see:
https://code.launchpad.net/~ed.so/duplicity/manpage/+merge/78609

some updates to the manpage
-- 
https://code.launchpad.net/~ed.so/duplicity/manpage/+merge/78609
Your team duplicity-team is requested to review the proposed merge of lp:~ed.so/duplicity/manpage into lp:duplicity.

=== modified file 'duplicity.1'
--- duplicity.1	2011-08-18 18:15:38 +0000
+++ duplicity.1	2011-10-07 14:24:48 +0000
@@ -628,6 +628,9 @@
 Should be specified only once because currently only 
 .B one
 signing key is supported. Last entry overrides all other entries.
+.br
+see also
+.BI "A NOTE ON SYMMETRIC ENCRYPTION AND SIGNING"
 
 .TP
 .B --ssh-askpass
@@ -688,12 +691,18 @@
 .BI --use-agent
 If this option is specified, then
 .I --use-agent
-is passed to the GnuPG
-encryption process and it will turn off any passphrase interaction with
-the user with respect to
+is passed to the GnuPG encryption process and it will try to connect to
+.B gpg-agent
+before it asks for a passphrase for
 .I --encrypt-key
 or
-.I --sign-key.
+.I --sign-key
+if needed.
+.br
+.B Note:
+GnuPG 2 and newer ignore this option and will always use a running
+.B gpg-agent
+if no passphrase was delivered.
 
 .TP
 .BI --use-scp
@@ -710,25 +719,22 @@
 for put and get operations
 
 .TP
-.BI -v verb ", --verbosity " verb
-Specify verbosity level (0 is total silent, 4 is the default, and 9 is
-noisiest).  Verbosity may also be one of: character
-.I ewnid,
-or word
-.I error,
-.I warning,
-.I notice,
-.I info,
-.I debug.
-The default is 4 (Notice).  The options
-.I -v4,
-.I -vn,
-and
-.I -vnotice
-are functionally equivalent, as are  the mixed/upper-case versions,
-.I -vN,
-.I -vNotice, and
-.I -vNOTICE.
+.BI "--verbosity " level ", -v" level
+Specify output verbosity level (log level).
+Named levels and corresponding values are
+0 Error, 2 Warning, 4 Notice (default), 8 Info, 9 Debug (noisiest).
+.br
+.I level
+may also be
+.br
+.B a character:
+e, w, n, i, d
+.br
+.B a word:
+error, warning, notice, info, debug
+
+The options -v4, -vn and -vnotice are functionally equivalent, as are the mixed/\
+upper-case versions -vN, -vNotice and -vNOTICE.
 
 .TP
 .BI --version
@@ -789,13 +795,14 @@
 .PP
 file:///some_dir
 .PP
-ftp://user[:password]@other.host[:port]/some_dir
+ftp[s]://user[:password]@other.host[:port]/some_dir
 .PP
 hsi://user[:password]@other.host/some_dir
 .PP
-imap://user[:password]@host.com[/from_address_prefix]
-.PP
-imaps://user[:password]@host.com[/from_address_prefix]
+imap[s]://user[:password]@host.com[/from_address_prefix]
+.br
+see also
+.BI "A NOTE ON IMAP"
 .PP
 .BI "using rsync daemon"
 .br
@@ -808,14 +815,20 @@
 rsync://user@xxxxxxxx[:port]//absolute_path
 .PP
 s3://host/bucket_name[/prefix]
-.PP
+.br
 s3+http://bucket_name[/prefix]
+.br
+see also
+.BI "A NOTE ON EUROPEAN S3 BUCKETS"
 .PP
 .BI "Ubuntu One"
 .br
 u1://host/volume_path
 .br
 u1+http://volume_path
+.br
+see also
+.BI "A NOTE ON UBUNTU ONE"
 .PP
 .BI "ssh protocols"
 .br
@@ -830,9 +843,7 @@
 .PP
 tahoe://alias/directory
 .PP
-webdav://user[:password]@other.host/some_dir
-.PP
-webdavs://user[:password]@other.host/some_dir
+webdav[s]://user[:password]@other.host/some_dir
 .PP
 gdocs://user[:password]@other.host/some_dir
 
@@ -1134,67 +1145,7 @@
 which aren't followed by 'foo'.  However, it wouldn't match /home even
 if /home/ben/1234567 existed.
 
-.SH OPERATION AND DATA FORMATS
-This section describes duplicity's basic operation and the format of
-its data files.  It should not necessary to read this section to use
-duplicity.
-
-The files used by duplicity to store backup data are tarfiles in GNU
-tar format.  They can be produced independently by
-.BR rdiffdir (1).
-For incremental backups, new files are saved normally in the tarfile.
-But when a file changes, instead of storing a complete copy of the
-file, only a diff is stored, as generated by
-.BR rdiff (1).
-If a file is deleted, a 0 length file is stored in the tar.  It is
-possible to restore a duplicity archive "manually" by using
-.B tar
-and then
-.BR cp ,
-.BR rdiff ,
-and
-.B rm
-as necessary.  These duplicity archives have the extension
-.BR difftar .
-
-Both full and incremental backup sets have the same format.  In
-effect, a full backup set is an incremental one generated from an
-empty signature (see below).  The files in full backup sets will start
-with
-.B duplicity-full
-while the incremental sets start with
-.BR duplicity-inc .
-When restoring, duplicity applies patches in order, so deleting, for
-instance, a full backup set may make related incremental backup sets
-unusable.
-
-In order to determine which files have been deleted, and to calculate
-diffs for changed files, duplicity needs to process information about
-previous sessions.  It stores this information in the form of tarfiles
-where each entry's data contains the signature (as produced by
-.BR rdiff )
-of the file instead of the file's contents.  These signature sets have
-the extension
-.BR sigtar .
-
-Signature files are not required to restore a backup set, but without
-an up-to-date signature, duplicity cannot append an incremental backup
-to an existing archive.
-
-To save bandwidth, duplicity generates full signature sets and
-incremental signature sets.  A full signature set is generated for
-each full backup, and an incremental one for each incremental backup.
-These start with
-.B duplicity-full-signatures
-and
-.B duplicity-new-signatures
-respectively. These signatures will be stored both locally and remotely.
-The remote signatures will be encrypted if encryption is enabled.
-The local signatures will not be encrypted and stored in the archive dir (see
-.B "--archive-dir"
-).
-
-.SH EUROPEAN S3 BUCKETS
+.SH A NOTE ON EUROPEAN S3 BUCKETS
 Amazon S3 provides the ability to choose the location of a bucket upon
 its creation. The purpose is to enable the user to choose a location
 which is better located network topologically relative to the user,
@@ -1230,15 +1181,7 @@
 or HTTP errors when trying to upload files to your newly created
 bucket. Give it a few minutes and the bucket should function normally.
 
-.SH UBUNTU ONE
-Connecting to Ubuntu One requires that you be running duplicity inside of an X
-session so that you can be prompted for your credentials if necessary by the
-Ubuntu One session daemon.
-.PP
-See https://one.ubuntu.com/ for more information about Ubuntu One.
-.PP
-
-.SH IMAP
+.SH A NOTE ON IMAP
 An IMAP account can be used as a target for the upload.  The userid may
 be specified and the password will be requested.
 .PP
@@ -1249,7 +1192,6 @@
 the
 .B from_address_prefix
 will distinguish between different backups.
-.PP
 
 .SH A NOTE ON SSH/SCP PROTOCOLS
 Duplicity specifies two protocol names for the same protocol.  This is
@@ -1274,23 +1216,98 @@
 all-sftp in order to allow the remote system to chroot the backup,
 thus providing better security.
 
-.SH BUGS
+.SH A NOTE ON UBUNTU ONE
+Connecting to Ubuntu One requires that you be running duplicity inside of an X
+session so that you can be prompted for your credentials if necessary by the
+Ubuntu One session daemon.
+.PP
+See https://one.ubuntu.com/ for more information about Ubuntu One.
+
+.SH A NOTE ON SYMMETRIC ENCRYPTION AND SIGNING
+Signing and symmetrically encrypt at the same time with the gpg binary on the
+command line, as used within duplicity, is a specifically challenging issue.
+Tests showed that the following combinations proved working.
+.PP
+1. Setup gpg-agent properly. Use the option
+.BI --use-agent
+and enter both passphrases (symmetric and sign key) in the gpg-agent's dialog.
+.PP
+2. Use a
+.BI PASSPHRASE
+for symmetric encryption of your choice but the signing key has an 
+.B empty
+passphrase.
+.PP
+3. The used
+.BI PASSPHRASE
+for symmetric encryption and the passphrase of the signing key are identical.
+
+.SH KNOWN ISSUES / BUGS
 Hard links currently unsupported (they will be treated as non-linked
 regular files).
 
 Bad signatures will be treated as empty instead of logging appropriate
 error message.
 
-If symmetric encryption is used and the signing key is passphrase-protected, the
-encryption passphrase must equal the passphrase of the signing key. This
-limitation can be circumvented by using
-.B gpg-agent
-for storing the passphrase of the signing key and the
-.B PASSPHRASE
-environment variable for the encryption key or by enabling asymmetric
-encryption using the 
-.B --encrypt-key
-option.
+.SH OPERATION AND DATA FORMATS
+This section describes duplicity's basic operation and the format of
+its data files.  It should not necessary to read this section to use
+duplicity.
+
+The files used by duplicity to store backup data are tarfiles in GNU
+tar format.  They can be produced independently by
+.BR rdiffdir (1).
+For incremental backups, new files are saved normally in the tarfile.
+But when a file changes, instead of storing a complete copy of the
+file, only a diff is stored, as generated by
+.BR rdiff (1).
+If a file is deleted, a 0 length file is stored in the tar.  It is
+possible to restore a duplicity archive "manually" by using
+.B tar
+and then
+.BR cp ,
+.BR rdiff ,
+and
+.B rm
+as necessary.  These duplicity archives have the extension
+.BR difftar .
+
+Both full and incremental backup sets have the same format.  In
+effect, a full backup set is an incremental one generated from an
+empty signature (see below).  The files in full backup sets will start
+with
+.B duplicity-full
+while the incremental sets start with
+.BR duplicity-inc .
+When restoring, duplicity applies patches in order, so deleting, for
+instance, a full backup set may make related incremental backup sets
+unusable.
+
+In order to determine which files have been deleted, and to calculate
+diffs for changed files, duplicity needs to process information about
+previous sessions.  It stores this information in the form of tarfiles
+where each entry's data contains the signature (as produced by
+.BR rdiff )
+of the file instead of the file's contents.  These signature sets have
+the extension
+.BR sigtar .
+
+Signature files are not required to restore a backup set, but without
+an up-to-date signature, duplicity cannot append an incremental backup
+to an existing archive.
+
+To save bandwidth, duplicity generates full signature sets and
+incremental signature sets.  A full signature set is generated for
+each full backup, and an incremental one for each incremental backup.
+These start with
+.B duplicity-full-signatures
+and
+.B duplicity-new-signatures
+respectively. These signatures will be stored both locally and remotely.
+The remote signatures will be encrypted if encryption is enabled.
+The local signatures will not be encrypted and stored in the archive dir (see
+.B "--archive-dir"
+).
 
 .SH AUTHOR
 Original Author - Ben Escoto <bescoto@xxxxxxxxxxxx>