Problems in gdb.1

esr@thyrsus.com esr@thyrsus.com
Tue Jun 18 11:31:00 GMT 2013


This is automatically generated email about markup problems in a man
page for which you appear to be responsible.  If you are not the right
person or list, please tell me so I can correct my database.

See http://catb.org/~esr/doclifter/bugs.html for details on how and
why these patches were generated.  Feel free to email me with any
questions.  Note: These patches do not change the modification date of
any manual page.  You may wish to do that by hand.

I apologize if this message seems spammy or impersonal. The volume of
markup bugs I am tracking is over five hundred - there is no real
alternative to generating bugmail from a database and template.

--
                             Eric S. Raymond
-------------- next part --------------
Problems with gdb.1:

The composer of this man page misunderstood and seriously overused
the \c escape.  Some uses were broken; others (notably the sequence
"\\c\n\\&") are bad style.

Ambiguous or invalid backslash.  This doesn't cause groff a problem.
but it confuses doclifter and may confuse older troff implementations.

--- gdb.1-unpatched	2013-05-25 10:47:23.548635192 -0400
+++ gdb.1	2013-05-25 10:47:35.008634978 -0400
@@ -1,428 +1,1557 @@
-.\" Copyright (C) 1991-2013 Free Software Foundation, Inc.
-.\" See section COPYING for conditions for redistribution
-.\" $Id: gdb.1,v 1.4 1999/01/05 00:50:50 jsm Exp $
-.TH gdb 1 "22may2002" "GNU Tools" "GNU Tools"
+.TH DUPLICITY 1 "January 23, 2013" "Version 0.6.21" "User Manuals" \"  -*- nroff -*-
+.\" disable justification (adjust text to left margin only)
+.\" command line examples stay readable through that
+.ad l
+.\" disable hyphenation
+.nh
+
 .SH NAME
-gdb \- The GNU Debugger
+duplicity \- Encrypted incremental backup to local or remote storage.
+
 .SH SYNOPSIS
-.na
+.B duplicity [full|incremental]
+.I [options]
+source_directory target_url
+
+.B duplicity verify
+.I [options] [--file-to-restore <relpath>]
+source_url target_directory
+
+.B duplicity collection-status
+.I [options]
+target_url
+
+.B duplicity list-current-files
+.I [options] [--time time]
+target_url
+
+.B duplicity [restore]
+.I [options] [--file-to-restore <relpath>] [--time time]
+source_url target_directory
+
+.B duplicity remove-older-than <time>
+.I [options] [--force]
+target_url
+
+.B duplicity remove-all-but-n-full  <count>
+.I [options] [--force]
+target_url
+
+.B duplicity remove-all-inc-of-but-n-full <count>
+.I [options] [--force]
+target_url
+
+.B duplicity cleanup
+.I [options] [--force] [--extra-clean]
+target_url
+
+.SH REQUIREMENTS
+Duplicity requires a POSIX-like operating system with a 
+.B python
+interpreter version 2.4+ installed. 
+It is best used under GNU/Linux.
+
+Some backends also require additional components (probably available as packages for your specific platform):
+.TP
+.BR "boto backend" " (S3 Amazon Web Services)"
+.B boto
+- 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
+.B "ftp backend"
+.B NcFTP Client
+- http://www.ncftp.com/
+.TP
+.B "ftps backend"
+.B LFTP Client
+- http://lftp.yar.ru/
+.TP
+.BR "gdocs backend" " (Google Docs)"
+.B Google Data APIs Python Client Library
+- http://code.google.com/p/gdata-python-client/
+.TP
+.BR "gio backend" " (Gnome VFS API)"
+.B PyGObject
+- http://live.gnome.org/PyGObject
+.br
+.B D-Bus
+(dbus)- http://www.freedesktop.org/wiki/Software/dbus
 .TP
-.B gdb
-.RB "[\|" \-help "\|]"
-.RB "[\|" \-nh "\|]"
-.RB "[\|" \-nx "\|]"
-.RB "[\|" \-q "\|]"
-.RB "[\|" \-batch "\|]"
-.RB "[\|" \-cd=\c
-.I dir\c
-\|]
-.RB "[\|" \-f "\|]"
-.RB "[\|" "\-b\ "\c
-.IR bps "\|]"
-.RB "[\|" "\-tty="\c
-.IR dev "\|]"
-.RB "[\|" "\-s "\c
-.I symfile\c
-\&\|]
-.RB "[\|" "\-e "\c
-.I prog\c
-\&\|]  
-.RB "[\|" "\-se "\c
-.I prog\c
-\&\|]
-.RB "[\|" "\-c "\c
-.I core\c
-\&\|]
-.RB "[\|" "\-x "\c
-.I file\c
-\&\|]
-.RB "[\|" "\-ex "\c
-.I cmd\c
-\&\|]
-.RB "[\|" "\-d "\c
-.I dir\c
-\&\|]
-.RB "[\|" \c
-.I prog
-.RB "[\|" \c
-.IR core \||\| procID\c
-\&\|]\&\|]
-.TP
-.B gdb
-.RB "[\|" \c
-.I options\c
-.RB "\|]"
-.RB "--args"
-.I prog
-.RB "[\|" \c
-.I arguments\c
-.RB "\|]"
-.TP
-.B gdbtui
-.RB "[\|" \c
-.I options\c
-.RB "\|]"
-.ad b
+.B "rsync backend"
+.B rsync client binary
+- http://rsync.samba.org/
+.PP
+There are two 
+.B ssh backends
+for scp/sftp/ssh access (also see 
+.BR "A NOTE ON SSH BACKENDS" ).
+.TP
+.BR "ssh paramiko backend" " (enabled by default)"
+.B paramiko
+(SSH2 for python) 
+- http://www.lag.net/paramiko/
+.br
+.B pycrypto
+(Python Cryptography Toolkit) 
+- http://www.dlitz.net/software/pycrypto/
+.TP
+.B ssh pexpect backend
+.B sftp/scp client binaries
+OpenSSH - http://www.openssh.com/
+.TP
+.B "Ubuntu One"
+.B httplib2
+(python  HTTP client library)
+- http://code.google.com/p/httplib2/
+.br
+.B oauthlib
+(python OAuth request-signing logic)
+- http://pypi.python.org/pypi/oauthlib
+.TP
+.B "webdav backend"
+.B certificate authority database file
+for ssl certificate verification of HTTPS connections
+- http://curl.haxx.se/docs/caextract.html
+.br
+(also see 
+.BR "A NOTE ON SSL CERTIFICATE VERIFICATION" ).
+
 .SH DESCRIPTION
