Documentation

Installation

REQUIREMENTS

duply needs duplicity. Install it or duply will be of no use for you.
Most distributions have readymade packages available. I suggest _not_ to use
these, because they generally lack behind duplicity development. If you 
encounter errors using the distro's duplicity please doublecheck if the 
version is outdated on http://duplicity.us or http://duplicity.gitlab.io .
If so please try using the latest stable from the website before filing 
bug reports or complaining in the mailing list.
If you install duplicity from the website's tarball check chapter 
"Requirements" on the mainpage first.


INSTALLATION

1. for convenience copy the file 'duply' somewhere into your path e.g. /bin 
   or simply use it from anywhere in your file system
2. doublecheck if the executable permission bits are set for all parties meant 
   to use duply e.g. 'ls -la /path/to/duply'
3. run 'duply usage' to get usage help


TIPS

INSTALL MULTIPLE VERSIONS

Sometimes a new version of duplicity has bugs. The default setup routine is not
designed to install multiple versions of duplicity in parallel. But doing this 
would allow you to go back to your working version of duplicity anytime. Here is
how I do it. Change version and prefix to your preference.

# install needed packages first
python python-devel librsync-devel
# download & extract
wget http://.../duplicity-0.6.07.tar.gz
tar xvf duplicity-0.6.07.tar.gz
cd duplicity-0.6.07/
# install into PREFIX
PREFIX=~/_apps/duplicity-0.6.07
python setup.py install --prefix="$PREFIX" --install-lib="$PREFIX"
# NOTE: 0.6.17 to 25 do not need the next step, 0.6.25 and newer do again 
# patch executable to find libs in PREFIX
awk '1;/import.*[ ,]+sys/{print "sys.path.insert(1,sys.path[0] + \47/../\47)"}' \
"$PREFIX/bin/duplicity" > "$PREFIX/bin/duplicity_mod" && \
chmod 755 "$PREFIX/bin/duplicity_mod" && \
mv "$PREFIX/bin/duplicity_mod" "$PREFIX/bin/duplicity"

If this works flawlessly than you will find the duplicity executable under
$PREFIX/bin/duplicity

ADD LOCAL DUPLY/DUPLICITY TO SYSTEM PATH

First make sure '/usr/local/bin' is in your PATH env var.
To change the systemwide used duplicity don't symlink it! It won't find it's 
script file structure it depends on then. Rather hack short wrapper like

/usr/local/bin/duply
-->
#!/bin/bash
DUPLY=/path/to/duply.sh
#DUPLY=~user/release/duply_1.5.2.3/duply
PATH=~user/path/to/duplicity-0.6.18/bin:$PATH
"$DUPLY" "$@"
<--

This way you can easily juggle with versions and stay up to date but have duply
in the path.
Alternatively you can of course simply add it to the systemwide PATH variable or
use only a duplicity wrapper like

/usr/local/bin/duplicity
-->
#!/bin/bash
PATH=~user/path/to/duplicity-0.6.18/bin:$PATH
duplicity "$@"
<--

UNINSTALL DUPLICITY

python setup.py install --record files.txt
cat files.txt | xargs rm -rf

Manpage

 Latest release is duply_2.5.3 .

