duply(1) - f37

1DUPLY(1)                         User Manuals                         DUPLY(1)
2
3
4

VERSION

6       duply version 2.4.2 (https://duply.net)
7

DESCRIPTION

9       Duply deals as a wrapper for the mighty duplicity magic.  It simplifies
10       running duplicity with cron or on command line by:
11
12              •  keeping recurring settings in profiles per backup job
13
14              •  enabling batch operations e.g. backup_verify+purge
15
16              •  executing pre/post scripts (different  actions  possible  de‐
17                 pending on previous or next command or it's exit status)
18
19              •  precondition checking for flawless duplicity operation
20
21       For  each  backup  job  one configuration profile must be created.  The
22       profile folder will be stored under '~/.duply/<profile>'  (where  ~  is
23       the current users home directory).
24
25       Hint:  If  the  folder  '/etc/duply' exists, the profiles for the super
26              user root will be searched & created there.
27

USAGE

29       first time usage (profile creation):
30              duply <profile> create
31
32       general usage in single or batch mode (see EXAMPLES):
33              duply <profile> <command>[[_|+|-]<command>[_|+|-]...] [<options>
34              ...]
35
36       For  batches  the  conditional separators can also be written as pseudo
37       commands and(+), or(-). See SEPARATORS for details.
38
39       Non duply options are passed on to duplicity (see OPTIONS).   All  conf
40       parameters can also be defined in the environment instead.
41

PROFILE

43       Indicated by a path or a profile name (<profile>), which is resolved to
44       '~/.duply/<profile>' (~ expands to environment variable $HOME).
45
46       Superuser root can place profiles under '/etc/duply'. Simply create the
47       folder manually before running duply as superuser.
48
49       Note:  Already  existing  profiles  in root's home folder will cease to
50              work unless they are moved to the new location manually.
51
52       example 1:
53              duply humbug backup
54
55       Alternatively a _path_ might be used e.g.  useful  for  quick  testing,
56       restoring or exotic locations. Shell expansion should work as usual.
57
58       Hint:  The  path  must  contain  at  least one path separator '/', e.g.
59              './test' instead of only 'test'.
60
61       example 2:
62              duply ~/.duply/humbug backup
63

SEPARATORS

65       _ (underscore)
66              neutral separator
67
68       + (plus sign), _and_
69              conditional AND the next command will only be  executed  if  the
70              previous succeeded
71
72       - (minus sign), _or_
73              conditional  OR  the  next  command will only be executed if the
74              previous failed
75
76       [] (square brackets), _groupIn_/_groupOut_
77              enables grouping of commands
78
79              example:
80                     ’pre+[bkp-verify]_post'           translates           to
81                     ’pre_and_groupIn_bkp_or_verify_groupOut_post'
82

COMMANDS

84       usage  get usage help text
85
86       and/or/groupIn/groupOut
87              pseudo commands used in batches (see SEPARATORS above)
88
89       create creates a configuration profile
90
91       backup backup  with  pre/post script execution (batch: [pre_bkp_post]),
92              full (if full_if_older matches or no earlier  backup  is  found)
93              incremental (in all other cases)
94
95       pre/post
96              execute '<profile>/pre', '<profile>/post' scripts
97
98       bkp    as above but without executing pre/post scripts
99
100       full   force full backup
101
102       incr   force incremental backup
103
104       list [<age>]
105              list all files in backup (as it was at <age>, default: now)
106
107       status prints backup sets and chains currently in repository
108
109       verify [<age>] [--compare-data]
110              list files changed, since age if given
111
112       verifyPath <rel_path_in_bkp> <local_path> [<age>] [--compare-data]
113              list  changes  of  a file or folder path in backup compared to a
114              local path, since age if given
115
116       restore <target_path> [<age>]
117              restore the complete backup  to  <target_path>  [as  it  was  at
118              <age>]
119
120       fetch <src_path> <target_path> [<age>]
121              fetch single file/folder from backup [as it was at <age>]
122
123       purge [<max_age>] [--force]
124              list outdated backup files (older than $MAX_AGE) [use --force to
125              actually delete these files]
126
127       purgeFull [<max_full_backups>] [--force]
128              list outdated backup files ($MAX_FULL_BACKUPS being  the  number
129              of full backups and associated incrementals to keep, counting in
130              reverse chronological order) [use  --force  to  actually  delete
131              these files]
132
133       purgeIncr [<max_fulls_with_incrs>] [--force]
134              list  outdated  incremental backups ($MAX_FULLS_WITH_INCRS being
135              the number of full backups which associated incrementals will be
136              kept,  counting  in reverse chronological order) [use --force to
137              actually delete these files]
138
139       purgeAuto [--force]
140              convenience batch wrapper for all purge commands above.   purge,
141              purgeFull, purgeIncr are added if their conf vars were set. e.g.
142
143   MAX_AGE=1Y
144   MAX_FULL_BACKUPS=6
145   MAX_FULLS_WITH_INCR=3
146       in profile conf file would result in [purge_purgeFull_purgeIncr]
147
148       cleanup [--force]
149              list  broken  backup chain files archives (e.g. after unfinished
150              run) [use --force to actually delete these files]
151
152              changelog
153                     print changelog / todo list
154
155              txt2man
156                     feature for package maintainers - create a manpage  based
157                     on    the    usage    output.   download   txt2man   from
158                     http://mvertes.free.fr/, put it in the PATH and run  'du‐
159                     ply txt2man' to create a man page.
160
161              version
162                     show version information of duply and needed programs
163

OPTIONS

165       --force
166              passed  to duplicity (see commands: purge, purgeFull, purgeIncr,
167              cleanup)
168
169       --preview
170              do nothing but print out generated duplicity command lines
171
172       --disable-encryption
173              disable encryption, overrides profile settings
174

TIME FORMATS

176       For all time related parameters like age, max_age etc.   Refer  to  the
177       duplicity  manpage  for  all  available  formats.  Here  some examples:
178       2002-01-25T07:00:00+02:00 (full date time format string) 2002/3/5 (date
179       string  YYYY/MM/DD) 12D (interval, 12 days ago) 1h78m (interval, 1 hour
180       78 minutes ago)
181

PRE POST SCRIPTS

183       Some useful internal duply variables are exported to the scripts.
184
185   PROFILE, CONFDIR, SOURCE, TARGET_URL_<PROT|HOSTPATH|USER|PASS>,
186   GPG_<KEYS_ENC|KEY_SIGN|PW>, CMD_ERR, RUN_START,
187       CMD_<PREV|NEXT> (previous/next command), CND_<PREV|NEXT> (condition be‐
188       fore/after)
189
190       The  CMD_* variables were introduced to allow different actions accord‐
191       ing   to   the   command   the   scripts   were   attached   to    e.g.
192       'pre_bkp_post_pre_verify_post' will call the pre script two times, with
193       CMD_NEXT variable set to 'bkp' on the first and to 'verify' on the sec‐
194       ond run.  CMD_ERR holds the exit code of the CMD_PREV .
195

EXAMPLES

197       create profile 'humbug':
198              duply humbug create (don't forget to edit this new conf file)
199
200       backup 'humbug' now:
201              duply humbug backup
202
203       list available backup sets of profile 'humbug':
204              duply humbug status
205
206       list and delete outdated backups of 'humbug':
207              duply humbug purge --force
208
209       restore latest backup of 'humbug' to /mnt/restore:
210              duply humbug restore /mnt/restore
211
212       restore /etc/passwd of 'humbug' from 4 days ago to /root/pw:
213              duply  humbug  fetch etc/passwd /root/pw 4D (see "duplicity man‐
214              page", section TIME FORMATS)
215
216       a one line batch job on 'humbug' for cron execution:
217              duply humbug backup_verify_purge --force
218
219       batch job to run a full backup with pre/post scripts:
220              duply humbug pre_full_post
221

FILES

223       in profile folder '~/.duply/<profile>' or '/etc/duply'
224
225       conf   profile configuration file
226
227       pre,post
228              pre/post scripts (see above for details)
229
230       gpgkey.*.asc
231              exported GPG key files
232
233       exclude
234              a globbing list of included or excluded files/folders (see  "du‐
235              plicity manpage", section FILE SELECTION)
236

IMPORTANT

238       Copy the _whole_ profile folder after the first backup to a safe place.
239       It contains everything (duply related) needed to restore your backups.
240
241       Pay attention to (possibly later added) external files such as  creden‐
242       tials  or  auth  files  (e.g.  netrc, .megarc, ssh keys) or environment
243       variables (e.g. DPBX_ACCESS_TOKEN).  It is good policy to  place  those
244       in  the  profile folder if possible at all.  e.g. in case of 'multi://'
245       target the config .json file Env vars should be  added  to  duply  pro‐
246       files' conf file.
247
248       Keep  access to these files restricted as they contain information (gpg
249       key, passphrases etc.) to access and modify your backups.
250
251       Finally: You should attempt a restore from an unrelated host to be sure
252       you really have everything needed for restoration.
253
254       Repeat  these  steps after _all_ configuration changes. Some configura‐
255       tion options are crucial for restoration.
256