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://u...@host.com[: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 <besc...@stanford.edu>
_______________________________________________ Mailing list: https://launchpad.net/~duplicity-team Post to : duplicity-team@lists.launchpad.net Unsubscribe : https://launchpad.net/~duplicity-team More help : https://help.launchpad.net/ListHelp
