Boxbackup howto

This page shows how to set up ONE boxbackup server and one or more clients in a Linux environment. At least this is more or less how I did it (and made it work). It doesn't attempt to explain thoroughly what is done, just show what needs to be done, and where. For explanation the Boxbackup documentation on the Boxbackup homepage serves as an excellent reference.

If you are setting a two-way backup scheme where guy A backs up to guy B and vice versa, be aware that that will be two separate setups, and the HOSTNAME_SRV (defined below) will be different for each. If unsure, set up one direction first and then when it works, start over for the other direction.

Please note that my choice of locations for the files in /etc differ slightly from examples in the official documentation. How & why:

Client configuration(s) are in /etc/boxbackup/clients/CLIENT/ instead of just /etc/boxbackup/. This lets you back up to multiple servers, should you want to.
Server configuration is in /etc/boxbackup/server/ instead of just /etc/boxbackup/. This makes distinction between server & client config files clearer in case you would like to run both a server and client(s) on the same machine. I use this with a friend such that I back up to his machine and he backs up to mine.

Other important caveats:

Boxbackup databases might be incompatible between versions - at least 0.09 and 0.10 are - so either check on the boxbackup homepage for compatibility statements or just plain use the same version of boxbackup for the server & the client(s).
In order for the backups to be of ANY use to a client, the client MUST keep the USERID-FileEncKeys.raw file (for details, see instructions below) in a secure place - burn it on (preferrably many) cds, write the bytes down on a paper as numbers, print them, make a reverse-engineerable image of them or whatever - store them somewhere safe - and if you want to be safe even in case your house burnt down, store them in some other house!

Getting started

The page is divided in three columns:

One for the CA i.e. Certificate Authority where you sign certificates to be used by servers and clients.
One for the Server i.e. the machine to store the backups
One for the Client i.e. the machine whose data to back up

There are two possible setups:

You have three machines: one to store the CA files, one for the server and one for the client. This is the setup recommended by Boxbackup, and the CA machine should preferrably not be connected to the internet.
You have two machines: one for the CA files and the server and one for the client.

Each column lists what commands should be run in the environment represented by the column in question. The commands should be run as the root user. The commands are expected to be run in the "bash" shell. If you are running some other shell (as root), either switch to bash (simply by running "bash") or modify the commands appropriately.

Some actions that need to be performed but aren't commands are written as bash comments (lines starting with a #) among the commands. These often indicate what files need to be exchanged between different environments. Example:

# send ${CONF_CLI}/bbackupd/123456-csr.pem
#   to CA

The above example means that the given file should be sent to the CA environment. ${CONF_CLI} means the value of the CONF_CLI variable as set in the beginning. With the example setup CONF_CLI would be /etc/boxbackup/clients/server.hostname.org so you would send the file /etc/boxbackup/clients/server.hostname.org/bbackupd/123456-csr.pem to the CA environment (by whatever means that is feasible - email, scp, etc..).

CA	Server	Client
Variables
Configuration variables used in commands. For convenience, copypaste these to a file on the machine you are currently operating, say /root/boxbackup-env, and edit the HOSTNAME_SRV, CONF_BASE, DATA_BASE and BBSTORED_USER to reflect your environment. The BBSTORED_USER might not be pre-created on your system, in this case you should consider creating it yourself. Note that the HOSTNAME_SRV setting needs to be the same for the CA, the Server and the Clients, the other settings can be configured separately at each machine if wanted / needed. Please also note that the same HOSTNAME_SRV needs resolve to an ip on ALL machines. To use these settings, just type 'source /root/boxbackup-env' in the shell you are using before running commands later on on this page. HOSTNAME_SRV=server.hostname.org CA_BASE=${HOME}/boxbackup-ca CONF_BASE=/etc/boxbackup DATA_BASE=/path/to/boxbackup/storage CONF_SRV=${CONF_BASE}/server DATA_SRV=${DATA_BASE}/server CONF_CLI=${CONF_BASE}/clients/${HOSTNAME_SRV} DATA_CLI=${DATA_BASE}/clients/${HOSTNAME_SRV} BBSTORED_USER=bbstored
Setting up the CA
CA	Server	Client
Setting up the CA environment mkdir ${CA_BASE} cd ${CA_BASE} chmod og= . bbstored-certs ca init
Setting up the server
CA	Server	Client
	Configure storage mkdir -p ${CONF_SRV} mkdir -p ${DATA_SRV} # Use either non-raid mode raidfile-config ${CONF_SRV} 4096 ${DATA_SRV} # .. or raid mode (see instructions in boxbackup's manual) raidfile-config ${CONF_SRV} 4096 ${DATA_SRV}/1 ${DATA_SRV}/2 ${DATA_SRV}/3 chown -R ${BBSTORED_USER} ${DATA_SRV}
	Generate server certificate request bbstored-config ${CONF_SRV} ${HOSTNAME_SRV} ${BBSTORED_USER} chown -R ${BBSTORED_USER} ${CONF_SRV} chmod -R go-rwx ${CONF_SRV}/bbstored chmod go-rwx ${CONF_SRV} # send ${CONF_SRV}/bbstored/${HOSTNAME_SRV}-csr.pem # to CA