-The purpose of a debugger such as GDB is to allow you to see what is
-going on ``inside'' another program while it executes\(em\&or what another
-program was doing at the moment it crashed.
+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
+.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.
+
+If you are backing up the root directory /, remember to --exclude
+/proc, or else duplicity will probably crash on the weird stuff in
+there.
+
+.SH EXAMPLES
+Here is an example of a backup, using sftp to back up /home/me to
+some_dir on the other.host machine:
+.PP
+.RS
+duplicity /home/me sftp://uid@other.host/some_dir
+.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
+.I full
+action:
+.PP
+.RS
+duplicity full /home/me sftp://uid@other.host/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
+.RS
+duplicity sftp://uid@other.host/some_dir /home/me
+.PP
+.RE
+Duplicity enters restore mode because the URL comes before the local
+directory.  If we wanted to restore just the file "Mail/article" in
+/home/me as it was three days ago into /home/me/restored_file:
+.PP
+.RS
+duplicity -t 3D --file-to-restore Mail/article sftp://uid@other.host/some_dir /home/me/restored_file
+.PP
+.RE
+The following command compares the files we backed up, so see what has
+changed since then:
+.PP
+.RS
+duplicity verify sftp://uid@other.host/some_dir /home/me
+.PP
+.RE
+Finally, duplicity recognizes several include/exclude options.  For
+instance, the following will backup the root directory, but exclude
+/mnt, /tmp, and /proc:
+.PP
+.RS
+duplicity --exclude /mnt --exclude /tmp --exclude /proc /
+file:///usr/local/backup
+.PP
+.RE
+Note that in this case the destination is the local directory
+/usr/local/backup.  The following will backup only the /home and /etc
+directories under root:
+.PP
+.RS
+duplicity --include /home --include /etc --exclude '**' /
+file:///usr/local/backup
+.PP
+.RE
+Duplicity can also access a repository via ftp.  If a user name is
+given, the environment variable FTP_PASSWORD is read to determine the
+password:
+.PP
+.RS
+FTP_PASSWORD=mypassword duplicity /local/dir ftp://user@other.host/some_dir
 
-GDB can do four main kinds of things (plus other things in support of
-these) to help you catch bugs in the act:
+.SH ACTIONS
+Duplicity knows action commands, which can be finetuned with options.
+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
+a restore is in order, is the local folder before target URL then this folder
+is about to be backed up to the target URL.
+.br
+If a backup is in order and old signatures can be found duplicity automatically
+performs an incremental backup.
 
 .TP
-\ \ \ \(bu
-Start your program, specifying anything that might affect its behavior.
+.B full
+Perform a full backup. A new backup chain is started even if
+signatures are available for an incremental backup.
+
+.TP
+.BR incr
+If this is requested an incremental backup will be performed.
+Duplicity will abort if no old signatures can be found.
+
+.TP
+.B collection-status
+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>]"
+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
+the other hand if the archive has been deleted or corrupted, this
+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>]"
+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 .
+Usually not needed as duplicity enters restore mode when it detects that the URL
+comes before the local folder.
+
+.TP
+.BI "remove-older-than " time
+Delete all backup sets older than the given time.  Old backup sets
+will not be deleted if backup sets newer than
+.I time
+depend on them.  See the
+.B TIME FORMATS
+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.
+
+.TP
+.BI "remove-all-but-n-full " count
+Delete all backups sets that are older than the count:th last full
+backup (in other words, keep the last
+.I count
+full backups and associated incremental sets).
+.I count
+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.
+
+.TP
+.BI "remove-all-inc-of-but-n-full " count
+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.
+
+.TP
+.B cleanup
+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.
 
