Duplicity

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

  1. man.page
  2. Merge into 0.6-series
Proposed by edso
Status: Merged
Merged at revision: 925
Proposed branch: lp:~ed.so/duplicity/man.page
Merge into: lp:duplicity/0.6
Diff against target: 481 lines (+142/-104)
1 file modified
bin/duplicity.1 (+142/-104)
To merge this branch: bzr merge lp:~ed.so/duplicity/man.page
Reviewer Review Type Date Requested Status
duplicity-team Pending
Review via email: mp+180734@code.launchpad.net

Description of the change

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

To post a comment you must log in.
Revision history for this message
Kenneth Loafman (kenneth-loafman) wrote :

Looking good!

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
=== 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 @@
9duplicity \- Encrypted incremental backup to local or remote storage.9duplicity \- Encrypted incremental backup to local or remote storage.
1010
11.SH SYNOPSIS11.SH SYNOPSIS
12For detailed descriptions for each command see chapter
13.BR ACTIONS .
14
12.B duplicity [full|incremental]15.B duplicity [full|incremental]
13.I [options]16.I [options]
14source_directory target_url17source_directory target_url
1518
16.B duplicity verify19.B duplicity verify
17.I [options] [--file-to-restore <relpath>]20.I [options] [--compare-data] [--file-to-restore <relpath>] [--time time]
18source_url target_directory21source_url target_directory
1922
20.B duplicity collection-status23.B duplicity collection-status
@@ -54,19 +57,16 @@
54Some backends also require additional components (probably available as packages for your specific platform):57Some backends also require additional components (probably available as packages for your specific platform):
55.TP58.TP
56.BR "boto backend" " (S3 Amazon Web Services, Google Cloud Storage)"59.BR "boto backend" " (S3 Amazon Web Services, Google Cloud Storage)"
57.B boto60.B boto version 2.0+
58- http://github.com/boto/boto61- http://github.com/boto/boto
59.TP62.TP
60.BR "cloudfiles backend" " (e.g. Rackspace Open Cloud)"63.BR "cloudfiles backend" " (e.g. Rackspace Open Cloud)"
61.B Cloud Files Python API64.B Cloud Files Python API
62- http://www.rackspace.com/knowledge_center/article/python-api-installation-for-cloud-files65- http://www.rackspace.com/knowledge_center/article/python-api-installation-for-cloud-files
63.TP66.TP
64.BR "OpenStack Swift backend"67.B "dpbx backend" (Dropbox)
65.B Python swiftclient module68.B Dropbox Python SDK
66- https://github.com/openstack/python-swiftclient/69- https://www.dropbox.com/developers/reference/sdk
67.br
68.B Python keystoneclient module
69- https://github.com/openstack/python-keystoneclient/
70.TP70.TP
71.B "ftp backend"71.B "ftp backend"
72.B NcFTP Client72.B NcFTP Client
@@ -99,7 +99,7 @@
99.BR "ssh paramiko backend" " (enabled by default)"99.BR "ssh paramiko backend" " (enabled by default)"
100.B paramiko100.B paramiko
101(SSH2 for python) 101(SSH2 for python)
102- http://www.lag.net/paramiko/102- http://pypi.python.org/pypi/paramiko (downloads); http://github.com/paramiko/paramiko (project page)
103.br103.br
104.B pycrypto104.B pycrypto
105(Python Cryptography Toolkit) 105(Python Cryptography Toolkit)
@@ -109,6 +109,13 @@
109.B sftp/scp client binaries109.B sftp/scp client binaries
110OpenSSH - http://www.openssh.com/110OpenSSH - http://www.openssh.com/
111.TP111.TP
112.BR "swift backend (OpenStack Object Storage)"
113.B Python swiftclient module
114- https://github.com/openstack/python-swiftclient/
115.br
116.B Python keystoneclient module
117- https://github.com/openstack/python-keystoneclient/
118.TP
112.B "Ubuntu One"119.B "Ubuntu One"
113.B httplib2120.B httplib2
114(python HTTP client library)121(python HTTP client library)
@@ -125,23 +132,17 @@
125.br132.br
126(also see 133(also see
127.BR "A NOTE ON SSL CERTIFICATE VERIFICATION" ).134.BR "A NOTE ON SSL CERTIFICATE VERIFICATION" ).
128.TP
129.B "dpbx backend"
130.B Dropbox Python SDK
131- https://www.dropbox.com/developers/reference/sdk
132.br
133135
134.SH DESCRIPTION136.SH DESCRIPTION
135Duplicity incrementally backs up files and directory137Duplicity incrementally backs up files and folders into
136by encrypting tar-format volumes with GnuPG and uploading them to a138tar-format volumes encrypted with GnuPG and places them to a
137remote (or local) file server. See139remote (or local) storage backend. See chapter
138.B URL FORMAT140.B URL FORMAT
139for a list all supported backends and how to address them.141for a list of all supported backends and how to address them.
140Because duplicity uses142Because duplicity uses librsync, incremental backups are space efficient
141librsync, the incremental archives are space efficient and only record143and only record the parts of files that have changed since the last backup.
142the parts of files that have changed since the last backup. Currently144Currently duplicity supports deleted files, full Unix permissions, uid/gid,
143duplicity supports deleted files, full Unix permissions, uid/gid, directories,145directories, symbolic links, fifos, etc., but not hard links.
144symbolic links, fifos, etc., but not hard links.
145146
146If you are backing up the root directory /, remember to --exclude147If you are backing up the root directory /, remember to --exclude
147/proc, or else duplicity will probably crash on the weird stuff in148/proc, or else duplicity will probably crash on the weird stuff in
@@ -156,7 +157,7 @@
156.PP157.PP
157.RE158.RE
158If the above is run repeatedly, the first will be a full backup, and159If the above is run repeatedly, the first will be a full backup, and
159subsequent ones will be incremental. To force a full backup, use the160subsequent ones will be incremental. To force a full backup, use the
160.I full161.I full
161action:162action:
162.PP163.PP
@@ -164,6 +165,14 @@
164duplicity full /home/me sftp://uid@other.host/some_dir165duplicity full /home/me sftp://uid@other.host/some_dir
165.PP166.PP
166.RE167.RE
168or enforcing a full every other time via
169.I --full-if-older-than <time>
170, e.g. a full every month:
171.PP
172.RS
173duplicity --full-if-older-than 1M /home/me sftp://uid@other.host/some_dir
174.PP
175.RE
167Now suppose we accidentally delete /home/me and want to restore it176Now suppose we accidentally delete /home/me and want to restore it
168the way it was at the time of last backup:177the way it was at the time of last backup:
169.PP178.PP
@@ -179,8 +188,7 @@
179duplicity -t 3D --file-to-restore Mail/article sftp://uid@other.host/some_dir /home/me/restored_file188duplicity -t 3D --file-to-restore Mail/article sftp://uid@other.host/some_dir /home/me/restored_file
180.PP189.PP
181.RE190.RE
182The following command compares the files we backed up, so see what has191The following command compares the latest backup with the current files:
183changed since then:
184.PP192.PP
185.RS193.RS
186duplicity verify sftp://uid@other.host/some_dir /home/me194duplicity verify sftp://uid@other.host/some_dir /home/me
@@ -213,6 +221,7 @@
213221
214.SH ACTIONS222.SH ACTIONS
215Duplicity knows action commands, which can be finetuned with options.223Duplicity knows action commands, which can be finetuned with options.
224.br
216The actions for backup (full,incr) and restoration (restore) can as well be225The actions for backup (full,incr) and restoration (restore) can as well be
217left out as duplicity detects in what mode it should switch to by the order226left out as duplicity detects in what mode it should switch to by the order
218of target URL and local folder. If the target URL comes before the local folder227of target URL and local folder. If the target URL comes before the local folder
@@ -221,24 +230,47 @@
221.br230.br
222If a backup is in order and old signatures can be found duplicity automatically231If a backup is in order and old signatures can be found duplicity automatically
223performs an incremental backup.232performs an incremental backup.
233.PP
234.B Note:
235The following explanations explain some but
236.B not
237all options that can be used in connection with that action command.
238Consult the OPTIONS section for more detailed informations.
224239
225.TP240.TP
226.B full241.BI "full " "<folder> <url>"
227Perform a full backup. A new backup chain is started even if242Perform a full backup. A new backup chain is started even if
228signatures are available for an incremental backup.243signatures are available for an incremental backup.
229244
230.TP245.TP
231.BR incr246.BI "incr " "<folder> <url>"
232If this is requested an incremental backup will be performed.247If this is requested an incremental backup will be performed.
233Duplicity will abort if no old signatures can be found.248Duplicity will abort if no old signatures can be found.
234249
235.TP250.TP
236.B collection-status251.BI "verify " "[--compare-data] [--time <time>] [--file-to-restore <relpath>] <url> <folder>"
252Verify compares the backup contents with the source folder.
253duplicity will exit with a non-zero error level if any files are different.
254On verbosity level info (4) or higher, a message for each file that has
255changed will be logged.
256.br
257The
258.I --file-to-restore
259option restricts verify to that file or folder.
260The
261.I --time
262option allows to select a backup to verify against.
263The
264.I --compare-data
265option enables data comparison (see below).
266
267.TP
268.BI "collection-status " "<url>"
237Summarize the status of the backup repository by printing the chains269Summarize the status of the backup repository by printing the chains
238and sets found, and the number of volumes in each.270and sets found, and the number of volumes in each.
239271
240.TP272.TP
241.BI "list-current-files " "[--time <time>]"273.BI "list-current-files " "[--time <time>] <url>"
242Lists the files contained in the most current backup or backup at time.274Lists the files contained in the most current backup or backup at time.
243The information will be extracted from the signature files, not the archive data275The information will be extracted from the signature files, not the archive data
244itself. Thus the whole archive does not have to be downloaded, but on276itself. Thus the whole archive does not have to be downloaded, but on
@@ -246,15 +278,7 @@
246command will not detect it.278command will not detect it.
247279
248.TP280.TP
249.BI "verify " "[--file-to-restore <relpath>]"281.BI "restore " "[--file-to-restore <relpath>] [--time <time>] <url> <target_folder>"
250Enter verify mode instead of restore. If the --file-to-restore option
251is given, restrict verify to that file or directory. duplicity will
252exit with a non-zero error level if any files are different. On
253verbosity level 4 or higher, log a message for each file that has
254changed.
255
256.TP
257.BI "restore " "[--file-to-restore <relpath>] [--time <time>]"
258You can restore the full monty or selected folders/files from a specific time.282You can restore the full monty or selected folders/files from a specific time.
259Use the relative path as it is printed by283Use the relative path as it is printed by
260.BR list-current-files .284.BR list-current-files .
@@ -262,7 +286,7 @@
262comes before the local folder.286comes before the local folder.
263287
264.TP288.TP
265.BI "remove-older-than " time289.BI "remove-older-than " "<time> [--force] <url>"
266Delete all backup sets older than the given time. Old backup sets290Delete all backup sets older than the given time. Old backup sets
267will not be deleted if backup sets newer than291will not be deleted if backup sets newer than
268.I time292.I time
@@ -271,10 +295,10 @@
271section for more information. Note, this action cannot be combined295section for more information. Note, this action cannot be combined
272with backup or other actions, such as cleanup. Note also that296with backup or other actions, such as cleanup. Note also that
273.I --force297.I --force
274will be needed to delete the files rather than just list them.298will be needed to delete the files instead of just listing them.
275299
276.TP300.TP
277.BI "remove-all-but-n-full " count301.BI "remove-all-but-n-full " "<count> [--force] <url>"
278Delete all backups sets that are older than the count:th last full302Delete all backups sets that are older than the count:th last full
279backup (in other words, keep the last303backup (in other words, keep the last
280.I count304.I count
@@ -283,26 +307,26 @@
283must be larger than zero. A value of 1 means that only the single most307must be larger than zero. A value of 1 means that only the single most
284recent backup chain will be kept. Note that308recent backup chain will be kept. Note that
285.I --force309.I --force
286will be needed to delete the files rather than just list them.310will be needed to delete the files instead of just listing them.
287311
288.TP312.TP
289.BI "remove-all-inc-of-but-n-full " count313.BI "remove-all-inc-of-but-n-full " "<count> [--force] <url>"
290Delete incremental sets of all backups sets that are older than the count:th last full314Delete incremental sets of all backups sets that are older than the count:th last full
291backup (in other words, keep only old full backups and not their increments).315backup (in other words, keep only old full backups and not their increments).
292.I count316.I count
293must be larger than zero. A value of 1 means that only the single most317must be larger than zero. A value of 1 means that only the single most
294recent backup chain will be kept intact. Note that318recent backup chain will be kept intact. Note that
295.I --force319.I --force
296will be needed to delete the files rather than just list them.320will be needed to delete the files instead of just listing them.
297321
298.TP322.TP
299.B cleanup323.BI "cleanup " "[--force] [--extra-clean] <url>"
300Delete the extraneous duplicity files on the given backend.324Delete the extraneous duplicity files on the given backend.
301Non-duplicity files, or files in complete data sets will not be325Non-duplicity files, or files in complete data sets will not be
302deleted. This should only be necessary after a duplicity session326deleted. This should only be necessary after a duplicity session
303fails or is aborted prematurely. Note that327fails or is aborted prematurely. Note that
304.I --force328.I --force
305will be needed to delete the files rather than just list them.329will be needed to delete the files instead of just listing them.
306330
307.SH OPTIONS331.SH OPTIONS
308332
@@ -374,6 +398,11 @@
374enough storage space is required to store two volumes.398enough storage space is required to store two volumes.
375399
376.TP400.TP
401.B --compare-data
402Enable data comparison of regular files on action verify.
403This is disabled by default for performance reasons.
404
405.TP
377.BI "--dry-run "406.BI "--dry-run "
378Calculate what would be done, but do not perform any backend actions407Calculate what would be done, but do not perform any backend actions
379408
@@ -670,7 +699,7 @@
670option). Default is to prompt the status each 3 seconds.699option). Default is to prompt the status each 3 seconds.
671700
672.TP701.TP
673.BI "--rename " "orig new"702.BI "--rename " "<original path> <new path>"
674Treats the path703Treats the path
675.I orig704.I orig
676in the backup as if it were the path705in the backup as if it were the path
@@ -943,7 +972,7 @@
943it is permitted however.972it is permitted however.
944Consider setting the environment variable 973Consider setting the environment variable
945.B FTP_PASSWORD 974.B FTP_PASSWORD
946instead, which is used by most, if not all backends, regardless of its name.975instead, which is used by most, if not all backends, regardless of it's name.
947.PP976.PP
948In protocols that support it, the path may be preceded by a single977In protocols that support it, the path may be preceded by a single
949slash, '/path', to represent a relative path to the target home directory,978slash, '/path', to represent a relative path to the target home directory,
@@ -958,6 +987,13 @@
958See also987See also
959.B "A NOTE ON CLOUD FILES ACCESS"988.B "A NOTE ON CLOUD FILES ACCESS"
960.PP989.PP
990.BI Dropbox
991.br
992dpbx:///some_dir
993.br
994Make sure to read
995.BR "A NOTE ON DROPBOX ACCESS" " first!"
996.PP
961file://[relative|/absolute]/local/path997file://[relative|/absolute]/local/path
962.PP998.PP
963ftp[s]://user[:password]@other.host[:port]/some_dir999ftp[s]://user[:password]@other.host[:port]/some_dir
@@ -1005,7 +1041,7 @@
1005swift://container_name1041swift://container_name
1006.br1042.br
1007See also1043See also
1008.B "A NOTE ON OPENSTACK SWIFT ACCESS"1044.B "A NOTE ON SWIFT (OPENSTACK OBJECT STORAGE) ACCESS"
1009.PP1045.PP
1010tahoe://alias/directory1046tahoe://alias/directory
1011.PP1047.PP
@@ -1018,25 +1054,7 @@
1018See also1054See also
1019.BI "A NOTE ON UBUNTU ONE"1055.BI "A NOTE ON UBUNTU ONE"
1020.PP1056.PP
1021webdav[s]://user[:password]@other.host/some_dir1057webdav[s]://user[:password]@other.host[:port]/some_dir
1022.PP
1023.BI Dropbox
1024.br
1025dpbx:///some_dir
1026.br
1027.IP 1.
1028"some_dir" must already exist in the Dropbox Application folder for
1029this application, like "Apps/Duplicity/some_dir".
1030.IP 2.
1031The first run of the backend must be ineractive!
1032It will print the URL that you need to open in the browser to obtain
1033OAuth token for the application. The token will be saved in the file
1034$HOME/.dropbox.token_store.txt and used in the future runs.
1035.IP 3.
1036When using Dropbox for storage, be aware that all files, including the
1037ones in the Apps folder, will be synced to all connected computers.
1038You may prefer to use a separate Dropbox account specially for the
1039backups, and not connect any computers to that account.
1040.RE1058.RE
10411059
1042.SH TIME FORMATS1060.SH TIME FORMATS
@@ -1172,21 +1190,26 @@
1172The1190The
1173.B --exclude1191.B --exclude
1174pattern option matches a file if:1192pattern option matches a file if:
1175.IP 1.1193.PP
1194.B 1.
1176.I pattern1195.I pattern
1177can be expanded into the file's filename, or1196can be expanded into the file's filename, or
1178.IP 2.1197.br
1198.B 2.
1179the file is inside a directory matched by the option.1199the file is inside a directory matched by the option.
1180.PP1200.PP
1181Conversely, the 1201Conversely, the
1182.B "--include " 1202.B "--include "
1183pattern matches a file if:1203pattern matches a file if:
1184.IP 1.1204.PP
1205.B 1.
1185.I pattern1206.I pattern
1186can be expanded into the file's filename, or1207can be expanded into the file's filename, or
1187.IP 2.1208.br
1209.B 2.
1188the file is inside a directory matched by the option, or1210the file is inside a directory matched by the option, or
1189.IP 3.1211.br
1212.B 3.
1190the file is a directory which contains a file matched by the option.1213the file is a directory which contains a file matched by the option.
1191.PP1214.PP
1192For example,1215For example,
@@ -1231,7 +1254,8 @@
1231interpreted similarly to the way1254interpreted similarly to the way
1232.I extended shell patterns1255.I extended shell patterns
1233are, with a few exceptions:1256are, with a few exceptions:
1234.IP 1.1257.PP
1258.B 1.
1235Globbing patterns like1259Globbing patterns like
1236.BR * ,1260.BR * ,
1237.BR ** ,1261.BR ** ,
@@ -1239,10 +1263,12 @@
1239and1263and
1240.B [...]1264.B [...]
1241are not expanded.1265are not expanded.
1242.IP 2.1266.br
1267.B 2.
1243Include patterns do not match files in a directory that is included.1268Include patterns do not match files in a directory that is included.
1244So /usr/local in an include file will not match /usr/local/doc.1269So /usr/local in an include file will not match /usr/local/doc.
1245.IP 3.1270.br
1271.B 3.
1246Lines starting with "+ " are interpreted as include directives, even1272Lines starting with "+ " are interpreted as include directives, even
1247if found in a filelist referenced by1273if found in a filelist referenced by
1248.BR --exclude-filelist .1274.BR --exclude-filelist .
@@ -1343,32 +1369,20 @@
1343.I must 1369.I must
1344be set in order to use other cloud files providers.1370be set in order to use other cloud files providers.
13451371
1346.SH A NOTE ON OPENSTACK SWIFT ACCESS1372.SH A NOTE ON DROPBOX ACCESS
13471373.IP 1.
1348Swift is the OpenStack Object Storage service.1374"some_dir" must already exist in the Dropbox Application folder for
13491375this application, like "Apps/Duplicity/some_dir".
1350The backend requires python-switclient to be installed on the system.1376.IP 2.
1351python-keystoneclient is also needed to use OpenStack's Keystone Identity service.1377The first run of the backend must be ineractive!
1352See 1378It will print the URL that you need to open in the browser to obtain
1353.B REQUIREMENTS 1379OAuth token for the application. The token will be saved in the file
1354above.1380$HOME/.dropbox.token_store.txt and used in the future runs.
13551381.IP 3.
1356It uses four environment variables for authentification:1382When using Dropbox for storage, be aware that all files, including the
1357.BR SWIFT_USERNAME " (required),"1383ones in the Apps folder, will be synced to all connected computers.
1358.BR SWIFT_PASSWORD " (required),"1384You may prefer to use a separate Dropbox account specially for the
1359.BR SWIFT_AUTHURL " (required),"1385backups, and not connect any computers to that account.
1360.BR SWIFT_TENANTNAME " (optional, the tenant can be included in the username)"
1361
1362If the user was previously authenticated, the following environment
1363variables can be used instead:
1364.BR SWIFT_PREAUTHURL " (required),"
1365.BR SWIFT_PREAUTHTOKEN " (required)"
1366
1367If
1368.B SWIFT_AUTHVERSION
1369is unspecified, it will default to version 1.
1370
1371
13721386
1373.SH A NOTE ON EUROPEAN S3 BUCKETS1387.SH A NOTE ON EUROPEAN S3 BUCKETS
1374Amazon S3 provides the ability to choose the location of a bucket upon1388Amazon S3 provides the ability to choose the location of a bucket upon
@@ -1529,7 +1543,31 @@
1529.B --ssl-no-check-certificate1543.B --ssl-no-check-certificate
1530option to disable certificate verification alltogether, in case some ssl library 1544option to disable certificate verification alltogether, in case some ssl library
1531is missing or verification is not wanted. Use it with care, as even with self signed 1545is missing or verification is not wanted. Use it with care, as even with self signed
1532servers manually providing the private ca certificate is definitely the safer option. 1546servers manually providing the private ca certificate is definitely the safer option.
1547
1548.SH A NOTE ON SWIFT (OPENSTACK OBJECT STORAGE) ACCESS
1549Swift is the OpenStack Object Storage service.
1550.br
1551The backend requires python-switclient to be installed on the system.
1552python-keystoneclient is also needed to use OpenStack's Keystone Identity service.
1553See
1554.B REQUIREMENTS
1555above.
1556
1557It uses four environment variables for authentification:
1558.BR SWIFT_USERNAME " (required),"
1559.BR SWIFT_PASSWORD " (required),"
1560.BR SWIFT_AUTHURL " (required),"
1561.BR SWIFT_TENANTNAME " (optional, the tenant can be included in the username)"
1562
1563If the user was previously authenticated, the following environment
1564variables can be used instead:
1565.BR SWIFT_PREAUTHURL " (required),"
1566.BR SWIFT_PREAUTHTOKEN " (required)"
1567
1568If
1569.B SWIFT_AUTHVERSION
1570is unspecified, it will default to version 1.
15331571
1534.SH A NOTE ON SYMMETRIC ENCRYPTION AND SIGNING1572.SH A NOTE ON SYMMETRIC ENCRYPTION AND SIGNING
1535Signing and symmetrically encrypt at the same time with the gpg binary on the1573Signing and symmetrically encrypt at the same time with the gpg binary on the

Subscribers

People subscribed via source and target branches

to all changes: