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",
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

By default, the server will fork into the background and run as a daemon. To
stay in the foreground, add the '-F' option.

UNIX CLIENT

The example client configuration file is /etc/burp/burp.conf.
It will backup /home by default.

A cron job for the client is installed to /etc/cron.d/burp and will run every
20 minutes. Whether or not this results in an actual backup depends upon the
timer settings in the server config files.

You can either force a backup by hand:
burp -a b
 
Or add a regular cron job like the following to /etc/cron.d/burp (or
equivalent). This makes the client ask the server every twenty minutes whether
it is yet time for a new backup. It is probably a good idea to change the
numbers for each client, in order to spread the load a bit:
MAILTO=
7,27,47 * * * * root    /sbin/burp -a t

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 can be found at src/win32/README in the source package.
The Windows installer will ask you for the address of your server, the client
name, and the client password. Burp will then install 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".

A Windows Scheduler task will have been installed and will be configured to
run every 20 minutes from the time of the installation. Whether or not this
results in an actual backup depends upon the timer settings in the server
config files.

To force a backup by hand, 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 forking mode. The program will accept a  single  query,  deal
	      with  it,  and  then exit. This is useful for debugging. Implies
	      '-F'.

       -F     Foreground mode. The server will fork into  the  background  and
	      run as a daemon if you do not give this option.

       -a s   Run this to connect to a running server to get a live monitor of
	      the status of all your backup clients.  If  your	server	config
	      file is not in the default location, you will also need to spec-
	      ify the path with the '-c' option.  The  live  monitor  requires
	      ncurses support at compile time.

       -a S   Similar to '-a s', but it prints the main status monitor summary
	      screen to stdout. The intention is that a script	can  run  this
	      and  email  an  administrator  the  output  on  a cron job. This
	      doesn't require ncurses support.

       -l [path]
	      Path to log file. The default is stdout. This  option  overrides
	      the  logfile option in the config file. Use /dev/null to deacti-
	      vate or '' to reactivate output.


CLIENT OPTIONS
       -a [b|t|r|l|L|v|]
	      Short for 'action'. The arguments  mean  backup,	timed  backup,
	      restore, list, long list or verify, 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.

       -l [path]
	      Short for 'log file'. The argument is a path to  the  log  file.
	      The  default is stdout. This option overrides the logfile option
	      in the config file. Use /dev/null to deactivate or '' to reacti-
	      vate output.


