BURP - BackUp and Restore Program
index why faq howto download contact



QUICK START

You need to compile burp on a unix-based operating system first.
Make sure that you have openssl, zlib and librsync libraries and development
libraries installed. With debian or ubuntu, this command should install them
for you:
apt-get install librsync-dev libz-dev libssl-dev
Change to the burp source directory and run "./configure --prefix=/usr",
then "make".
All being well, burp will compile successfully.
Then run "make install" as root to install.

Start the burp server with this command:
burp -c /etc/burp/burp-server.conf

UNIX CLIENT

The example client configuration file is /etc/burp/burp.conf.
It will backup /home/graham/testdir by default, which probably does not exist
on your system, so you will want to edit the config file to point to somewhere
that does exist.

To run a backup, start the burp client:
burp -a b

WINDOWS CLIENT

Pick the 32-bit or 64-bit Burp installer as appropriate - visit
http://burp.grke.net/ to find one of them.
Compilation instructions will be included in a separate guide.
The Windows installer will ask you for the address of your server, the client
name, and the client password. Burp will then installed its files to:
C:/Program Files/Burp
If you need to change client configuration settings, the file can be found at:
C:/Program Files/Burp/burp.conf
It will be configured to backup "C:/Documents and Settings".

To run a backup, start the burp client from within its directory:
cd "C:\Program Files\Burp\bin"
burp.exe -a b
If you are running Windows 7, you might need to start the command prompt with
"Run as Administrator".



For more help, see the man page - type 'man burp'.


For the benefit of the website, the man page now follows.


Burp(8) 							       Burp(8)



NAME
       Burp - BackUp and Restore Program

SYNOPSIS
       burp [OPTIONS]

DESCRIPTION
       BackUp and Restore Program.


SERVER OPTIONS
       -c path
	      Short  for  'config  file'. The argument is a path to the config
	      file. The default is /etc/burp/burp.conf.

       -n     No daemon mode. The program will accept  a  single  query,  deal
	      with it, and then exit. This is useful for debugging.


CLIENT OPTIONS
       -a [b|r|l|L]
	      Short  for 'action'. The arguments mean backup, restore, list or
	      long list, respectively.

       -b [number|a]
	      Short for 'backup number'. The argument is a number, or  'a'  to
	      select all backups.

       -c [path]
	      Short  for  'config  file'. The argument is a path to the config
	      file.  The  default  is	/etc/burp/burp.conf,   or   C:\Program
	      Files\Burp\burp.conf on Windows.

       -d [path]
	      Short  for 'directory'. The argument is a path to an alternative
	      directory to restore to.

       -f [path]
	      Short for 'force overwrite'. Without this option set, a  restore
	      will not overwrite existing files.

       -r [regex]
	      Short  for  'regular  expression'.  The  argument  is  a regular
	      expression with which to match backup files. Use	it  for  lists
	      and restores.


EXAMPLES
       burp -a l
	      Lists the available backups and dates

       burp -a l -b 1
	      Lists all the files in backup number 1.

       burp -a l -b a
	      Lists all the files in all the backups.

       burp -a l -b 1 -r myregex
	      Lists  all  the  files in backup number 1 that match the regular
	      expression 'myregex'.

       burp -a L -b 1 -r myregex
	      Long lists all the files in backup number 1 that match the regu-
	      lar expression 'myregex'. This is like doing an 'ls -l'.

       burp -a r -b 1 -r myregex
	      Restores all the files in backup number 1 that match the regular
	      expression 'myregex' back to their original location. You  won't
	      be given a warning if the files already exist there, so use with
	      caution.

       burp -a r -b 1 -r myregex -d /tmp/restoredir
	      Restores all the files in backup number 1 that match the regular
	      expression 'myregex' into the directory /tmp/restoredir.

       burp -a r
	      Restores all the files in the most recent backup to their origi-
	      nal location. You won't be given a warning if the files  already
	      exist there, so use with caution.