VERSION:
  duply version 2.5.3
  (https://duply.net)
  
DESCRIPTION: 
  Duply deals as a wrapper for the mighty duplicity magic.
  It simplifies running duplicity with cron or on command line by:

    - keeping recurring settings in profiles per backup job
    - enabling batch operations e.g. backup_verify+purge
    - executing pre/post scripts (different actions possible 
      depending on previous or next command or it's exit status)
    - precondition checking for flawless duplicity operation

  For each backup job one configuration profile must be created.
  The profile folder will be stored under '~/.duply/<profile>'
  (where ~ is the current users home directory).
  Hint:  
   If the folder '/etc/duply' exists, the profiles for the super
   user root will be searched & created there.

USAGE:
  first time usage (profile creation):  
    duply <profile> create

  general usage in single or batch mode (see EXAMPLES):  
    duply <profile> <command>[[_|+|-]<command>[_|+|-]...] [<options> ...]

  For batches the conditional separators can also be written as pseudo commands
  and(+), or(-). See SEPARATORS for details.

  Non duply options are passed on to duplicity (see OPTIONS).
  All conf parameters can also be defined in the environment instead.

PROFILE:
  Indicated by a path or a profile name (<profile>), which is resolved 
  to '~/.duply/<profile>' (~ expands to environment variable $HOME).

  Superuser root can place profiles under '/etc/duply'. Simply create
  the folder manually before running duply as superuser.
  Note:  
    Already existing profiles in root's home folder will cease to work
    unless they are moved to the new location manually.

  example 1:   duply humbug backup

  Alternatively a _path_ might be used e.g. useful for quick testing, 
  restoring or exotic locations. Shell expansion should work as usual.
  Hint:  
    The path must contain at least one path separator '/', 
    e.g. './test' instead of only 'test'.

  example 2:   duply ~/.duply/humbug backup

SEPARATORS:
  _ (underscore)  
             neutral separator
  + (plus sign), _and_  
             conditional AND
             the next command will only be executed if the previous succeeded
  - (minus sign), _or_  
             conditional OR
             the next command will only be executed if the previous failed
  [] (square brackets), _groupIn_/_groupOut_  
             enables grouping of commands

   example:  
    'pre+[bkp-verify]_post' translates to
    'pre_and_groupIn_bkp_or_verify_groupOut_post'

COMMANDS:
  usage      get usage help text

  and/or/groupIn/groupOut  
             pseudo commands used in batches (see SEPARATORS above)

  create     creates a configuration profile
  backup     backup with pre/post script execution (batch: [pre_bkp_post]),
              full (if full_if_older matches or no earlier backup is found)
              incremental (in all other cases)
  pre/post   execute '<profile>/pre', '<profile>/post' scripts
  bkp        as above but without executing pre/post scripts
  full       force full backup
  incr       force incremental backup
  list [<age>]  
             list all files in backup (as it was at <age>, default: now)
  status     prints backup sets and chains currently in repository
  verify [<age>] [--compare-data]  
             list files changed, since age if given
  verifyPath <rel_path_in_bkp> <local_path> [<age>] [--compare-data]  
             list changes of a file or folder path in backup compared to a
             local path, since age if given
  restore <target_path> [<age>]  
             restore the complete backup to <target_path> [as it was at <age>]
  fetch <src_path> <target_path> [<age>]  
             fetch single file/folder from backup [as it was at <age>]
  purge [<max_age>] [--force]  
             list outdated backup files (older than $MAX_AGE)
              [use --force to actually delete these files]
  purgeFull [<max_full_backups>] [--force]  
             list outdated backup files ($MAX_FULL_BACKUPS being the number of
             full backups and associated incrementals to keep, counting in 
             reverse chronological order)
              [use --force to actually delete these files]
  purgeIncr [<max_fulls_with_incrs>] [--force]  
             list outdated incremental backups ($MAX_FULLS_WITH_INCRS being 
             the number of full backups which associated incrementals will be
             kept, counting in reverse chronological order) 
              [use --force to actually delete these files]
  purgeAuto [--force]  
             convenience batch wrapper for all purge commands above.
             purge, purgeFull, purgeIncr are added if their conf vars were set. e.g.
              MAX_AGE=1Y
              MAX_FULL_BACKUPS=6
              MAX_FULLS_WITH_INCR=3
             in profile conf file would result in
              [purge_purgeFull_purgeIncr]
  cleanup [--force]  
             list broken backup chain files archives (e.g. after unfinished run)
              [use --force to actually delete these files]

  changelog  print changelog / todo list
  txt2man    feature for package maintainers - create a manpage based on the 
             usage output. download txt2man from http://mvertes.free.fr/, put 
             it in the PATH and run 'duply txt2man' to create a man page.
  version    show version information of duply and needed programs

OPTIONS:
  --force    passed to duplicity (see commands: 
             purge, purgeFull, purgeIncr, cleanup)
  --preview  do nothing but print out generated duplicity command lines
  --disable-encryption  
             disable encryption, overrides profile settings

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

PRE/POST SCRIPTS:
  Some useful internal duply variables are exported to the scripts.

    PROFILE, CONFDIR, SOURCE, TARGET_URL_<PROT|HOSTPATH|USER|PASS>, 
    GPG_<KEYS_ENC|KEY_SIGN|PW>, CMD_ERR, RUN_START,
    CMD_<PREV|NEXT> (previous/next command), 
    CND_<PREV|NEXT> (condition before/after)

  The CMD_* variables were introduced to allow different actions according to 
  the command the scripts were attached to e.g. 'pre_bkp_post_pre_verify_post' 
  will call the pre script two times, with CMD_NEXT variable set to 'bkp' 
  on the first and to 'verify' on the second run.
  CMD_ERR holds the exit code of the CMD_PREV .

EXAMPLES:
  create profile 'humbug':  
    duply humbug create (don't forget to edit this new conf file)
  backup 'humbug' now:  
    duply humbug backup
  list available backup sets of profile 'humbug':  
    duply humbug status
  list and delete outdated backups of 'humbug':  
    duply humbug purge --force
  restore latest backup of 'humbug' to /mnt/restore:  
    duply humbug restore /mnt/restore
  restore /etc/passwd of 'humbug' from 4 days ago to /root/pw:  
    duply humbug fetch etc/passwd /root/pw 4D
    (see "duplicity manpage", section TIME FORMATS)
  a one line batch job on 'humbug' for cron execution:  
    duply humbug backup_verify_purge --force
  batch job to run a full backup with pre/post scripts:  
    duply humbug pre_full_post

FILES:
  in profile folder '~/.duply/<profile>' or '/etc/duply'
  conf             profile configuration file
  pre,post         pre/post scripts (see above for details)
  gpgkey.*.asc     exported GPG key files
  exclude          a globbing list of included or excluded files/folders
                   (see "duplicity manpage", section FILE SELECTION)

IMPORTANT:
  Copy the _whole_ profile folder after the first backup to a safe place.
  It contains everything (duply related) needed to restore your backups. 

  Pay attention to (possibly later added) external files such as credentials
  or auth files (e.g. netrc, .megarc, ssh keys) or environment variables
  (e.g. DPBX_ACCESS_TOKEN). 
  It is good policy to place those in the profile folder if possible at all.
    e.g. in case of 'multi://' target the config .json file
  Env vars should be added to duply profiles' conf file.

  Keep access to these files restricted as they contain information (gpg key,
  passphrases etc.) to access and modify your backups.
  
  Finally:
  You should attempt a restore from an unrelated host to be sure you really
  have everything needed for restoration.

  Repeat these steps after _all_ configuration changes. Some configuration 
  options are crucial for restoration.

SEE ALSO:
  duplicity man page duplicity(1) or http://duplicity.us/docs.html