-.TP
-\ \ \ \(bu
-Make your program stop on specified conditions.
+.SH OPTIONS
 
 .TP
-\ \ \ \(bu
-Examine what has happened, when your program has stopped.
+.BI --allow-source-mismatch
+Do not abort on attempts to use the same archive dir or remote backend
+to back up different directories. duplicity will tell you if you need
+this switch.
+
+.TP
+.BI "--archive-dir " path
+The archive directory.
+.B NOTE:
+This option changed in 0.6.0.  The archive directory is now necessary
+in order to manage persistence for current and future enhancements.
+As such, this option is now used only to change the location of the
+archive directory.  The archive directory should
+.B not
+be deleted, or duplicity will have to recreate it from
+the remote repository (which may require decrypting the backup contents).
+
+When backing up or restoring, this option specifies that the local
+archive directory is to be created in
+.IR path .
+If the archive directory is not specified, the default will be to
+create the archive directory in
+.IR ~/.cache/duplicity/ .
+
+The archive directory can be shared between backups to multiple targets,
+because a subdirectory of the archive dir is used for individual backups (see
+.B --name
+).
+
+The combination of archive directory and backup name must be unique
+in order to separate the data of different backups.
+
+The interaction between the
+.B --archive-dir
+and the
+.B --name
+options allows for four possible combinations for the location of the archive dir:
+
+.RS
+.IP 1.
+neither specified (default)
+ ~/.cache/duplicity/\c
+.IR hash-of-url
+.IP 2.
+--archive-dir=/arch, no --name
+ /arch/\c
+.IR hash-of-url
+.IP 3.
+no --archive-dir, --name=foo
+ ~/.cache/duplicity/foo
+.IP 4.
+--archive-dir=/arch, --name=foo
+ /arch/foo
+.RE
+
+.TP
+.BI "--asynchronous-upload "
+(EXPERIMENTAL) Perform file uploads asynchronously in the background,
+with respect to volume creation. This means that duplicity can upload
+a volume while, at the same time, preparing the next volume for
+upload. The intended end-result is a faster backup, because the local
+CPU and your bandwidth can be more consistently utilized. Use of this
+option implies additional need for disk space in the temporary storage
+location; rather than needing to store only one volume at a time,
+enough storage space is required to store two volumes.
+
+.TP
+.BI "--dry-run "
+Calculate what would be done, but do not perform any backend actions
+
+.TP
+.BI "--encrypt-key " key-id
+When backing up, encrypt to the given public key, instead of using
+symmetric (traditional) encryption.  Can be specified multiple times.
+The key-id can be given in any of the formats supported by GnuPG; see 
+.BR gpg (1),
+section "HOW TO SPECIFY A USER ID" for details.
+
+
+.TP
+.BI "--encrypt-secret-keyring " filename
+This option can only be used with
+.BR --encrypt-key ,
+and changes the path to the secret keyring for the encrypt key to
+.I filename
+This keyring is not used when creating a backup. If not specified, the
+default secret keyring is used which is usually located at .gnupg/secring.gpg
+
+.TP
+.BI "--encrypt-sign-key " key-id
+Convenience parameter. Same as
+.BR --encrypt-key 
+.IR key-id
+.BR --sign-key 
+.IR "key-id" .
+
+.TP
+.BI "--exclude " shell_pattern
+Exclude the file or files matched by
+.IR shell_pattern .
+If a directory is matched, then files under that directory will also
+be matched.  See the
+.B FILE SELECTION
+section for more information.
+
+.TP
+.B "--exclude-device-files"
+Exclude all device files.  This can be useful for security/permissions
+reasons or if rdiff-backup is not handling device files correctly.
+
+.TP
+.BI "--exclude-filelist " filename
+Excludes the files listed in
+.IR filename .
+See the
+.B FILE SELECTION
+section for more information.
+
+.TP
+.B --exclude-filelist-stdin
+Like
+.B --exclude-filelist,
+but the list of files will be read from standard input.  See the
+.B FILE SELECTION
+section for more information.
+
+.TP
+.BR "--exclude-globbing-filelist " filename
+Like
+.B --exclude-filelist
+but each line of the filelist will be interpreted according to the
+same rules as
+.B --include
+and
+.B --exclude.
 
 .TP
-\ \ \ \(bu
-Change things in your program, so you can experiment with correcting the
-effects of one bug and go on to learn about another.
-.PP
-
-You can use GDB to debug programs written in C, C++, and Modula-2.
-Fortran support will be added when a GNU Fortran compiler is ready.
-
-GDB is invoked with the shell command \c
-.B gdb\c
-\&.  Once started, it reads
-commands from the terminal until you tell it to exit with the GDB
-command \c
-.B quit\c
-\&.  You can get online help from \c
-.B gdb\c
-\& itself
-by using the command \c
-.B help\c
-\&.
-
-You can run \c
-.B gdb\c
-\& with no arguments or options; but the most
-usual way to start GDB is with one argument or two, specifying an
-executable program as the argument:
-.sp
-.br
-gdb\ program
-.br
-.sp
-
-You can also start with both an executable program and a core file specified:
-.sp
-.br
-gdb\ program\ core
-.br
-.sp
+.BR "--exclude-if-present " filename
+Exclude directories if filename is present. This option needs to
+come before any other include or exclude options.
 
-You can, instead, specify a process ID as a second argument, if you want
-to debug a running process:
-.sp
-.br
-gdb\ program\ 1234
-.br
-.sp
+.TP
+.B --exclude-other-filesystems
+Exclude files on file systems (identified by device number) other than
+the file system the root of the source directory is on.
 
-would attach GDB to process \c
-.B 1234\c
-\& (unless you also have a file
-named `\|\c
-.B 1234\c
-\&\|'; GDB does check for a core file first).
+.TP
+.BI "--exclude-regexp " regexp
+Exclude files matching the given regexp.  Unlike the
+.B --exclude
+option, this option does not match files in a directory it matches.
+See the
+.B FILE SELECTION
+section for more information.
 
-Here are some of the most frequently needed GDB commands:
 .TP
-.B break \fR[\|\fIfile\fB:\fR\|]\fIfunction
-\&
-Set a breakpoint at \c
-.I function\c
-\& (in \c
-.I file\c
-\&).
+.B --extra-clean
+When cleaning up, be more aggressive about saving space.  For example, this
+may delete signature files for old backup chains.
+See the
+.B cleanup
+argument for more information.
+
 .TP
-.B run \fR[\|\fIarglist\fR\|]
-Start your program (with \c
-.I arglist\c
-\&, if specified).
+.BI "--file-to-restore " path
+This option may be given in restore mode, causing only
+.I path
+to be restored instead of the entire contents of the backup archive.
+.I path
+should be given relative to the root of the directory backed up.
+
 .TP
-.B bt
-Backtrace: display the program stack.
+.BI "--full-if-older-than " time
+Perform a full backup if an incremental backup is requested, but the
+latest full backup in the collection is older than the given
+.IR time .
+See the
+.B TIME FORMATS
+section for more information.
+
 .TP
-.BI print " expr"\c
-\&
-Display the value of an expression.
+.B --force
+Proceed even if data loss might result.  Duplicity will let the user
+know when this option is required.
+
 .TP
-.B c
-Continue running your program (after stopping, e.g. at a breakpoint).
+.B --ftp-passive
+Use passive (PASV) data connections.  The default is to use passive,
+but to fallback to regular if the passive connection fails or times
+out.
+
 .TP
-.B next
-Execute next program line (after stopping); step \c
-.I over\c
-\& any
-function calls in the line.
+.B --ftp-regular
+Use regular (PORT) data connections.
+
 .TP
-.B edit \fR[\|\fIfile\fB:\fR\|]\fIfunction
-look at the program line where it is presently stopped.
+.B --gio
+Use the GIO backend and interpret any URLs as GIO would.
+
 .TP
-.B list \fR[\|\fIfile\fB:\fR\|]\fIfunction
-type the text of the program in the vicinity of where it is presently stopped.
+.BI "--hidden-encrypt-key " key-id
+Same as
+.BR --encrypt-key ,
+but it hides user's key id from encrypted file. It uses the gpg's
+.B --hidden-recipient
+command to obfuscate the owner of the backup. On restore, gpg will 
+automatically try all available secret keys in order to decrypt the 
+backup. See gpg(1) for more details.
+
+
 .TP
-.B step
-Execute next program line (after stopping); step \c
-.I into\c
-\& any
-function calls in the line.
+.B --ignore-errors
+Try to ignore certain errors if they happen. This option is only
+intended to allow the restoration of a backup in the face of certain
+problems that would otherwise cause the backup to fail. It is not ever
+recommended to use this option unless you have a situation where you
+are trying to restore from backup and it is failing because of an
+issue which you want duplicity to ignore. Even then, depending on the
+issue, this option may not have an effect.
+
+Please note that while ignored errors will be logged, there will be no
+summary at the end of the operation to tell you what was ignored, if
+anything. If this is used for emergency restoration of data, it is
+recommended that you run the backup in such a way that you can revisit
+the backup log (look for lines containing the string IGNORED_ERROR).
+
+If you ever have to use this option for reasons that are not
+understood or understood but not your own responsibility, please
+contact duplicity maintainers. The need to use this option under
+production circumstances would normally be considered a bug.
+
 .TP
-.B help \fR[\|\fIname\fR\|]
-Show information about GDB command \c
-.I name\c
-\&, or general information
-about using GDB.
+.BI "--imap-mailbox " option
+Allows you to specify a different mailbox.  The default is
+"INBOX".
+Other languages may require a different mailbox than the default.
+
 .TP
-.B quit
-Exit from GDB.
-.PP
-For full details on GDB, see \c
-.I 
-Using GDB: A Guide to the GNU Source-Level Debugger\c
-\&, by Richard M. Stallman and Roland H. Pesch.  The same text is available online
-as the \c
-.B gdb\c
-\& entry in the \c
-.B info\c
-\& program.
-.SH OPTIONS
-Any arguments other than options specify an executable
-file and core file (or process ID); that is, the first argument
-encountered with no 
-associated option flag is equivalent to a `\|\c
-.B \-se\c
-\&\|' option, and the
-second, if any, is equivalent to a `\|\c
-.B \-c\c
-\&\|' option if it's the name of a file.  Many options have
-both long and short forms; both are shown here.  The long forms are also
-recognized if you truncate them, so long as enough of the option is
-present to be unambiguous.  (If you prefer, you can flag option
-arguments with `\|\c
-.B +\c
-\&\|' rather than `\|\c
-.B \-\c
-\&\|', though we illustrate the
-more usual convention.)
+.BI "--gpg-options " options
+Allows you to pass options to gpg encryption.  The
+.I options
+list should be of the form "opt1=parm1 opt2=parm2" where the string is
+quoted and the only spaces allowed are between options.
 
-All the options and command line arguments you give are processed
-in sequential order.  The order makes a difference when the
-`\|\c
-.B \-x\c
-\&\|' option is used.
+.TP
+.BI "--include " shell_pattern
+Similar to
+.B --exclude
+but include matched files instead.  Unlike
+.BR --exclude ,
+this option will also match parent directories of matched files
+(although not necessarily their contents).  See the
+.B FILE SELECTION
+section for more information.
 
 .TP
-.B \-help
+.BI "--include-filelist " filename
+Like
+.BR --exclude-filelist ,
+but include the listed files instead.  See the
+.B FILE SELECTION
+section for more information.
+
 .TP
-.B \-h
-List all options, with brief explanations.
+.B --include-filelist-stdin
+Like
+.BR --include-filelist ,
+but read the list of included files from standard input.
 
 .TP
-.BI "\-symbols=" "file"\c
+.BI "--include-globbing-filelist " filename
+Like
+.B --include-filelist
+but each line of the filelist will be interpreted according to the
+same rules as
+.B --include
+and
+.B --exclude.
+
 .TP
-.BI "\-s " "file"\c
-\&
-Read symbol table from file \c
-.I file\c
-\&.
+.BI "--include-regexp " regexp
+Include files matching the regular expression
+.IR regexp .
+Only files explicitly matched by
+.I regexp
+will be included by this option.  See the
+.B FILE SELECTION
+section for more information.
 
 .TP
-.B \-write
-Enable writing into executable and core files.
+.BI "--log-fd " number
+Write specially-formatted versions of output messages to the specified file
+descriptor.  The format used is designed to be easily consumable by other
+programs.
 
 .TP
-.BI "\-exec=" "file"\c
+.BI "--log-file " filename
+Write specially-formatted versions of output messages to the specified file.
+The format used is designed to be easily consumable by other programs.
+
 .TP
-.BI "\-e " "file"\c
-\&
-Use file \c
-.I file\c
-\& as the executable file to execute when
-appropriate, and for examining pure data in conjunction with a core
-dump.
+.BI "--name " symbolicname
+Set the symbolic name of the backup being operated on. The intent is
+to use a separate name for each logically distinct backup. For
+example, someone may use "home_daily_s3" for the daily backup of a
+home directory to Amazon S3. The structure of the name is up to the
+user, it is only important that the names be distinct. The symbolic
+name is currently only used to affect the expansion of
+.B --archive-dir
+, but may be used for additional features in the future. Users running
+more than one distinct backup are encouraged to use this option.
+
+If not specified, the default value is a hash of the backend URL.
 
 .TP
-.BI "\-se=" "file"\c
-\&
-Read symbol table from file \c
-.I file\c
-\& and use it as the executable
-file.
+.B --no-encryption
+Do not use GnuPG to encrypt files on remote system.  Instead just
+write gzipped volumes.
 
 .TP
-.BI "\-core=" "file"\c
+.B --no-print-statistics
+By default duplicity will print statistics about the current session
+after a successful backup.  This switch disables that behavior.
+
 .TP
-.BI "\-c " "file"\c
-\&
-Use file \c
-.I file\c
-\& as a core dump to examine.
+.B --null-separator
+Use nulls (\\0) instead of newlines (\\n) as line separators, which
+may help when dealing with filenames containing newlines.  This
+affects the expected format of the files specified by the
+--{include|exclude}-filelist[-stdin] switches as well as the format of
+the directory statistics file.
 
 .TP
-.BI "\-command=" "file"\c
+.B --numeric-owner
+On restore always use the numeric uid/gid from the archive and not the 
+archived user/group names, which is the default behaviour.
+Recommended for restoring from live cds which might have the users with 
+identical names but different uids/gids.
+
 .TP
-.BI "\-x " "file"\c
-\&
-Execute GDB commands from file \c
-.I file\c
-\&.  
+.BI "--num-retries " number
+Number of retries to make on errors before giving up.
 
 .TP
-.BI "\-ex " "command"\c
-\&
-Execute given GDB \c
-.I command\c
-\&.
+.B --old-filenames
+Use the old filename format (incompatible with Windows/Samba) rather than
+the new filename format.
 
 .TP
-.BI "\-directory=" "directory"\c
+.BI "--rename " "orig new"
+Treats the path
+.I orig
+in the backup as if it were the path
+.I new.
+Can be passed multiple times. An example:
+
+duplicity restore --rename Documents/metal Music/metal sftp://uid@other.host/some_dir /home/me
+
 .TP
-.BI "\-d " "directory"\c
-\&
-Add \c
-.I directory\c
-\& to the path to search for source files.
-.PP
+.BI "--rsync-options " options
+Allows you to pass options to the rsync backend.  The
+.I options
+list should be of the form "opt1=parm1 opt2=parm2" where the option string is
+quoted and the only spaces allowed are between options. The option string
+will be passed verbatim to rsync, after any internally generated option
+designating the remote port to use. Here is a possibly useful example:
+
+duplicity --rsync-options="--partial-dir=.rsync-partial" /home/me rsync://uid@other.host/some_dir
 
 .TP
-.B \-nh
-Do not execute commands from ~/.gdbinit.
+.BI "--s3-european-buckets"
+When using the Amazon S3 backend, create buckets in Europe instead of
+the default (requires
+.B --s3-use-new-style
+). Also see the
+.B EUROPEAN S3 BUCKETS
+section.
 
 .TP
-.B \-nx
+.BI "--s3-unencrypted-connection"
+Don't use SSL for connections to S3.
+
+This may be much faster, at some cost to confidentiality.
+
+With this option, anyone who can observe traffic between your computer and S3
+will be able to tell: that you are using Duplicity, the name of the bucket,
+your AWS Access Key ID, the increment dates and the amount of data in each
+increment.
+
+This option affects only the connection, not the GPG encryption of the backup
+increment files.  Unless that is disabled, an observer will not be able to see
+the file names or contents.
+
 .TP
-.B \-n
-Do not execute commands from any `\|\c
-.B .gdbinit\c
-\&\|' initialization files.
+.BI "--s3-use-new-style"
+When operating on Amazon S3 buckets, use new-style subdomain bucket
+addressing. This is now the preferred method to access Amazon S3, but
+is not backwards compatible if your bucket name contains upper-case
+characters or other characters that are not valid in a hostname.
 
+.TP
+.BI "--scp-command " command
+.B (only ssh pexpect backend with --use-scp enabled)
+The
+.I command
+will be used instead of "scp" to send or receive files.
+To list and delete existing files, the sftp command is used.
+.br
+See also
+.B "A NOTE ON SSH BACKENDS"
+section
+.BR "SSH pexpect backend" .
 
 .TP
-.B \-quiet
+.BI "--sftp-command " command
+.B (only ssh pexpect backend)
+The
+.I command
+will be used instead of "sftp". 
+.br
+See also
+.B "A NOTE ON SSH BACKENDS"
+section
+.BR "SSH pexpect backend" .
+
+.TP
+.BI --short-filenames
+If this option is specified, the names of the files duplicity writes
+will be shorter (about 30 chars) but less understandable.  This may be
+useful when backing up to MacOS or another OS or FS that doesn't
+support long filenames.
+
+.TP
+.BI "--sign-key " key-id
+This option can be used when backing up, restoring or verifying. 
+When backing up, all backup files will be signed with keyid
+.IR key .
+When restoring, duplicity will signal an error if any remote file is
+not signed with the given key-id. The key-id can be givein in any of 
+the formats supported by GnuPG; see 
+.BR gpg (1),
+section "HOW TO SPECIFY A USER ID" for details.
+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 \-q
-``Quiet''.  Do not print the introductory and copyright messages.  These
-messages are also suppressed in batch mode.
+.B --ssh-askpass
+Tells the ssh backend to prompt the user for the remote system password, 
+if it was not defined in target url and no FTP_PASSWORD env var is set.
+This password is also used for passphrase-protected ssh keys.
 
 .TP
-.B \-batch
-Run in batch mode.  Exit with status \c
-.B 0\c
-\& after processing all the command
-files specified with `\|\c
-.B \-x\c
-\&\|' (and `\|\c
-.B .gdbinit\c
-\&\|', if not inhibited).
-Exit with nonzero status if an error occurs in executing the GDB
-commands in the command files.
+.BI "--ssh-backend " backend
+Allows the explicit selection of a ssh backend. Defaults to 
+.BR paramiko .
+Alternatively you might choose 
+.BR pexpect .
+.br
+See also
+.BR "A NOTE ON SSH BACKENDS" .
 
-Batch mode may be useful for running GDB as a filter, for example to
-download and run a program on another computer; in order to make this
-more useful, the message
-.sp
+.TP
+.BI "--ssh-options " options
+Allows you to pass options to the ssh backend.  The
+.I options
+list should be of the form "-oOpt1=parm1 -oOpt2=parm2" where the option string is
+quoted and the only spaces allowed are between options. The option string
+will be passed verbatim to both scp and sftp, whose command line syntax
+differs slightly hence the options should therefore be given in the long option format described in
+.BR ssh_config(5) ,
+like in this example:
+
+duplicity --ssh-options="-oProtocol=2 -oIdentityFile=/my/backup/id" /home/me scp://uid@other.host/some_dir
+
+.B NOTE:
+.I ssh paramiko backend
+currently supports only the
+.B -oIdentityFile
+setting.
+.RE
+
+.TP
+.BI "--ssl-cacert-file " file
+.B (only webdav backend)
+Provide a cacert file for ssl certificate verification.
 .br
-Program\ exited\ normally.
+See also
+.BR "A NOTE ON SSL CERTIFICATE VERIFICATION" .
+
+.TP
+.B --ssl-no-check-certificate
+.B (only webdav backend)
+Disable ssl certificate verification.
 .br
-.sp
+See also
+.BR "A NOTE ON SSL CERTIFICATE VERIFICATION" .
 
-(which is ordinarily issued whenever a program running under GDB control
-terminates) is not issued when running in batch mode.
+.TP
+.BI "--tempdir " directory
+Use this existing directory for duplicity temporary files instead of
+the system default, which is usually the /tmp directory. This option
+supersedes any environment variable.
+.br
+See also
+.BR "ENVIRONMENT VARIABLES" .
 
 .TP
-.BI "\-cd=" "directory"\c
-\&
-Run GDB using \c
-.I directory\c
-\& as its working directory,
-instead of the current directory.
+.BI -t time ", --time " time ", --restore-time " time
+Specify the time from which to restore or list files.
 
 .TP
-.B \-fullname
+.BI "--time-separator " char
+Use
+.IR char
+as the time separator in filenames instead of colon (":").
+
 .TP
-.B \-f
-Emacs sets this option when it runs GDB as a subprocess.  It tells GDB
-to output the full file name and line number in a standard,
-recognizable fashion each time a stack frame is displayed (which
-includes each time the program stops).  This recognizable format looks
-like two `\|\c
-.B \032\c
-\&\|' characters, followed by the file name, line number
-and character position separated by colons, and a newline.  The
-Emacs-to-GDB interface program uses the two `\|\c
-.B \032\c
-\&\|' characters as
-a signal to display the source code for the frame.
+.BI "--timeout " seconds
+Use
+.IR seconds
+as the socket timeout value if duplicity begins to timeout during
+network operations.  The default is 30 seconds.
 
 .TP
-.BI "\-b " "bps"\c
-\&
-Set the line speed (baud rate or bits per second) of any serial
-interface used by GDB for remote debugging.
+.BI --use-agent
+If this option is specified, then
+.I --use-agent
+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
+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 "\-tty=" "device"\c
-\&
-Run using \c
-.I device\c
-\& for your program's standard input and output.
+.BI --use-scp
+If this option is specified, then the ssh backend will use the
+scp protocol rather than sftp for backend operations.
+.br
+See also
+.BR "A NOTE ON SSH BACKENDS" .
 
 .TP
-.BI "\-\-args"\c
-Pass \c
-.I arguments\c
-\& after the program name to the program when it is run.
+.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 "\-tui"\c
-Run GDB using a text (console) user interface.
+.BI --version
+Print duplicity's version and quit.
+
+.TP
+.BI "--volsize " number
+Change the volume size to
+.IR number
+Mb. Default is 25Mb.
+
+.SH ENVIRONMENT VARIABLES
+
+.TP
+.B TMPDIR, TEMP, TMP
+In decreasing order of importance, specifies the directory to use for
+temporary files (inherited from Python's tempfile module).
+Eventually the option
+.B --tempdir
+supercedes any of these.
+.TP
+.B FTP_PASSWORD
+Supported by most backends which are password capable. More secure than
+setting it in the backend url (which might be readable in the operating
+systems process listing to other users on the same machine).
+.TP
+.B PASSPHRASE
+This passphrase is passed to GnuPG. If this is not set, the user will be
+prompted for the passphrase.
+.TP
+.B SIGN_PASSPHRASE
+The passphrase to be used for 
+.BR --sign-key .
+If ommitted 
+.B and
+sign key is also one of the keys to encrypt against 
+.B PASSPHRASE 
+will be reused instead.
+Otherwise, if passphrase is needed but not set the user will be prompted for it.
+
+.SH URL FORMAT
+Duplicity uses the URL format (as standard as possible) to define data locations.
+The generic format for a URL is:
+.PP
+.RS
+scheme://[user[:password]@]host[:port]/[/]path
+.PP
+.RE
+It is not recommended to expose the password on the command line since
+it could be revealed to anyone with permissions to do process listings,
+it is permitted however.
+Consider setting the environment variable 
+.B FTP_PASSWORD 
+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,
+or preceded by a double slash, '//path', to represent an absolute
+filesystem path.
+.PP
+Formats of each of the URL schemes follow:
+.RS
+.PP
+cf+http://container_name
+.br
+See also
+.B "A NOTE ON CLOUD FILES ACCESS"
+.PP
+file://[relative|/absolute]/local/path
+.PP
+ftp[s]://user[:password]@other.host[:port]/some_dir
 .PP
+gdocs://user[:password]@other.host/some_dir
+.PP
+hsi://user[:password]@other.host/some_dir
+.PP
+imap[s]://user[:password]@host.com[/from_address_prefix]
+.br
+See also
+.B "A NOTE ON IMAP"
+.PP
+.B "using rsync daemon"
+.br
+rsync://user[:password]@host.com[:port]::[/]module/some_dir
+.br
+.B "using rsync over ssh (only key auth)"
+.br
+rsync://user@host.com[:port]/[relative|/absolute]_path
+.PP
+s3://host/bucket_name[/prefix]
+.br
+s3+http://bucket_name[/prefix]
+.br
+See also
+.B "A NOTE ON EUROPEAN S3 BUCKETS"
+.PP
+scp://.. or ssh://.. are synonymous with
+.br
+sftp://user[:password]@other.host[:port]/[/]some_dir
+.br
+See also
+.BR --ssh-backend ,
+.BR --ssh-askpass ,
+.BR --use-scp ,
+.B  --ssh-options
+and
+.BR "A NOTE ON SSH BACKENDS" .
+.PP
+tahoe://alias/directory
+.PP
+.BI "Ubuntu One"
+.br
+u1://host_is_ignored/volume_path
+.br
+u1+http://volume_path
+.br
+See also
+.BI "A NOTE ON UBUNTU ONE"
+.PP
+webdav[s]://user[:password]@other.host/some_dir
+.RE
 
-.SH "SEE ALSO"
-The full documentation for
-.B gdb
-is maintained as a Texinfo manual.  If the
-.B info
+.SH TIME FORMATS
+duplicity uses time strings in two places.  Firstly, many of the files
+duplicity creates will have the time in their filenames in the w3
+datetime format as described in a w3 note at
+http://www.w3.org/TR/NOTE-datetime.  Basically they look like
+"2001-07-15T04:09:38-07:00", which means what it looks like.  The
+"-07:00" section means the time zone is 7 hours behind UTC.
+.PP
+Secondly, the
+.BR -t ", " --time ", and " --restore-time
+options take a time string, which can be given in any of several
+formats:
+.IP 1.
+the string "now" (refers to the current time)
+.IP 2.
+a sequences of digits, like "123456890" (indicating the time in
+seconds after the epoch)
+.IP 3.
+A string like "2002-01-25T07:00:00+02:00" in datetime format
+.IP 4.
+An interval, which is a number followed by one of the characters s, m,
+h, D, W, M, or Y (indicating seconds, minutes, hours, days, weeks,
+months, or years respectively), or a series of such pairs.  In this
+case the string refers to the time that preceded the current time by
+the length of the interval.  For instance, "1h78m" indicates the time
+that was one hour and 78 minutes ago.  The calendar here is
+unsophisticated: a month is always 30 days, a year is always 365 days,
+and a day is always 86400 seconds.
+.IP 5.
+A date format of the form YYYY/MM/DD, YYYY-MM-DD, MM/DD/YYYY, or
+MM-DD-YYYY, which indicates midnight on the day in question, relative
+to the current time zone settings.  For instance, "2002/3/5",
+"03-05-2002", and "2002-3-05" all mean March 5th, 2002.
+
+.SH FILE SELECTION
+duplicity accepts the same file selection options
+.B rdiff-backup
+does, including --exclude, --exclude-filelist-stdin, etc.
+
+When duplicity is run, it searches through the given source
+directory and backs up all the files specified by the file selection
+system.  The file selection system comprises a number of file
+selection conditions, which are set using one of the following command
+line options:
+.RS
+--exclude
+.br
+--exclude-device-files
+.br
+--exclude-filelist
+.br
+--exclude-filelist-stdin
+.br
+--exclude-globbing-filelist
+.br
+--exclude-regexp
+.br
+--include
+.br
+--include-filelist
+.br
+--include-filelist-stdin
+.br
+--include-globbing-filelist
+.br
+--include-regexp
+.RE
+Each file selection condition either matches or doesn't match a given
+file.  A given file is excluded by the file selection system exactly
+when the first matching file selection condition specifies that the
+file be excluded; otherwise the file is included.
+
+For instance,
+.PP
+.RS
+duplicity --include /usr --exclude /usr /usr scp://user@host/backup
+.PP
+.RE
+is exactly the same as
+.PP
+.RS
+duplicity /usr scp://user@host/backup
+.PP
+.RE
+because the include and exclude directives match exactly the same
+files, and the
+.B --include
+comes first, giving it precedence.  Similarly,
+.PP
+.RS
+duplicity --include /usr/local/bin --exclude /usr/local /usr
+scp://user@host/backup
+.PP
+.RE
+would backup the /usr/local/bin directory (and its contents), but not
+/usr/local/doc.
+
+The
+.BR include ,
+.BR exclude ,
+.BR include-globbing-filelist ,
+and
+.B exclude-globbing-filelist
+options accept some
+.IR "extended shell globbing patterns" .
+These patterns can contain
+.BR * ,
+.BR ** ,
+.BR ? ,
 and
-.B gdb
-programs and GDB's Texinfo documentation are properly installed at
-your site, the command
-.IP
-.B info gdb
+.B [...]
+(character ranges). As in a normal shell,
+.B *
+can be expanded to any string of characters not containing "/",
+.B ?
+expands to any character except "/", and
+.B [...]
+expands to a single character of those characters specified (ranges
+are acceptable).  The new special pattern,
+.BR ** ,
+expands to any string of characters whether or not it contains "/".
+Furthermore, if the pattern starts with "ignorecase:" (case
+insensitive), then this prefix will be removed and any character in
+the string can be replaced with an upper- or lowercase version of
+itself.
+
+Remember that you may need to quote these characters when typing them
+into a shell, so the shell does not interpret the globbing patterns
+before duplicity sees them.
+
+The
+.B --exclude
+pattern option matches a file if:
+.IP 1.
+.I pattern
+can be expanded into the file's filename, or
+.IP 2.
+the file is inside a directory matched by the option.
+.PP
+Conversely, the 
+.B "--include " 
+pattern matches a file if:
+.IP 1.
+.I pattern
+can be expanded into the file's filename, or
+.IP 2.
+the file is inside a directory matched by the option, or
+.IP 3.
+the file is a directory which contains a file matched by the option.
 .PP
-should give you access to the complete manual.
+For example,
+
+.B --exclude
+/usr/local
+
+matches e.g. /usr/local, /usr/local/lib, and /usr/local/lib/netscape.  It
+is the same as --exclude /usr/local --exclude '/usr/local/**'.
+
+Or
+.br
+.B --include
+/usr/local
+
+specifies that /usr, /usr/local, /usr/local/lib, and
+/usr/local/lib/netscape (but not /usr/doc) all be backed up. Thus you
+don't have to worry about including parent directories to make sure
+that included subdirectories have somewhere to go. 
+
+Finally,
+.br
+.B --include
+ignorecase:'/usr/[a-z0-9]foo/*/**.py'
 
-.I 
-Using GDB: A Guide to the GNU Source-Level Debugger\c
-, Richard M. Stallman and Roland H. Pesch, July 1991.
-.SH COPYING
-Copyright (c) 1991, 2010 Free Software Foundation, Inc.
+would match a file like /usR/5fOO/hello/there/world.py.  If it did
+match anything, it would also match /usr.  If there is no existing
+file that the given pattern can be expanded into, the option will not
+match /usr alone.
+
+The
+.BR --include-filelist ,
+.BR --exclude-filelist ,
+.BR --include-filelist-stdin ,
+and
+.B --exclude-filelist-stdin
+options also introduce file selection conditions.  They direct
+duplicity to read in a file, each line of which is a file
+specification, and to include or exclude the matching files.  Lines
+are separated by newlines or nulls, depending on whether the
+--null-separator switch was given.  Each line in a filelist is
+interpreted similarly to the way
+.I extended shell patterns
+are, with a few exceptions:
+.IP 1.
+Globbing patterns like
+.BR * ,
+.BR ** ,
+.BR ? ,
+and
+.B [...]
+are not expanded.
+.IP 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.
+Lines starting with "+ " are interpreted as include directives, even
+if found in a filelist referenced by
+.BR --exclude-filelist .
+Similarly, lines starting with "- " exclude files even if they are
+found within an include filelist.
 .PP
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
+For example, if file "list.txt" contains the lines:
+
+.RS
+/usr/local
+.br
+- /usr/local/doc
+.br
+/usr/local/bin
+.br
++ /var
+.br
+- /var
+.RE
+
+then 
+.B "--include-filelist list.txt"
+would include /usr, /usr/local, and
+/usr/local/bin.  It would exclude /usr/local/doc,
+/usr/local/doc/python, etc.  It neither excludes nor includes
+/usr/local/man, leaving the fate of this directory to the next
+specification condition.  Finally, it is undefined what happens with
+/var.  A single file list should not contain conflicting file
+specifications.
+
+The
+.B --include-globbing-filelist
+and
+.B --exclude-globbing-filelist
+options also specify filelists, but each line in the filelist will be
+interpreted as a globbing pattern the way
+.B --include
+and
+.B --exclude
+options are interpreted (although "+ " and "- " prefixing is still
+allowed).  For instance, if the file "globbing-list.txt" contains the
+lines:
+
+.RS
+dir/foo
+.br
++ dir/bar
+.br
+- **
+.RE
+
+Then 
+.B "--include-globbing-filelist globbing-list.txt" 
+would be exactly the same as specifying 
+.B "--include dir/foo --include dir/bar --exclude **"
+on the command line.
+
+Finally, the
+.B --include-regexp
+and
+.B --exclude-regexp
+options allow files to be included and excluded if their filenames match a
+python regular expression.  Regular expression syntax is too
+complicated to explain here, but is covered in Python's library
+reference.  Unlike the
+.B --include
+and
+.B --exclude
+options, the regular expression options don't match files containing
+or contained in matched files.  So for instance
+.PP
+.RS
+--include '[0-9]{7}(?!foo)'
+.PP
+.RE
+matches any files whose full pathnames contain 7 consecutive digits
+which aren't followed by 'foo'.  However, it wouldn't match /home even
+if /home/ben/1234567 existed.
+
+.SH A NOTE ON CLOUD FILES ACCESS
+Cloudfiles is Rackspace's implementation of OpenStack Object Storage
+protocol.
+
+The backend requires python-cloudfiles to be installed on the system.
+See 
+.B REQUIREMENTS 
+above.
+
+It uses three environment variables for authentification:
+.BR CLOUDFILES_USERNAME " (required),"
+.BR CLOUDFILES_APIKEY " (required),"
+.BR CLOUDFILES_AUTHURL " (optional)"
+
+If 
+.B CLOUDFILES_AUTHURL 
+is unspecified it will default to the value
+provided by python-cloudfiles, which points to rackspace, hence this value 
+.I must 
+be set in order to use other cloud files providers.
+
+.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,
+because it may allow for faster data transfers.
+.PP
+duplicity will create a new bucket the first time a bucket access is
+attempted. At this point, the bucket will be created in Europe if
+.B --s3-european-buckets
+was given. For reasons having to do with how the Amazon S3 service
+works, this also requires the use of the
+.B --s3-use-new-style
+option. This option turns on subdomain based bucket addressing in
+S3. The details are beyond the scope of this man page, but it is
+important to know that your bucket must not contain upper case letters
+or any other characters that are not valid parts of a
+hostname. Consequently, for reasons of backwards compatibility, use of
+subdomain based bucket addressing is not enabled by default.
+.PP
+Note that you will need to use
+.B --s3-use-new-style
+for all operations on European buckets; not just upon initial
+creation.
+.PP
+You only need to use
+.B --s3-european-buckets
+upon initial creation, but you may may use it at all times for
+consistency.
+.PP
+Further note that when creating a new European bucket, it can take a
+while before the bucket is fully accessible. At the time of this
+writing it is unclear to what extent this is an expected feature of
+Amazon S3, but in practice you may experience timeouts, socket errors
+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 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
+The
+.B from_address_prefix
+may be specified (and probably should be). The text will be used as
+the "From" address in the IMAP server.  Then on a restore (or list) command
+the
+.B from_address_prefix
+will distinguish between different backups.
+
+.SH A NOTE ON SSH BACKENDS
+The 
+.I ssh backends
+support
+.I sftp
+and
+.I scp/ssh
+transport protocols.
+This is a known user-confusing issue as these are fundamentally different.
+If you plan to access your backend via one of those please inform yourself 
+about the requirements for a server to support
+.IR sftp " or"
+.I scp/ssh
+access.
+To make it even more confusing the user can choose between two ssh backends via
+.BR --ssh-backend " option."
+.br
+Both support
+.BR --use-scp ,
+.BR --ssh-askpass " and"
+.BR --ssh-options "."
+Only the 
+.B pexpect
+backend allows to define
+.BR --scp-command " and"
+.BR --sftp-command .
+.PP
+.BR "SSH paramiko backend " "(selected by default)"
+is a complete reimplementation of ssh protocols natively in python. Advantages 
+are speed and maintainability. Minor disadvantage is that extra packages are 
+needed as listed in
+.B REQUIREMENTS
+above. In
+.I sftp
+(default) mode all operations are done via the according sftp commands. In
+.I scp
+mode (
+.I --use-scp
+) though scp access is used for put/get operations but listing is done via ssh remote shell.
+.PP
+.B SSH pexpect backend
+is the legacy ssh backend using the command line ssh binaries via pexpect.
+Older versions used
+.I scp
+for get and put operations and
+.I sftp
+for list and
+delete operations.  The current version uses
+.I sftp
+for all four supported
+operations, unless the
+.I --use-scp
+option is used to revert to old behavior. 
+.PP
+.B Why use sftp instead of scp?
+The change to sftp was made in order to allow the remote system to chroot the backup,
+thus providing better security and because it does not suffer from shell quoting issues like scp. 
+Scp also does not support any kind of file listing, so sftp or ssh access will always be needed 
+in addition for this backend mode to work properly. Sftp does not have these limitations but needs
+an sftp service running on the backend server, which is sometimes not an option.
+
+.SH A NOTE ON SSL CERTIFICATE VERIFICATION
+Certificate verification as implemented right now [01.2013] only in the webdav backend needs a file
+based database of certification authority certificates (cacert file). It has to be a
+.B PEM
+formatted text file as currently provided by the 
+.B CURL
+project. See
+.PP
+.RS
+http://curl.haxx.se/docs/caextract.html
+.PP
+.RE
+After creating/retrieving a valid cacert file you should copy it to either
+.PP
+.RS
+~/.duplicity/cacert.pem
+.br
+~/duplicity_cacert.pem
+.br
+/etc/duplicity/cacert.pem
+.PP
+.RE
+Duplicity searches it there in the same order and will fail if it can't find it.
+You can however specify the option
+.BI --ssl-cacert-file " <file>"
+to point duplicity to a copy in a different location.
+.PP
+Finally there is the
+.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. 
+
+.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
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
+2. Use a
+.BI PASSPHRASE
+for symmetric encryption of your choice but the signing key has an 
+.B empty
+passphrase.
 .PP
-Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be included in
-translations approved by the Free Software Foundation instead of in
-the original English.
+3. The used
+.BI PASSPHRASE
+for symmetric encryption and the passphrase of the signing key are identical.
+
+.SH A NOTE ON UBUNTU ONE
+
+To use Ubuntu One you must have an Ubuntu One OAuth access token. Such 
+OAuth tokens have a practically unlimited lifetime; you can have multiple 
+active tokens and you can revoke tokens using the Ubuntu One web interface.
+.PP
+Duplicity expects the token in the environment variable 
+.B FTP_PASSWORD
+(in the format "consumer_key:consumer_secret:token:token_secret"). If no
+token is present, duplicity asks for your Ubuntu One email address and password
+and requests an access token from the Ubuntu SSO service. The newly 
+acquired token is then printed to the console.
+.PP
+See https://one.ubuntu.com/ for more information about Ubuntu One.
+
+.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.
+
+.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
+.TP
+.BR "Original Author" " - Ben Escoto <bescoto@stanford.edu>"
+.TP
+.BR "Current Maintainer" " - Kenneth Loafman <kenneth@loafman.com>"
+.br
+.TP
+.B "Continuous Contributors"
+Edgar Soldin, Mike Terry
+.PP
+Most backends were contributed individually.
+Information about their authorship may be found in the according file's header.
+.br
+Also we'd like to thank everybody posting issue to the mailing list or on 
+launchpad, sending in patches or contributing otherwise. Duplicity wouldn't
+be as stable and useful if it weren't for you.
+
+.SH SEE ALSO
+.BR rdiffdir (1),
+.BR python (1),
+.BR rdiff (1),
+.BR rdiff-backup (1).


More information about the Gdb-patches mailing list