SERVER CONFIGURATION FILE OPTIONS
       mode=server
	      Required to run in server mode.

       port=[port number]
	      Defines the TCP port that the server listens on.

       directory=[path]
	      Path to the directory in which to store backups.

       clientconfdir=[path]
	      Path to the directory that contains client configuration files.

       lockfile=[path]
	      Path to the lockfile that ensures that two server processes can-
	      not run simultaneously.

       keep=[number]
	      Number of backups to keep. This can be overriddden by the client
	      configuration files in clientconfdir on the server.

       hardlinked_archive=[0|1]
	      On  the  server, defines whether to keep hardlinked files in the
	      backups, or whether to generate reverse deltas  and  delete  the
	      original	files. Can be set to either 0 (off) or 1 (on).	Disad-
	      vantage: More disk space will be used Advantage:	Restores  will
	      be faster, and since no reverse deltas need to be generated, the
	      time and effort the server needs at  the	end  of  a  backup  is
	      reduced.

       working_dir_recovery_method=[merge|use|delete]
	      This  option tells the server what to do when it finds the work-
	      ing directory of an interrupted backup (perhaps somebody	pulled
	      the plug on the server, or something). This can be overridden by
	      the client configurations files in clientconfdir on the  server.
	      Options are...

       delete: Just delete the old working directory.

       use: Convert the working directory into a complete backup.

       merge:  Merge  the working directory with the previous complete backup.
       The resulting backup will contain the  newest  files  from  them  both.
       This  option takes effect when you try to do a new backup on the client
       that was interrupted. Once the old working directory is dealt with,  an
       entirely new backup will be made.

       ssl_cert_ca=[path]
	      The  path  to the SSL CA certificate. This file will probably be
	      the same on both the server and the client.

       ssl_cert=[path]
	      The path to the server SSL certificate.

       ssl_cert_password=[password]
	      The SSL certificate password.

       ssl_dhfile=[path]
	      Path to Diffie-Hellman parameter	file.  To  generate  one  with
	      openssl,	 use   a  command  like  this:	openssl  dhparam  -out
	      dhfile.pem -5 1024


CLIENT CONFIGURATION FILE OPTIONS
       mode=client
	      Required to run in client mode.

       server=[IP address or hostname]
	      Defines the server to connect to.

       port=[port number]
	      Defines the TCP port that the server is listening on.

       cname=[password]
	      Defines the client name to identify as to the server.

       password=[password]
	      Defines the password to send to the server.

       lockfile=[path]
	      Path to the lockfile that ensures that two client processes can-
	      not run simultaneously (this currently doesn't work on Windows).

       include=[path]
	      Path  to	include  in  the backup. You can have multiple include
	      lines.

       exclude=[path]
	      Path to exclude from the backup. You can have  multiple  exclude
	      lines.   ssl_cert_ca=[path]  The path to the SSL CA certificate.
	      This file will probably be the same on both the server  and  the
	      client.

       ssl_cert=[path]
	      The path to the client SSL certificate.

       ssl_cert_password=[password]
	      The SSL certificate password.



       SERVER CLIENTCONFDIR FILE

       For  the  server to know about clients that can contact it, you need to
       place a file named after the client in  clientconfdir.  The  file  name
       must  much  the	name in the 'cname' field on the client. "ssl_peer_cn"
       must also be set and match the common name in the SSL certificate  that
       the  client  gives  when it connects.  The file needs to contain a line
       like "password=[password]" that matches the same field on  the  client.
       Additionally,   the  "keep"  and  "working_dir_recovery_method"	server
       options can be overridden here for each client.


Some notes on SSL certificates
       The burp example configs come with example SSL certificates  and  keys.
       You can use these and burp will work. But if you are worried about net-
       work security, you should generate your own certificates and  keys  and
       point  your config files to them. To create the example files, I used a
       handy  interface  to  openssl,	called	 'tinyca'   (http://tinyca.sm-
       zone.net/).  If	you  are  using  Debian,  you can run 'apt-get install
       tinyca' to get it.


Examining backups
       As well as using the client list options described above,  you  can  go
       directly  to  the  storage  directory  on the server. The backups for a
       client are in the directory named after the client. Inside each	backup
       directory is a file called manifest.gz.

       This  contains  a  list	of all the files in the backup, and where they
       originally came from on the client.

       There is also a 'log.gz' file in the backup directory,  which  contains
       the output generated by the server during the backup.

       The 'data' directory contains complete backup files.

       The  'deltas.reverse'  directory  contains  reverse  deltas that can be
       applied to the data from the next backup in the sequence (indicated  by
       the contents of the 'forward' file).

       Anything  with  a .gz suffix is compressed in gzip format.  You can use
       standard tools, such as zcat, zless or cp, to view them	or  copy  them
       elsewhere.



BUGS
       If you find bugs, please report them to the email list. See the website
        for details.


AUTHOR
       The main author of Burp is Graham Keeling.


COPYRIGHT
       See the LICENCE file included with the source distribution.



				     Burp			       Burp(8)

Burp is open and free software. I work on it in my spare time. If you would like this work to continue, please consider making a small donation.


Late updated: February 2011