# Box Backup client configuration

## Before you start

Before you can do any configuration, you need to know the hostname of the server you will be using, and your account number on that server.

Later in the process, you will need to send a certificate request to the administrator of that server for it to be signed.

Installation is covered in the compiling and installing section. You only need the backup-client parcel.

It is important that you read all the output of the config scripts. See the end of this page for an example.

The backup client has to be run as root, because it needs to read all your files to back them up, although it is possible to back up a single user's files by running it as that user. (Tip: specify a directory other than /etc/box, and then give the alternate config file as the first argument to bbackupd). However, it will fall over if you don't give yourself read access to one of your files.

## Step 1

Run the `bbackupd-config` script to generate the configuration files and generate a private key and certificate request.

    /usr/local/bin/bbackupd-config /etc/box lazy 999 hostname /var/bbackupd /home

(See OpenSSL notes if you get an OpenSSL error)

The items in bold need to be changed. In order, they are the account number, the hostname of the server you're using, and finally, the directories you want backed up. You can include as many you want here.

However, the directories you specify must not contain other mounted file systems within them at any depth. Specify them separately, one per mount point. No checks are currently made to catch bad configuration of this nature!

You may also want to consider changing the mode from lazy to snapshot, depending on what your system is used for.

lazy
  This mode regularly scans the files, with only a rough schedule. It uploads files as and when they are changed, if the latest version is more than a set age. This is good for backing up user's documents stored on a server, and spreads the load out over the day.
snapshot
  This mode emulates the traditional backup behaviour of taking a snapshot of the filesystem. The backup daemon does absolutely nothing until it is instructed to make a backup using the `bbackupctl` utility (probably as a cron job), at which point it uploads all files which have been changed since the last time it uploaded.

When you run the config script, it will tell you what you need to do next. Don't forget to read all the output. An example is shown at the end of this page, but the instructions for your installation may be different.

## Step 2

After you have sent your certificate request off to the server administrator and received your certificate and CA root back, install them where instructed by the `bbackupd-config` script in step 1.

You can then run the daemon (as root) by typing `/usr/local/bin/bbackupd`, and of course, adding it to your system's startup scripts. The first time it's run it will upload everything. Interrupting it and restarting it will only upload files which were not uploaded before - it's very tolerant.

If you run in snapshot mode, you will need to add a cron job to schedule backups. The config script will tell you the exact command to use for your system.

Please read the Troubleshooting page if you have problems.

Remember to make a traditional backup of the keys file, as instructed. You cannot restore files without it.

It is recommended that you backup up all of `/etc/box` as it will make things easier if you need to restore files. But only the keys are absolutely essential.

If you want to see what it's doing in more detail (probably a good idea), follow the instructions in the server setup to create new log files with syslog.

## Adding and removing backed up locations

By editing the `/etc/box/bbackupd.conf` file, you can add and remove directories to back up -- see comments in this file for help. Send `bbackupd` a HUP signal after you modify it.

When you remove a location, it will not be marked as deleted immediately. Instead, `bbackupd` waits about two days before doing so, just in case you change your mind. After this, it will be eventually removed from the store by the housekeeping process.

## Run as root

The backup client is designed to be run as root. It is possible to run without root, but this is not recommended.

## Clock synchronisation for file servers

If you are using the backup client to backup a filesystem served from a fileserver, you should ideally ensure that the fileserver clocks are synchronised with the fileserver.

`bbackupd` will cope perfectly well if the clocks are not synchronised. Errors up to about half an hour cause no problems. Larger discrepancies cause a loss of efficiency and the potential to back up a file during a write process.

There is a configuration parameter `MaxFileTimeInFuture`, which specifies how far in the future a file must be for it to be uploaded as soon as it is seen. You should not need to adjust this (default is 2 days). Instead, get those clocks synchronised.

## Excluding files and directories from the backup

Within the `bbackupd.conf` file, there is a section named `BackupLocations` which specifies which locations on disc should be backed up. It has subsections, each of which is in the format

      name
      {
         Path = /path/of/directory
         (optional exclude directives)
      }

name is derived from the Path by the config script, but should merely be unique.

The exclude directives are of the form

      [Exclude|AlwaysInclude][File|Dir][|sRegex] = regex or full pathname

(The regex suffix is shown as 'sRegex' to make File or Dir plural)

For example:

      ExcludeDir = /home/guest-user
      ExcludeFilesRegex = *.(mp3|MP3)\$
      AlwaysIncludeFile = /home/username/veryimportant.mp3

This excludes the directory /home/guest-user from the backup along with all mp3 files, except one MP3 file in particular.

In general, Exclude excludes a file or directory, unless the directory is explicitly mentioned in a AlwaysInclude directive.

If a directive ends in Regex, then it is a regular expression rather than a explicit full pathname. See

      man 7 re_format

for the regex syntax on your platform.

## Example configuration output

This is an example of output from the bbstored-config script. Important: Follow the instructions output by your script, not the ones here -- they may be different for your system.

    # /usr/local/bin/bbackupd-config /etc/box lazy 51 server.example.com /var/bbackupd /home /etc/samba

    Setup bbackupd config utility.

    Configuration:
       Writing configuration file: /etc/box/bbackupd.conf
       Account: 51
       Server hostname: server.example.com
       Directories to back up:
          /home
          /etc/samba

    Note: If other file systems are mounted inside these directories, then problems may occur
    with files on the store server being renamed incorrectly. This will cause efficiency
    problems, but not affect the integrity of the backups.

    WARNING: Directories not checked against mountpoints. Check mounted filesystems manually.

    Creating /etc/box...
    Creating /etc/box/bbackupd
    Generating private key...
     [OpenSSL output omitted]

    Generating keys for file backup
    Writing notify script /etc/box/bbackupd/NotifyStoreFull.sh
    Writing configuration file /etc/box/bbackupd.conf

    ===================================================================

    bbackupd basic configuration complete.

    What you need to do now...

    1) Make a backup of /etc/box/bbackupd/51-FileEncKeys.raw
       This should be a secure offsite backup.
       Without it, you cannot restore backups. Everything else can
       be replaced. But this cannot.
       KEEP IT IN A SAFE PLACE, OTHERWISE YOUR BACKUPS ARE USELESS.

    2) Send /etc/box/bbackupd/51-csr.pem
       to the administrator of the backup server, and ask for it to
       be signed.

    3) The administrator will send you two files. Install them as
          /etc/box/bbackupd/51-cert.pem
          /etc/box/bbackupd/serverCA.pem
       after checking their authenticity.

    4) You may wish to read the configuration file
          /etc/box/bbackupd.conf
       and adjust as appropraite.

       There are some notes in it on excluding files you do not
       wish to be backed up.

    5) Review the script
          /etc/box/bbackupd/NotifyStoreFull.sh
       and check that it will email the right person when the store
       becomes full. This is important -- when the store is full, no
       more files will be backed up. You want to know about this.

    6) Start the backup daemon with the command
          /usr/local/bin/bbackupd
       in /etc/rc.local, or your local equivalent.
       Note that bbackupd must run as root.

    ===================================================================

    Remember to make a secure, offsite backup of your backup keys,
    as described in step 1 above. If you do not, you have no backups.

© Ben Summers, 2003, 2004