Users should be familiar with the Terminal in Mac OS X. Default installation of the configuration files is ~/backup
. If you choose to use another location, you will need to use the -x
option at runtime. To setup rsyncbackup you need to edit exactly four files:
~/backup/config.conf
~/backup/destinations.conf
~/backup/sources.conf
~/backup/backupset.conf
Now we will describe the syntax of the configuration files.
The config.conf file includes parameters that will given to rsync for every combination of source and destination. Here is the example that follows the installation:
--stats --progress -Htr
We have used --stats
and --progress
for enabling statistics in our logs. (This applies to all combinations of sources and combinations). Second -Htr
tells us this (fetched from the manpage of rsync):
-H, --hard-links preserve hard links -t, --times preserve times -r, --recursive recurse into directories
Using -r
is a good idea, unless you do not want to backup subdirectories.
This is the configuration file where you specify all possible destinations for your backups, name each with a tag and the rsync options for each destinations. Here is the syntax: tag|Destination path|Conditional shell code|Optional rsync parameters
. And here is the example file that follows the installation ( \
means that newline is added here for easy reading and should not appear in the config file):
ipod|local:/Volumes/iPodAndreas/Backup/|\ test -d /Volumes/iPodAndreas/Backup/live/|--whole-file media-backup|ssh[key=insecure-ibook]:andrs@192.168.1.22:/Volumes/Backup/rsync/Snow|\ traceroute -m 2 192.168.1.22|--bwlimit=300
The destination path is either via SSH or local. Version 0.2 users should observe that the destination path format is changed. Local files should be prefixed with local:
followed by the path of the destination folder. Notice that rsync expects that you to put a trailing slash on your destinations paths. When using SSH, the destination path should be prefixed with ssh[key=rsyncbackup]:
, followed by the username@host:remotepath
. The key=filename
parameter is optional, and specify which ssh key to use when connecting. To do a local backup you want to use the --whole-file
rsync option. This will improve speed. But do not use this option if you backup to a remote location. The example above includes two backup destinations. Let's look at the first example which starts with ipod
. ipod
is my iPod named iPodAndreas, on which I have created a Backup folder which is specified here by /Volumes/iPodAndreas/Backup/
. Next, we have added conditional shell code. This is code that will be executed by your shell before the backup starts. If the shell code returns false, then the backup is not executed. In this example, test -d /Volumes/iPodAndreas/Backup
returns true if the iPod is mounted and false if not. If you do not want to apply conditional shell code for an entry, then enter true
. true
is a program that always returns true and will force the backup to be run.
This overview shows the subset of all available rsync options that is most relevant to destinations. You can add rsync options both to a destination (see Section 5.2, “destinations.conf”), a source (see Section 5.3, “sources.conf”), a backupset (see Section 5.4, “backupset.conf” and in general (see Section 5.1, “config.conf”). You will soon understand that placing rsync options on the most logical place will keep things more tidy.
-b, --backup make backups (default ~ suffix) --backup-dir make backups into this directory --suffix=SUFFIX define backup suffix -u, --update update only (don't overwrite newer files) -l, --links copy symlinks as symlinks -L, --copy-links copy the referent of symlinks --copy-unsafe-links copy links outside the source tree --safe-links ignore links outside the destination tree -H, --hard-links preserve hard links -p, --perms preserve permissions -o, --owner preserve owner (root only) -g, --group preserve group -D, --devices preserve devices (root only) -t, --times preserve times -S, --sparse handle sparse files efficiently -W, --whole-file copy whole files, no incremental checks --no-whole-file turn off --whole-file -x, --one-file-system don't cross filesystem boundaries -e, --rsh=COMMAND specify the remote shell to use --rsync-path=PATH specify path to rsync on the remote machine --existing only update files that already exist --ignore-existing ignore files that already exist on the receiving side --delete delete files that don't exist on the sending side --delete-excluded also delete excluded files on the receiving side --delete-after delete after transferring, not before --ignore-errors delete even if there are IO errors --max-delete=NUM don't delete more than NUM files --partial keep partially transferred files --force force deletion of directories even if not empty --numeric-ids don't map uid/gid values by user/group name --timeout=TIME set IO timeout in seconds -I, --ignore-times don't exclude files that match length and time --size-only only use file size when determining if a file should be transferred --modify-window=NUM Timestamp window (seconds) for file match (default=0) -T --temp-dir=DIR create temporary files in directory DIR --compare-dest=DIR also compare destination files relative to DIR --link-dest=DIR create hardlinks to DIR for unchanged files -P equivalent to --partial --progress -z, --compress compress file data --blocking-io use blocking IO for the remote shell --no-blocking-io turn off --blocking-io
To see the full list of rsync options, go to Section 14, “The rsync manpage”.
The source file setup possible sources to backup. The syntax of the file is: Tag|Source Path|Conditional shell code|Optional rsync options
And here is the example file that follows the installation:
home-bin|local:/Users/andrs/bin|true|-lp home-dot-ssh|local:/Users/andrs/.ssh|true|-lp home-backupconf|local:/Users/andrs/.backup|true|-lp library-prefs|local:/Users/andrs/Library/Preferences|true|-lp library-appsup|local:/Users/andrs/Library/Application Support|true|-lp documents|local:/Users/andrs/Documents|true|-lp sites|local:/Users/andrs/Sites|true|-lp
Shown is a bunch of locations that I want to backup on my computer. Note here, unlike in the destination config file, that rsync does not want a trailing slash on the source path. Be sure you tag your sources with a informative and unique tag, because the source and destination tags is used to create the filenames of the logfiles. In my example I have not put any conditional shell code to any source. You can disable backup from a source by entering false
instead of true
. An example of usage could be entering test -d directorypath to only backup a source if it exists.
The syntax of the source path field is equal to the desination path field of destinations.conf
(see Section 5.2, “destinations.conf”), except that the source path is obviously not allowed to set the incremental
parameter.
Version 0.2 users should notice that earlier rsyncbackup let you have multiple source-files, now just one is allowed, instead backup sets are set up with backupset.conf
.
This overview shows the subset of all available rsync options that is most relevant to destinations. You can add rsync options both to a destination (see Section 5.2, “destinations.conf”), a source (see Section 5.3, “sources.conf”), a backupset (see Section 5.4, “backupset.conf” and in general (see Section 5.1, “config.conf”). You will soon understand that placing rsync options on the most logical place will keep things more tidy.
-c, --checksum always checksum -a, --archive archive mode, equivalent to -rlptgoD -r, --recursive recurse into directories -R, --relative use relative path names -l, --links copy symlinks as symlinks -L, --copy-links copy the referent of symlinks --copy-unsafe-links copy links outside the source tree --safe-links ignore links outside the destination tree -H, --hard-links preserve hard links -p, --perms preserve permissions -o, --owner preserve owner (root only) -g, --group preserve group -D, --devices preserve devices (root only) -t, --times preserve times -S, --sparse handle sparse files efficiently -x, --one-file-system don't cross filesystem boundaries -B, --block-size=SIZE checksum blocking size (default 700) -C, --cvs-exclude auto ignore files in the same way CVS does -I, --ignore-times don't exclude files that match length and time --size-only only use file size when determining if a file should be transferred --exclude=PATTERN exclude files matching PATTERN --exclude-from=FILE exclude patterns listed in FILE --include=PATTERN don't exclude files matching PATTERN --include-from=FILE don't exclude patterns listed in FILE --read-batch=PREFIX read batch fileset starting with PREFIX --write-batch=PREFIX write batch fileset starting with PREFIX
To see the full list of rsync options, go to Section 14, “The rsync manpage”.
The backup set file, is where you combine source tags and destination tags, to create sets of backup. You can specify which backup set to use from the command line by using -s
. The syntax is: rsyncbackup -b -s daily
to run the [daily]
backup set. If no -s
parameter is given, the [default]
backup set is used. You can backup a single source to multiple destinations by entering a comma-separated list of destination tags. (You remember the destination tag was the name you entered in the destinations.conf
file). The syntax is: First a line with the name of the backup set in brackets, like [daily]
. Second, one or more lines with a list of sources, and a list of destinatinos, and conditional shell code, and at last rsync options. The concept is best explained by showing an example backupset.conf
file:
[default] home-bin,home-dot-ssh,home-backupconf|ipod,media-backup|true| library-prefs,library-appsup|ipod,media-backup|true| [daily] documents|ipod-incr|true|--progress sites|ipod|true|--progress [nightly] documents|media-backup-incr|true|--progress sites|ipod,media-backup|true| bilder|media-iphoto|true|--progress [weekly] documents,sites|ipod,media-backup-incr|true| bilder|media-iphoto|true|
When entering both multiple sources and destinations, all combinations will be exectued. In example home-bin,home-dot-ssh,home-backupconf|ipod,media-backup
will imply:
home-bin
to ipod
home-dot-ssh
to ipod
home-backupconf
to ipod
home-bin
to media-backup
home-dot-ssh
to media-backup
home-backupconf
to media-backup