NAME

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.

SYNOPSIS

      ./backup [options]

DESCRIPTION

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:

    <global>
         src_rootdir = $HOME     # Root directory on the (local) source
         include_dir = *         # backup all sub-directories (relative to src_rootdir)
    </global>

    <default>
         target_url = drive:///Volumes/Backup  # backup on an external drive 'Backup'
    </default>

    <sbimage>
         target_url  = sparsebundle:///path/to/image.sparsebundle
         dst_rootdir = myBackup         # Specialized root directory for this backup
    </sbimage>

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

    <nas>
          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>

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

OPTIONS

The following options are available:

--debug

Debug mode. Display debugging information probably only relevant to me ;)

--dry-run -n

Simulate the operations to show what would have been done and/or transferred but do not perform any backend actions.

--exact-sync -e

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.

--history

(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

--help -h

Display a help screen and quit.

--mac-fork -m

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

--notification

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.

--post-script

Execute the script whose complete path is specified with this argument AFTER the backup operation.

--pre-script

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 -p

Push mode: push data on the backup target. This is the default behaviour of backup.

--quiet

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.

--restore --retrieve -r

Retrieve mode: restore data from the backup. Use with caution as this will probably overwrite files on your local machine!

--section=SECTION[, SECTION2 ...]

-s=SECTION[, SECTION2 ...]

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 -v

Verbose mode. Display more information

--version

Display the version number then quit.

CONFIGURATION FILE FORMAT

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:

<Directory DIR ... </Directory> >>

This directive makes it possible to specialize the behaviour of backup for the directory DIR. You may overwrite the following options

• dst_rootdir = ROOTDIR

  see dst_rootdir

• src_in_subfolder = SUBDIR

  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)

dst_rootdir = ROOTDIR

Root directory on the backup target (/ by default)

exclude_dir = PATTERN1 [PATTERN2] [PATTERN3]...

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.

exclude_dir_exception = PATTERN1 [PATTERN2] [PATTERN3]...

Add exceptions to exclude_dir (nice if wildcards have been used) You may use the pattern symbols *, ^ and $ for each element of the list.

include_dir = PATTERN1 [PATTERN2] [PATTERN3]...

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

pass_file = 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)

patternfile_exclude = FILE

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:

        *~
        .#*

restrict_on_subnet = SUBNET

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:

• (eth0, eth1)

  on Linux system (obtained by the uname command)

• (en0, en1)

  on FreeBSD, OpenBSD and Darwin systems (which include Mac OS X)

src_rootdir

Root directory on the (local) source (/ by default)

ssh_auth_sock = /path/to/ssh-agent.socket

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.

target_url = URL

Define the target url of the backup (see TARGET URL FORMAT).

use_duplicity = yes

(Not yet supported) use duplicity instead of rsync

TARGET URL FORMAT

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.

FILES

/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/

BUGS

Please report bugs using informations provided at the page http://ibackup.gforge.uni.lu/bugs.html

AUTHOR

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

COPYRIGHT

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.