Creative Commons License
All content on this web page is Copyright 2006 Jonas Berlin (aka xkr47) and licensed under the Creative Commons Attribution 2.5 License. Contact information is available on my home page.

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:

Other important caveats:

Getting started

The page is divided in three columns:

There are two possible setups:

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


Variables

CAServerClient

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

CAServerClient

Setting up the CA environment

mkdir ${CA_BASE}
cd ${CA_BASE}
chmod og= .

bbstored-certs ca init

Setting up the server

CAServerClient

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)

CAServerClient

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

CAServerClient

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

CAServerClient

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

CAServerClient

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

CAServerClient

Erasing the CA

cd
rm -r ${CA_BASE}

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