Home

Configuration

dups reads its config from ~/.config/dups/config.yaml.

To store backups on a local target, your config would look like:

target:
  path: /absolute/local/path/

To store backups on a remote target, your config would look like:

target:
  path: /absolute/remote/path/
  host: <backup-host>

To change ssh related options like user, port, key-file etc. the ssh config file is used.

For remote backups to work, you have to have ssh key-based authentication set up.
Passphrases are not supported.

Additional config options can be found here.

Preamble CLI

The following does not cover all capabilities of dups command-line interface.
Therefore you may invoke --help, -h at any point.

$ dups -h
$ dups restore -h
$ dups list -h
...

Managing items

Includes

To manage files, folders and/or patterns which are to be included, you use include, i.

List includes

To list all includes you add --list, -l.

$ dups include -l

Add includes

To add items you use include, i.

$ dups include /absolute/path/to/file.txt
$ dups include ./relative/path/to/folder

To include items based on patterns you have to properly quote or escape each given item.

# Will include all .png files contained in "/absolute/path/to/folder"
$ dups include '/absolute/path/to/folder/*.png'

# Will includes all .png files contained in "Pictures" (subdirectories
# excluded) for all users
$ dups include '/home/**/Pictures/*.png'

# Will include all .png files contained within the folder
# "folder * with $ special \ chars"
$ dups include '/folder\ \*\ with\ \$\ special\ \\\ chars/*png'

include patterns will ultimately rely on shell expansion.

Remove includes

To remove included items you add --remove, r.

$ dups include -r /absolute/path/to/file.txt
$ dups include -r '/absolute/path/to/folder/*.png'

Excludes

To manage files, folders and/or patterns which are to be excluded, you use exclude, e.

List excludes

To list all excludes you add --list, -l.

$ dups exclude -l

Add excludes

To add items you use exclude, e.

$ dups exclude /absolute/path/to/file.txt
$ dups exclude ./relative/path/to/folder

To include items based on patterns you have to properly quote or escape each given item.

# Excludes ALL .mkv files
$ dups exclude '*.mkv'

# Exclude all .mkv files contained in "Videos" (subdirectories excluded) for
# all users.
$ dups exclude '/home/**/Videos/*.mkv'

Unlike with includes, excludes will not rely on shell expansion.
Instead, rsync applies its INCLUDE/EXCLUDE PATTERN RULES.

Remove excludes

To remove excluded items you add --remove, -r.

$ dups exclude -r /absolute/path/to/file.txt
$ dups exclude -r '*.mkv'

Managing backups

Create backups

To start a new backup you use backup, b.

To have backups run in the background you first need a daemon.
Once a daemon is running, you can start a new background backup by adding --bg for user daemons or --sbg for system daemons.

$ dups backup
$ dups backup --bg

List backups

To list all backups you use list, l.

$ dups list
Name             Date                    Valid   Size
20180801180005   01, Aug 2018 18:00:05   yes     3.34 GB
20180802180005   02, Aug 2018 18:00:05   yes     3.32 GB
20180803180006   03, Aug 2018 18:00:06   yes     3.28 GB
...

Restore backups

To restore a backup you use restore, r.
This would restore the entire backup to its original location overwriting all existing files.

$ dups restore

To restore a specific backup you use --backup, -b and add the backups name.
The keyword latest will automatically resolve to the latest backup.

$ dups restore -b latest
$ dups restore -b 20180801180005

To restore the nth most recent backup you use -n, --nth.

# Restores from the most recent backup.
$ dups restore -n 0

# Restores from the 5th most recent backup.
$ dups restore -n 5

To restore only certain files to a specific target you first add the target followed by a list of items to restore.

# Restores the given files to their original location.
$ dups restore -b 20180801180005 / /path/to/file.txt ./file2.txt

# Restores the given files including the directory hierarchy to /tmp instead.
$ dups restore -b 20180801180005 /tmp /path/to/file.txt ./file2.txt

To have backups restore in the background you first need a daemon.
Once a daemon is running, you can start a new background restore by adding --bg for user daemons or --sbg for system daemons.

$ dups restore -b 20180801180005 --bg

Remove backups

To remove individual backups you use remove, rm.

$ dups remove 20180801180005

All but keep

To remove all backups but keep n of the most recent you use --all-but-keep.

$ dups remove --all-but-keep 7

Older than

To remove all backups older than some given time you use --older-than.
The value is a combination of amount and identifier and supports:

Identifier	Unit
s	Seconds
m	Minutes
h	Hours
d	Days
w	Weeks

# Removes all backups older than 7 Weeks
$ dups remove --older-than 7w

Grandfather-father-son

To remove backups based on the grandfather-father-son rotation scheme, you use --gffs.
The value consists of multiple amount and identifier and supports:

Identifier	Unit
d	Days
w	Weeks
m	Months
y	Years

# Keep 7 days per week, 4 weeks per month, 12 month per year for 10 years
# => 33 backups after 10 years
$ dups remove --gffs 7d4w12m10y

Invalid

To remove all invalid backups you use --invalid.

# Removes all backups older than 7 Weeks
$ dups remove --invalid

Log files

Both backup and restore logs are stored in ${HOME}/.cache/dups/.
To print the most recent log you use log together with either --backup, -b or --restore, -r.

$ dups log --backup
$ dups log --restore

# Tip: To f.e. search within the log you can simply pipe the output to less or vi(m).
$ dups log --backup | less
$ dups log --restore | vim -

Daemon

dups can be run as a daemon to handle backup and restore tasks in the background.

To start a daemon you use either daemon, d together with either --session or --system.

User daemon

The user daemon is intended for user-sessions and should suffice for most cases.
To backup/restore items owned by other users (e.g. root) have a look at the system daemon.

$ dups daemon --session

System daemon

The system daemon is intended for users who need to include files owned by other users (e.g. root).

To still read the correct config files (for dups, ssh etc.) you add your username with --user.

# Has to be run with elevated permissions.
$ dups --user <username> daemon --system

To still get desktop notifications, you have to additionally start a user daemon.

Systemd

If system files have been included in your installation, there are systemd services available for both, the user daemon and the system daemon.

User service

$ systemctl --user enable dups
$ systemctl --user start dups

System service

$ systemctl enable dups@<username>
$ systemctl start dups@<username>

Scheduled backups

Scheduling is not included in dups but instead relies on external tools like cron.

I recommend cronie for systems where it is available. If not available, anacron (which cronie is based upon) is your best bet.

Here is an example on how I schedule my backups.

0 18 * * * nm-online -q -t 180 && dups rm --all-but-keep 13 --yes && dups backup --sbg

This will:

1. Use NetworkManager to wait up to 3 minutes for a network connection.
2. Remove all, but keep the most recent 13 backups
3. Instruct my system daemon to start a new backup (resulting in 14 backups total)

FAQ

I have not been asked questions yet :)