5. Configuration files

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:

Now we will describe the syntax of the configuration files.

5.1. config.conf

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.

5.2. destinations.conf

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.

5.2.1. Common rsync options for destinations

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”.

5.3. sources.conf

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 and earlier

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.

5.3.1. Common rsync options for sources

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”.

5.4. backupset.conf

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