summaryrefslogtreecommitdiff
path: root/boxbackup
diff options
context:
space:
mode:
Diffstat (limited to 'boxbackup')
-rw-r--r--boxbackup/Makefile66
-rw-r--r--boxbackup/adminguide.xml1981
-rw-r--r--boxbackup/bb-book.xsl17
-rw-r--r--boxbackup/bb-man.xsl9
-rw-r--r--boxbackup/bb-nochunk-book.xsl17
-rw-r--r--boxbackup/bbackupctl.xml147
-rw-r--r--boxbackup/bbackupquery.xml380
-rw-r--r--boxbackup/bbstoreaccounts.xml290
-rw-r--r--boxbackup/bbstored-certs.xml125
-rw-r--r--boxbackup/bbstored-config.xml140
-rw-r--r--boxbackup/generate_except_xml.pl74
-rw-r--r--boxbackup/html/bbdoc-man.css104
-rw-r--r--boxbackup/html/bbdoc.css112
-rw-r--r--boxbackup/html/images/arrow.pngbin0 -> 197 bytes
-rw-r--r--boxbackup/html/images/bblogo.pngbin0 -> 5882 bytes
-rw-r--r--boxbackup/html/images/stepahead.pngbin0 -> 298 bytes
-rw-r--r--boxbackup/instguide.xml766
-rw-r--r--boxbackup/raidfile-config.xml143
18 files changed, 4371 insertions, 0 deletions
diff --git a/boxbackup/Makefile b/boxbackup/Makefile
new file mode 100644
index 00000000..aefa3ee2
--- /dev/null
+++ b/boxbackup/Makefile
@@ -0,0 +1,66 @@
+
+
+# Process DocBook to HTML
+
+DBPROC=/usr/bin/xsltproc
+BOOKXSL=bb-book.xsl
+NOCHUNKBOOKXSL=bb-nochunk-book.xsl
+MANXSL=bb-man.xsl
+HTMLPREFIX=box-html
+VPATH= adminguide
+.SUFFIXES: .html .xml
+
+all: docs
+
+docs: instguide adminguide manpages
+ mkdir -p $(HTMLPREFIX)/images
+ cp html/images/*.png $(HTMLPREFIX)/images/.
+ cp html/*.css $(HTMLPREFIX)/.
+
+adminguide: $(HTMLPREFIX)/adminguide/index.html
+
+$(HTMLPREFIX)/adminguide/index.html: adminguide.xml ExceptionCodes.xml $(BOOKXSL)
+ # docname=`echo $@ | sed -e 's/\/index.html//'`
+ $(DBPROC) -o $(HTMLPREFIX)/adminguide/ $(BOOKXSL) adminguide.xml
+
+instguide: $(HTMLPREFIX)/instguide/index.html
+
+$(HTMLPREFIX)/instguide/index.html: instguide.xml $(BOOKXSL)
+ $(DBPROC) -o $(HTMLPREFIX)/instguide/ $(BOOKXSL) instguide.xml
+
+ExceptionCodes.xml: ../../ExceptionCodes.txt
+ perl ./generate_except_xml.pl
+
+manpages: man-dirs man-nroff man-html
+
+man-dirs: man-pages/.there $(HTMLPREFIX)/man-html/.there
+
+$(HTMLPREFIX)/man-html/.there:
+ if [ ! -d man-html ]; then mkdir -p $(HTMLPREFIX)/man-html; touch $(HTMLPREFIX)/man-html/.there; fi
+
+man-pages/.there:
+ if [ ! -d man-pages ]; then mkdir man-pages; touch man-pages/.there; fi
+
+man-nroff: bbackupquery.1 bbackupctl.1 bbstoreaccounts.1 bbstored-config.1 raidfile-config.1 bbstored-certs.1
+
+man-html: bbackupquery.html bbackupctl.html bbstoreaccounts.html bbstored-config.html raidfile-config.html bbstored-certs.html
+
+%.html: %.xml
+ $(DBPROC) -o $@ $(NOCHUNKBOOKXSL) $<
+ mv $@ $(HTMLPREFIX)/man-html/.
+
+%.1: %.xml
+ $(DBPROC) -o $@ $(MANXSL) $<
+ mv $@ man-pages/.
+ gzip -f -9 man-pages/$@
+
+dockit: clean docs
+ tar zcf documentation-kit-0.10.tar.gz $(HTMLPREFIX)/
+
+clean:
+ if [ -d ./$(HTMLPREFIX) ]; then rm -rf $(HTMLPREFIX) ; fi
+ if [ -d ./man-pages ]; then rm -rf ./man-pages/; fi
+ if [ -f ExceptionCodes.xml ]; then rm ExceptionCodes.xml; fi
+ if [ -f documentation-kit-0.10.tar.gz ]; then rm documentation-kit-0.10.tar.gz; fi
+
+
diff --git a/boxbackup/adminguide.xml b/boxbackup/adminguide.xml
new file mode 100644
index 00000000..d3552725
--- /dev/null
+++ b/boxbackup/adminguide.xml
@@ -0,0 +1,1981 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+<!ENTITY __ExceptionCodes__elfjz3fu SYSTEM "ExceptionCodes.xml">
+]>
+<book>
+ <title>Box Backup administrator's guide</title>
+
+ <preface>
+ <title>License</title>
+
+ <para>Copyright © 2003 - 2007, Ben Summers and contributors. All rights
+ reserved.</para>
+
+ <para>Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are
+ met:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.</para>
+ </listitem>
+
+ <listitem>
+ <para>Redistributions in binary form must reproduce the above
+ copyright notice, this list of conditions and the following disclaimer
+ in the documentation and/or other materials provided with the
+ distribution.</para>
+ </listitem>
+
+ <listitem>
+ <para>All use of this software and associated advertising materials
+ must display the following acknowledgement: This product includes
+ software developed by Ben Summers and contributors.</para>
+ </listitem>
+
+ <listitem>
+ <para>The names of the Authors may not be used to endorse or promote
+ products derived from this software without specific prior written
+ permission.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>[Where legally impermissible the Authors do not disclaim liability
+ for direct physical injury or death caused solely by defects in the
+ software unless it is modified by a third party.]</para>
+
+ <para>THIS SOFTWARE IS PROVIDED BY THE AUTHORS "AS IS" AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
+ NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</para>
+ </preface>
+
+ <chapter>
+ <title>Configuration</title>
+
+ <section>
+ <title>System configuration</title>
+
+ <section>
+ <title>Server</title>
+
+ <para>After you've downloaded and compiled the programs you need to
+ install the programs on your server. As root do the following:</para>
+
+ <programlisting>make install-backup-server</programlisting>
+
+ <para>This assumes that you are installing on the same server that you
+ compiled the software on. If not, copy the
+ boxbackup-x.xx-backup-server-OSNAME.tgz file to the server you want to
+ run on, and install there. For example (on Mac OS X):</para>
+
+ <programlisting>tar zxvf boxbackup-0.10-server-darwin8.5.0.tgz
+cd boxbackup-0.10-server-darwin8.5.0
+./install-backup-server</programlisting>
+
+ <para>Then create the user for the backup daemon on the server:</para>
+
+ <programlisting>useradd _bbstored</programlisting>
+
+ <para>Box Backup has a built-in software RAID facility (redundant
+ array of inexpensive disks) for the backup store. This allows you to
+ spread the store data over three disks, and recover from the loss of
+ any one disk without losing data. However, this is now deprecated, and
+ you are recommended to use the software or hardware RAID facilities of
+ your operating system instead. Use the following command if you want
+ to create a simple server without Box Backup RAID:</para>
+
+ <programlisting>mkdir /tmp/boxbackupRepository # Create the directory
+chown _bbstored /tmp/boxbackupRepository/ # Change the owner to the new boxbackup daemon user
+
+/usr/local/bin/raidfile-config /etc/box/ 1024 /tmp/boxbackupRepository
+
+#substitute 1024 with the desired blocksize
+#substitute /tmp/boxbackupRepository with a directory that exists where you want the backup store located
+#/usr/local/bin/raidfile-config --help shows you the options</programlisting>
+
+ <para>Then create the configuration file /etc/box/bbstored.conf The
+ hostname is tricky as it is used for two things: The name of the
+ server in the certificate and the address the server is listening on.
+ Since you might be using NAT, might move the server around or the
+ domain name might change, choose a name that describes the server.
+ When the network address of the server changes, you need to update the
+ <literal>ListenAddresses</literal> directive in the
+ <filename>/etc/box/bbstored.conf</filename> file.</para>
+
+ <programlisting>/usr/local/bin/bbstored-config /etc/box hostname _bbstored</programlisting>
+
+ <para>This last step outputs 5 instructions that you must execute to
+ the letter. A lot of questions are raised on the mailing list because
+ these steps have not been followed properly.</para>
+
+ <para>TODO: Expand on this. Explain the 5 steps in detail.</para>
+
+ <para>If you want to run the server as a non-root user, look <link
+ linkend="WORoot">here</link>.</para>
+ </section>
+
+ <section>
+ <title>Certificate Management</title>
+
+ <para>There are two steps involved to create an account. You need to
+ create the account on the server, and sign a certificate to give the
+ client permission to connect to the server.</para>
+
+ <para>Running a Certification Authority for TLS (SSL) connections is
+ not trivial. However, a script to does most of the work in a way which
+ should be good enough for most deployments.</para>
+
+ <important>
+ <para>The certificate authority directory is intended to be stored
+ on another server. It should not be kept on the backup server, in
+ order to limit the impact of a server compromise. The instructions
+ and the script assume that it will be kept elsewhere, so will ask
+ you to copy files to and from the CA.</para>
+ </important>
+
+ <warning>
+ <para>SSL certificates contain validity dates, including a "valid
+ from" time. If the clock on the machine which signs the certificates
+ is not syncronised to the clocks of the machines using these
+ certificates, you will probably get strange errors until the start
+ time is reached on all machines. If you get strange errors when
+ attempting to use new certificates, check the clocks on all machines
+ (client, store and CA). You will probably just need to wait a while
+ until the certificates become valid, rather than having to
+ regenerate them.</para>
+ </warning>
+
+ <section>
+ <title>Set up a Certificate Authority</title>
+
+ <para>It is recommended that you keep your Certificate Authority on
+ a separate machine than either the client or the server, preferably
+ without direct network access. The contents of this directory
+ control who can access your backup store server.</para>
+
+ <para>To setup the basic key structure, do the following:</para>
+
+ <programlisting>/usr/local/bin/bbstored-certs ca init</programlisting>
+
+ <para>(See <ulink url="instguide.xml">OpenSSL notes</ulink> if you
+ get an OpenSSL error)</para>
+
+ <para>This creates the directory called <filename>ca</filename> in
+ the current directory, and initialises it with basic keys.</para>
+ </section>
+
+ <section>
+ <title>Sign a server certificate</title>
+
+ <para>When you use the <command>bbstored-config</command> script to
+ set up a config file for a server, it will generate a certificate
+ request (CSR) for you. Transfer it to the machine with your CA, then
+ do:</para>
+
+ <programlisting>/usr/local/bin/bbstored-certs ca sign-server hostname-csr.pem</programlisting>
+
+ <para>This signs the certificate for the server. Follow the
+ instructions in the output on which files to install on the server.
+ The CSR file is now no longer needed. Make sure you run this command
+ from the directory above the directory 'ca'.</para>
+
+ <para>TODO: Explain instructions in output.</para>
+ </section>
+
+ <section>
+ <title>Set up an account</title>
+
+ <para>Choose an account number for the user. This must be unique on
+ the server, and is presented as a 31 bit number in hex greater than
+ 0, for example, 1 or 75AB23C. Then on the backup store server,
+ create the account with:</para>
+
+ <programlisting>/usr/local/bin/bbstoreaccounts create 75AB23C 0 4096M 4505M</programlisting>
+
+ <para>This looks complicated. The numbers are, in order:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The account number allocated (hex)</para>
+ </listitem>
+
+ <listitem>
+ <para>The RAID disc set (0 if you use raidfile-config and don't
+ add a new set)</para>
+ </listitem>
+
+ <listitem>
+ <para>Soft limit (size)</para>
+ </listitem>
+
+ <listitem>
+ <para>Hard limit (size)</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The sizes are are specified in Mb, Gb, or blocks, depending on
+ the suffix. 1M specifies 1 Mb, 1G specifies 1 Gb, and 1B specifies 1
+ block, the size of which depends on how you have configured the
+ raidfile system with raidfile-config.</para>
+
+ <para>In this example, I have allocated 4Gb (assuming you use 2048
+ byte blocks as per my example) as the soft limit, and 4Gb + 10% as
+ the hard limit.</para>
+
+ <para>NOTE The sizes specified here are pre-RAID. So if you are
+ using userland RAID, you are actually allocating two-thirds of this
+ amount. This means that, when you take compression into account,
+ that if you allocate 2Gb on the server, it'll probably hold about
+ 2Gb of backed up files (depending on the compressability of those
+ files).</para>
+
+ <para>The backup client will (voluntarily) try not to upload more
+ data than is allowed by the soft limit. The store server will refuse
+ to accept a file if it would take it over the hard limit, and when
+ doing housekeeping for this account, try and delete old versions and
+ deleted files to reduce the space taken to below the soft
+ limit.</para>
+
+ <para>This command will create some files on disc in the raid file
+ directories (if you run as root, the utility will change to the user
+ specified in the bbstored.conf file to write them) and update the
+ accounts file. A server restart is not required.</para>
+
+ <para>NOTE If you get a message saying 'Exception: RaidFile (2/8)',
+ the directories you specified in the raidfile.conf are not writable
+ by the _bbstored user -- fix it, and try again.</para>
+
+ <para>Finally, tell the user their account number, and the hostname
+ of your server. They will use this to set up the backup client, and
+ send you a CSR. This has the account number embedded in it, and you
+ should be sure that it has the right account number in it.</para>
+
+ <para>Sign this CSR with this command:</para>
+
+ <programlisting>/usr/local/bin/bbstored-certs ca sign 75AB23C-csr.pem</programlisting>
+
+ <para>Don't forget to check that the embedded account number is
+ correct! Then send the two files back to the user, as instructed by
+ the script.</para>
+
+ <para>Please read the Troubleshooting page if you have
+ problems.</para>
+
+ <para>TODO: Link to troubleshooting...</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Log Files</title>
+
+ <para>You may wish to see what's going on with the server. Edit
+ /etc/syslog.conf, and add:</para>
+
+ <programlisting>local6.info /var/log/box
+local5.info /var/log/raidfile</programlisting>
+
+ <para><emphasis role="bold">Note:</emphasis> Separators must be tabs,
+ otherwise these entries will be ignored.</para>
+
+ <programlisting>touch /var/log/box
+touch /var/log/raidfile</programlisting>
+
+ <para>Set up log rotation for these new log files. For example, if you
+ have <filename>/etc/newsyslog.conf</filename>, add the following lines
+ to it:</para>
+
+ <programlisting>/var/log/box 644 7 2000 * Z
+/var/log/raidfile 644 7 2000 * Z</programlisting>
+
+ <para>If you have <filename>/etc/logrotate.d</filename>, create a new
+ file in there (for example
+ <filename>/etc/logrotate.d/boxbackup</filename>) containing the
+ following:</para>
+
+ <programlisting>/var/log/box /var/log/raidfile {
+ weekly
+ create
+ compress
+ rotate 52
+}</programlisting>
+
+ <para>Then restart syslogd, for example:</para>
+
+ <programlisting>/etc/init.d/syslogd restart</programlisting>
+ </section>
+
+ <section>
+ <title>Configuring a client</title>
+
+ <para>Before you can do any configuration, you need to know the
+ hostname of the server you will be using, and your account number on
+ that server.</para>
+
+ <para>Later in the process, you will need to send a certificate
+ request to the administrator of that server for it to be
+ signed.</para>
+
+ <para>Installation is covered in the compiling and installing section.
+ You only need the backup-client parcel.</para>
+
+ <para>It is important that you read all the output of the config
+ scripts. See the end of this page for an example.</para>
+
+ <para>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 <filename>/etc/box</filename>, and then give the
+ alternate config file as the first argument to
+ <command>bbackupd</command>). However, it will fall over if you don't
+ give yourself read access to one of your files.</para>
+
+ <section>
+ <title id="BasicConfig">Basic configuration</title>
+
+ <para>Run the <command>bbackupd-config</command> script to generate
+ the configuration files and generate a private key and certificate
+ request.</para>
+
+ <programlisting>/usr/local/bin/bbackupd-config /etc/box lazy <emphasis
+ role="bold">999 hostname</emphasis> /var/bbackupd <emphasis
+ role="bold">/home</emphasis></programlisting>
+
+ <para>(See <ulink url="instguide.xml">OpenSSL notes</ulink> if you
+ get an OpenSSL error)</para>
+
+ <para>The items in bold need to be changed. 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.</para>
+
+ <para>However, the directories you specify must not contain other
+ mounted file systems within them at any depth. Specify them
+ separately, one per mount point. No checks are currently made to
+ catch bad configuration of this nature!</para>
+
+ <para>You may also want to consider changing the mode from lazy to
+ snapshot, depending on what your system is used for:</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm>Lazy Mode</glossterm>
+
+ <glossdef>
+ <para>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's documents stored on a server, and spreads
+ the load out over the day.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Snapshot Mode</glossterm>
+
+ <glossdef>
+ <para>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.</para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+
+ <para>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.</para>
+ </section>
+
+ <section>
+ <title>Certificates</title>
+
+ <para>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 during
+ basic bbackupd configuration.</para>
+
+ <para>You can then run the daemon (as root) by running
+ <command>/usr/local/bin/bbackupd</command>, and of course, adding 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.</para>
+
+ <para>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.</para>
+
+ <para>Please read the Troubleshooting page if you have
+ problems.</para>
+
+ <para>Remember to make a traditional backup of the keys file, as
+ instructed. You cannot restore files without it.</para>
+
+ <para>It is recommended that you backup up all of /etc/box as it
+ will make things easier if you need to restore files. But only the
+ keys are absolutely essential.</para>
+
+ <para>If you want to see what it's doing in more detail (probably a
+ good idea), follow the instructions in the server setup to create
+ new log files with syslog. </para>
+ </section>
+
+ <section>
+ <title>Adding and removing backed up locations</title>
+
+ <para>By editing the /etc/box/bbackupd.conf file, you can add and
+ remove directories to back up - see comments in this file for help.
+ Send bbackupd a HUP signal after you modify it.</para>
+
+ <para>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.</para>
+
+ <para>The backup client is designed to be run as root. It is
+ possible to run without root, but this is not recommended. Clock
+ synchronisation for file servers.</para>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>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 (default
+ is 2 days). Instead, get those clocks synchronised. Excluding files
+ and directories from the backup.</para>
+
+ <para>Within the bbackupd.conf file, there is a section named
+ BackupLocations which specifies which locations on disc should be
+ backed up. It has subsections, each of which is in the
+ format:</para>
+
+ <programlisting> name
+ {
+ Path = /path/of/directory
+ (optional exclude directives)
+ }</programlisting>
+
+ <para><emphasis role="bold">name</emphasis> is derived from the Path
+ by the config script, but should merely be unique.</para>
+
+ <para>The exclude directives are of the form:</para>
+
+ <programlisting>[Exclude|AlwaysInclude][File|Dir][|sRegex] = regex or full pathname</programlisting>
+
+ <para>(The regex suffix is shown as 'sRegex' to make File or Dir
+ plural)</para>
+
+ <para>For example:</para>
+
+ <programlisting> ExcludeDir = /home/guest-user
+ ExcludeFilesRegex = *.(mp3|MP3)\$
+ AlwaysIncludeFile = /home/username/veryimportant.mp3</programlisting>
+
+ <para>This excludes the directory /home/guest-user from the backup
+ along with all mp3 files, except one MP3 file in particular.</para>
+
+ <para>In general, Exclude excludes a file or directory, unless the
+ directory is explicitly mentioned in a AlwaysInclude
+ directive.</para>
+
+ <para>If a directive ends in Regex, then it is a regular expression
+ rather than a explicit full pathname. See</para>
+
+ <programlisting> man 7 re_format</programlisting>
+
+ <para>for the regex syntax on your platform.</para>
+ </section>
+
+ <section>
+ <title>Example configuration output</title>
+
+ <para>This is an example of output from the bbstored-config
+ script.</para>
+
+ <important>
+ <para>Follow the instructions output by your script, not the ones
+ here -- they may be different for your system.</para>
+ </important>
+
+ <programlisting>/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.
+
+===================================================================</programlisting>
+
+ <para>Remember to make a secure, offsite backup of your backup keys,
+ as described in <link linkend="BasicConfig">Basic
+ configuration</link> above. If you do not, and that key is lost, you
+ have no backups.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Configuration Options</title>
+
+ <para>Box Backup has many options in its configuration file. We will
+ try to list them all here.</para>
+
+ <para>First of all, here is an example configuration file, for
+ reference:</para>
+
+ <example>
+ <title>Example Configuration File</title>
+
+ <programlisting>StoreHostname = localhost
+AccountNumber = 0x2
+
+KeysFile = /etc/box/2-FileEncKeys.raw
+CertificateFile = /etc/box/2-cert.pem
+PrivateKeyFile = /etc/box/2-key.pem
+TrustedCAsFile = /etc/box/serverCA.pem
+DataDirectory = /var/run/boxbackup
+NotifyScript = /etc/box/NotifySysadmin.sh
+CommandSocket = /var/run/box/bbackupd.sock
+
+UpdateStoreInterval = 86400
+MinimumFileAge = 3600
+MaxUploadWait = 7200
+FileTrackingSizeThreshold = 65536
+DiffingUploadSizeThreshold = 65536
+MaximumDiffingTime = 20
+ExtendedLogging = no
+LogAllFileAccess = yes
+
+Server
+{
+ PidFile = /var/run/bbackupd.pid
+}
+BackupLocations
+{
+ etc
+ {
+ Path = /etc
+ }
+ home
+ {
+ Path = /home
+ ExcludeDir = /home/shared
+ ExcludeDir = /home/chris/.ccache
+ ExcludeDir = /home/chris/.mozilla/firefox/vvvkq3vp.default/Cache
+ }
+}</programlisting>
+ </example>
+
+ <para>As you can see from the example above, the configuration file
+ has a number of subsections, enclosed in curly braces {}. Some options
+ appear outside of any subsection, and we will refer to these as <link
+ linkend="RootOptions">root options</link>. The available options in
+ each section are described below.</para>
+
+ <para>Every option has the form <quote>name = value</quote>. Names are
+ not case-sensitive, but values are. Depending on the option, the value
+ may be:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>a path (to a file or directory);</para>
+ </listitem>
+
+ <listitem>
+ <para>a number (usually in seconds or bytes);</para>
+ </listitem>
+
+ <listitem>
+ <para>a boolean (the word Yes or No);</para>
+ </listitem>
+
+ <listitem>
+ <para>a hostname (or IP address).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Paths are specified in native format, i.e. a full Windows path
+ with drive letter on Windows clients, or a full Unix path on Unix
+ clients.</para>
+
+ <para><example>
+ <title>Example:</title>
+
+ <para>StoreObjectInfoFile =
+ /var/state/boxbackup/bbackupd.dat</para>
+
+ <para>StoreObjectInfoFile = C:\Program Files\Box
+ Backup\data\bbackupd.dat</para>
+ </example>The use of relative paths (which do not start with a
+ forward slash on Unix, or a drive specification on Windows) is
+ possible but not recommended, since they are interpreted relative to
+ the current working directory when bbackupd was started, which is
+ liable to change unexpectedly over time.</para>
+
+ <para>Numbers which start with "0x" are interpreted as hexadecimal.
+ Numbers which do not start with "0x" are interpreted as
+ decimal.</para>
+
+ <section>
+ <title id="RootOptions">Root Options</title>
+
+ <para>These options appear outside of any subsection. By convention
+ they are at the beginning of the configuration file.</para>
+
+ <para>Some options are required, and some are optional.</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm>StoreHostname (required)</glossterm>
+
+ <glossdef>
+ <para>The Internet host name (DNS name) or IP address of the
+ server. This is only used to connect to the server.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>AccountNumber (required)</glossterm>
+
+ <glossdef>
+ <para>The number of the client's account on the server. This
+ must be provided by the server operator, and must match the
+ account number in the client's certificate, otherwise the
+ client will not be able to log into the server.</para>
+
+ <para>The account number may be specified in hexadecimal
+ (starting with 0x, as in the example above) or in decimal, but
+ since the server operator works in hexadecimal, that format is
+ highly recommended and is the default.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>KeysFile (required)</glossterm>
+
+ <glossdef>
+ <para>The path to the file containing the encryption key used
+ for data encryption of client file data and filenames. This is
+ the most important file to keep safe, since without it your
+ backups cannot be decrypted and are useless. Likewise, if an
+ attacker gets access to this key and to your encrypted
+ backups, he can decrypt them and read all your data. </para>
+
+ <para>Do not change the encryption key without deleting all
+ files from the account on the server first. None of your old
+ files on the store will be readable if you do so, and if you
+ change it back, none of the files uploaded with the new key
+ will be readable.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>CertificateFile (required)</glossterm>
+
+ <glossdef>
+ <para>The path to the OpenSSL client certificate in PEM
+ format. This is supplied by the server operator in response to
+ the certificate request which you send to them. Together with
+ the PrivateKeyFile, this provides access to the store server
+ and the encrypted data stored there.</para>
+
+ <para>It is not critical to protect this file or to back it up
+ safely, since it can be regenerated by creating a new
+ certificate request, and asking the server operator to sign
+ it. You may wish to back it up, together with the
+ PrivateKeyFile, to avoid this inconvenience if you lose all
+ your data and need quick access to your backups.</para>
+
+ <para>If you do back them up, you should keep them in a
+ separate location to the KeysFile, since any person holding
+ the KeysFile and the PrivateKeyFile can gain access to your
+ encrypted data and decrypt it.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>PrivateKeyFile (required)</glossterm>
+
+ <glossdef>
+ <para>The path to the OpenSSL private key in PEM format. This
+ is generated at the same time as the certificate request, but
+ there is no need to send it to the server operator, and you
+ should not do so, in case the communication is intercepted by
+ an attacker. Together with the CertificateFile, this provides
+ access to the store server and the encrypted data stored
+ there.</para>
+
+ <para>See the notes under CertificateFile for information
+ about backing up this file.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>TrustedCAsFile (required)</glossterm>
+
+ <glossdef>
+ <para>The path to the OpenSSL certificate of the Client
+ Certificate Authority (CCA), in PEM format. This is supplied
+ by the server operator along with your account details, or
+ along with your signed client certificate. This is used to
+ verify that the server which you are connecting to is
+ authorised by the person who signed your certificate. It
+ protects you against DNS and ARP poisoning and IP spoofing
+ attacks.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>DataDirectory (required)</glossterm>
+
+ <glossdef>
+ <para>The path to a directory where bbackupd will keep local
+ state information. This consists of timestamp files which
+ identify the last backup start and end times, used by
+ <command>bbackupquery</command> to determine whether files
+ have changed, and optionally a database of inode numbers,
+ which are used to check for files being renamed. The database
+ is only saved if Box Backup is built with Berkeley Database
+ (BDB) support.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>NotifyScript (optional)</glossterm>
+
+ <glossdef>
+ <para>The path to the script or command to run when the Box
+ Backup client detects an error during the backup process. This
+ is normally used to notify the client system administrator by
+ e-mail when a backup fails for any reason.</para>
+
+ <para>The script or command is called with one of the
+ following additional arguments to identify the cause of the
+ problem:</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm>store-full</glossterm>
+
+ <glossdef>
+ <para>The backup store is full. No new files are being
+ uploaded. If some files are marked as deleted, they
+ should be removed in due course by the server's
+ housekeeping process. Otherwise, you need to remove some
+ files from your backup set, or ask the store operator
+ for more space.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>read-error</glossterm>
+
+ <glossdef>
+ <para>One or more files which were supposed to be backed
+ up could not be read. This could be due to:<itemizedlist>
+ <listitem>
+ <para>running the server as a non-root user;</para>
+ </listitem>
+
+ <listitem>
+ <para>backing up a mounted filesystem such as
+ NFS;</para>
+ </listitem>
+
+ <listitem>
+ <para>access control lists being applied to some
+ files;</para>
+ </listitem>
+
+ <listitem>
+ <para>SELinux being enabled;</para>
+ </listitem>
+
+ <listitem>
+ <para>trying to back up open files under
+ Windows;</para>
+ </listitem>
+
+ <listitem>
+ <para>strange directory permissions such as 0000 or
+ 0400.</para>
+ </listitem>
+ </itemizedlist>Check the client logs, e.g.
+ /var/log/bbackupd on Unix, or the Windows Event Viewer
+ in Control Panel &gt; Administrative Tools, for more
+ information about which files are not being backed up
+ and why.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>backup-error</glossterm>
+
+ <glossdef>
+ <para>There was a communications error with the server,
+ or an unexpected exception was encountered during a
+ backup run. Check the client logs, e.g.
+ <filename>/var/log/box</filename> on Unix, or the
+ Windows Event Viewer in Control Panel &gt;
+ Administrative Tools, for more information about the
+ problem.</para>
+
+ <para>You may wish to check your Internet access to the
+ server, check that the server is running, and ask your
+ server operator to check your account on the
+ server.</para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>CommandSocket (optional)</glossterm>
+
+ <glossdef>
+ <para>The path to the Unix socket which
+ <command>bbackupd</command> creates when running, and which
+ <command>bbackupctl</command> uses to communicate with it, for
+ example to force a sync or a configuration reload. If this
+ option is omitted, no socket will be created, and
+ <command>bbackupctl</command> will not function.</para>
+
+ <para>Unix sockets appear within the filesystem on Unix, as a
+ special type of file, and must be created in a directory which
+ exists and to which bbackupd has write access, and bbackupctl
+ has read access. </para>
+
+ <para>On Windows, the path is ignored, and a <glossterm>named
+ pipe</glossterm> is created instead. This does not currently
+ have any security attached, so it can be accessed by any user.
+ Unlike a Unix socket it can also be accessed remotely. Please
+ use this option with extreme caution on Windows, and only on
+ fully trusted networks.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>AutomaticBackup (optional)</glossterm>
+
+ <glossdef>
+ <para>Enable or disable the client from connecting
+ automatically to the store every
+ <glossterm>UpdateStoreInterval</glossterm> seconds. When
+ enabled (set to <quote>Yes</quote>), the client is in
+ <glossterm>Lazy Mode</glossterm>. When disabled (set to
+ <quote>No</quote>), it is in <glossterm>Snapshot
+ Mode</glossterm>. This setting is optional, and the default
+ value is <quote>Yes</quote>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>UpdateStoreInterval (required)</glossterm>
+
+ <glossdef>
+ <para>The approximate time between successive connections to
+ the server, in seconds, when the client is in <glossterm>Lazy
+ Mode</glossterm>. The actual time is randomised slightly to
+ prevent "rush hour" traffic jams on the server, where many
+ clients try to connect at the same time.</para>
+
+ <para>This value is ignored if the client is in
+ <glossterm>Snapshot Mode</glossterm>. However, it is still
+ required. It can be set to zero in this case.</para>
+
+ <para>You will probably need to experiment with the value of
+ this option. A good value to start with is probably 86400
+ seconds, which is one day.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>MinimumFileAge (required)</glossterm>
+
+ <glossdef>
+ <para>The number of seconds since a file was last modified
+ before it will be backed up. The reason for this is to avoid
+ repeatedly backing up files which are repeatedly changing. A
+ good value is about 3600 seconds (one hour). If set to zero,
+ files which have changed will always be backed up on the next
+ backup run. </para>
+
+ <para>The <glossterm>MaxUploadWait</glossterm> option
+ overrides this option in some circumstances.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>MaxUploadWait (required)</glossterm>
+
+ <glossdef>
+ <para>The number of seconds since a file was last uploaded
+ before it will be uploaded again, even if it keeps changing.
+ The reason for this is to ensure that files which are
+ continuously modified are eventually uploaded anyway. This
+ should be no less than the value of
+ <glossterm>MinimumFileAge</glossterm>. A good value is about
+ 14400 seconds (4 hours).</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>MaxFileTimeInFuture (optional)</glossterm>
+
+ <glossdef>
+ <para>The maximum time that a file's timestamp can be in the
+ future, before it will be backed up anyway. Due to clock
+ synchronisation problems, it is inevitable that you will
+ occasionally see files timestamped in the future. Normally,
+ for files which are dated only slightly in the future, you
+ will want to wait until after the file's date before backing
+ it up. However, for files whose dates are very wrong (more
+ than a few hours) you will normally prefer to back them up
+ immediately.</para>
+
+ <para>A good value is about 7200 seconds (2 hours) to cope
+ with potential problems when moving in and out of daylight
+ saving time, if applicable in your timezone. The default
+ value, if this setting is not provided, is 172800 seconds (2
+ days).</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>FileTrackingSizeThreshold (required)</glossterm>
+
+ <glossdef>
+ <para>The minimum size of files which will be tracked by inode
+ number to detect renames. It is not worth detecting renames of
+ small files, since they are quick to upload again in full, and
+ keeping their inode numbers in memory increases the client's
+ memory usage and slows down searches. Larger files should be
+ tracked to avoid wasting space on the store and long
+ uploads.</para>
+
+ <para>A good value is about 65536 bytes (64 kilobytes).</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>DiffingUploadSizeThreshold (required)</glossterm>
+
+ <glossdef>
+ <para>The minimum size of files which will be compared to the
+ old file on the server, and for which only changes will be
+ uploaded. It is not worth comparing small files, since they
+ are quick to upload again in full, and sending the entire file
+ reduces the risk of data loss if the store is accidentally
+ corrupted. Larger files should have only their differences
+ uploaded to avoid wasting space on the store and long
+ uploads.</para>
+
+ <para>A good value is about 65536 bytes (64 kilobytes).</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>MaximumDiffingTime (optional)</glossterm>
+
+ <glossdef>
+ <para>The maximum time for which the client will attempt to
+ find differences between the current version and the old
+ version in the store, before giving up and uploading the
+ entire file again. Very large files (several gigabytes) may
+ take a very long time to scan for changes, but would also take
+ a very long time to upload again and use a lot of space on the
+ store, so it is normally worth omitting this value. </para>
+
+ <para>Use this option only if, for some bizarre reason, you
+ prefer to upload really large files in full rather than spend
+ a long time scanning them for changes.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>KeepAliveTime (optional)</glossterm>
+
+ <glossdef>
+ <para>The interval (in seconds) between sending Keep-Alive
+ messages to the server while performing long operations such
+ as finding differences in large files, or scanning large
+ directories. </para>
+
+ <para>These messages ensure that the SSL connection is not
+ closed by the server, or an intervening firewall, due to lack
+ of activity.</para>
+
+ <para>The server will normally wait up to 15 minutes (900
+ seconds) before disconnecting the client, so the value should
+ be given and should be less than 900. Some firewalls may time
+ out inactive connections after 10 or 5 minutes. </para>
+
+ <para>A good value is 300 seconds (5 minutes). You may need to
+ reduce this if you frequently see TLSReadFailed or
+ TLSWriteFailed errors on the client.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>StoreObjectInfoFile (optional)</glossterm>
+
+ <glossdef>
+ <para>Enables the use of a state file, which stores the
+ client's internal state when the client is not running. This
+ is useful on clients machines which are frequently shut down,
+ for example desktop and laptop computers, because it removes
+ the need for the client to recontact the store and rescan all
+ directories on the first backup run, which may take some time.
+ This feature is somewhat experimental and not well tested.
+ </para>
+
+ <para>This is option is disabled by default, in which case the
+ state is stored in memory only. The value is the path to the
+ state file.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>ExtendedLogging (optional)</glossterm>
+
+ <glossdef>
+ <para>Enables the connection debugging mode of the client,
+ which writes all commands sent to or received from the server
+ to the system logs. This generates a <emphasis>lot</emphasis>
+ of output, so it should only be used when instructed, or when
+ you suspect a connection problem or client-server protocol
+ error (and you know how to interpret the output).</para>
+
+ <para>This is a boolean value, which may be set to
+ <quote>Yes</quote> or <quote>No</quote>. The default is of
+ course <quote>No</quote>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>ExtendedLogFile (optional, new in 0.11)</glossterm>
+
+ <glossdef>
+ <para>Enables the same debugging output as
+ <glossterm>ExtendedLogging</glossterm>, but written to a file
+ instead of the system logs. This is useful if you need
+ extended logging, but do not have access to the system logs,
+ for example if you are not the administrator of the
+ computer.</para>
+
+ <para>The value is the path to the file where these logs will
+ be written. If omitted, extended logs will not be written to a
+ file. This is entirely independent of the
+ <glossterm>ExtendedLogging</glossterm> option. It does not
+ make much sense to use both at the same time.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>LogAllFileAccess (optional, new in 0.11)</glossterm>
+
+ <glossdef>
+ <para>Enables logging of all local file and directory access,
+ file uploads (full and differential), and excluded files. This
+ may be useful if the client is failing to upload a particular
+ file, or crashing while trying to upload it. The logs will be
+ sent to the system log or Windows Event Viewer.</para>
+
+ <para>This generates a <emphasis>lot</emphasis>
+ of output, so it should only be used when instructed, or when
+ you suspect that bbackupd is skipping some files and want to
+ know why. Because it is verbose, the messages are hidden by
+ default even if the option is enabled. To see them, you must
+ run bbackupd with at least one -v option.</para>
+
+ <para>This is a boolean value, which may be set to
+ <quote>Yes</quote> or <quote>No</quote>. The default is of
+ course <quote>No</quote>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>SyncAllowScript (optional)</glossterm>
+
+ <glossdef>
+ <para>The path to the script or command to run when the client
+ is about to start an automatic backup run, and wishes to know
+ whether it is safe to do so. This is useful for clients which
+ do not always have access to the server, for example laptops
+ and computers on dial-up Internet connections.</para>
+
+ <para>The script should either output the word
+ <quote>now</quote> if the backup should proceed, or else a
+ number, in seconds, which indicates how long the client should
+ wait before trying to connect again. Any other output will
+ result in an error on the client, and the backup will not
+ run.</para>
+
+ <para>This value is optional, and by default no such script is
+ used.</para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+ </section>
+
+ <section>
+ <title>Server Section</title>
+
+ <para>These options appear within the Server subsection, which is at
+ the root level.</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm>PidFile</glossterm>
+
+ <glossdef>
+ <para>This option enables the client to write its processs
+ identifier (PID) to the specified file after starting. The
+ file will be deleted when the client daemon exits for any
+ reason. This is disabled by default, but is recommended
+ whenever you run the client daemon as a daemon (in the
+ background), which is usually the case. This file can be used
+ by scripts to determine whether the daemon is still running,
+ and to send it messages to reload its configuration or to
+ terminate.</para>
+
+ <example>
+ <title>Example Server Section</title>
+
+ <programlisting>Server
+{
+ PidFile = /var/state/boxbackup/bbackupd.pid
+}</programlisting>
+ </example>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+ </section>
+
+ <section>
+ <title>Backup Locations Section</title>
+
+ <para>This section serves only as a container for all defined backup
+ locations.</para>
+
+ <example>
+ <title>Example Backup Locations Section</title>
+
+ <programlisting>BackupLocations
+{
+ etc
+ {
+ Path = /etc
+ }
+ home
+ {
+ Path = /home
+ ExcludeDir = /home/shared
+ ExcludeDir = /home/chris/.ccache
+ ExcludeDir = /home/chris/.mozilla/firefox/vvvkq3vp.default/Cache
+ }
+}</programlisting>
+ </example>
+
+ <para>Each subsection is a backup location. The name of the
+ subsection is the name that will be used on the server. The root
+ directory of the account on the server contains one subdirectory per
+ location. The name should be simple, not containing any spaces or
+ special characters.</para>
+
+ <para>If you do not define any locations, the client will not back
+ up any files!</para>
+
+ <para>It is currently not recommended to back up the root directory
+ of the filesystem on Unix. Box Backup is designed to back up
+ important data and configuration files, not full systems.
+ Nevertheless, nothing prevents you from doing so if you
+ desire.</para>
+
+ <para>On Windows, it is currently not possible to back up files
+ which are open (currently in use), such as open documents in
+ Microsoft Office, and system files such as the registry and the
+ paging file. You will get an error for each open file which the
+ client attempts to back up. Once the file has been closed, it will
+ be backed up normally. System files will always be open, and should
+ be excluded from your backups.</para>
+ </section>
+ </section>
+ </section>
+ </chapter>
+
+ <chapter>
+ <title>Administration</title>
+
+ <para>This chapter deals with the dauily running and management of the Box
+ Backup system. It explains most day-to-day tasks.</para>
+
+ <section>
+ <title>Regular Maintenance</title>
+
+ <para>The steps involved in maintaining and keeping the backup sets
+ healthy are outlined in this section.</para>
+
+ <section>
+ <title>Controlling a backup client</title>
+
+ <para>The bbackupctl program sends control commands to the bbackupd
+ daemon. It must be run as the same user as the daemon, and there is no
+ exception for root.</para>
+
+ <para>The command line syntax is:</para>
+
+ <programlisting>/usr/local/bin/bbackupctl [-q] [-c config-file] command</programlisting>
+
+ <para>The -q option reduces the amount of output the program emits,
+ and -c allows an alternative configuration file to be
+ specified.</para>
+
+ <para>Valid commands are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">terminate</emphasis></para>
+
+ <para>Stop the bbackupd daemon now (equivalent to kill)</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">reload</emphasis></para>
+
+ <para>Reload the configuration file (equivalent to kill
+ -HUP)</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">sync</emphasis></para>
+
+ <para>Connect to the server and synchronise files now</para>
+ </listitem>
+ </itemizedlist>
+
+ <para><emphasis role="bold">bbackupctl</emphasis> communicates with
+ the server via a UNIX domain socket, specified in bbackupd.conf with
+ the CommandSocket directive. This does not need to be specified, and
+ <emphasis role="bold">bbackupd</emphasis> will run without the command
+ socket, but in this case bbackupctl will not be able to communicate
+ with the daemon.</para>
+
+ <para>Some platforms cannot check the user id of the connecting
+ process, so this command socket becomes a denial of service security
+ risk. <emphasis role="bold">bbackupd</emphasis> will warn you when it
+ starts up if this is the case on your platform, and you should
+ consider removing the CommandSocket directive on these
+ platforms.</para>
+ </section>
+
+ <section>
+ <title>Using bbackupctl to perform snapshots</title>
+
+ <para><emphasis role="bold">bbackupctl</emphasis>'s main purpose is to
+ implement snapshot based backups, emulating the behaviour of
+ traditional backup software.</para>
+
+ <para>Use bbackupd-config to write a configuration file in snapshot
+ mode, and then run the following command as a cron job.</para>
+
+ <programlisting>/usr/local/bin/bbackupctl -q sync</programlisting>
+
+ <para>This will cause the backup daemon to upload all changed files
+ immediately. <emphasis role="bold">bbackupctl</emphasis> will exit
+ almost immediately, and will not output anything unless there is an
+ error.</para>
+ </section>
+
+ <section>
+ <title>Checking storage space used on the server</title>
+
+ <section>
+ <title>From the client machine</title>
+
+ <para>bbackupquery can tell you how much space is used on the server
+ for this account. Either use the usage command in interactive mode,
+ or type:</para>
+
+ <programlisting>/usr/local/bin/bbackupquery -q usage quit</programlisting>
+
+ <para>to show the space used as a single command.</para>
+ </section>
+
+ <section>
+ <title>On the server</title>
+
+ <para>bbstoreaccounts allows you to query the space used, and change
+ the limits. To display the space used on the server for an account,
+ use:</para>
+
+ <programlisting>/usr/local/bin/bbstoreaccounts info 75AB23C</programlisting>
+
+ <para>To adjust the soft and hard limits on an account, use:</para>
+
+ <programlisting>/usr/local/bin/bbstoreaccounts setlimit 75AB23C new-soft-limit new-hard-limit</programlisting>
+
+ <para>You do not need to restart the server.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Verify and restore files</title>
+
+ <para>Backups are no use unless you can restore them. The bbackupquery
+ utility does this and more.</para>
+
+ <para>You don't provide any login information to it, as it just picks
+ up the data it needs from /etc/box/bbackupd.conf. You should run it as
+ root so it can find everything it needs.</para>
+
+ <para>Full documentation can be found in the <ulink
+ url="bbackupquery.xml">bbackupquery manual page</ulink>. It follows
+ the model of a command line sftp client quite closely.</para>
+
+ <para>TODO: Link to bbackupquery man-page here.</para>
+
+ <para>On systems where GNU readline is available (by default) it uses
+ that for command line history and editing. Otherwise it falls back to
+ very basic UNIX text entry.</para>
+
+ <para>TODO: Did the readline dependency change to editline?</para>
+
+ <section>
+ <title>Using bbackupquery</title>
+
+ <para>bbackupquery is the tool you use to verify, restore and
+ investigate your backup files with. When invoked, it simply logs
+ into the server using the certificates you have listed in
+ bbackupd.conf.</para>
+
+ <para>After you run bbackupquery, you will see a prompt, allowing
+ you to execute commands. The list (or ls) command lets you view
+ files in the store. It works much like unix ls, but with different
+ options. An example:</para>
+
+ <programlisting>[pthomsen@host bbackupquery]$ bbackupquery
+Box Backup Query Tool v0.10, (c) Ben Summers and contributors 2003-2006
+Using configuration file /etc/box/bbackupd.conf
+Connecting to store...
+Handshake with store...
+Login to store...
+Login complete.
+
+Type "help" for a list of commands.
+
+query &gt; ls
+00000002 -d---- mp3
+00000003 -d---- video
+00000004 -d---- home-pthomsen
+00000005 -d---- root
+query &gt; </programlisting>
+
+ <para>The ls commands shows the directories that are backed up. Now
+ we'll take a closer look at the home-pthomsen directory:</para>
+
+ <programlisting>query &gt; cd home-pthomsen
+query &gt; ls
+00002809 f----- sample.tiff
+0000280a f----- s3.tiff
+0000280b f----- s4.tiff
+0000280d f----- s2.tiff
+0000280e f----- foo.pdf
+0000286c f----- core.28720
+0000339a -d---- .emacs.d
+0000339d -d---- bbackup-contrib
+00003437 f----- calnut.compare.txt
+0000345d f----- DSCN1783.jpg
+0000345e f----- DSCN1782.jpg
+query &gt;</programlisting>
+
+ <para>The ls command takes the following options;</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">-r </emphasis>-- recursively list
+ all files</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">-d</emphasis> -- list deleted
+ files/directories</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">-o</emphasis> -- list old versions
+ of files/directories</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">-I</emphasis> -- don't display
+ object ID</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">-F </emphasis>-- don't display
+ flags</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">-t </emphasis>-- show file
+ modification time (and attr mod time if has the object has
+ attributes, ~ separated)</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">-s</emphasis> -- show file size in
+ blocks used on server (only very approximate indication of size
+ locally)</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The flags displayed from the ls command are as follows:</para>
+
+ <simplelist>
+ <member>f = file</member>
+
+ <member>d = directory</member>
+
+ <member>X = deleted</member>
+
+ <member>o = old version</member>
+
+ <member>R = remove from server as soon as marked deleted or
+ old</member>
+
+ <member>a = has attributes stored in directory record which
+ override attributes in backup file</member>
+ </simplelist>
+ </section>
+
+ <section>
+ <title>Verify backups</title>
+
+ <para>As with any backup system, you should frequently check that
+ your backups are working properly by comparing them. Box Backup
+ makes this very easy and completely automatic. All you have to do is
+ schedule the <command>bbackupquery compare</command> command to run
+ regularly, and check its output. You can run the command manually as
+ follows:</para>
+
+ <programlisting>/usr/local/bin/bbackupquery "compare -a" quit</programlisting>
+
+ <para>This command will report all the differences found between the
+ store and the files on disc. It will download everything, so may
+ take a while. You should expect to see some differences on a typical
+ compare, because files which have recently changed are unlikely to
+ have been uploaded yet. It will also tell you how many files have
+ been modified since the last backup run, since these will normally
+ have changed, and such failures are expected.</para>
+
+ <para>You are strongly recommended to add this command as a
+ <command>cron</command> job, at least once a month, and to check the
+ output for anything suspicious, particularly a large number of
+ compare failures, failures on files that have not been modified, or
+ any error (anything except a compare mismatch) that occurs during
+ the compare operation.</para>
+
+ <para>Consider keeping a record of these messages and comparing them
+ with a future verification.</para>
+
+ <para>If you would like to do a "quick" check which just downloads
+ file checksums and compares against that, then run:</para>
+
+ <programlisting>/usr/local/bin/bbackupquery "compare -aq" quit</programlisting>
+
+ <para>However, this does not check that the file attributes are
+ correct, and since the checksums are generated on the client they
+ may not reflect the data on the server if there is a problem -- the
+ server cannot check the encrypted contents. View this as a quick
+ indication, rather than a definite check that your backup verifies
+ correctly.</para>
+ </section>
+
+ <section>
+ <title>Restore backups</title>
+
+ <para>You will need the keys file created when you configured the
+ server. Without it, you cannot restore the files; this is the
+ downside of encrypted backups. However, by keeping the small keys
+ file safe, you indirectly keep your entire backup safe.</para>
+
+ <para>The first step is to recreate the configuration of the backup
+ client. It's probably best to have stored the /etc/box directory
+ with your keys. But if you're recreating it, all you really need is
+ to have got the login infomation correct (ie the certs and
+ keys).</para>
+
+ <para>Don't run bbackupd yet! It will mark all your files as deleted
+ if you do, which is not hugely bad in terms of losing data, just a
+ major inconvenience. (This assumes that you are working from a blank
+ slate. If you want to restore some files to a different location,
+ it's fine to restore while bbackupd is running, just do it outside a
+ backed up directory to make sure it doesn't start uploading the
+ restored files.)</para>
+
+ <para>Type:</para>
+
+ <programlisting>/usr/local/bin/bbackupquery</programlisting>
+
+ <para>to run it in interactive mode.</para>
+
+ <para>Type:</para>
+
+ <programlisting>list</programlisting>
+
+ <para>to see a list of the locations stored on the server.</para>
+
+ <para>For each location you want to restore, type:</para>
+
+ <programlisting>restore name-on-server local-dir-name</programlisting>
+
+ <para>The directory specified by local-dir-name must not exist yet.
+ If the restore is interrupted for any reason, repeat the above
+ steps, but add the <emphasis role="bold">-r</emphasis> flag to the
+ restore command to tell it to resume.</para>
+ </section>
+
+ <section>
+ <title>Retrieving deleted and old files</title>
+
+ <para>Box Backup makes old versions of files and files you have
+ deleted available, subject to there being enough disc space on the
+ server to hold them.</para>
+
+ <para>This is how to retrieve them using bbackupquery. Future
+ versions will make this far more user-friendly.</para>
+
+ <para>Firstly, run bbackupquery in interactive mode. It behaves in a
+ similar manner to a command line sftp client.</para>
+
+ <programlisting>/usr/local/bin/bbackupquery</programlisting>
+
+ <para>Then navigate to the directory containing the file you want,
+ using list, cd and pwd.</para>
+
+ <programlisting>query &gt; cd home/profiles/USERNAME</programlisting>
+
+ <para>List the directory, using the "o" option to list the files
+ available without filtering out everything apart from the current
+ version. (if you want to see deleted files as well, use list
+ -odt)</para>
+
+ <programlisting>query &gt; list -ot
+00000078 f--o- 2004-01-21T20:17:48 NTUSER.DAT
+00000079 f--o- 2004-01-21T20:17:48 ntuser.dat.LOG
+0000007a f--o- 2004-01-21T17:55:12 ntuser.ini
+0000007b f---- 2004-01-12T15:32:00 ntuser.pol
+0000007c -d--- 1970-01-01T00:00:00 Templates
+00000089 -d--- 1970-01-01T00:00:00 Start Menu
+000000a0 -d--- 1970-01-01T00:00:00 SendTo
+000000a6 -d--- 1970-01-01T00:00:00 Recent
+00000151 -d--- 1970-01-01T00:00:00 PrintHood
+00000152 -d--- 1970-01-01T00:00:00 NetHood
+00000156 -d--- 1970-01-01T00:00:00 My Documents
+0000018d -d--- 1970-01-01T00:00:00 Favorites
+00000215 -d--- 1970-01-01T00:00:00 Desktop
+00000219 -d--- 1970-01-01T00:00:00 Cookies
+0000048b -d--- 1970-01-01T00:00:00 Application Data
+000005da -d--- 1970-01-01T00:00:00 UserData
+0000437e f--o- 2004-01-24T02:45:43 NTUSER.DAT
+0000437f f--o- 2004-01-24T02:45:43 ntuser.dat.LOG
+00004380 f--o- 2004-01-23T17:01:29 ntuser.ini
+00004446 f--o- 2004-01-24T02:45:43 NTUSER.DAT
+00004447 f--o- 2004-01-24T02:45:43 ntuser.dat.LOG
+000045f4 f---- 2004-01-26T15:54:16 NTUSER.DAT
+000045f5 f---- 2004-01-26T15:54:16 ntuser.dat.LOG
+000045f6 f---- 2004-01-26T16:54:31 ntuser.ini</programlisting>
+
+ <para>(this is a listing from a server which is used as a Samba
+ server for a network of Windows clients.) You now need to fetch the
+ file using it's ID, rather than it's name. The ID is the hex number
+ in the first column. Fetch it like this:</para>
+
+ <programlisting>query &gt; get -i 0000437e NTUSER.DAT
+Object ID 0000437e fetched successfully.</programlisting>
+
+ <para>The object is now available on your local machine. You can use
+ lcd to move around, and sh ls to list directories on your local
+ machine.</para>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title id="FixCorruptions">Fixing corruptions of store data</title>
+
+ <para>This section gives help on what to do if your server has suffered
+ corruption, for example, after an unclean shutdown or other operating
+ system or hardware problem.</para>
+
+ <para>In general, as updates to the store are made in an atomic manner,
+ the most likely result is wasted disc space. However, if really bad
+ things happen, or you believe that there is a lot of wasted space, then
+ these instructions will help to restore your data.</para>
+
+ <para>You know you will need to do something if you get strange errors,
+ and bbackupd attempts to contact the server every 100 seconds or so. Or
+ if one of the discs in your RAID disc set has failed.</para>
+
+ <para>After following these instructions, the end result will be that
+ bbackupquery will be able to see all the files which were stored on your
+ server, and retrieve them. Some of them may be in lost+found directories
+ in the root of the store (or in their original position if they have
+ been moved) but they will all be able to be retrieved.</para>
+
+ <para>After you have retrieved the files you want, bbackupd will upload
+ new versions where necessary, and after about two days, mark any
+ lost+found directories as deleted. Finally, those directories will be
+ removed by the housekeeping process on the server.</para>
+
+ <para>These instructions assume you're working on account 1234. Replace
+ this with the account number that you actually want to check (the one
+ that is experiencing errors). These steps will need to be repeated for
+ all affected accounts.</para>
+
+ <section>
+ <title>Stop bbackupd</title>
+
+ <para>First, make sure that bbackupd is not running on the client
+ machine for the account you are going to recover. Use
+ <command>bbackupctl terminate</command> to stop it. This step is not
+ strictly necessary, but is recommended. During any checks on the
+ account, bbackupd will be unable to log in, and after they are
+ complete, the account is marked as changed on the server so bbackupd
+ will perform a complete scan.</para>
+ </section>
+
+ <section>
+ <title>Are you using RAID on the server?</title>
+
+ <para>The raidfile recovery tools have not been written, and probably
+ will not be, since Box Backup RAID is deprecated. However, when two
+ out of three files are available, the server will successfully allow
+ access to your data, even if it complains a lot in the logs. The best
+ thing to do is to fix the accounts, if necessary, and retrieve any
+ files you need. Then move the old store directories aside (in case you
+ need them) and start afresh with new accounts, and let the clients
+ upload all their data again.</para>
+ </section>
+
+ <section>
+ <title>Check and fix the account</title>
+
+ <para>First, run the check utility, and see what errors it
+ reports.</para>
+
+ <programlisting>/usr/local/bin/bbstoreaccounts check 1234</programlisting>
+
+ <para>This will take some time, and use a fair bit of memory (about 16
+ bytes per file and directory). If the output looks plausible and
+ reports errors which need fixing, run it again but with the fix
+ flag:</para>
+
+ <programlisting>/usr/local/bin/bbstoreaccounts check 1234 fix</programlisting>
+
+ <para>This will fix any errors, and remove unrecoverable files.
+ Directories will be recreated if necessary.</para>
+
+ <para><emphasis role="bold">NOTE</emphasis>: The utility may adjust
+ the soft and hard limits on the account to make sure that housekeeping
+ will not remove anything -- check these afterwards.</para>
+ </section>
+
+ <section>
+ <title>Grab any files you need with bbackupquery</title>
+
+ <para>At this point, you will have a working store. Every file which
+ was on the server, and wasn't corrupt, will be available.</para>
+
+ <para>On the client, use bbackupquery to log in and examine the store.
+ (type help at the prompt for instructions). Retrieve any files you
+ need, paying attention to any lost+found directories in the root
+ directory of the store.</para>
+
+ <para>You can skip this step if you are sure that the client machine
+ is fine -- in this case, bbackupd will bring the store up to
+ date.</para>
+ </section>
+
+ <section>
+ <title>Restart bbackupd</title>
+
+ <para>Restart bbackupd on the client machine. The store account will
+ be brought up to date, and files in the wrong place will be marked for
+ eventual deletion.</para>
+ </section>
+ </section>
+
+ <section>
+ <title id="Troubleshooting">Troubleshooting</title>
+
+ <para>If you are trying to fix a store after your disc has been
+ corrupted, see <link linkend="FixCorruptions">Fixing corruptions of
+ store data</link>.</para>
+
+ <para>Unfortunately, the error messages are not particularly helpful at
+ the moment. This page lists some of the common errors, and the most
+ likely causes of them.</para>
+
+ <para>When an error occurs, you will see a message like 'Exception:
+ RaidFile/OSFileError (2/8)' either on the screen or in your log files.
+ (it is recommended you set up another log file as recommended in the
+ server setup instructions.)</para>
+
+ <para>This error may not be particularly helpful, although some do have
+ extra information about probable causes. To get further information,
+ check the ExceptionCodes.txt file in the root of the distribution. This
+ file is generated by the ./configure script, so you will need to have
+ run that first.</para>
+
+ <para>Some common causes of exceptions are listed below.</para>
+
+ <para>Please email me with any other codes you get, and I will let you
+ know what they mean, and add notes here.</para>
+
+ <section>
+ <title>RaidFile (2/8)</title>
+
+ <para>This is found either when running bbstoreaccounts or in the
+ bbstored logs.</para>
+
+ <para><emphasis role="bold">Problem</emphasis>: The directories you
+ specified in the raidfile.conf are not writable by the _bbstored
+ user.</para>
+
+ <para><emphasis role="bold">Resolution</emphasis>: Change permissions
+ appropriately.</para>
+ </section>
+
+ <section>
+ <title>Common (1/2)</title>
+
+ <para>This usually occurs when the configuration files can't be
+ opened.</para>
+
+ <para><emphasis role="bold">Problem</emphasis>: You created your
+ configurations in non-standard locations, and the programs cannot find
+ them.</para>
+
+ <para><emphasis role="bold">Resolution</emphasis>: Explicitly specify
+ configuration file locations to daemons and programs. For
+ example</para>
+
+ <programlisting>/usr/local/bin/bbstored /some/other/dir/bbstored.config /usr/local/bin/bbackupquery -c /some/other/dir/bbackupd.config</programlisting>
+
+ <para>(daemons specify the name as the first argument, utility
+ programs with the -c option).</para>
+
+ <para><emphasis role="bold">Problem</emphasis>: bbstored can't find
+ the raidfile.conf file specified in bbstored.conf.</para>
+
+ <para><emphasis role="bold">Resolution</emphasis>: Edit bbstored.conf
+ to point to the correct location of this additional configuration
+ file.</para>
+ </section>
+
+ <section>
+ <title>Server (3/16)</title>
+
+ <para>The server can't listen for connections on the IP address
+ specified when you configured it.</para>
+
+ <para><emphasis role="bold">Problem</emphasis>: This probably means
+ you've specified the wrong hostname to bbstored-config -- maybe your
+ server is behind a NAT firewall?</para>
+
+ <para><emphasis role="bold">Resolution</emphasis>: Edit bbstored.conf
+ and correct the ListenAddresses line. You should replace the server
+ address with the IP address of your machine.</para>
+ </section>
+
+ <section>
+ <title>Connection (7/x)</title>
+
+ <para>These errors all relate to connections failing -- you may see
+ them during operation if there are network failures or other problems
+ between the client and server. The backup system will recover from
+ them automatically.</para>
+
+ <section>
+ <title>Connection (7/30) - SSL problems</title>
+
+ <para>Log snippet from client side:</para>
+
+ <programlisting>bbackupd[1904]: Opening connection to server xxxx.xxx...
+bbackupd[1904]: SSL err during Connect: error:xxxxxxxx:rsa routines:RSA_padding_check_PKCS1_type_1:block type is not 01
+bbackupd[1904]: SSL err during Connect: error:xxxxxxxx:rsa routines:RSA_EAY_PUBLIC_DECRYPT:padding check failed
+bbackupd[1904]: SSL err during Connect: error:xxxxxxxx:asn1 encoding routines:ASN1_verify:EVP lib
+bbackupd[1904]: SSL err during Connect: error:xxxxxxxx:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
+bbackupd[1904]: TRACE: Exception thrown: ConnectionException(Conn_TLSHandshakeFailed) at SocketStreamTLS.cpp(237)
+bbackupd[1904]: Exception caught (7/30), reset state and waiting to retry...</programlisting>
+
+ <para>And from the server:</para>
+
+ <programlisting>bbstored[19291]: Incoming connection from xx.xxx.xx.xxx port xxxxx (handling in child xxxxx)
+bbstored[21588]: SSL err during Accept: error:xxxxxxxx:SSL routines:SSL3_READ_BYTES:tlsv1 alert decrypt error
+bbstored[21588]: in server child, exception Connection TLSHandshakeFailed (7/30) -- terminating child</programlisting>
+
+ <para><emphasis role="bold">Solution</emphasis>: Create a new CA on
+ the server side and re-generate the client certificate. Re-creating
+ the client certificate request is not necessary.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Advanced troubleshooting</title>
+
+ <para>If this really doesn't help, then using the DEBUG builds of the
+ system will give you much more information -- a more descriptive
+ exception message and the file and line number where the error
+ occurred.</para>
+
+ <para>For example, if you are having problems with bbstoreaccounts,
+ build the debug version with:</para>
+
+ <programlisting>cd boxbackup-0.0
+cd bin/bbstoreaccounts
+make</programlisting>
+
+ <para>Within the module directories, make defaults to building the
+ debug version. At the top level, it defaults to release.</para>
+
+ <para>This will build an executable in debug/bin/bbstoreaccounts which
+ you can then use instead of the release version. It will give far more
+ useful error messages.</para>
+
+ <para>When you get an error message, use the file and line number to
+ locate where the error occurs in the code. There will be comments
+ around that line to explain why the exception happened.</para>
+
+ <para>If you are using a debug version of a daemon, these extended
+ messages are found in the log files.</para>
+ </section>
+ </section>
+ </chapter>
+
+ &__ExceptionCodes__elfjz3fu;
+
+ <appendix>
+ <title id="WORoot">Running without root</title>
+
+ <para>It is possible to run both the server and client without root
+ privileges.</para>
+
+ <section>
+ <title>Server</title>
+
+ <para>The server, by default, runs as a non-root user. However, it
+ expects to be run as root and changes user to a specified user as soon
+ as it can, simply for administrative convenience. The server uses a port
+ greater than 1024, so it doesn't need root to start.</para>
+
+ <para>To run it entirely as a non-root user, edit the bbstored.conf
+ file, and remove the User directive from the Server section. Then simply
+ run the server as your desired user.</para>
+ </section>
+
+ <section>
+ <title>Client</title>
+
+ <para>The client requires root for normal operation, since it must be
+ able to access all files to back them up. However, it is possible to run
+ the client as a non-root user, with certain limitations.</para>
+
+ <para>Follow the installation instructions, but install the executable
+ files manually to somewhere in your home directory. Then use
+ bbackupd-config to configure the daemon, but use a directory other than
+ /etc/box, probably somewhere in your home directory.</para>
+
+ <para>All directories you specify to be backed up must be readable, and
+ all files must be owned by the user and readable to that user.</para>
+
+ <para>Important: If any file or directory is not readable by this user,
+ the backup process will skip that file or directory. Keep an eye on the
+ logs for reports of this failure.</para>
+
+ <para>Non-root operation of the backup client is recommended only for
+ testing, and should not be relied on in a production environment.</para>
+ </section>
+ </appendix>
+</book>
diff --git a/boxbackup/bb-book.xsl b/boxbackup/bb-book.xsl
new file mode 100644
index 00000000..a4f05fdb
--- /dev/null
+++ b/boxbackup/bb-book.xsl
@@ -0,0 +1,17 @@
+<?xml version='1.0'?>
+<xsl:stylesheet
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/>
+
+<xsl:param name="html.stylesheet" select="'../bbdoc.css'"/>
+<xsl:param name="chunk.section.depth" select="'0'"/>
+<xsl:template name="user.header.navigation">
+<div id="header">
+<div id="logo">
+<img src="../images/bblogo.png" alt="logo" height="65" width="331" border="0" vspace="5" align="middle" /> <img src="../images/stepahead.png" alt="a step ahead in data security" width="182" height="11" hspace="10" vspace="20" border="0" align="middle" /></div>
+</div>
+</xsl:template>
+
+
+</xsl:stylesheet>
diff --git a/boxbackup/bb-man.xsl b/boxbackup/bb-man.xsl
new file mode 100644
index 00000000..24d99381
--- /dev/null
+++ b/boxbackup/bb-man.xsl
@@ -0,0 +1,9 @@
+<?xml version='1.0'?>
+<xsl:stylesheet
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"/>
+
+<xsl:param name="chunk.section.depth" select="'0'"/>
+
+</xsl:stylesheet>
diff --git a/boxbackup/bb-nochunk-book.xsl b/boxbackup/bb-nochunk-book.xsl
new file mode 100644
index 00000000..86574122
--- /dev/null
+++ b/boxbackup/bb-nochunk-book.xsl
@@ -0,0 +1,17 @@
+<?xml version='1.0'?>
+<xsl:stylesheet
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/>
+
+<xsl:param name="html.stylesheet" select="'../bbdoc-man.css'"/>
+<xsl:param name="chunk.section.depth" select="'0'"/>
+<xsl:template name="user.header.content">
+<div id="header">
+<div id="logo">
+<img src="../images/bblogo.png" alt="logo" height="65" width="331" border="0" vspace="5" align="middle" /> <img src="../images/stepahead.png" alt="a step ahead in data security" width="182" height="11" hspace="10" vspace="20" border="0" align="middle" /></div>
+</div>
+</xsl:template>
+
+
+</xsl:stylesheet>
diff --git a/boxbackup/bbackupctl.xml b/boxbackup/bbackupctl.xml
new file mode 100644
index 00000000..09085be8
--- /dev/null
+++ b/boxbackup/bbackupctl.xml
@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry>
+ <refmeta>
+ <refentrytitle>bbackupctl</refentrytitle>
+
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>bbackupctl</refname>
+
+ <refpurpose>Control the bbackupd daemon </refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>bbackupctl [-q] [-c config-file] command</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para><literal>bbackupctl</literal> lets the user control the bbackupd
+ daemon on a client machine. The main use is to force a sync with the store
+ server. This is especially important if bbackupd(1) is configured to do
+ snapshot backups. In that case <literal>bbackupctl</literal> is the only
+ way to effect a backup.</para>
+
+ <para>Communication with the bbackupd daemon takes place over a local
+ socket. Some platforms (notably Windows) can't determine if the user
+ connecting on this socket has the correct credentials to execute the
+ commands, leaving a rather sizeable security hole open. To avoid this,
+ unset the CommandSocket parameter in <literal>bbackupd.conf</literal>(8).
+ That disables the command socket, so bbackupd is secure. This does,
+ however, render bbackupctl unusable.</para>
+
+ <refsection>
+ <title>Options</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>-q -- quiet. Do not output status messages.</para>
+ </listitem>
+
+ <listitem>
+ <para>-c config_file -- Use a different config file from the default
+ one. Can be a full or a relative path.</para>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+
+ <refsection>
+ <title>Commands</title>
+
+ <para>The following commands are available in bbackupctl:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>terminate</literal></para>
+
+ <para>This command stops the bbackupd server. This is the equivalent
+ of killing (kill -KILL) the bbackupd process.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>reload</literal></para>
+
+ <para>Causes the bbackupd daemon to re-read all its configuration
+ files. Equivalent to kill -HUP.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>sync</literal></para>
+
+ <para>Initiates a backup to the store of whatever needs to be backed
+ up.</para>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+ </refsection>
+
+ <refsection>
+ <title>Author</title>
+
+ <para>Ben Summers and contributors. For help, please go to the <ulink
+ url="http://www.boxbackup.org/trac/">Wiki</ulink>, or subscribe to the Box
+ Backup <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list.</ulink></para>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+
+ <para><literal>bbackupd.conf(8)</literal></para>
+
+ <para>bbackupd(1)</para>
+ </refsection>
+
+ <refsection>
+ <title>Files</title>
+
+ <para><literal>bbackupctl</literal> uses the Box Backup client
+ configuration file, usually located in
+ <filename>/etc/box/bbackupd.conf</filename>. On Windows this file is
+ usually located in the installation directory, and is named
+ <filename>bbackupd.conf</filename> as well.</para>
+ </refsection>
+
+ <refsection>
+ <title>Bugs</title>
+
+ <para>If you find a bug in Box Backup, and you want to let us know about
+ it, join the <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list</ulink>, and send a description of the problem there.</para>
+
+ <para>To report a bug, give us at least the following information:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The version of Box Backup you are running</para>
+ </listitem>
+
+ <listitem>
+ <para>The platform you are running on (Hardware and OS), for both
+ client and server.</para>
+ </listitem>
+
+ <listitem>
+ <para>If possible attach your config files (bbstored.conf,
+ bbackupd.conf) to the bug report.</para>
+ </listitem>
+
+ <listitem>
+ <para>Also attach any log file output that helps shed light on the
+ problem you are seeing.</para>
+ </listitem>
+
+ <listitem>
+ <para>And last but certainly not least, a description of what you are
+ seeing, in as much detail as possible.</para>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+</refentry>
diff --git a/boxbackup/bbackupquery.xml b/boxbackup/bbackupquery.xml
new file mode 100644
index 00000000..2902c189
--- /dev/null
+++ b/boxbackup/bbackupquery.xml
@@ -0,0 +1,380 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry>
+ <refmeta>
+ <refentrytitle>bbackupquery</refentrytitle>
+
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>bbackupquery</refname>
+
+ <refpurpose>Box Backup store query and retrieval</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>bbackupquery [-q] [-c configfile] [commands ...]</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para><literal>bbackupquery</literal> is the main way of interacting with
+ the backup store from a Box Backup client machine. It supports both
+ interactive and batch modes of operation.</para>
+
+ <para>It can be used to reviewing the status of a client machine's backup
+ store, getting status from the store server. The main use is to retrieve
+ files and directories when needed.</para>
+
+ <para><literal>bbackupquery</literal> supports interactive and batch modes
+ of operation. Interactive mode allows for interaction with the server much
+ like an interactive FTP client.</para>
+
+ <para>Batch mode is invoked by putting commands into the invocation of
+ bbackupquery. Example:</para>
+
+ <programlisting>bbackupquery "list home-dirs" quit</programlisting>
+
+ <para>Note that commands that contain spaces are enclosed in double
+ quotes. If the <literal>quit</literal> command is ommitted, after the
+ preceding commands are completed, <literal>bbackupquery</literal> will
+ enter interactive mode.</para>
+
+ <para><emphasis role="bold">Options</emphasis></para>
+
+ <para><emphasis>-q: Quiet. Suppresses status output while
+ running.</emphasis></para>
+
+ <para><emphasis>-c configfile: Use config file, instead of the default
+ bbackupd.conf file. Can be a relative or full path.</emphasis></para>
+
+ <refsection>
+ <title>Commands</title>
+
+ <para>The commands that can be used in <literal>bbackupquery</literal>
+ are listed below.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>help</literal></para>
+
+ <para>Displays the basic help message, which gives information about
+ the commands available in bbackupquery. Use the form <literal>help
+ command</literal>, to get help on a specific command.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>quit</literal></para>
+
+ <para>End the session with the store server, and quit
+ <literal>bbackupquery</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>cd [options] &lt;directory-name&gt;</literal></para>
+
+ <para>Change directory. Options:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>-d</literal> -- consider deleted directories for
+ traversal</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-o</literal> -- consider old versions of
+ directories for traversal. This option should never be useful in
+ a correctly formed store.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para><literal>lcd &lt;local-directory-name&gt;</literal></para>
+
+ <para>Change directory on the client machine. To list the contents
+ of the local directory, type <literal>sh ls</literal> (on unix-like
+ machines). TODO: Does <literal>sh dir</literal> work on
+ Windows?</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>list [options] [directory-name]</literal></para>
+
+ <para>The <literal>list</literal> (or its synonym
+ <literal>ls</literal>) command lists the content of the current, or
+ specified, directory. The options are as follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>-r</literal> -- recursively list all files</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-d</literal> -- list deleted files and
+ directories</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-o</literal> -- list old versions of files and
+ directories</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-I</literal> -- don't display object IDs</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-F</literal> -- don't display flags</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-t</literal> -- show file modification time (and
+ attr mod time, if the object has attributes.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-s</literal> -- show file size in blocks used on
+ server. Note that this is only a very approximate indication of
+ local file size.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para><literal>ls [options] [directory-name]</literal></para>
+
+ <para>Synonym for <literal>list</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal><literal>pwd</literal></literal></para>
+
+ <para>Print current directory, always relative to the backup store
+ root.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>sh &lt;shell command&gt;</literal></para>
+
+ <para>Everything after the sh is passed to a shell and run. All
+ output from the command is displayed in the client.</para>
+
+ <para>Example: to list the contents of the current directory on the
+ client machine type <literal>sh ls</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>compare -a</literal></para>
+
+ <para><literal>compare -l &lt;location-name&gt;</literal></para>
+
+ <para><literal>compare &lt;store-dir-name&gt;
+ &lt;local-dir-name&gt;</literal></para>
+
+ <para>Compare the current data in the store with the data on the
+ disc. Please note that all the data will be downloaded from the
+ store, so this can be a very lengthy process depending on the size
+ of the store, and the size of the part you are comparing.</para>
+
+ <para>Options:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>-a</literal> -- compare all locations. </para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-l</literal> -- compare one backup location as
+ specified in the configuration file. This compares one of the
+ top level store directories.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-c</literal> -- set return code. The return code
+ is set to the following values, if <literal>quit</literal> is
+ the next command. So, if another command is run after the
+ <literal>compare</literal>, the return code will not refer to
+ the <literal>compare</literal>. This option is very useful for
+ automating compares. Return code values:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>1 -- no differences were found</para>
+ </listitem>
+
+ <listitem>
+ <para>2 -- differences were found</para>
+ </listitem>
+
+ <listitem>
+ <para>3 -- an error occured</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para><literal>get &lt;object-filename&gt;
+ [&lt;local-filename&gt;]</literal></para>
+
+ <para><literal>get -i &lt;object-id&gt;
+ &lt;local-filename&gt;</literal></para>
+
+ <para>Gets a file from the store. Object is specified as the
+ filename within the current directory. Local filename is optional.
+ Ignores old and deleted files when searching the directory for the
+ file to retrieve.</para>
+
+ <para>To get an old or deleted file, use the <literal>-i</literal>
+ option and select the object as a hex object ID (first column in
+ listing). The local filename must be specified.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>getobject &lt;object-id&gt;
+ &lt;local-filename&gt;</literal></para>
+
+ <para>Gets the object specified by the object id (in hex) and stores
+ the raw contents in the local file specified. <emphasis
+ role="bold">Note</emphasis>: This is only useful for debugging as it
+ does not decode files from the stored format, which is encrypted and
+ compressed.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>restore [-d] &lt;directory-name&gt;
+ &lt;local-directory-name&gt;</literal></para>
+
+ <para><literal>restore -r</literal></para>
+
+ <para>Restores a directory to the local disc. The local directory
+ specified must not exist (unless a previous restore is being
+ restarted). The root cannot be restored -- restore locations
+ individually. </para>
+
+ <para>Options:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>-d</literal> -- restore a deleted
+ directory</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-r</literal> -- resume an interrupted
+ restore</para>
+ </listitem>
+ </itemizedlist>
+
+ <para> If a restore operation is interrupted for any reason, it can
+ be restarted using the <literal>-r</literal> switch. Restore
+ progress information is saved in a file at regular intervals during
+ the restore operation to allow restarts.</para>
+ </listitem>
+
+ <listitem>
+ <para>usage</para>
+
+ <para>Show space used on the server for this account. Display
+ fields:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>Used</literal>: Total amount of space used on the
+ server</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Old files</literal>: Space used by old
+ files</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Deleted files</literal>: Space used by deleted
+ files</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Directories</literal>: Space used by the
+ directory structure</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>When Used exceeds the soft limit, the server will start to
+ remove old and deleted files until the usage drops below the soft
+ limit. After a while, you should expect to see the usage stay at
+ just below the soft limit. You only need more space if the space
+ used by old and deleted files is near zero.</para>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+ </refsection>
+
+ <refsection>
+ <title>Author</title>
+
+ <para>Ben Summers and contributors. For help, please go to the <ulink
+ url="http://www.boxbackup.org/trac/">Wiki</ulink>, or subscribe to the Box
+ Backup <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list.</ulink></para>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+
+ <para>bbackupd.conf(8)</para>
+ </refsection>
+
+ <refsection>
+ <title>Files</title>
+
+ <para><literal>bbackupquery</literal> uses the Box Backup client
+ configuration file, usually located in
+ <filename>/etc/box/bbackupd.conf</filename>. On Windows this file is
+ usually located in the installation directory, and is named
+ <filename>bbackupd.conf</filename> as well.</para>
+ </refsection>
+
+ <refsection>
+ <title>Bugs</title>
+
+ <para>If you find a bug in Box Backup, and you want to let us know about
+ it, join the <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list</ulink>, and send a description of the problem there.</para>
+
+ <para>To report a bug, give us at least the following information:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The version of Box Backup you are running</para>
+ </listitem>
+
+ <listitem>
+ <para>The platform you are running on (Hardware and OS), for both
+ client and server.</para>
+ </listitem>
+
+ <listitem>
+ <para>If possible attach your config files (bbstored.conf,
+ bbackupd.conf) to the bug report.</para>
+ </listitem>
+
+ <listitem>
+ <para>Also attach any log file output that helps shed light on the
+ problem you are seeing.</para>
+ </listitem>
+
+ <listitem>
+ <para>And last but certainly not least, a description of what you are
+ seeing, in as much detail as possible.</para>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+</refentry>
diff --git a/boxbackup/bbstoreaccounts.xml b/boxbackup/bbstoreaccounts.xml
new file mode 100644
index 00000000..8ff3be0d
--- /dev/null
+++ b/boxbackup/bbstoreaccounts.xml
@@ -0,0 +1,290 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry>
+ <refmeta>
+ <refentrytitle>bbstoreaccounts</refentrytitle>
+
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>bbstoreaccounts</refname>
+
+ <refpurpose>View and change account information on the store
+ server</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>bbstoreaccounts [-c configfile] command account_id
+ [command-specific arguments]</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para><literal>bbstoreaccounts</literal> is the tool for managing accounts
+ on the store server. It can be used to view information related to
+ accounts, as well as create, change and delete accounts on the store
+ server. </para>
+
+ <para><literal>bbstoreaccounts</literal> alwas takes at least 2
+ parameters: the command name and the account ID. Some commands require
+ additional parameters, and some commands have optional parameters.</para>
+
+ <refsection>
+ <title>Options</title>
+
+ <para><literal>-c &lt;configfile&gt;</literal></para>
+
+ <para>The configfile to use for connecting to the store. Default is
+ <literal>/etc/box/bbstored.conf</literal>.</para>
+ </refsection>
+
+ <refsection>
+ <title>Commands</title>
+
+ <para>The commands tells bbstoreaccounts what action to perform.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>check &lt;account-id&gt; [fix]</literal></para>
+
+ <para>The <literal>check</literal> command verifies the integrity of
+ the store account given, and optionally fixes any corruptions.
+ <emphasis role="bold">Note</emphasis>: It is recommended to run the
+ 'simple' check command (without <literal>fix</literal>) before using
+ the <literal>fix</literal> option, This gives an overview of the
+ extent of any problems, before attempting to fix them.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>create &lt;account-id&gt; &lt;discset&gt;
+ &lt;softlimit&gt; &lt;hardlimit&gt;</literal></para>
+
+ <para>Creates a new store account with the parameters given. The
+ parameters are as follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>account-id</literal>: the ID of the new account
+ to be created. A 32-bit hexadecimal number. Cannot already exist
+ on the server.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>discset</literal>: the disc set from
+ raidfile.conf(5) where the backups for this client will be
+ stored.. A number. Each RAID-file set has a number in
+ raidfile.conf. This number is what's used.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>softlimit</literal>: The soft limit is the amount
+ of storage that the server will guarantee to be available for
+ storage.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>hardlimit</literal>: The amount of storage that
+ the the server will allow, before rejecting uploads, and
+ starting to eliminate old and deleted files to get back down to
+ <literal>softlimit</literal>. </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para><literal>delete &lt;account-id&gt; [yes]</literal></para>
+
+ <para>Deletes the account from the store server completely. Removes
+ all backups and deletes all references to the account in the config
+ files.</para>
+
+ <para><literal>delete</literal> will ask for confirmation from the
+ user, when called. Using the <literal>yes</literal> flag, eliminates
+ that need. This is useful when deleting accounts from within a
+ script or some other automated means.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>info &lt;account-id&gt;</literal></para>
+
+ <para>Display information about the given account. Example:</para>
+
+ <programlisting>[root]# bbstoreaccounts info 1
+ Account ID: 00000001
+ Last object ID: 58757
+ Blocks used: 9864063 (38531.50Mb)
+ Blocks used by old files: 62058 (242.41Mb)
+Blocks used by deleted files: 34025 (132.91Mb)
+ Blocks used by directories: 6679 (26.09Mb)
+ Block soft limit: 11796480 (46080.00Mb)
+ Block hard limit: 13107200 (51200.00Mb)
+ Client store marker: 1139559852000000 </programlisting>
+
+ <para>Explanation:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Account ID: The account ID being displayed.</para>
+ </listitem>
+
+ <listitem>
+ <para>Last Object ID: A counter that keeps track of the objects
+ that have been backed up. This number refers to the last file
+ that was written to the store. The ID is displayed as a decimal
+ number, and the object ID can be converted to a path name to a
+ file as follows: convert the number to hex (e.g.: 58757 =&gt;
+ 0xE585); The last backed up file will be (relative from the
+ client's store root): <literal>e5/o85.rfw</literal>. Longer
+ numbers infer more directories in the structure, so as an
+ example 3952697264 as the last object ID gives 0xEB995FB0, which
+ translates to a backup pathname of
+ <literal>eb/99/5f/ob0.rfw.</literal></para>
+ </listitem>
+
+ <listitem>
+ <para>Blocks used: The number of blocks used by the store. The
+ size in Mb depends on the number of blocks, as well as the block
+ size for the disc set given in
+ <literal>raidfile.conf(5)</literal>. In this case the block size
+ is 4096.</para>
+ </listitem>
+
+ <listitem>
+ <para>Blocks used by old files: The number of blocks occupied by
+ files that have newer versions in the store. This data is at
+ risk for being removed during housekeeping.</para>
+ </listitem>
+
+ <listitem>
+ <para>Blocks used by deleted files: The number of blocks used by
+ files that have been deleted on the client. Thi s data is at
+ risk for being removed during housekeeping.</para>
+ </listitem>
+
+ <listitem>
+ <para>Blocks used by directories: The number of blocks used by
+ directories in the store.</para>
+ </listitem>
+
+ <listitem>
+ <para>Block soft limit: The soft limit in blocks. The soft limit
+ is the maximum guaranteed storage space available to the
+ account. When housekeeping starts, and the old and deleted files
+ are removed, they are removed in chronological order (oldest
+ first), until the data used is less than the soft limit.</para>
+ </listitem>
+
+ <listitem>
+ <para>Block hard limit: The hard limit in blocks. The hard limit
+ is the most amount of storage the server will allow in an
+ account. Any data above this amount will be rejected.
+ Housekeeping will reduce the storage use, so more data can be
+ uploaded.</para>
+ </listitem>
+
+ <listitem>
+ <para>Client store marker: TODO What exactly is this? </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para><literal>setlimit &lt;account-id&gt; &lt;softlimit&gt;
+ &lt;hardlimit&gt;</literal></para>
+
+ <para>Changes the storage space allocation for the given account. No
+ server restart is needed.</para>
+
+ <para>Parameters:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>account-id</literal>: the ID of the new account
+ to be created. A 32-bit hexadecimal number. Cannot already exist
+ on the server.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>softlimit</literal>: The soft limit is the amount
+ of storage that the server will guarantee to be available for
+ storage.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>hardlimit</literal>: The amount of storage that
+ the the server will allow, before rejecting uploads, and
+ starting to eliminate old and deleted files to get back down to
+ <literal>softlimit</literal>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+ </refsection>
+
+ <refsection>
+ <title>Author</title>
+
+ <para>Ben Summers and contributors. For help, please go to the <ulink
+ url="http://www.boxbackup.org/trac/">Wiki</ulink>, or subscribe to the Box
+ Backup <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list.</ulink></para>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+
+ <para><literal>bbstored.conf(5)</literal></para>
+
+ <para><literal>raidfile.conf(5)</literal></para>
+ </refsection>
+
+ <refsection>
+ <title>Files</title>
+
+ <para><literal>bbstoreaccounts</literal> uses the Box Backup server
+ configuration file, usually located in
+ <filename>/etc/box/bbstored.conf</filename>. </para>
+ </refsection>
+
+ <refsection>
+ <title>Bugs</title>
+
+ <para>If you find a bug in Box Backup, and you want to let us know about
+ it, join the <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list</ulink>, and send a description of the problem there.</para>
+
+ <para>To report a bug, give us at least the following information:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The version of Box Backup you are running</para>
+ </listitem>
+
+ <listitem>
+ <para>The platform you are running on (Hardware and OS), for both
+ client and server.</para>
+ </listitem>
+
+ <listitem>
+ <para>If possible attach your config files (bbstored.conf,
+ bbackupd.conf) to the bug report.</para>
+ </listitem>
+
+ <listitem>
+ <para>Also attach any log file output that helps shed light on the
+ problem you are seeing.</para>
+ </listitem>
+
+ <listitem>
+ <para>And last but certainly not least, a description of what you are
+ seeing, in as much detail as possible.</para>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+</refentry>
diff --git a/boxbackup/bbstored-certs.xml b/boxbackup/bbstored-certs.xml
new file mode 100644
index 00000000..05d3f852
--- /dev/null
+++ b/boxbackup/bbstored-certs.xml
@@ -0,0 +1,125 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry>
+ <refmeta>
+ <refentrytitle>bbstored-certs</refentrytitle>
+
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>bbstored-certs</refname>
+
+ <refpurpose>Manage certificates for the Box Backup system</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>bbstored-certs &lt;certs-dir&gt; &lt;command&gt;
+ [&lt;arguments&gt;]</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para><literal>bbstored-certs</literal> creates and signs certificates for
+ use in Box Backup. It allows the user to create and sign the server keys,
+ as well as signing client keys.</para>
+
+ <para>All commands must be followed by the <literal>certs-dir</literal>,
+ which is the directory in which the certificates are stored.</para>
+
+ <refsection>
+ <title>Commands</title>
+
+ <para>There are 3 commands:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>init</literal>: Create the
+ <literal>certs-dir</literal>, and generate the server keys for
+ bbstored. <literal>certs-dir</literal> cannot exist before running
+ the command.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>sign-server &lt;servercsrfile&gt;</literal>: Sign the
+ server certificate. The <literal>servercsrfile</literal> is the file
+ generated by the <literal>init</literal> command.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>sign &lt;clientcsrfile&gt;</literal>: Sign a client
+ certificate. The <literal>clientcsrfile</literal> is generated
+ during client setup. See <literal>bbackupd-config(1)</literal>. Send
+ the signed certificate back to the client, and install according to
+ the instructions given by <literal>bbackupd-config</literal>.</para>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+ </refsection>
+
+ <refsection>
+ <title>Author</title>
+
+ <para>Ben Summers and contributors. For help, please go to the <ulink
+ url="http://www.boxbackup.org/trac/">Wiki</ulink>, or subscribe to the Box
+ Backup <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list.</ulink></para>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+
+ <para><literal>bbstored-config(1)</literal></para>
+
+ <para><literal>bbstored.conf(5)</literal></para>
+
+ <para><literal>bbstoreaccounts(1)</literal></para>
+ </refsection>
+
+ <refsection>
+ <title>Files</title>
+
+ <para><literal>raidfile-config</literal> generates the raidfile.conf(5)
+ file.</para>
+ </refsection>
+
+ <refsection>
+ <title>Bugs</title>
+
+ <para>If you find a bug in Box Backup, and you want to let us know about
+ it, join the <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list</ulink>, and send a description of the problem there.</para>
+
+ <para>To report a bug, give us at least the following information:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The version of Box Backup you are running</para>
+ </listitem>
+
+ <listitem>
+ <para>The platform you are running on (Hardware and OS), for both
+ client and server.</para>
+ </listitem>
+
+ <listitem>
+ <para>If possible attach your config files (bbstored.conf,
+ bbackupd.conf) to the bug report.</para>
+ </listitem>
+
+ <listitem>
+ <para>Also attach any log file output that helps shed light on the
+ problem you are seeing.</para>
+ </listitem>
+
+ <listitem>
+ <para>And last but certainly not least, a description of what you are
+ seeing, in as much detail as possible.</para>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+</refentry>
diff --git a/boxbackup/bbstored-config.xml b/boxbackup/bbstored-config.xml
new file mode 100644
index 00000000..b7658782
--- /dev/null
+++ b/boxbackup/bbstored-config.xml
@@ -0,0 +1,140 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry>
+ <refmeta>
+ <refentrytitle>bbstored-config</refentrytitle>
+
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>bbstored-config</refname>
+
+ <refpurpose>Create config files for bbstored</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>bbstored-config &lt;configdir&gt; &lt;servername&gt;
+ &lt;username&gt;</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>The <literal>bbstored-config</literal> script creates config files
+ and server certificates for a bbstored instance. It takes three
+ parameters:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>configdir</literal>: The directory where config files
+ will reside. A subdirectory bbstored will be created, where several
+ config files will reside. the <literal>bbstored.conf</literal> file
+ will be created in <literal>configdir</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>servername</literal>: The name of the server that is
+ being configured. Usually the fully qualified domain name of the
+ machine in question.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>username</literal>: The name of the user that should be
+ running the bbstored processes. Recommended name:
+ _<literal>bbstored.</literal></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>A valid raidfile.conf(5) must be found in configdir. Several steps
+ are taken during the run of bbstored-config:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Configuration files are created.</para>
+ </listitem>
+
+ <listitem>
+ <para>Server certificates are created. This requires interaction from
+ the operator.</para>
+ </listitem>
+
+ <listitem>
+ <para>The raid volumes are checked, to ensure that the configuration
+ is consistent, and will work.</para>
+ </listitem>
+
+ <listitem>
+ <para>Instructions for next steps to take are shown. These steps may
+ be different for different OS platforms, so pay close attention to
+ these instructions.</para>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+
+ <refsection>
+ <title>Author</title>
+
+ <para>Ben Summers and contributors. For help, please go to the <ulink
+ url="http://www.boxbackup.org/trac/">Wiki</ulink>, or subscribe to the Box
+ Backup <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list.</ulink></para>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+
+ <para><literal>raidfile-config(1)</literal></para>
+
+ <para><literal>bbstored.conf(5)</literal></para>
+
+ <para><literal>raidfile.conf(5)</literal></para>
+ </refsection>
+
+ <refsection>
+ <title>Files</title>
+
+ <para><literal>bbstoreaccounts</literal> uses the Box Backup server
+ configuration file, usually located in
+ <filename>/etc/box/bbstored.conf</filename>.</para>
+ </refsection>
+
+ <refsection>
+ <title>Bugs</title>
+
+ <para>If you find a bug in Box Backup, and you want to let us know about
+ it, join the <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list</ulink>, and send a description of the problem there.</para>
+
+ <para>To report a bug, give us at least the following information:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The version of Box Backup you are running</para>
+ </listitem>
+
+ <listitem>
+ <para>The platform you are running on (Hardware and OS), for both
+ client and server.</para>
+ </listitem>
+
+ <listitem>
+ <para>If possible attach your config files (bbstored.conf,
+ bbackupd.conf) to the bug report.</para>
+ </listitem>
+
+ <listitem>
+ <para>Also attach any log file output that helps shed light on the
+ problem you are seeing.</para>
+ </listitem>
+
+ <listitem>
+ <para>And last but certainly not least, a description of what you are
+ seeing, in as much detail as possible.</para>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+</refentry>
diff --git a/boxbackup/generate_except_xml.pl b/boxbackup/generate_except_xml.pl
new file mode 100644
index 00000000..9046d5cf
--- /dev/null
+++ b/boxbackup/generate_except_xml.pl
@@ -0,0 +1,74 @@
+#!/usr/bin/perl -w
+use strict;
+
+open (EXCEPT, "<../../ExceptionCodes.txt") or die "Can't open ../../ExceptionCodes.txt: $!\n";
+open (DOCBOOK, ">ExceptionCodes.xml") or die "Can't open Exceptioncodes.xml for writing: $!\n";
+
+print DOCBOOK <<EOD;
+<?xml version="1.0" encoding="UTF-8"?>
+
+<appendix>
+ <title>Exception codes</title>
+
+EOD
+my $sectionName;
+my $sectionNum;
+my $sectionDesc;
+my $exceptionCode;
+my $exceptionShortDesc;
+my $exceptionLongDesc;
+while(<EXCEPT>)
+{
+ next if(m/^#/);
+ chomp;
+ if(m/^EXCEPTION TYPE (\w+) (\d+)/)
+ {
+ $sectionName = ucfirst(lc($1));
+ $sectionNum = $2;
+ if($sectionName ne "Common")
+ {
+ $sectionDesc = "the " . $sectionName;
+ }
+ else
+ {
+ $sectionDesc = "any";
+ }
+ print DOCBOOK <<EOD;
+ <section>
+ <title>$sectionName Exceptions ($sectionNum)</title>
+
+ <para>These are exceptions that can occur in $sectionDesc module
+ of the system.</para>
+
+ <itemizedlist>
+EOD
+ }
+
+ # The END TYPE line
+ if(m/^END TYPE$/)
+ {
+ print DOCBOOK " </itemizedlist>\n </section>\n";
+ }
+
+ # The actual exceptions
+ if(m/(\(\d+\/\d+\)) - (\w+ \w+)(?: - )?(.*)$/)
+ {
+ $exceptionCode = $1;
+ $exceptionShortDesc = $2;
+ $exceptionLongDesc = $3;
+
+ print DOCBOOK " <listitem>\n <para><emphasis role=\"bold\">";
+ print DOCBOOK $exceptionCode . ": " . $exceptionShortDesc . "</emphasis>";
+ if($exceptionLongDesc ne "")
+ {
+ print DOCBOOK " -- " . $exceptionLongDesc;
+ }
+ print DOCBOOK "</para>\n </listitem>\n";
+ }
+}
+
+print DOCBOOK "</appendix>\n";
+
+close EXCEPT;
+close DOCBOOK;
+ \ No newline at end of file
diff --git a/boxbackup/html/bbdoc-man.css b/boxbackup/html/bbdoc-man.css
new file mode 100644
index 00000000..0345560e
--- /dev/null
+++ b/boxbackup/html/bbdoc-man.css
@@ -0,0 +1,104 @@
+body {
+ font-family: Verdana, Geneva, Arial, sans-serif;
+ background-color: #edeef3;
+ font-size: .75em;
+ line-height: 180%;
+ text-align: left;
+ margin-top: 20px;
+ margin-right: 100px;
+ margin-left: 250px;
+ position: relative;
+ width: auto; }
+
+table {
+ font-family: Verdana, Geneva, Arial, sans-serif;
+ background-color: #edeef3;
+ font-size: 10pt;
+ line-height: 100%; }
+
+
+code {
+ font-size: 11pt; }
+
+
+
+div.navheader {
+ font-family: Verdana, Geneva, Arial, sans-serif;
+ background-color: #edeef3;
+ line-height: 100%; }
+
+#header {
+ background-color: #e4e6ed;
+ text-align: left;
+ padding-top: 10px;
+ margin-right: -100px;
+ margin-left: -250px;
+ top: 20px;
+ border-top: 1px solid #c4c4d5;
+ border-bottom: 1px solid white }
+
+#logo {
+ position: relative;
+ margin-left: 200px }
+
+
+#page {
+ font-size: .75em;
+ line-height: 180%;
+ text-align: left;
+ margin-top: 50px;
+ margin-right: 100px;
+ margin-left: 250px;
+ position: relative;
+ width: auto }
+
+#disc { }
+
+.informaltable td,tr {font-size: 1em;
+ line-height: 140%;
+ text-align: left;
+ background-color: #e4e6ed;
+ padding: 4px }
+
+tr,td {font-size: 1em;
+ line-height: 100%;
+ background-color: #edeef3; }
+
+pre, tt { font-size: 1.3em;
+ color: #088;
+ letter-spacing: 1px;
+ word-spacing: 2px}
+
+h1 {
+ color: #c00;
+ font-size: 16pt;
+ margin-bottom: 2em;
+ margin-left: -50px }
+
+h2 {
+ color: #324e95;
+ font-size: 12pt;
+ margin-top: 2em;
+ margin-left: -50px }
+
+h3 {
+ color: #324e95;
+ font-size: 10pt;
+ margin-top: 2em;
+ margin-left: -50px }
+
+dt { font-weight: bold }
+
+a:link {
+ color: #324e95;
+ text-decoration: none;
+ background-color: transparent }
+
+a:visited {
+ color: #90c;
+ text-decoration: none }
+
+a:hover {
+ color: #c00;
+ text-decoration: underline;
+ background-color: transparent }
diff --git a/boxbackup/html/bbdoc.css b/boxbackup/html/bbdoc.css
new file mode 100644
index 00000000..d3b4a1c2
--- /dev/null
+++ b/boxbackup/html/bbdoc.css
@@ -0,0 +1,112 @@
+body {
+ font-family: Verdana, Geneva, Arial, sans-serif;
+ background-color: #edeef3;
+ font-size: .75em;
+ line-height: 180%;
+ text-align: left;
+ margin-top: 20px;
+ margin-right: 100px;
+ margin-left: 250px;
+ position: relative;
+ width: auto; }
+
+table {
+ font-family: Verdana, Geneva, Arial, sans-serif;
+ background-color: #edeef3;
+ font-size: 10pt;
+ line-height: 100%; }
+
+
+
+
+div.navheader {
+ font-family: Verdana, Geneva, Arial, sans-serif;
+ background-color: #edeef3;
+ line-height: 100%; }
+
+#header {
+ background-color: #e4e6ed;
+ text-align: left;
+ padding-top: 10px;
+ margin-right: -100px;
+ margin-left: -250px;
+ top: 20px;
+ border-top: 1px solid #c4c4d5;
+ border-bottom: 1px solid white }
+
+#logo {
+ position: relative;
+ margin-left: 200px }
+
+
+#page {
+ font-size: .75em;
+ line-height: 180%;
+ text-align: left;
+ margin-top: 50px;
+ margin-right: 100px;
+ margin-left: 250px;
+ position: relative;
+ width: auto }
+
+#disc { }
+
+.informaltable td,tr {font-size: 1em;
+ line-height: 140%;
+ text-align: left;
+ background-color: #e4e6ed;
+ padding: 4px }
+
+tr,td {font-size: 1em;
+ line-height: 100%;
+ background-color: #edeef3; }
+
+pre, tt { font-size: 1.3em;
+ color: #088;
+ letter-spacing: 1px;
+ word-spacing: 2px}
+
+h1 {
+ color: #c00;
+ font-size: 16pt;
+ margin-bottom: 2em;
+ margin-left: -50px }
+
+h2 {
+ color: #324e95;
+ font-size: 12pt;
+ margin-top: 2em;
+ margin-left: -50px }
+
+h3 {
+ color: #324e95;
+ font-size: 10pt;
+ margin-top: 2em;
+ margin-left: -50px }
+
+dt { font-weight: bold }
+
+ul {
+ list-style-image: url(images/arrow.png) }
+
+ul li {
+ background-color: #e4e6ed;
+ margin: 1em 6em 1em -2em;
+ padding: 0.2em 0.5em 0.2em 1em;
+ border-style: solid;
+ border-width: 1px;
+ border-color: #c4c4d5 #fff #fff #c4c4d5 }
+
+a:link {
+ color: #324e95;
+ text-decoration: none;
+ background-color: transparent }
+
+a:visited {
+ color: #90c;
+ text-decoration: none }
+
+a:hover {
+ color: #c00;
+ text-decoration: underline;
+ background-color: transparent }
diff --git a/boxbackup/html/images/arrow.png b/boxbackup/html/images/arrow.png
new file mode 100644
index 00000000..4c60805d
--- /dev/null
+++ b/boxbackup/html/images/arrow.png
Binary files differ
diff --git a/boxbackup/html/images/bblogo.png b/boxbackup/html/images/bblogo.png
new file mode 100644
index 00000000..b33230b4
--- /dev/null
+++ b/boxbackup/html/images/bblogo.png
Binary files differ
diff --git a/boxbackup/html/images/stepahead.png b/boxbackup/html/images/stepahead.png
new file mode 100644
index 00000000..9ac05b8c
--- /dev/null
+++ b/boxbackup/html/images/stepahead.png
Binary files differ
diff --git a/boxbackup/instguide.xml b/boxbackup/instguide.xml
new file mode 100644
index 00000000..c857da0d
--- /dev/null
+++ b/boxbackup/instguide.xml
@@ -0,0 +1,766 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<book>
+ <title>Box Backup Build and Installation Guide</title>
+
+ <preface>
+ <title>License</title>
+
+ <para>Copyright &copy; 2003 - 2007, Ben Summers and contributors.
+ All rights reserved.</para>
+
+ <para>Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are
+ met:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.</para>
+ </listitem>
+
+ <listitem>
+ <para>Redistributions in binary form must reproduce the above
+ copyright notice, this list of conditions and the following disclaimer
+ in the documentation and/or other materials provided with the
+ distribution.</para>
+ </listitem>
+
+ <listitem>
+ <para>All use of this software and associated advertising materials
+ must display the following acknowledgement: This product includes
+ software developed by Ben Summers.</para>
+ </listitem>
+
+ <listitem>
+ <para>The names of the Authors may not be used to endorse or promote
+ products derived from this software without specific prior written
+ permission.</para>
+ </listitem>
+ </itemizedlist>
+
+
+ <para>[Where legally impermissible the Authors do not disclaim liability
+ for direct physical injury or death caused solely by defects in the
+ software unless it is modified by a third party.]</para>
+
+ <para>THIS SOFTWARE IS PROVIDED BY THE AUTHORS "AS IS" AND ANY EXPRESS
+ OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
+ ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+ IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.</para>
+ </preface>
+
+ <chapter>
+ <title>Introduction</title>
+
+ <para>The backup daemon, bbackupd, runs on all machines to be backed up.
+ The store server daemon, bbstored runs on a central server. Data is sent
+ to the store server, which stores all data on local filesystems, that is,
+ only on local hard drives. Tape or other archive media is not used.</para>
+
+ <para>The system is designed to be easy to set up and run, and cheap to
+ use. Once set up, there should be no need for user or administrative
+ intervention, apart from usual system maintenance.</para>
+
+ <section>
+ <title>Client daemon</title>
+
+ <para>bbackupd is configured with a list of directories to back up. It
+ has a lazy approach to backing up data. Every so often, the directories
+ are scanned, and new data is uploaded to the server. This new data must
+ be over a set age before it is uploaded. This prevents rapid revisions
+ of a file resulting in many uploads of the same file in a short period
+ of time.</para>
+
+ <para>It can also operate in a snapshot mode, which behaves like
+ traditional backup software. When instructed by an external bbackupctl
+ program, it will upload all changed files to the server.</para>
+
+ <para>The daemon is always running, although sleeping most of the time.
+ In lazy mode, it is completely self contained -- scripts running under
+ cron jobs are not used. The objective is to keep files backed up, not to
+ make snapshots of the filesystem at particular points in time
+ available.</para>
+
+ <para>If an old version of the file is present on the server, a modified
+ version of the rsync algorithm is used to upload only the changed
+ portions of the file.</para>
+
+ <para>After a new version is uploaded, the old version is still
+ available (subject to disc space on the server). Similarly, a deleted
+ file is still available. The only limit to their availability is space
+ allocated to this account on the server</para>
+
+ <para>Future versions will add the ability to mark the current state of
+ files on the server, and restore from this mark. This will emulate the
+ changing of tapes in a tape backup system.</para>
+
+ <section>
+ <title>Restoration</title>
+
+ <para>Restoring files is performed using a query tool, bbackupquery.
+ This can be used to restore entire directories, or as an 'FTP-like'
+ tool to list and retrieve individual files. Old versions and deleted
+ files can be retrieved using this tool for as long as they are kept on
+ the server.</para>
+ </section>
+
+ <section>
+ <title>Client Resource Usage</title>
+
+ <para>bbackupd uses only a minimal amount of disc space to store
+ records on uploaded files -- less than 32 bytes per directory and file
+ over a set size threshold. However, it minimises the amount of queries
+ it must make to the server by storing, in memory, a data structure
+ which allows it to determine what data is new. It does not need to
+ store a record of all files, essentially just the directory names and
+ last modification times. This is not a huge amount of memory.</para>
+
+ <para>If there are no changes to the directories, then the client will
+ not even connect to the server.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Security</title>
+
+ <para>Box Backup is designed to be secure in several ways. The data
+ stored on the backup store server is encrypted using secret-key
+ cryptography. Additionally, the transport layer is encrypted using TLS,
+ to ensure that the communications can't be snooped.</para>
+
+ <section>
+ <title>Encryption</title>
+
+ <para>The files, directories, filenames and file attributes are all
+ encrypted. By examining the stored files on the server, it is only
+ possible to determine the approximate sizes of a files and the tree
+ structure of the disc (not names, just number of files and
+ subdirectories in a directory). By monitoring the actions performed by
+ a client, it is possible to determine the frequency and approximate
+ scope of changes to files and directories.</para>
+
+ <para>The connections between the server and client are encrypted
+ using TLS (latest version of SSL). Traffic analysis is possible to
+ some degree, but limited in usefulness.</para>
+
+ <para>An attacker will not be able to recover the backed up data
+ without the encryption keys. Of course, you won't be able to recover
+ your files without the keys either, so you must make a conventional,
+ secure, backup of these keys.</para>
+ </section>
+
+ <section>
+ <title>Authentication</title>
+
+ <para>SSL certificates are used to authenticate clients. UNIX user
+ accounts are not used to minimise the dependence on the configuration
+ of the operating system hosting the server.</para>
+
+ <para>A script is provided to run the necessary certification
+ authority with minimal effort.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Server daemon</title>
+
+ <para>The server daemon is designed to be simple to deploy, and run on
+ the cheapest hardware possible. To avoid the necessity to use expensive
+ hardware RAID or software RAID with complex setup, it (optionally)
+ stores files using RAID techniques.</para>
+
+ <para>It does not need to run as a privileged user.</para>
+
+ <para>Each account has a set amount of disc space allocated, with a soft
+ and a hard limit. If the account exceeds the soft limit, a housekeeping
+ process will start deleting old versions and deleted files to reduce the
+ space used to below the soft limit. If the backup client attempts to
+ upload a file which causes the store to exceed the hard limit, the
+ upload will be refused.</para>
+ </section>
+ </chapter>
+
+ <chapter>
+ <title>Building and installing</title>
+
+ <section>
+ <title>Before you start</title>
+
+ <para>Firstly, check that all the clocks on your clients, servers and
+ signing machines are accurate and in sync. A disagreement in time
+ between a client and a server is the biggest cause of installation
+ difficulties, as the times in the generated certificates will cause
+ login failures if the start date is in the future.</para>
+ </section>
+
+ <section>
+ <title>Box Backup compile</title>
+
+ <para>In the following instructions, replace 0.00 with the actual
+ version number of the archive you have downloaded.</para>
+
+ <para>For help building on Windows, see the <link linkend="AppB">Windows
+ Compile Appendix</link>. And if you want to build a Linux RPM, <link
+ linkend="AppC">look here</link>.</para>
+
+ <para>You need the latest version of OpenSSL, as some of the extra APIs
+ it provides are required. You should have this anyway, as earlier
+ versions have security flaws. (If you have an earlier version installed,
+ the configuration script will give you instructions on enabling
+ experimental support for older versions.)</para>
+
+ <para>See <link linkend="AppA">OpenSSL notes</link> for more information
+ on OpenSSL issues.</para>
+
+ <para>There are some notes in the archive about compiling on various
+ platforms within the boxbackup-0.00 directory -- read them first. For
+ example, if you are compiling under Linux, look for LINUX.txt as
+ boxbackup-0.00/LINUX.txt after untaring the archive.</para>
+
+ <para>Download the archive, then in that directory type</para>
+
+ <programlisting>tar xvzf boxbackup-0.00.tgz
+cd boxbackup-0.00
+./configure
+make</programlisting>
+
+ <para>The server and client will be built and packaged up for
+ installation on this machine, or ready to be transferred as tar files to
+ another machine for installation.</para>
+
+ <para>This builds two parcels of binaries and scripts, 'backup-client'
+ and 'backup-server'. The generated installation scripts assumes you want
+ everything installed in <emphasis
+ role="bold">/usr/local/bin</emphasis></para>
+
+ <para>Optionally, type <emphasis role="bold">make test</emphasis> to run
+ all the tests.</para>
+ </section>
+
+ <section>
+ <title>Local installation</title>
+
+ <para>Type <emphasis role="bold">make install-backup-client</emphasis>
+ to install the backup client.</para>
+
+ <para>Type <emphasis role="bold">make install-backup-server</emphasis>
+ to install the backup server.</para>
+ </section>
+
+ <section>
+ <title>Remote installation</title>
+
+ <para>In the parcels directory, there are tar files for each parcel. The
+ name reflects the version and platform you have built it for.</para>
+
+ <para>Transfer this tar file to the remote server, and unpack it, then
+ run the install script. For example:</para>
+
+ <programlisting>tar xvzf boxbackup-0.00-backup-server-OpenBSD.tgz
+cd boxbackup-0.00-backup-server-OpenBSD
+./install-backup-server</programlisting>
+ </section>
+
+ <section>
+ <title>Configure options</title>
+
+ <para>You can use arguments to the configure script to adjust the
+ compile and link lines in the generated Makefiles, should this be
+ necessary for your platform. The configure script takes the usual GNU
+ autoconf arguments, a full list of which can be obtained with <emphasis
+ role="bold">--help</emphasis>. Additional options for Box Backup
+ include:</para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry char="-">--enable-gnu-readline</entry>
+
+ <entry>Use GNU readline if present. Linking Box Backup against
+ GNU readline may create licence implications if you then
+ distribute the binaries. libeditline is also supported as a safe
+ alternative, and is used by default if available.</entry>
+ </row>
+
+ <row>
+ <entry>--disable-largefile</entry>
+
+ <entry>Omit support for large files</entry>
+ </row>
+
+ <row>
+ <entry>--with-bdb-lib=DIR</entry>
+
+ <entry>Specify Berkeley DB library location</entry>
+ </row>
+
+ <row>
+ <entry>--with-bdb-headers=DIR</entry>
+
+ <entry>Specify Berkeley DB headers location</entry>
+ </row>
+
+ <row>
+ <entry>--with-random=FILE</entry>
+
+ <entry>Use FILE as random number seed (normally
+ auto-detected)</entry>
+ </row>
+
+ <row>
+ <entry>--with-tmp-dir=DIR</entry>
+
+ <entry>Directory for temporary files (normally /tmp)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>See <link linkend="AppA">OpenSSL notes</link> for the OpenSSL
+ specific options.</para>
+ </section>
+
+ <section>
+ <title>Tests</title>
+
+ <para>There are a number of unit tests provided. To compile and run one
+ type:</para>
+
+ <programlisting>./runtest.pl bbackupd release
+./runtest.pl common debug
+./runtest.pl ALL</programlisting>
+
+ <para>The runtest.pl script will compile and run the test. The first
+ argument is the test name, and the second the type of build. Use ALL as
+ a test name to run all the tests.</para>
+
+ <para>The output from the tests is slightly muddled using this script.
+ If you're developing, porting or trying out new things, it might be
+ better to use the following scheme:</para>
+
+ <programlisting>cd test/bbackupd
+make
+cd ../../debug/test/bbackupd
+./t</programlisting>
+
+ <para>or in release mode...</para>
+
+ <programlisting>cd test/bbackupd
+make -D RELEASE
+cd ../../release/test/bbackupd
+./t</programlisting>
+
+ <para>(use RELEASE=1 with GNU make)</para>
+
+ <para>I tend to use two windows, one for compilation, and one for
+ running tests.</para>
+ </section>
+ </chapter>
+
+ <appendix>
+ <title id="AppA">Box Backup and SSL</title>
+
+ <section>
+ <title>General notes</title>
+
+ <para>Ideally, you need to use version 0.9.7 or later of OpenSSL. If
+ this is installed on your system by default (and it is on most recent
+ releases of UNIX like OSes) then everything should just work.</para>
+
+ <para>However, if it isn't, you have a few options.</para>
+
+ <section>
+ <title>Upgrade your installation</title>
+
+ <para>The best option is to upgrade your installation to use 0.9.7.
+ Hopefully your package manager will make this easy for you. This may
+ require reinstallation of lots of software which depends on OpenSSL,
+ so may not be ideal.</para>
+
+ <para>(But as there have been a few security flaws in OpenSSL
+ recently, you probably want to upgrade it anyway.)</para>
+ </section>
+
+ <section>
+ <title>Install another OpenSSL</title>
+
+ <para>The second best option is to install another copy. If you
+ download and install from source, it will probably install into
+ /usr/local/ssl. You can then configure Box Backup to use it
+ using:</para>
+
+ <programlisting>./configure --with-ssl-headers=/usr/local/ssl/include --with-ssl-lib=/usr/local/ssl/lib</programlisting>
+
+ <para>which will set up the various includes and libraries for
+ you.</para>
+
+ <para>The configuration scripts may be a problem, depending on your
+ installation. See below for more information.</para>
+ </section>
+
+ <section>
+ <title>Use the old version of OpenSSL</title>
+
+ <para>If you have an old version installed, the configuration script
+ will give you instructions on how to enable support for older
+ versions. Read the warnings, and please, whatever you do, don't
+ release binary packages or ports which enable this option.</para>
+
+ <para>You may have issues with the configuration scripts, see
+ below.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>If you have problems with the config scripts</title>
+
+ <para>If you get OpenSSL related errors with the configuration scripts,
+ there are two things to check:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The bin directory within your OpenSSL directory is in the path
+ (if you have installed another version)</para>
+ </listitem>
+
+ <listitem>
+ <para>You have an openssl.cnf file which works and can be
+ found.</para>
+ </listitem>
+ </itemizedlist>
+
+ <section>
+ <title>OpenSSL config file</title>
+
+ <para>You need to have an openssl.cnf file. The default will generally
+ work well (see example at end). Make sure the openssl utility can find
+ it, either set the OPENSSL_CONF environment variable, or install it
+ into the location that is mentioned in the error messages.</para>
+
+ <para>Example OpenSSL config file:</para>
+
+ <programlisting id="openssl.cnf" xreflabel="openssl.cnf">#
+# OpenSSL example configuration file.
+# This is mostly being used for generation of certificate requests.
+#
+
+RANDFILE = /dev/arandom
+
+####################################################################
+[ req ]
+default_bits = 1024
+default_keyfile = privkey.pem
+distinguished_name = req_distinguished_name
+attributes = req_attributes
+
+[ req_distinguished_name ]
+countryName = Country Name (2 letter code)
+#countryName_default = AU
+countryName_min = 2
+countryName_max = 2
+
+stateOrProvinceName = State or Province Name (full name)
+#stateOrProvinceName_default = Some-State
+
+localityName = Locality Name (eg, city)
+
+0.organizationName = Organization Name (eg, company)
+#0.organizationName_default = Internet Widgits Pty Ltd
+
+# we can do this but it is not needed normally :-)
+#1.organizationName = Second Organization Name (eg, company)
+#1.organizationName_default = CryptSoft Pty Ltd
+
+organizationalUnitName = Organizational Unit Name (eg, section)
+#organizationalUnitName_default =
+
+commonName = Common Name (eg, fully qualified host name)
+commonName_max = 64
+
+emailAddress = Email Address
+emailAddress_max = 64
+
+[ req_attributes ]
+challengePassword = A challenge password
+challengePassword_min = 4
+challengePassword_max = 20
+
+unstructuredName = An optional company name
+
+[ x509v3_extensions ]
+
+nsCaRevocationUrl = http://www.cryptsoft.com/ca-crl.pem
+nsComment = "This is a comment"
+
+# under ASN.1, the 0 bit would be encoded as 80
+nsCertType = 0x40</programlisting>
+ </section>
+ </section>
+ </appendix>
+
+ <appendix>
+ <title id="AppB">Compiling bbackupd on Windows using Visual C++</title>
+
+ <para>This Appendix explains how to build the bbackupd daemon for Windows
+ using the Visual C++ compiler.</para>
+
+ <para>If you have any problems following these instructions, please sign
+ up to the <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ lis</ulink>t and report them to us, or send an email to <ulink
+ url="mailto:bbwiki@qwirx.com">Chris Wilson</ulink>. Thanks!</para>
+
+ <para><emphasis role="bold">Note</emphasis>: bbstored will not be built
+ with this process. bbstored is not currently supported on Windows. There
+ are no plans for bbstored support on Windows.</para>
+
+ <section>
+ <title>Tools</title>
+
+ <para>You will need quite a bit of software to make this work. All of it
+ is available for free on the Internet, although Visual C++ Express has
+ license restrictions and a time limit.</para>
+
+ <section>
+ <title>Visual C++</title>
+
+ <para>Microsoft's Visual C++ compiler and development environment are
+ part of their commercial product <ulink
+ url="http://msdn.microsoft.com/vstudio/">Visual Studio</ulink>. Visual
+ Studio 2005 is supported, and 2003 should work as well.</para>
+
+ <para>You can also <ulink
+ url="http://msdn.microsoft.com/vstudio/express/visualc/download/">download</ulink>
+ a free copy of Visual C++ 2005 Express. This copy must be registered
+ (activated) within 30 days, and is free for one year.</para>
+
+ <para>You will need the <ulink
+ url="http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/">Platform
+ SDK</ulink> to allow you to compile Windows applications.</para>
+ </section>
+
+ <section>
+ <title>Perl</title>
+
+ <para>Download and install <ulink
+ url="http://www.activestate.com/Products/ActivePerl/">ActivePerl for
+ Windows</ulink>, which you can probably find <ulink
+ url="http://downloads.activestate.com/ActivePerl/Windows/5.6/ActivePerl-5.6.1.638-MSWin32-x86.msi">here</ulink>.</para>
+ </section>
+
+ <section>
+ <title>Libraries</title>
+
+ <para>You will need to download and install several libraries. They
+ must all be built in the same directory, to be able to link
+ properly.</para>
+
+ <para>Choose a directory where you will unpack and compile OpenSSL,
+ Zlib and Box Backup. We will call this the base directory. An example
+ might be:</para>
+
+ <programlisting>C:\Documents and Settings\Your Username\Desktop\Box</programlisting>
+
+ <para>Make sure you know the full path to this directory.</para>
+
+ <section>
+ <title>OpenSSL</title>
+
+ <para>You will need to compile OpenSSL using Visual C++. The latest
+ release at this time, OpenSSL 0.9.8a, does not compile with Visual
+ C++ 2005 out of the box, so you need <ulink
+ url="http://bbdev.fluffy.co.uk/svn/box/chris/win32/support/openssl-0.9.8a-vc2005.zip">a
+ patched version</ulink>. The <ulink
+ url="http://www.openssl.org/source/openssl-0.9.8a.tar.gz">original
+ source</ulink> and <ulink
+ url="http://bbdev.fluffy.co.uk/svn/box/chris/win32/support/openssl-0.9.8a-win32fix.patch">patch</ulink>
+ are also available.</para>
+
+ <para>To compile OpenSSL:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Use a Windows unzipper such as <ulink
+ url="http://www.winzip.com/">WinZip (free trial)</ulink> to
+ extract the <emphasis
+ role="bold">openssl-0.9.8a-vc2005.tar.gz</emphasis> archive,
+ which you just downloaded, into the base directory.</para>
+ </listitem>
+
+ <listitem>
+ <para>Rename the folder from <emphasis
+ role="bold">openssl-0.9.8a-vc2005</emphasis> to <emphasis
+ role="bold">openssl</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>Open a command shell (run <emphasis
+ role="bold">cmd.exe</emphasis>) and <emphasis
+ role="bold">cd</emphasis> to the openssl directory</para>
+ </listitem>
+
+ <listitem>
+ <para>Run the following commands:</para>
+
+ <programlisting>perl Configure VC-WIN32
+ms\do_ms
+"c:\program files\Microsoft Visual Studio 8\Common7\Tools\vsvars32.bat"
+nmake -f ms\ntdll.mak</programlisting>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Zlib</title>
+
+ <para>You will need to download the <ulink
+ url="http://www.zlib.net/zlib123-dll.zip">Zlib compiled DLL</ulink>.
+ Create a directory called <emphasis role="bold">zlib</emphasis> in
+ the base directory, and unzip the file you just downloaded into that
+ directory. You don't need to compile anything.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Download Box Backup</title>
+
+ <para>The first version of Box Backup that's known to compile and with
+ Visual C++ 2005 is available on the <ulink
+ url="http://bbdev.fluffy.co.uk/svn/box/chris/win32/vc2005-compile-fixes/">Subversion
+ server</ulink>. However, this version has not been extensively tested
+ and may be out of date.</para>
+
+ <para>The changes are expected to be merged into the <ulink
+ url="http://bbdev.fluffy.co.uk/svn/box/trunk">Subversion trunk</ulink>
+ at some point, and this page should then be updated. If in doubt,
+ please sign up to the <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list</ulink> and ask us.</para>
+
+ <para>To get the source code out of Subversion you will need a <ulink
+ url="http://subversion.tigris.org/files/documents/15/25364/svn-1.2.3-setup.exe">Subversion
+ client for Windows</ulink>. After installing it, open a new command
+ prompt, go to the base directory, and type:</para>
+
+ <programlisting>svn co http://bbdev.fluffy.co.uk/svn/box/chris/win32/vc2005-compile-fixes/ boxbackup</programlisting>
+
+ <para>This should create a directory called <emphasis
+ role="bold">boxbackup</emphasis> inside the base directory.</para>
+ </section>
+
+ <section>
+ <title>Configure Box Backup</title>
+
+ <para>Open a command prompt, change to the base directory then
+ <emphasis role="bold">boxbackup</emphasis>, and run <emphasis
+ role="bold">win32.bat</emphasis> to configure the sources. Otherwise,
+ Visual C++ will complain about missing files whose names start with
+ <emphasis role="bold">autogen</emphasis>, and missing <emphasis
+ role="bold">config.h</emphasis>.</para>
+ </section>
+
+ <section>
+ <title>Compile Box Backup</title>
+
+ <para>Open Visual C++. Choose "File/Open/Project", navigate to the
+ base directory, then to <emphasis
+ role="bold">boxbackup\infrastructure\msvc\2005</emphasis> (or
+ <emphasis role="bold">2003</emphasis> if using Visual Studio 2003),
+ and open any project or solution file in that directory.</para>
+
+ <para>Press F7 to compile Box Backup. If the compilation is
+ successful, <emphasis
+ role="bold">boxbackup\Debug\bbackupd.exe</emphasis> will be
+ created.</para>
+ </section>
+
+ <section>
+ <title>Install Box Backup</title>
+
+ <para>Create the destination directory, <emphasis
+ role="bold">C:\Program Files\Box Backup\bbackupd</emphasis>.</para>
+
+ <para>Write a configuration file, keys and certificate on a Unix
+ machine, and copy them into the <emphasis role="bold">Box
+ Backup</emphasis> directory, together with the following files from
+ the base directory:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>boxbackup\Debug\bbackupd.exe</para>
+ </listitem>
+
+ <listitem>
+ <para>openssl\out32dll\libeay32.dll</para>
+ </listitem>
+
+ <listitem>
+ <para>openssl\out32dll\ssleay32.dll</para>
+ </listitem>
+
+ <listitem>
+ <para>zlib\zlib1.dll</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Ensure that the user running Box Backup can read from the
+ <emphasis role="bold">Box Backup</emphasis> directory, and write to
+ the <emphasis role="bold">bbackupd</emphasis> directory inside
+ it.</para>
+
+ <para>Run Box Backup by double-clicking on it, and check that it
+ connects to the server. If the window opens and closes immediately,
+ it's probably due to a problem with the configuration file - check the
+ Windows Event Viewer for details.</para>
+ </section>
+
+ <section>
+ <title>Windows Service</title>
+
+ <para>Box Backup can also run as a Windows service, in which case it
+ will be automatically started at boot time in the background. To
+ install this, open a command prompt, and run:</para>
+
+ <programlisting>cd "C:\Program Files\Box Backup"
+bbackupd.exe -i</programlisting>
+
+ <para>This should output Box Backup service installed.</para>
+ </section>
+ </section>
+ </appendix>
+
+ <appendix>
+ <title id="AppC">Compilation and installation by building an RPM on
+ Linux</title>
+
+ <para>It is very easy to build an RPM of Box Backup on Linux platforms.
+ This should work on all Red Hat distributions (including Fedora), SuSE,
+ and probably others too.</para>
+
+ <para>Given that you have the correct development packages installed
+ simply execute this command (replacing the version number):</para>
+
+ <programlisting>rpmbuild -ta boxbackup-0.00.tgz</programlisting>
+
+ <para>rpmbuild will report where the packages have been written to, and
+ these can be installed in the normal manner.</para>
+
+ <para>If you have never built an RPM before you should set up a convenient
+ build area as described in the <ulink
+ url="http://www.rpm.org/max-rpm/s1-rpm-anywhere-different-build-area.html">RPM
+ book</ulink>.</para>
+
+ <para>If you wish to customise the package you can find the spec file in
+ the contrib/rpm directory.</para>
+ </appendix>
+</book>
diff --git a/boxbackup/raidfile-config.xml b/boxbackup/raidfile-config.xml
new file mode 100644
index 00000000..c610ceab
--- /dev/null
+++ b/boxbackup/raidfile-config.xml
@@ -0,0 +1,143 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry>
+ <refmeta>
+ <refentrytitle>raidfile-config</refentrytitle>
+
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>raidfile-config</refname>
+
+ <refpurpose>Configure Box Backup's RAID files</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>raidfile-config &lt;configdir&gt; &lt;blocksize&gt;
+ &lt;dir1&gt; [&lt;dir2&gt; &lt;dir3&gt;]</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>raidfile-config creates a raidfile.conf file for Box Backup. This
+ file holds information about the directories used to store backups in. Box
+ Backup supports userland RAID, in a restricted RAID5 configuration, where
+ 3 and only 3 'drives' are supported. You can read more about RAID5 (and
+ other RAID-levels) <ulink
+ url="http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks#RAID_5">here</ulink>.
+ </para>
+
+ <refsection>
+ <title>Parameters</title>
+
+ <para>The parameters are as follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>configdir</literal>: The directory path where
+ configuration files are located. Usually this is
+ <literal>/etc/box</literal>. <literal>raidfile.conf</literal> will
+ be written in this directory.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>blocksize</literal>: The block size used for file
+ storage in the system, in bytes. Using a multple of the file system
+ block size is a good strategy. Depending on the size of the files
+ you will be backing up, this multiple varies. Of course it also
+ depends on the native block size of your file system.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>dir1</literal>: The first directory in the built-in
+ RAID array.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>dir2</literal>: The second directory in the built-in
+ RAID array. If you are not using the built-in RAID functionality,
+ this field should be ignored. You should not use the built-in RAID,
+ when you have a hardware RAID solution, or if you're using another
+ type of software RAID (like md on Linux).</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>dir3</literal>: The third directory in the built-in
+ RAID array. The same notes that apply to <literal>dir2</literal>
+ also apply to <literal>dir3</literal>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Note that there are currently no way to add multiple disk sets to
+ the raidfile.conf file using command line tools, etc. See
+ raidfile.conf(5) for details on adding more disks</para>
+ </refsection>
+ </refsection>
+
+ <refsection>
+ <title>Author</title>
+
+ <para>Ben Summers and contributors. For help, please go to the <ulink
+ url="http://www.boxbackup.org/trac/">Wiki</ulink>, or subscribe to the Box
+ Backup <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list.</ulink></para>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+
+ <para><literal>bbstored-config(1)</literal></para>
+
+ <para><literal>bbstored.conf(5)</literal></para>
+
+ <para><literal>raidfile.conf(5)</literal></para>
+ </refsection>
+
+ <refsection>
+ <title>Files</title>
+
+ <para><literal>raidfile-config</literal> generates the raidfile.conf(5)
+ file.</para>
+ </refsection>
+
+ <refsection>
+ <title>Bugs</title>
+
+ <para>If you find a bug in Box Backup, and you want to let us know about
+ it, join the <ulink
+ url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+ list</ulink>, and send a description of the problem there.</para>
+
+ <para>To report a bug, give us at least the following information:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The version of Box Backup you are running</para>
+ </listitem>
+
+ <listitem>
+ <para>The platform you are running on (Hardware and OS), for both
+ client and server.</para>
+ </listitem>
+
+ <listitem>
+ <para>If possible attach your config files (bbstored.conf,
+ bbackupd.conf) to the bug report.</para>
+ </listitem>
+
+ <listitem>
+ <para>Also attach any log file output that helps shed light on the
+ problem you are seeing.</para>
+ </listitem>
+
+ <listitem>
+ <para>And last but certainly not least, a description of what you are
+ seeing, in as much detail as possible.</para>
+ </listitem>
+ </itemizedlist>
+ </refsection>
+</refentry>