Version 29 (modified by chris, 11 years ago) (diff)

document the installation guide

Download and Installation Instructions

Warning: The latest stable version (0.10) has known bugs with files over 2 GB in size. Please read the information below to find out how this may affect you and how to avoid them.

Other Languages

Official Guide

The official installation guide is distributed with every copy of Box Backup. It may be less up-to-date than the Wiki version, but may also be more complete.

Stable Download

Version 0.10 is the current stable released version, and should be your choice if you're not testing the current development versions. It has some known problems:

  • Backing up files over 2GB chooses an invalid block size, which can be restored but causes quick compare to fail with BackupStore BadBackupStoreFile (4/11) (see [1599] and ticket:2)
  • Incremental updates to files over 2GB may also fail with BackupStore BadBackupStoreFile (4/11)
  • Restoring files over 2GB fails instantly (see ticket:2)
  • Build on Debian Etch 64-bit fails with the error BackupQueries.cpp:818: error: LLONG_MIN was not declared in this scope.
  • Windows support is not very good, the Windows client will often deadlock with bbackupctl and various other problems.

To fix issues with files over 2GB, please try the latest development version.

Box Backup 0.10 is available pre-packaged for the following systems:

If you know of any pre-packaged and supported versions for other architectures then please update this part of the wiki.

If you have a different system to the above then you'll need to build it from the source by following the GeneralInstall instructions.

Development Download

Development is actively underway on version 0.11, the next version of Box Backup, but it is not yet ready for general use. However, it is known to address two key problems that have been identified in version 0.10 - more stable support for Windows clients, and backing up files larger than 2GB, so you may want to try it if you need to overcome either of those problems.

Packaged development versions are made available as beta releases or release candidates, depending on their stability. They are available from the BetaReleases page. If you want to build from source then see the SourceCodeRepository page.

Packaged Versions


As of may 2007 official packages are available for Box Backup in debian main:

thus, if you are running debian unstable, you are ready to install.

if you are running debian etch, a backport of the official packages is available on - see for instructions on how to use packages from

if you are running sarge (oldstable) on i386 the following unofficial repository from Jérôme Schell may still be of interest: (but upgrading to etch may be the better plan ;)

deb sarge main
deb-src sarge main

in either case use something like

apt-get install boxbackup-client

to install.

RPM Packages

Instructions on building your own Redhat packages (RPMs), also applicable to Fedora, SuSE and Mandriva, are available on the CompileLinuxRPM page. If you know of any supported pre-built packages then please update this part of the wiki.


Please be aware that this is experimental, and likely to have a few bugs, so it should not be your only backup strategy. Comments and feedback are very welcome, preferably to the mailing lists.

A pre-compiled Windows client is available here. Unless you have a deep desire to build your own binaries from source, we recommend that you use one of these, preferably the latest one.

The source code can be downloaded from here using Subversion, and compiled by following these instructions.

Windows users should use (or build) one of these Windows-specific versions - compiling and using the main Box Backup source code under Cygwin is known to have problems.

There are some known issues with the Windows client at present - see the known bugs page for more details.


A FreeBSD port is also available. This can be installed by either:

  • Running the binary package: pkg_add -r boxbackup
  • Compiling from ports: cd /usr/ports/sysutils/boxbackup; make install clean


  • GNU Readline support has been disabled by default, but can be enabled by installing from ports.
  • If GNU Readline is not enabled, then bbackupquery has no line editing ability, due to FreeBSD's implementation of libedit not being detected by autoconf. Hopefully this will be fixed in a future release.

Gentoo Linux

Box Backup is available within the standard Portage tree as app-backup/boxbackup, although version 0.10 is currently marked as unstable and so you'll have to unmask it to install it. Do that as follows:

echo ~app-backup/boxbackup-0.10 ~x86 >> /etc/portage/package.keywords
emerge -aDvt boxbackup

The ebuild will, by default, install both the client and server portions. If you're installing a machine that will only be a client then you can add the client-only USE flag for a slightly smaller install. There are also a couple of path differences to be aware of:

  • The configuration files live in /etc/boxbackup rather than the /etc/box directory often discussed in this documentation. The contents of this directory are the same, however.
  • The binaries and scripts are installed into /usr/sbin rather than /usr/local/bin.


Unless otherwise stated for a particular Box Backup version, both the client and server must be running the same software version (ie if you upgrade the server then you must also upgrade all of your clients).

Generally speaking, the data held by your backup server should be preserved when upgrading the server. Again, refer to the specific page on the version you're upgrading to for exact details. Note that even though the data might be preserved when moving up in version (eg from 0.09 to 0.10), the same is not generally true when downgrading the server as the server data format will have been changed by the upgrade.

There are pages that describe specific versions below; each of those pages will give details on the main changes from the previous version as well as details on platform compatibility and upgrade details.