EXAMPLES
       burp -a b
	      Runs a backup.

       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 1 -l /dev/null
	      Lists all the files in backup number 1 without extra debug info.

       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.

       burp -a v
	      Verifies the most recent backup.

       burp -a v -b 1 -r myregex
	      Verifies	everything in backup number 1 that matches the regular
	      expression 'myregex'.

       burp -a t
	      Timed backup. The same as 'burp -a b', except that a  script  is
	      run  on the server before deciding to go ahead. The intention is
	      that this command will be run on a repeating  cron  job  with  a
	      short  interval, and that the server will decide when it is time
	      for a new backup.


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

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

       status_port=[port number]
	      Defines the TCP port that  the  server  listens  on  for	status
	      requests.

       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.

       pidfile=[path]
	      Synonym for lockfile.

       logfile=[path]
	      Path to the logfile.

       keep=[number]
	      Number of backups to keep. This can be overriddden by the client
	      configuration files in clientconfdir on the server. Specify mul-
	      tiple 'keep' entries on separate lines in order to keep multiple
	      periods  of  backups. For example, assuming that you are doing a
	      backup a day, keep=7 keep=4 keep=6 (on separate lines) will keep
	      7 daily backups, 4 weekly backups (7x4=28), and 6 multiples of 4
	      weeks (7x4x6=168) - roughly 6 monthly backups. Effectively,  you
	      will  be	guaranteed  to	be able to restore up to 168 days ago,
	      with the number of available backups exponentially decreasing as
	      you  go  back  in time to that point. In this example, every 7th
	      backup will be hardlinked to allow burp to safely delete	inter-
	      mediate  backups	when  necessary.  You  can have as many 'keep'
	      lines as you like, as long as they don't	exceed	52560000  when
	      multiplied  together.  That  is,	a  backup every minute for 100
	      years.

       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.

       librsync=[0|1]
	      When set to 0, delta differencing will not take place. That  is,
	      when a file changes, the server will request the whole new file.
	      The default is 1. This option can be overridden  by  the	client
	      configuration files in clientconfdif on the server.

       compression=[gzip0-9]
	      Choose  the  level of gzip compression. Setting 0 or gzip0 turns
	      compression off. The default is gzip9. This option can be  over-
	      ridden by the client configuration files in clientconfdif on the
	      server.

       client_lockdir=[path]
	      Path to the directory in which to keep per-client lock files. By
	      default,	this  is  set  to  the	path  given by the 'directory'
	      option.

       user=[username]
	      Run as a particular user. This can be overridden by  the	client
	      configuration files in clientconfdir on the server.

       group=[groupname]
	      Run  as a particular group. This can be overridden by the client
	      configuration files in clientconfdir on the server.

       umask=[umask]
	      Set the file creation umask. Default is 0022.

       ratelimit=[Mb/s]
	      Set the network send rate limit, in Mb/s. If this option is  not
	      given, burp will send data as fast as it can.

       working_dir_recovery_method=[resume|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:  This  option is deprecated - please use 'resume' instead. 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	inter-
       rupted.	Once  the old working directory is dealt with, an entirely new
       backup will be made.

       resume: Simply continue the previous backup from the point at which  it
       left off.

       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. The file should con-
	      tain just the certificate in PEM format

       ssl_cert=[path]
	      The path to the server SSL certificate. It works for me when the
	      file contains the concatenation of the certificate  and  private
	      key in PEM format.

       ssl_key=[path]
	      The path to the server SSL private key in PEM format.

       ssl_key_password=[password]
	      The SSL key password.

       ssl_cert_password=[password]
	      Synonym for ssl_key_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

       max_children=[number]
	      Defines  the  number  of	child processes to fork (the number of
	      clients that can simultaneously connect. The default is 5.

       timer_script=[path]
	      Path to the script to run when a client connects with the  timed
	      backup  option.  If  the script exits with code 0, a backup will
	      run. The first two arguments are the client name and the path to
	      the  'current'  storage  directory. The next three arguments are
	      reserved, and user arguments are appended after that. An example
	      timer  script  is provided. The timer_script option can be over-
	      riddden by the client configuration files  in  clientconfdir  on
	      the server.

       timer_arg=[string]
	      A user-definable argument to the timer script. You can have many
	      of these. The timer_arg options can be overriddden by the client
	      configuration files in clientconfdir on the server.

       notify_success_script=[path]
	      Path to the script to run when a backup succeeds. User arguments
	      are appended after the first five reserved arguments. An example
	      notify  script is provided. The notify_success_script option can
	      be overriddden by the  client  configuration  files  in  client-
	      confdir on the server.

       notify_success_arg=[string]
	      A  user-definable argument to the notify success script. You can
	      have many of these. The notify_success_arg options can be  over-
	      riddden  by  the	client configuration files in clientconfdir on
	      the server.

       notify_failure_script=[path]
	      The same as notify_success_script, but for backups that failed.

       notify_failure_arg=[string]
	      The same as notify_failure_arg, but for backups that failed.


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

       pidfile=[path]
	      Synonym for lockfile.

       logfile=[path]
	      Path to the logfile.

       user=[username]
	      Run as a particular user (not supported on Windows).

       group=[groupname]
	      Run as a particular group (not supported on Windows).

       ratelimit=[Mb/s]
	      Set  the network send rate limit, in Mb/s. If this option is not
	      given, burp will send data as fast as it can.

       include=[path]
	      Path to include in the backup. You  can  have  multiple  include
	      lines.  Use  forward  slashes  '/',  not backslashes '\' as path
	      delimiters.

       exclude=[path]
	      Path to exclude from the backup. You can have  multiple  exclude
	      lines.  Use  forward  slashes  '/',  not backslashes '\' as path
	      delimiters.

       exclude_ext=[extension]
	      Extensions to exclude from the backup. Case insensitive. You can
	      have multiple exclude extension lines. For example, set 'vdi' to
	      exclude VirtualBox disk images.

       cross_filesystem=[path]
	      Allow backups to cross a particular filesystem mountpoint.

       cross_all_filesystems=[0|1]
	      Allow backups to cross all filesystem mountpoints.

       nobackup=[file name]
	      If this file system entry exists, the  directory	containing  it
	      will not be backed up.

       read_fifo=[path]
	      Do  not  back  up the given fifo itself, but open it for reading
	      and back up the contents as if it were a regular file.

       read_all_fifos=[0|1]
	      Open all fifos for reading and back up the contents as  if  they
	      were regular files.

       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. The file should con-
	      tain just the certificate in PEM format

       ssl_cert=[path]
	      The path to the client SSL certificate. It works for me when the
	      file contains the concatenation of the certificate  and  private
	      key in PEM format.

       ssl_key=[path]
	      The path to the client SSL private key in PEM format.

       ssl_key_password=[password]
	      The SSL key password.

       ssl_cert_password=[password]
	      Synonym for ssl_key_password.

       encryption_password=[password]
	      Set  this to enable client side file Blowfish encryption. If you
	      do not want encryption, leave this  field  out  of  your	config
	      file.  IMPORTANT:  Configuring  this  renders delta differencing
	      pointless, since the smallest real change to a  file  will  make
	      the whole file look different. Therefore, activating this option
	      turns off delta differencing so  that  whenever  a  client  file
	      changes, the whole new file will be uploaded on the next backup.
	      ALSO IMPORTANT: If you manage to lose your encryption  password,
	      you  will not be able to unencrypt your files. You should there-
	      fore think about having a copy of the encryption password  some-
	      where  off-box,  in  case  of  your  client  hard  disk failing.
	      FINALLY: If you change your encryption password, you will end up
	      with  a mixture of files on the server with different encryption
	      and it may become tricky to restore more	than  one  file  at  a
	      time.  For  this reason, if you change your encryption password,
	      you may want to start a fresh chain of backups  (by  moving  the
	      original set aside, for example). Burp will cope fine with turn-
	      ing the same encryption password on and off between backups, and
	      will  restore  a backup of mixed encrypted and unencrypted files
	      without a problem.

       backup_script_pre=[path]
	      Path to a script to run before a backup. The arguments to it are
	      'pre', 'reserved2' to 'reserved5', and then arguments defined by
	      backup_script_pre_arg.

       backup_script_pre_arg=[string]
	      A user-definable argument to the backup pre script. You can have
	      many of these.

       backup_script_post=[path]
	      Path  to a script to run after a backup. The arguments to it are
	      'post', [0|1] if the backup failed or succeeded, 'reserved3'  to
	      'reserved5',	and	 then	  arguments	defined     by
	      backup_script_post_arg.

       backup_script_post_arg=[string]
	      A user-definable argument to the backup  post  script.  You  can
	      have many of these.

       backup_script_post_run_on_fail=[0|1]
	      If  this is set to 1, backup_script_post will be run whether the
	      backup succeeds or not. The  default  is	0,  which  means  that
	      backup_script_post will only be run if the backup succeeds.

       restore_script_pre=[path]
	      Path  to	a  script to run before a restore. The arguments to it
	      are  'pre',  'reserved2'	to  'reserved5',  and  then  arguments
	      defined by restore_script_pre_arg.

       restore_script_pre_arg=[string]
	      A  user-definable  argument  to  the restore pre script. You can
	      have many of these.

       restore_script_post=[path]
	      Path to a script to run after a restore. The arguments to it are
	      'post', [0|1] if the restore failed or succeeded, 'reserved3' to
	      'reserved5',     and     then	arguments      defined	    by
	      restore_script_post_arg.

       restore_script_post_arg=[string]
	      A  user-definable  argument  to the restore post script. You can
	      have many of these.

       restore_script_post_run_on_fail=[0|1]
	      If this is set to 1, restore_script_post will be run whether the
	      restore  succeeds  or  not.  The	default is 0, which means that
	      restore_script_post will only be run if the restore succeeds.

       backup_script=[path]
	      You can use this to save space in your config file when you want
	      to  run  the same script before and after a backup. It overrides
	      backup_script_pre and backup_script_post.

       backup_script_arg=[path]
	      Goes with backup_script and overrides backup_script_pre_arg  and
	      backup_script_post_arg.

       restore_script=[path]
	      You can use this to save space in your config file when you want
	      to run the same script before and after a restore. It  overrides
	      restore_script_pre and restore_script_post.

       restore_script_arg=[path]
	      Goes  with  restore_script  and overrides restore_script_pre_arg
	      and restore_script_post_arg.


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 match the name in the 'cname' field on the client.

       ssl_peer_cn=[string]  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, or passwd=[encrypted password] - where
       the plain text password	on  the  client  will  be  tested  against  an
       encrypted password of the kind you might find in /etc/passwd.

       Additionally,  the  following  options  can be overridden here for each
       client:
	      directory keep working_dir_recovery_method librsync  compression
	      timer_script  timer_arg notify_success_script notify_success_arg
	      notify_failure_script notify_failure_arg


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. There is also the option of using burp_ca, which you
       can find in the source distribution, courtesy of Patrick Koppen.


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.


Burp, don't suck. Last updated: October 2011