backup, a highly flexible script utility to backup directories from your local system on various targets (external drive, sparsebundle, remote server with SSH access etc.)
backup relies for that on rsync (see http://samba.anu.edu.au/rsync/) and (in a future release) duplicity (see http://duplicity.nongnu.org/) together with a configuration file.
./backup [options]
backup rely on a configuration file to describe the characteristics of a backup to be performed (files to include/exclude, target url etc. -- see CONFIGURATION FILE FORMAT for more details). Here is a illustrative examples:
# Configuration file example
#
#### Mandatory global settings ####
<global>
src_rootdir = $HOME # Root directory on the (local) source
include_dir = * # backup all sub-directories (relative to src_rootdir)
</global>
#### Mandatory default backup definition ####
<default>
target_url = drive:///Volumes/Backup # backup on an external drive 'Backup'
</default>
# Definition of the backup on a local [encrypted] sparse bundle (Mac OS X)
<sbimage>
target_url = sparsebundle:///path/to/image.sparsebundle
dst_rootdir = myBackup # Specialized root directory for this backup
</sbimage>
# Definition of the backup on the machine 'toto' (via SSH access)
<toto>
target_url = ssh://mylogin@toto.example.org # backup through ssh
dst_rootdir = /backup/`whoami`@`hostname` # Specialized root directory on target server
restrict_on_subnet = 10.7.14 # backup only when you're working
</toto>
# Definition of the backup on the company NAS (via AFP access)
<nas>
# backup through AFP (eventually put the password in a separate file and use the directive 'pass_file')
target_url = afp://mylogin:mypassword@nas.company.com/volname
dst_rootdir = myBackup # Root directory for the backup
restrict_on_subnet = 10.7.14 # backup only when you're working
</nas>
# Definition of the backup on a remote [encrypted] sparse bundle on the company NAS
<nassbimage>
target_url = afp://mylogin:mypassword@nas.company.com/volname/path/to/image.sparsebundle
dst_rootdir = myBackup # Root directory for the backup
restrict_on_subnet = 10.7.14 # backup only when you're working
</nassbimage>
So appart from the 'global' section, each backup is defined in a named block that helps to complete and/or overwrite the global settings. To run the backup configured by default, just run:
./backup -f /path/to/config_file
To run the backup configured by the 'toto' section, just run:
./backup -f /path/to/config_file -s=toto
If a configuration file is not passed command-line through the -f option, backup
use by default $HOME/.backup.conf and then /etc/backup.conf.
To restore data from the backup 'toto', run :
./backup -f /path/to/config_file -s=toto -r
Note that backup try to use the configuration files /etc/backup.conf or ~/.backup.conf
so that the -f option can be avoided.
The following options are available:
Debug mode. Display debugging information probably only relevant to me ;)
Simulate the operations to show what would have been done and/or transferred but do not perform any backend actions.
Exact synchronization mode. Causes backup to delete files on the target if absent in the source directory. This ensure an exact replica but you may loose files so use this option with caution.
(Experimental) Keeps an history of backups. Each backup creates a timestamped directory in the specified target where files are backuped. To limit disk usage, unchanged files are hard linked with existing version on target. Up-to-date snapshot is always available under the "latest" directory. (Not yet supported) Backup with history over SSH (Not yet implemented) Behavior on target disk full (Not yet implemented) History consolidation (Not yet implemented) Retrieve mode from latest snapshot
Display a help screen and quit.
Use Mac OS resource fork for backup. Causes backup to use the Mac OS resource forks when calling the rsync function. This will preserve Mac OS extended attributes
Activates user notification of backup status. This feature requires growlnotify (under Mac OS X) or notify-send (under Linux) to be installed and in your applications path.
Execute the script whose complete path is specified with this argument AFTER the backup operation.
Execute the script whose complete path is specified with this argument BEFORE the backup operation. If the execution of this script fails, the backup will not continue.
Push mode: push data on the backup target. This is the default behaviour of backup.
Quiet mode. Minimize the number of printed messages and don't ask questions. Very useful for invoking this script in a crontab yet use with caution has all operations will be performed without your interaction.
Retrieve mode: restore data from the backup. Use with caution as this will probably overwrite files on your local machine!
Specify the successive sections to use for the backup configuration. If this option is not set, backup will use the section default. Currently, the implementation make the script exits as soon as an error happens (wrong subnet, target drive not available etc.) yet future release will just go on the next backup section on error which will be helpfull for crontab configuration.
Verbose mode. Display more information
Display the version number then quit.
The configuration file for backup is divided into sections defined as blocks.
A block looks much like a block in the wellknown apache config format.
It starts with <blockname> and ends with </blockname>
Two sections are mandatory: 'global' (which define global settings for the backup) and
'default' (which refer to the default backup configuration).
Each additionnal section is considered as a separate backup configuration and can be
refered using the command-line option -s (see DESCRIPTION).
When defining directory lists, you may use the following patterns symbols:
the wildcard *, the symbol ^ to specify the begining
of a name and the symbol $ to refer to its end.
For instance, you can use the following patterns:
* : all sub-directories (including the hidden one that starts with '.')
^AR* : all subdirectories whose name starts by AR
*ES$ : all subdirectories whose name ends by ES
^.* : all hidden directories (the one that starts by '.')
The following directives are recognized:
This directive makes it possible to specialize the behaviour of backup for the directory DIR. You may overwrite the following options
see dst_rootdir
this sub section is used to separate on the target the files and subfolders in DIR into a subdirectory named 'SUBDIR'. For instance, let assume one want to synchronize the $HOME/.ssh folder from multiples computers comp1, comp2 etc. on the server target_server, each computer running the backup script. Unless any special behaviour, the files $HOME/.ssh/id_dsa* will be overwritted on target_server every time the script is invoked on the computers. On the other hand, assuming we have set the src_in_subfolder directive as follow:
<Directory .ssh>
src_in_subfolder = `hostname`
</Directory>
Then the $dst_rootdir/$HOME/.ssh folder on the target server target_server will contain subfolders comp1, comp2 etc., each containing the files and subdirs of $HOME/.ssh/ from the source computer. In other work, you will be in the following configuration:
On'comp1': On 'comp2': on 'target_server':
$HOME/.ssh/id_dsa $HOME/.ssh/id_dsa $dst_rootdir/$HOME/.ssh/comp1/id_dsa
$HOME/.ssh/id_dsa.pub $HOME/.ssh/id_dsa.pub $dst_rootdir/$HOME/.ssh/comp1/id_dsa.pub
$dst_rootdir/$HOME/.ssh/comp2/id_dsa
$dst_rootdir/$HOME/.ssh/comp2/id_dsa.pub
This directive is ignored in retrieve mode (see option -r)
Root directory on the backup target (/ by default)
Space separated list of directories to exclude from synchronization (relative to $src_rootdir).
You may use the pattern symbols *, ^ and $ for each element of the list.
Add exceptions to exclude_dir (nice if wildcards have been used)
You may use the pattern symbols *, ^ and $ for each element of the list.
Space separated list of directories to include from synchronization (relative to $src_rootdir).
You may use the pattern symbols *, ^ and $ for each element of the list.
pass_file
Set FILE as the password file for backup. Each line of the password file corresponds to a password entry with the following format:
target_url password
Example:
afp://user@server/volumename mypasword
For the moment, this option is only relevant for AFP connection as it seemed impossible to rely on other (more secure) mechanisms such as keychain (used for encrypted sparse bundle mounts for instance), or agents (used for SSH -- see the 'auth_auth_sock' directive). I simply thought it's a better alternative than putting the password in backup configuration file.
By the way, it's NEVER a good idea to put clear password in text file. At minimum, ensure correct rights on this file ('chmod 600 /path/to/passwordfile') and don't put a personnal password in it. Prefer a random (unique) one generated by openSSL ('openssl rand 16 -base64' for instance)
The file containing file patterns that should NOT be synchronized. For instance, if you don't want to synchronize the temporary files generated by emacs or vim, you should put the following entries in FILE:
*~
#*#
.#*
Operate the synchronization only when your machine (i.e the network interface) belongs to the subnet SUBNET. The successive network interface checked for an IP compared with SUBNET are:
on Linux system (obtained by the uname command)
on FreeBSD, OpenBSD and Darwin systems (which include Mac OS X)
Root directory on the (local) source (/ by default)
Set the environment variable $SSH_AUTH_SOCK for this synchronization to the socket
of the socket file of the ssh-agent instance.
This is mandatory if you set a passphrase to you SSH key (it's always a good idea) and
want the backup script to automatically authenticate on a remote server wher you setup
an ssh public key authentication.
Define the target url of the backup (see TARGET URL FORMAT).
(Not yet supported) use duplicity instead of rsync
backup tries to maintain a standard URL format for backup targets. The generic format for a target URL is:
protocol://path|user[@host[:port]]
backup don't support the exposure of cleartext passwords on purpose for obvious security
reasons. The exception is for AFP connections (see notes on this subject in the 'pass_file'
directive and the afp protocol).
Current supported protocols include:
drive : an external drive
Example:
drive:///Volumes/MyDrive (under Mac OS X)
drive:///mnt/mydrive (under Linux)
file : a local folder
Example:
file:///path/to/local/folder
sparsebundle : a Mac OS X Sparse Bundle [encrypted] image
Example:
sparsebundle:///path/to/sparsebundle/image.sparsebundle
With the previous line, the sparse bundle image /path/to/file.sparsebundle will be mounted (let's say in /Volumes/ImageName). Typically, create an encrypted sparse bundle image (via Disk Utility) and use it as a secure container for your backup.
Even if this is not required, it is strongly recommended for encrypted sparsebundle passwords to be stored in the user keychain. This is mandatory if backup is to be launched in a crontab for instance.
ssh : SSH access to a remote server, with public key authentication
Example:
ssh://mylogin@server1
ssh://mylogin@server1.example.org
ssh://mylogin@server2.example.org:8022
Even if public key authentication is not required, it is strongly recommended and mandatory if backup it to be launched in a crontab for instance.
To setup public key authentication, please refer to http://sial.org/howto/openssh/publickey-auth/
afp : AFP (Apple Filing Protocol) access to a remote server (a NAS typically).
Example:
afp://[user[:password]@]host[:port]/volumename/path/to/backupdir
afp://[user[:password]@]host[:port]/volumename/path/to/image.sparsebundle
This is only available on Mac OS X (and may work on other systems if the mount_afp command is available). Whereas you can precise the password directly in the target_url, it is strongly unadvised. Prefer the 'pass_file' directive even if exposing clear password is far from a good solution. See the notes on this subject in the 'pass_file' directive.
/etc/backup.conf
~/.backup.conf
The backup configuration file. See CONFIGURATION FILE FORMAT.
A documented example of configuration file is proposed in
etc/backup.conf.example that is included in the tarball of the
distribution.
For recent info, read the backup home page: http://ibackup.gforge.uni.lu/
Please report bugs using informations provided at the page http://ibackup.gforge.uni.lu/bugs.html
Most of backup was made by Sebastien Varrette (see http://varrette.gforge.uni.lu/).
Guillaume-Jean Herbiet (http://herbiet.gforge.uni.lu) joined force recently to improve the script in many ways (sparsebundle support, notification etc.)
backup is released under GNU GPL Licence v3.
This is a free software. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.