ConfiguringAClient
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.
Run the bbackupd-config script to generate the configuration files and generate a private key and certificate request, as follows:
/usr/local/sbin/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.
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.
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.
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/sbin/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.
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.
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.
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.
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](ExcludeDir) = /home/guest-user
[ExcludeFilesRegex](ExcludeFilesRegex) = .+\.(mp3|MP3)$
[AlwaysIncludeFile](AlwaysIncludeFile) = /home/username/veryimportant.mp3
This excludes the directory /home/guest-user from the backup along with all mp3 files (specifically, all files with names with one or more characters followed by a dot followed by mp3 or MP3), 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
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.
This is an example of output from the bbstored-config script. Important: Follow the instructions output by
- your
/usr/local/sbin/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/sbin/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.
The client daemon can be controlled whilst it is running with the bbackupctl tool. See the ControllingAClient page for details.
The NotifyScript is called by the client daemon, bbackupd, in response to events or changes in backup state. See the NotifyScript page for more information.
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 LogFile option allows the client's logs to be written to a file instead of system logs, which can be useful for reporting. LogFileLevel sets the detail level written to that file, along with LogAllFileAccess.
The LogFacility option sets the "facility" used to distinguish between different logging sources on Unix.
For logging the output of bbackupquery see: LoggingOutput
- Introduction
- Overview
- System Requirements
- Comparison With Other Systems
- Endorsements
- Installation
- Common Tasks
- Related Projects