|
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.
-i Print an index table of symbols that humans may see burp pro-
duce, and exit.
-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|e]
Short for 'action'. The arguments mean backup, timed backup,
restore, list, long list, verify, or estimate, 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.
-i Print an index table of symbols that humans may see burp pro-
duce, and exit.
-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.
max_hardlinks=[number]
On the server, the number of times that a single file can be
hardlinked. The bedup program also obeys this setting. The
default is 10000.
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.
network_timeout=[s]
Set the network timeout in seconds. If no data is sent or
received over a period of this length, burp will give up. The
default is 7200 seconds (2 hours).
working_dir_recovery_method=[resume|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.
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_success_warnings_only=[0|1]
Set to 1 to send success notifications only when there were
warnings. Leave unset or set to 0 to send success notifications
for every backup.
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.
dedup_group=[string]
Enables you to group clients together for file deduplication
purposes. For example, you might want to set 'dedup_group=xp'
for each Windows XP client, and then run the bedup program on a
cron job every other day with the option '-g xp'.
server_script_pre=[path]
Path to a script to run on the server after each successfully
authenticated connection but before any work is carried out. The
arguments to it are 'pre', '(client command)', 'reserved3' to
'reserved5', and then arguments defined by
server_script_pre_arg. If the script returns non-zero, the task
asked for by the client will not be run. This command and
related options can be overriddden by the client configuration
files in clientconfdir on the server.
server_script_pre_arg=[string]
A user-definable argument to the server pre script. You can have
many of these.
server_script_post=[path]
Path to a script to run on the server before the client discon-
nects. The arguments to it are 'post', '(client command)',
'reserved3' to 'reserved5', and then arguments defined by
server_script_post_arg. This command and related options can be
overriddden by the client configuration files in clientconfdir
on the server.
server_script_post_arg=[string]
A user-definable argument to the server post script. You can
have many of these.
server_script=[path]
You can use this to save space in your config file when you want
to run the same server script twice. It overrides
server_script_pre and server_script_post. This command and
related options can be overriddden by the client configuration
files in clientconfdir on the server.
server_script_arg=[path]
Goes with server_script and overrides server_script_pre_arg and
server_script_post_arg.
server_script_post_run_on_fail=[0|1]
If this is set to 1, server_script_post will always be run. The
default is 0, which means that if the task asked for by the
client fails, server_script_post will not be run.
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.
network_timeout=[s]
Set the network timeout in seconds. If no data is sent or
received over a period of this length, burp will give up. The
default is 7200 seconds (2 hours).
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.
min_file_size=[b/Kb/Mb/Gb]
Do not back up files that are less than the specified size.
Example: 'min_file_size = 10Mb'. Set to 0 (the default) to have
no limit.
max_file_size=[b/Kb/Mb/Gb]
Do not back up files that are greater than the specified size.
Example: 'max_file_size = 10Mb'. Set to 0 (the default) to have
no limit.
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_success_warnings_only notify_failure_script notify_fail-
ure_arg dedup_group server_script_pre server_script_pre_arg
server_script_post server_script_post_arg server_script
server_script_arg server_script_post_run_on_fail
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)
|