Sign the server certificate # place ${HOSTNAME_SRV}-csr.pem # in ${CA_BASE} and then: cd ${CA_BASE} bbstored-certs ca sign-server ${HOSTNAME_SRV}-csr.pem rm ${HOSTNAME_SRV}-csr.pem # send ${CA_BASE}/ca/servers/${HOSTNAME_SRV}-cert.pem # and ${CA_BASE}/ca/roots/clientCA.pem # to server
	Install the certificate # place ${HOSTNAME_SRV}-cert.pem # and clientCA.pem # in ${CONF_SRV}/bbstored/
	Edit the server startup script to use ${CONF_SRV}/bbstored.conf emacs /etc/init.d/bbstored (sample gentoo script)
	Start the server daemon chown -R ${BBSTORED_USER} ${DATA_SRV} /etc/init.d/bbstored start
Adding a new client (a user that wants to back up something to the server)
CA	Server	Client
	Create new account 123456 - you can use any number from 0 to 99999999. 4096M and 4505M represet soft and hard quotas respectively. bbstoreaccounts -c ${CONF_SRV}/bbstored.conf create 123456 0 4096M 4505M
		Generate certificate request and set up first directory to backup - in this case we back up /home/ mkdir -p ${CONF_CLI} ${DATA_CLI} chmod og= ${CONF_CLI} ${DATA_CLI} bbackupd-config ${CONF_CLI} lazy 123456 ${HOSTNAME_SRV} ${DATA_CLI} /home/
		Some automatic config updates perl -i -pe 's!(/var/run/bbackupd)\.!$1-'${HOSTNAME_SRV}'.!;' ${CONF_CLI}/bbackupd.conf grep -q /var/run/bbackupd-${HOSTNAME_SRV} ${CONF_CLI}/bbackupd.conf \|\| echo Something went wrong
		Send ceritifcate request to CA # send ${CONF_CLI}/bbackupd/123456-csr.pem # to CA
Sign certificate # place 123456-csr.pem # in ${CA_BASE} cd ${CA_BASE} bbstored-certs ca sign 123456-csr.pem rm 123456-csr.pem # send ${CA_BASE}/ca/clients/123456-cert.pem # and ${CA_BASE}/ca/roots/serverCA.pem # to client
		Install the certificate # place 123456-cert.pem # and serverCA.pem # in ${CONF_CLI}/bbackupd/
		Review configuration # You may wish to read the configuration file # ${CONF_CLI}/bbackupd.conf # and adjust as appropraite. # There are some notes in it on excluding files you do not # wish to be backed up.
		Review notification script # Review the script # ${CONF_CLI}/bbackupd/NotifySysadmin.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.
		Edit the client startup script to use ${CONF_CLI}/bbackupd.conf emacs /etc/init.d/bbackupd (sample gentoo script - edit server names)
		Start the client daemon /etc/init.d/bbackupd start
		Store the PRIVATE KEYS somewhere SAFE. The file ${CONF_CLI}/bbackupd/123456-FileEncKeys.raw MUST be stored in some safe place where you can get it from in case your client machine loses it. According to the boxbackup documentation this is the ONLY file you need from the client machine to be able to restore your files.
What to do if the server hostname changes
CA	Server	Client
	Changing the listen address (if needed) /etc/init.d/bbstored stop # Edit ${CONF_SRV}/bbstored.conf - change the ListenAddresses field /etc/init.d/bbstored start
		Changing the server hostname /etc/init.d/bbackupd stop # Edit ${CONF_CLI}/bbackupd.conf - just change the StoreHostname value /etc/init.d/bbackupd start
Getting rid of a client
CA	Server	Client
		Stopping the client daemon and erasing configs & database /etc/init.d/bbackupd stop rm -r ${CONF_CLI} ${DATA_CLI}
	Remove user from configs & database bbstoreaccounts -c ${CONF_SRV}/bbstored.conf delete 123456
Getting rid of the client certificate cd ${CA_BASE} rm ca/clients/123456-cert.pem
Getting rid of a server - do this only if the server has no clients left
CA	Server	Client
	Stopping the server daemon and erasing configs & database /etc/init.d/bbstored stop rm -r ${CONF_SRV} ${DATA_SRV}
Getting rid of a CA - do this only if you have no servers left
CA	Server	Client
Erasing the CA cd rm -r ${CA_BASE}

This page was last updated Sat Jan 6 16:59:17 EET 2007.

Boxbackup howto

Getting started

Variables

Setting up the CA

Setting up the server

Adding a new client (a user that wants to back up something to the server)

What to do if the server hostname changes

Getting rid of a client

Getting rid of a server - do this only if the server has no clients left

Getting rid of a CA - do this only if you have no servers left