Configuring a Client Machine

Before you Start

Before you can do any configuration, you need to know the hostname of the backup 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. See the RunningWithoutRoot page for further details.

If your client boxes use filenames with international characters (for example, if you live in a country or work in an environment where languages other than English are widely spoken), please read the CharacterEncoding page carefully.

Step 1

Run the bbackupd-config script to generate the configuration files and generate a private key and certificate request, as follows:

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

(See OpenSSLNotes if you get an OpenSSL error)

The items in square brackets above need to be changed (but don't enter any square brackets in your version). 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, and exclude any mount points inside any of them. Box Backup 0.11 checks for mount points inside a location, and skips them with a warning message if you have not explicitly excluded them.

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

The working directory (/var/bbackupd in this case) is used as the DataDirectory, and is created if it doesn't exist.

Lazy Backup Mode

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 documents stored on a server, and spreads the load out over the day.

Snapshot Backup Mode

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. The ControllingAClient page gives some details on this.

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 the following:

/usr/local/bin/bbackupd

You'll probably also want to add 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 the /etc/box directory 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, at least during initial setup), 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 the comments in this file for help. Send bbackupd a HUP signal after you modify it so that it will adopt the new configuration without having to restart the backup daemon.

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. The the RunningWithoutRoot page for details.

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 (the 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, one per location, in the following format:

BackupLocations
{
   name
   {
      Path = /path/to/directory
      (optional exclude directives)
   }
   name2
   {
      Path = /path/to/directory2
      (optional exclude directives)
   }
}

name is derived from the Path by the config script, but should merely be unique. It will be used as the directory name off the account's root directory on the store.

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. Use the following command for the regex syntax on your platform:

man 7 re_format

Regular Expressions and the Windows Client

There are some things to be aware of when using regular expressions in the Box Backup configuration file on Windows. See the Win32Regex page for more details.

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.

Controlling a Client

The client daemon can be controlled whilst it is running with the bbackupctl tool. See the ControllingAClient page for details.

NotifyScript?

The NotifyScript? is called by the client daemon, bbackupd, in response to events or changes in backup state.

You are not required to have a NotifyScript?, but it is advisable, as otherwise you may not find out about backup failures. The default script generated by bbackupd-config on Unix, and the supplied NotifySysadmin.vbs script for Windows users, will send you an email if a backup fails.

Please note that some event types have been added since 0.10. If you have a NotifyScript? generated by 0.10, then it will send emails about Unknown error whenever it receives one of these events, because it doesn't know about them. Please see the Upgrading page to find out how to fix this.

The following notifications are sent to the NotifyScript?. The notification name is sent as the first command-line parameter of the script.

Name	Type	When
backup-start	Event	At the beginning of every backup run
backup-finish	Event	At the end of every backup run
backup-ok	Status	When the backup run finished without errors
read-error	Status	When the backup failed to read one or more files due to a permissions problem
store-full	Status	When the store account is full or became full during the backup
backup-error	Status	When another error, such as an exception, occurred during the backup

Event notifications are sent every time they occur. Status notifications are sent if they differ from the previous status. That means that after you have been notified about the event once, you will not receive further notifications until bbackupd is restarted, or the state changes. For example, consider the following sequence of backup runs:

• Backup finishes OK. backup-ok notification is sent.
• Backup finishes OK. Duplicate backup-ok notification is suppressed.
• Backup finishes OK. Duplicate backup-ok notification is suppressed.
• Store becomes full during backup. store-full notification is sent.
• Store is still full during the next backup. Duplicate store-full notification is suppressed.
• A read error occurs. read-error notification is sent.
• No read error occurs, but the store is still full. store-full notification is sent.
• Store is still full during the next backup. Duplicate store-full notification is suppressed.
• Store is no longer full. backup-ok notification is sent.
• Backup finishes OK. Duplicate backup-ok notification is suppressed.

If you want to disable the suppression of duplicate notification, in order to receive one at the end of every backup, you can set the NotifyAlways? parameter to true.

Status notifications are always sent just before the backup-finish event. If you want to send a report at the end of every backup, and include the status of the backup, then catch the status notifications and save a record of the last one received to a file. Then when you receive the backup-finish event, you can read the contents of the file to determine the status of the last backup. This works even if the NotifyAlways? option is not enabled, as a status notification is sent to the script whenever the status changes, so you can be sure that the status file represents the status of the last backup.