Provided by: burp_2.2.18-2_amd64 
NAME
Burp - BackUp and Restore Program
SYNOPSIS
burp [OPTIONS]
DESCRIPTION
BackUp and Restore Program.
SERVER OPTIONS
-a c Run as a stand-alone champion chooser process (useful for debugging protocol2 style backups).
-c [path]
Short for 'config file'. The argument is a path to the config file. The default is
/etc/burp/burp.conf.
-F Foreground mode. The server will fork into the background and run as a daemon if you do not give
this option.
-g Generate initial CA keys and certificates, and then exit.
-h Print help and then exit.
-? Print help and then exit.
-i Print an index table of symbols that humans may see burp produce, and exit.
-n No forking mode. The program will accept a single query, deal with it, and then exit. This is
useful for debugging. Implies '-F'. If you intend to debug a protocol2 session, you will also want
to run a separate champion chooser process ('-a c' below).
-o [option=value]
Override a given option. You can use this flag several times to override multiple options. You
can even reset list options with the special syntax ':=' (example: '-o "include:=/tmp"').
-Q Do not log to stdout (overrides config file 'stdout' setting).
-t Dry-run mode to test config file syntax.
-v Log to stdout (overrides config file 'stdout' setting).
-V Print version and exit.
ADDITIONAL SERVER OPTIONS TO USE WITH '-a c'
-C [client]
Run as if forked via a connection from this client.
CLIENT OPTIONS
-a [b|t|r|l|L|v|delete|e|T|d|D]
Short for 'action'. The arguments mean backup, timed backup, restore, list, long list, verify,
delete, estimate, timer check, diff, or long diff, 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 %PROGRAMFILES%\Burp\burp.conf on Windows.
-C [client]
Allows you to specify an alternative client to list or restore from. Requires that the server
configuration of the alternative client permits your client to do this. See the 'restore_client'
option.
-d [path]
Short for 'directory'. When restoring, the argument is a path to an alternative directory to
restore to. When listing, the argument is the directory to list.
-f Short for 'force overwrite'. Without this option set, a restore will not overwrite existing files.
-h Print help and then exit.
-? Print help and then exit.
-o [option=value]
Override a given option. You can use this flag several times to override multiple options. You
can even reset list options with the special syntax ':=' (example: '-o "include:=/tmp"').
-i Print an index table of symbols that humans may see burp produce, and exit.
-q [max secs]
When running a timed backup, sleep for a random number of seconds (between 0 and the number given)
before contacting the server. Alternatively, this can be specified by the 'randomise'
configuration file option.
-Q Do not log to stdout (overrides config file 'stdout' setting).
-r [regex]
Short for 'regular expression'. The argument is a regular expression with which to match backup
files. Use it for lists and restores.
-s [number]
For use with restores - strip a number of leading path components.
-t Dry-run mode to test config file syntax.
-v Log to stdout (overrides config file 'stdout' setting).
-x (on Windows)
On restore, do not use the Windows VSS API on restore - give this option when you are restoring a
backup that contains no VSS data.
-x (on non-Windows)
On restore, strip the Windows VSS data - give this option when you are restoring a backup that
contains VSS data.
-a s Run this to connect to a running server to get a live monitor of the status of all your backup
clients. 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. One application
is that a script can run this and email an administrator the output on a cron job. This doesn't
require ncurses support. There are additional options that can be given with both these options,
listed below.
ADDITIONAL CLIENT OPTIONS TO USE WITH '-a s' and '-a S'
-C [client]
Limit the output to a single client.
-b [number]
Show listable files in a particular backup (requires -C).
-z [file]
Dump a particular log file in a backup (requires -C and -b).
-d [path]
Show a particular path in a backup (requires -C and -b).
-l [path]
Log file for status monitor - useful for debugging.
EXAMPLES
burp -a b
Runs a backup.
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.
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 c
Lists all the files in the current backup.
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 regular expression 'myregex'. This is
like doing an 'ls -l'.
burp -a L -b 1 -d ''
Long list the top level directory of backup 1.
burp -a L -b 1 -d '/home/graham'
Long list the /home/graham directory of backup 1. These '-d' versions of the list function provide
the ability to 'browse' backups.
burp -C altclient -a L
Long list the top level directory of backup 1 of client 'altclient'.
burp -a r -d /tmp/restoredir
Restores all the files in the most recent backup into the directory /tmp/restoredir.
burp -a r -b 1 -d /tmp/restoredir -r myregex
Restores all the files in backup number 1 into the directory /tmp/restoredir, if they match the
regular expression 'myregex'.
burp -a r -b 1 -d /tmp/restoredir -r myregex -s 2
Restores all the files in backup number 1 into the directory /tmp/restore, if they match the
regular expression 'myregex', and strip 2 leading path components.
burp -C altclient -a r -b 1 -d /tmp/restoredir -r myregex
Restores all the files in backup number 1 of client 'altclient' into the directory
/tmp/restoredir, if that match the regular expression 'myregex'.
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 delete -b 1
Deletes backup number 1. Note that burp will not delete backup directories that other backup
directories depend upon.
burp -a d -b 1 -b 2
Report the differences between backups 1 and 2 (use -a D for more verbosity).
burp -a s
Run the ncurses status monitor.
burp -a S
Print a status monitor snapshot, summarising all clients.
burp -C testclient -a S
Print a status monitor snapshot, showing client 'testclient' only.
SERVER CONFIGURATION FILE OPTIONS
. [glob]
Read additional configuration files.
mode=server
Required to run in server mode.
listen=[address]:[port]
Defines the main TCP address and port that the server listens on. The default is either '::' or
'0.0.0.0', dependent upon compile time options. Specify multiple 'listen' entries on separate
lines in order to listen on multiple addresses and ports. Each pair can be configured with its own
'max_children' value.
listen_status=[address]:[port]
Defines the main TCP address and port that the server listens on for status requests. Specify
multiple 'listen_status' entries on separate lines in order to listen on multiple addresses and
ports. Each pair can be configured with its own 'max_status_children' value. Comment out to have
no status server.
cname_lowercase=[0|1]
Whether to force lowercase cname when looking-up in clientconfdir. This also affects the fqdn
lookup on the client (see client configuration options for details). The default is 0. When set to
1 the name provided by the client while authenticating will be lowercased.
cname_fqdn=[0|1]
Whether to keep fqdn cname (like 'testclient.example.com') when looking-up in clientconfdir. This
also affects the fqdn lookup on the client (see client configuration options for details). The
default is 1. When set to 0, the fqdn provided by the client while authenticating will be stripped
('testclient.example.com' becomes 'testclient').
daemon=[0|1]
Whether to daemonise. The default is 1.
fork=[0|1]
Whether to fork children. The default is 1.
directory=[path]
Path to the directory in which to store backups.
directory_tree=[0|1]
When turned on (which is the default) and the client is on version 1.3.6 or greater, the structure
of the storage directory will mimic that of the original filesystem on the client.
timestamp_format=[strftime format]
This allows you to tweak the format of the timestamps of individual backups. See 'man strftime' to
see available substitutions. If this option is unset, burp uses "%Y-%m-%d %H:%M:%S %z".
password_check=[0|1]
Allows you to turn client password checking on or off. The default is on. SSL certificates will
still be checked if you turn passwords off. This option can be overridden by the client
configuration files in clientconfdir on the server.
clientconfdir=[path]
Path to the directory that contains client configuration files.
protocol=[0|1|2]
Choose which style of backups and restores to use. 0 (the default) automatically decides based on
the client version and which protocol is set on the client side. 1 forces protocol1 style (file
level granularity with a pseudo mirrored storage on the server and optional rsync). 2 forces
protocol2 style (inline deduplication with variable length blocks). If you choose a forced
setting, it will be an error if the client also chooses a forced setting. This option can be
overridden by the client configuration files in clientconfdir on the server.
lockfile=[path]
Path to the lockfile that ensures that two server processes cannot run simultaneously.
pidfile=[path]
Synonym for lockfile.
syslog=[0|1]
Log to syslog. Defaults to off.
stdout=[0|1]
Log to stdout. Defaults to on.
keep=[number]
Number of backups to keep. This can be overridden by the clientconfdir configuration files in
clientconfdir on the server. Specify multiple '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 intermediate 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.
manual_delete=[path]
This can be overridden by the clientconfdir configuration files in clientconfdir on the server.
When the server needs to delete old backups, or rubble left over from generating reverse patches
with librsync=1, it will normally delete them in place. If you use the 'manual_delete' option, the
files will be moved to the path specified for deletion at a later point. You will then need to
configure a cron job, or similar, to delete the files yourself. Do not specify a path that is not
on the same filesystem as the client storage directory.
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).
Disadvantage: 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 clientconfdir on the server.
librsync_max_size=[B/KB/MB/GB]
Only use librsync when a file is less than the given size. Both the most recently backed up
version of a file and the version to be backed up are checked. The default is 0, which means the
option is off. This option can be overridden by the client configuration files in clientconfdir on
the server.
compression=zlib[0-9] (or gzip[0-9])
Choose the level of zlib compression for files stored in backups. Setting 0 or zlib0 turns
compression off. The default is zlib9. This option can be overridden by the client configuration
files in clientconfdir on the server. 'gzip' is a synonym of 'zlib'.
hard_quota=[B/KB/MB/GB]
Do not back up the client if the estimated size of all files is greater than the specified size.
Example: 'hard_quota = 100GB'. Set to 0 (the default) to have no limit.
soft_quota=[B/KB/MB/GB]
A warning will be issued when the estimated size of all files is greater than the specified size
and smaller than hard_quota. Example: 'soft_quota = 95GB'. Set to 0 (the default) to have no
warning.
version_warn=[0|1]
When this is on, which is the default, a warning will be issued when the client version does not
match the server version. This option can be overridden by the client configuration files in
clientconfdir on the server.
path_length_warn=[0|1]
When this is on, which is the default, a warning will be issued when the client sends a path that
is too long to replicate in the storage area tree structure. The file will still be saved in a
numbered file outside of the tree structure, regardless of the setting of this option. This option
can be overridden by the client configuration files in clientconfdir 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. If you want the server's sending speed to be limited, you will also need to set this
option on the server side.
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|delete]
This option tells the server what to do when it finds the working 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.
resume: Continue the previous backup from the point at which it left off. NOTE: If the client has changed
its include/exclude configuration since the backup was interrupted, the recovery method will
automatically switch to 'delete'. See also the 'resume attempts' option.
max_resume_attempts=[number]
If working_dir_recovery_method is 'resume', this option tells the server how many times to attempt
to resume before giving up and deleting the working directory. The default is 0, which means to
never give up.
client_can_delete=[0|1]
Turn this off to prevent clients from deleting backups with the '-a delete' option. The default is
that clients can delete backups. Restore clients can override this setting.
client_can_diff=[0|1]
Turn this off to prevent clients from diffing backups with the '-a d' option. The default is that
clients can diff backups. Restore clients can override this setting.
client_can_force_backup=[0|1]
Turn this off to prevent clients from forcing backups with the '-a b' option. Timed backups will
still work. The default is that clients can force backups.
client_can_list=[0|1]
Turn this off to prevent clients from listing backups with the '-a l' option. The default is that
clients can list backups. Restore clients can override this setting.
client_can_restore=[0|1]
Turn this off to prevent clients from initiating restores with the '-a r' option. The default is
that clients can initiate restores. Restore clients can override this setting.
client_can_verify=[0|1]
Turn this off to prevent clients from initiating a verify job with the '-a v' option. The default
is that clients can initiate a verify job. Restore clients can override this setting.
restore_client=[client]
A client that is permitted to list, verify, restore, delete, and diff files belonging to any other
client. You may specify multiple restore_clients. If this is too permissive, you may set a
restore_client for individual original clients in the individual clientconfdir files. Note that
restoring a backup from a Windows computer onto a Linux computer will currently leave the VSS
headers in place at the beginning of each file. This will be addressed in a future version of
burp.
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 contain just the certificate in PEM format. For more information on this,
and the other ssl_* options, please see docs/burp_ca.txt.
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]
Only needed for loading an encrypted certificate.
ssl_cert_password=[password]
Synonym for ssl_key_password.
ssl_ciphers=[cipher list]
Allowed SSL ciphers. See openssl ciphers for details.
ssl_compression=zlib[0|5] (or gzip[0|5])
Choose the level of zlib compression over SSL. Setting 0 or zlib0 turns SSL compression off.
Setting non-zero gives zlib5 compression (it is not currently possible for openssl to set any
other level). The default is 5. 'gzip' is a synonym of 'zlib'.
ssl_verify_peer_early=[0|1]
Verify and authenticate client certificates at SSL layer before receiving or sending Burp traffic.
The default is to verify client certificates only after password authentication.
ssl_dhfile=[path]
Path to Diffie-Hellman parameter file. To generate one with openssl, use a command like this:
openssl dhparam -dsaparam -out dhfile.pem 2048
max_children=[number]
Defines the number of child processes to fork (the number of clients that can simultaneously
connect. The default is 5. Specify multiple 'max_children' entries on separate lines if you have
configured multiple 'listen' entries.
max_status_children=[number]
Defines the number of status child processes to fork (the number of status clients that can
simultaneously connect. The default is 5. Specify multiple 'max_status_children' entries on
separate lines if you have configured multiple 'listen_status' entries.
max_storage_subdirs=[number]
Defines the number of subdirectories in the data storage areas. The maximum number of
subdirectories that ext3 allows is 32000. If you do not set this option, it defaults to 30000.
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 three arguments are the client name, the path to the
'current' storage directory, and the path to the top level storage directories. The next two
arguments are reserved, and user arguments (see timer_arg) are appended after that. An example
timer script is provided. The timer_script option can be overridden by the client configuration
files in clientconfdir on the server. If this option is not set, equivalent code internal to Burp
will be run instead. The internal code also uses the timer_arg parameters.
timer_arg=[string]
A user-definable argument to the timer script. You can have many of these. The timer_arg options
can be overridden 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 six
reserved arguments. An example notify script is provided. The notify_success_script option can be
overriddden by the client configuration files in clientconfdir 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 overriddden by the client configuration files in clientconfdir
on the server.
notify_success_warnings_only=[0|1]
Set to 1 to send success notifications when there were warnings. If this and
notify_success_changes_only are not turned on, success notifications are always sent.
notify_success_changes_only=[0|1]
Set to 1 to send success notifications when there were new or changed files. If this and
notify_success_warnings_only are not turned on, success notifications are always sent.
notify_failure_script=[path]
The same as notify_success_script, but for backups that failed.
notify_failure_arg=[string]
The same as notify_success_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)', '(client name)', '(0
or 1 for success or failure)', '(timer script exit code)', 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_pre_notify=[0|1]
Turn on to send a notification email when the server pre script returns non-zero. The output of
the script will be included in the email. The default is off. Most people will not want this
turned on because clients usually contact the server at 20 minute intervals and this could cause a
lot of emails to be generated. Requires the notify_failure options to be set.
server_script_post=[path]
Path to a script to run on the server before the client disconnects. The arguments to it are
'post', '(client command)', '(client name), '(0 or 1 for success or failure)', '(timer script exit
code)', 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_post_notify=[0|1]
Turn on to send a notification email when the server post script returns non-zero. The output of
the script will be included in the email. The default is off. Requires the notify_failure options
to be set.
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_notify=[0|1]
Turn on to send notifications email when the server pre and post scripts return non-zero. The
output of the script will be included in the email. The default is off. Requires the
notify_failure options to be set.
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.
autoupgrade_dir=[path]
Path to autoupgrade directory from which upgrades are downloaded. The option can be left unset in
order not to autoupgrade clients. Please see docs/autoupgrade.txt in the source package for more
help with this option.
ca_conf=[path]
Path to certificate authority configuration file. The CA configuration file will usually be
/etc/burp/CA.cnf. The CA directory indicated by CA.cnf will usually be /etc/burp/CA. If ca_conf is
set and the CA directory does not exist, the server will create, populate it, and the paths
indicated by ssl_cert_ca, ssl_cert, ssl_key and ssl_dhfile will be overwritten. For more detailed
information on this and the other ca_* options, please see docs/burp_ca.txt.
ca_name=[name]
Name of the CA that the server will generate when using the ca_conf option.
ca_server_name=[name]
The name that the server will put into its own SSL certficates when using the ca_conf option.
ca_burp_ca=[path]
Path to the burp_ca script when using the ca_conf option.
ca_crl=[path]
Override the default path to the certificate revocation list.
ca_crl_check=[0|1]
Whether to check for revoked certificates in the certificate revocation list.
monitor_browse_cache=[0|1]
Whether or not the server should cache the directory tree when a monitor client is browsing.
Advantage: browsing is faster. Disadvantage: more memory is used.
label=[string]
You can have multiple labels, and they can be overridden in the client configuration files in
clientconfdir on the server. They will appear as an array of strings in the server status monitor
JSON output. The idea is to provide a mechanism for arbirtrary values to be passed to clients of
the server status monitor.
enabled=[0|1]
Set this to 0 if you want to disable all clients. The default is 1. This option can be overridden
per-client in the client configuration files in clientconfdir on the server.
rblk_memory_max=[B/KB/MB/GB]
The maximum amount of data from the disk cached in server memory during a protocol2
restore/verify. The default is 256MB. This option can be overriden per-client in the client
configuration files in clientconfdir on the server.
fail_on_warning=[0|1]
If a warning is generated during a backup, fail the backup. The default is 0. This option can be
overriden per-client in the client configuration files in clientconfdir on the server.
CLIENT CONFIGURATION FILE OPTIONS
. [glob]
Read additional configuration files. On Windows, the glob is unimplemented - you will need to
specify an actual file.
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 on the server that we will send requests to. If this option is set, it is the
default for these options, which can be overridden individually: port_backup, port_restore,
port_verify, port_list, port_delete. If this option is not set, you will need to set all of the
port options separately.
port_backup=[port number]
Defines the TCP port on the server that we will send backup requests to. If not set, it defaults
to the port option.
port_restore=[port number]
Defines the TCP port on the server that we will send restore requests to. If not set, it defaults
to the port option.
port_verify=[port number]
Defines the TCP port on the server that we will send verify requests to. If not set, it defaults
to the port_restore option.
port_list=[port number]
Defines the TCP port on the server that we will send list requests to. If not set, it defaults to
the port option.
port_delete=[port number]
Defines the TCP port on the server that we will send delete requests to. If not set, it defaults
to the port option.
status_port=[port number]
Defines the TCP port that the server is listening on for status requests.
cname=[client name]
Defines the client name to identify as to the server.
cname_lowercase=[0|1]
Whether to force lowercase cname when detecting cname automatically (ie. no cname provided above).
The default is 0. When set to 1 the name returned by the get_fqdn function will be lowercased.
cname_fqdn=[0|1]
Whether to keep fqdn cname (like 'testclient.example.com') when detecting cname automatically (ie.
no cname provided above). The default is 1. When set to 0, the fqdn returned by the get_fqdn
function will be stripped ('testclient.example.com' becomes 'testclient').
protocol=[0|1|2]
Choose which style of backups and restores to use. 0 (the default) automatically decides based on
the server version and which protocol is set on the server side. 1 forces protocol1 style (file
level granularity with a pseudo mirrored storage on the server and optional rsync). 2 forces
protocol2 style (inline deduplication with variable length blocks). If you choose a forced
setting, it will be an error if the server also chooses a forced setting.
password=[password]
Defines the password to send to the server.
enabled=[0|1]
Set this to 0 if you want to disable a client. The default is 1. This option can also be set in
the client configuration files in clientconfdir on the server.
lockfile=[path]
Path to the lockfile that ensures that two client processes cannot run simultaneously (this
currently doesn't work on Windows).
pidfile=[path]
Synonym for lockfile.
syslog=[0|1]
Log to syslog. Defaults to off.
stdout=[0|1]
Log to stdout. Defaults to on.
progress_counter=[0|1]
Print progress counters on stdout. Defaults to on.
randomise=[max secs]
When running a timed backup, sleep for a random number of seconds (between 0 and the number given)
before contacting the server. Alternatively, this can be specified by the '-q' command line
option.
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. If you want the client's sending speed to be limited, you will also need to set this
option on the client side.
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).
ca_burp_ca=[path]
Path to the burp_ca script (burp_ca.bat on Windows). For more information on this, please see
docs/burp_ca.txt.
ca_csr_dir=[path]
Directory where certificate signing requests are generated. For more information on this, please
see docs/burp_ca.txt.
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 contain just the certificate in PEM format. For more information on this
and the other ssl_* options, please see docs/burp_ca.txt.
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]
Only needed for loading an encrypted certificate.
ssl_cert_password=[password]
Synonym for ssl_key_password.
ssl_peer_cn=[string]
Must match the common name in the SSL certificate that the server gives when it connects. If
ssl_peer_cn is not set, the server name will be used instead.
ssl_ciphers=[cipher list]
Allowed SSL ciphers. See openssl ciphers for details.
server_can_override_includes=[0|1]
To prevent the server from being able to override your local include/exclude list, set this to 0.
The default is 1.
server_can_restore=[0|1]
To prevent the server from initiating restores, set this to 0. The default is 1. You will also
need to give a location for the files to be restored to with the 'restoreprefix' option.
restoreprefix=[path]
When restoring, this path will be prefixed to the restore path. The '-d' command line option
overrides this setting. This setting is required if you are using server initiated restores.
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 therefore think
about having a copy of the encryption password somewhere 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 turning
the same encryption password on and off between backups, and will restore a backup of mixed
encrypted and unencrypted files without a problem.
glob_after_script_pre=[0|1]
Set this to 0 if you do not want include_glob settings to be evaluated after the pre script is
run. The default is 1.
backup_script_pre=[path]
Path to a script to run before a backup. It is not run if the server decides it is not yet time
for a backup. The arguments to it are 'pre', 'reserved2' to 'reserved5', and then arguments
defined by backup_script_pre_arg - unless the option 'backup_script_reserved_args' is off, then
only arguments defined by backup_script_pre_arg are passed to it. If the script fails (ie. when
the return code is not 0), then the backup is aborted.
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 -
unless the option 'backup_script_reserved_args' is off, then only arguments defined by
backup_script_post_arg are passed to it.
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 - unless the option
'restore_script_reserved_args' is off, then only arguments defined by restore_script_pre_arg are
passed to it.
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 - unless the option 'restore_script_reserved_args' is off, then only
arguments defined by restore_script_post_arg are passed to it.
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.
backup_script_reserved_args=[0|1]
Whether to pass reserved arguments to backup scripts. The default is on.
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.
restore_script_reserved_args=[0|1]
Whether to pass reserved arguments to restore scripts. The default is on.
autoupgrade_dir=[path]
Path to autoupgrade directory into which upgrades are downloaded. Please see docs/autoupgrade.txt
in the source package for more help with this option. If you do not want your client to
autoupgrade, do not set this option.
autoupgrade_os=[string]
Name of the client operating system. Should match a directory name in the server's
autoupgrade_dir. If you do not want your client to autoupgrade, do not set this option.
monitor_exe=[path]
Where to look to find the burp binary to use when forking a monitor client. This might be needed
on systems that don't have any sensible way to self-determine a process' own path, such as
openbsd.
INCLUDES / EXCLUDES
The following options specify exactly what is backed up. The client can specify these options, or if you
include at least one 'include=' in the client configuration files on the server, the server will override
them all.
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.
include_glob=[glob expression]
Include paths that match the glob expression. For example, '/home/*/Documents' will include
'/home/user1/Documents' and '/home/user2/Documents' if directories 'user1' and 'user2' exist in
'/home'. The Windows implementation currently limit the expression to contain only one '*'.
include_regex=[regular expression]
Include paths that match the regular expression. You need at least one 'include' or 'include_glob'
option to have files to be matched against the regex. If you have at least one 'include_regex'
line, then any path NOT matching the regex will be excluded from your backup.
exclude_regex=[regular expression]
Exclude paths that match the regular expression.
include_logic=[logic expression]
Not yet implemented. See 'exclude_logic' for details on the 'logic expression' syntax.
exclude_logic=[logic expression]
Exclude paths that match the 'logic expression'. A 'logic expression' may contain several tests
chained with boolean operators. The supported operators are: 'and', 'or', 'not' as well as groups
of expressions surrounded by parentheses. The supported tests are: 'file_size', 'file_match',
'path_match' and 'file_ext'. The 'file_size' test supports comparisons with '>', '>=', '<', '<=',
'=' and take a size as parameter, example: 'file_size<=5Mb'. The 'file_ext' test takes an
extension as parameter, example: 'file_ext=pst'. Finally, the 'file_match' and 'path_match' tests
take a regular expression as parameter, example: file_match=b$. 'file_match' is ran against the
filename (exemple 'file1') while 'path_match' is ran against the full path of the file (exemple:
'/home/test/file1'). A complete expression may look like '(file_size>=5Mb and file_size<=10Mb) and
(file_ext=pst or file_match=movies) and not file_ext=mp3'. There are some limitations though,
white-spaces and parentheses must be escaped inside a test either by quoting the expression or
escaping a given character: 'file_match="perso(nnal)?"', 'file_match=a filename'.
include_ext=[extension]
Extensions to include in the backup. Case insensitive. Nothing else will be included in the
backup. You can have multiple include extension lines. For example, set 'txt' to include files
that end in '.txt'. You need to specify an 'include' line so that burp knows where to start
looking.
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.
exclude_comp=[extension]
Extensions to exclude from compression. Case insensitive. You can have multiple exclude
compression lines. For example, set 'gz' to exclude gzipped files from compression.
exclude_fs=[fstype]
File systems to exclude from the backup. Case insensitive. You can have multiple exclude file
system lines. For example, set 'tmpfs' to exclude tmpfs. Burp has an internal mapping of file
system names to file system IDs. If you know the file system ID, you can use that instead. For
example, 'exclude_fs = 0x01021994' will also exclude tmpfs.
include_fs=[fstype]
File systems to include into the backup. Case insensitive. You can have multiple include file
system lines. For example, set 'ext4' to include ext4. Burp has an internal mapping of file system
names to file system IDs. If you know the file system ID, you can use that instead. For example,
'include_fs = 0x01021994' will also include tmpfs. If at least one file system is included, all
other filesystems will be excluded per default. Included directories that do not live on an
included file system will be skipped, even if cross_all_filesystems is enabled and they contain
subdirectories with included file systems.
Note that on SunOS systems include_fs and exclude_fs will do a case sensitive compare of the
string descriptors of the file systems instead of the numeric IDs (see f_basetype member is struct
statvfs).
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.
read_blockdev=[path]
Do not back up the given block device itself, but open it for reading and back up the contents as
if it were a regular file.
read_all_blockdevs=[0|1]
Open all block devices for reading and back up the contents as if they were regular files.
split_vss=[0|1]
When backing up Windows computers with burp protocol 1, this option allows you to save the VSS
header data separate from the file data. The default is off, which means that the VSS header data
is saved prepended to the file data. This option has no effect in protocol 2.
strip_vss=[0|1]
When backing up Windows computers with burp protocol 1, this option allows you to prevent the VSS
header data being backed up. The default is off. To restore a backup that has no VSS information
on Windows, you need to give the client the '-x' command line option. This option has no effect in
protocol 2.
vss_drives=[list of drive letters]
When backing up Windows computers, this option allows you to specify which drives have VSS
snapshots taken of them. If you omit this option, burp will automatically decide based on the
'include' options. If you want no drives to have snapshots taken of them, you can specify '0'.
acl=[0|1]
If acl support is compiled into burp, this allows you to decide whether or not to backup acls at
runtime. The default is '1'.
xattr=[0|1]
If xattr support is compiled into burp, this allows you to decide whether or not to backup xattrs
at runtime. The default is '1'.
atime=[0|1]
This allows you to control whether the client uses O_NOATIME when opening files and directories.
The default is 0, which enables O_NOATIME. This means that the client can read files and
directories without updating the access times. However, this is only possible if you are running
as root, or are the owner of the file or directory. If this is not the case (perhaps you only have
group or world access to the files), you will get errors until you set atime=1. With atime=1, the
access times will be updated on the files and directories that get backed up.
scan_problem_raises_error=[0|1]
When enabled, this causes problems in the phase1 scan (such as an 'include' being missing) to be
treated as fatal errors. The default is off.
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. Files beginning with '.' or ending with '~' are ignored. Directories are also ignored.
The file name must match the name in the 'cname' field on the client.
ssl_peer_cn=[string] must match the common name in the SSL certificate that the client gives when it
connects. If ssl_peer_cn is not set, the client name will be used instead (the clientconfdir file name).
The file needs to contain a line like password=[password] that matches the same field on the client, or
passwd=[hash] - where the plain text password on the client will be tested against a hash of the kind you
might find in /etc/passwd.
Additionally, the following options can be overridden here for each client:
enabled protocol directory client_lockdir directory_tree timestamp_format password_check keep
manual_delete working_dir_recovery_method librsync librsync_max_size version_warn path_length_warn
syslog client_can_delete client_can_force_backup client_can_list client_can_restore
client_can_verify restore_client compression hard_quota soft_quota label rblk_memory_max
fail_on_warning timer_script timer_arg notify_success_script notify_success_arg
notify_success_warnings_only notify_failure_script notify_failure_arg dedup_group
server_script_pre server_script_pre_arg server_script_pre_notify server_script_post
server_script_post_arg server_script_post_notify server_script server_script_arg
server_script_notify server_script_post_run_on_fail
Additionally, the includes and excludes can be overridden here, as described in the section above.
As with the other configuration files, extra configuration can be included with the '.
path/to/config/file' syntax.
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 network 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 zlib (gzip) format. You can use standard tools, such as
zcat, zless or cp, to view them or copy them elsewhere. Files from Windows backups will probably contain
VSS headers and/or footers. For help stripping these, see the vss_strip man page.
Server initiated backups
You can queue a backup on the server, to be performed when the client next makes contact. To do this, you
put a file called 'backup' into the top level of the client storage directory. The contents of the file
are ignored.
Server initiated restores
You can queue a restore on the server, to be performed when the client next makes contact. To do this,
you put a file called 'restore' into the top level of the client storage directory. The client can deny
server initiated restores by setting "server_can_restore=0" in its burp.conf. The client also needs to
specify 'restoreprefix' in its configuration as a destination for the restored files. Valid fields to
include in the restore file are:
orig_client=[client]
The original client to restore from. Equivalent to '-C' when initiating a restore from a client.
Do not include this line when restoring to the original client. See also the 'restore_client'
server option.
backup=[number|a]
The number of the backup to restore from. Equivalent to '-b' when initiating a restore from the
client.
overwrite=[0|1]
Whether to overwrite existing files. Equivalent to '-f' when initiating a restore from the client.
strip=[number]
Number of leading path components to strip. Equivalent to '-s' when initiating a restore from the
client.
restoreprefix=[path]
Appended to the client-side 'restoreprefix' setting, and then prefixed to the restore path.
stripfrompath=[string]
Strip matching string from restore paths (before prefix is prepended).
regex=[regular expression]
Only restore files matching the regular expression. Equivalent to '-r' when initiating a restore
from the client.
include=[path]
Restore directories and files that match the path. If it is a directory, the contents of the
directory will be restored. You can have multiple 'include' lines. There is no equivalent when
initiating a restore from the client.
SIGNALS
Sending signal 1 (HUP) to the main server process will cause it to reload. For the vast majority of
configuration changes, a reload is unnecessary as the server will pick up changes "on-the-fly". Sending
signal 12 (USR2) to the main server process will cause it to wait until there are no longer any child
processes, and then exit. The intention is to help with upgrades without interrupting current backups. if
you are running upstart, a new burp server process will start up when the old one exits.
RETURN CODES (SERVER)
0: success
1: error
RETURN CODES (CLIENT)
0: success
1: error
2: restore gave warnings
3: timer conditions on the server were not met
4: could not connect to server
BUGS
If you find bugs, please report them to the email list. See the website <http://burp.grke.net/> for
details.
AUTHOR
The main author of Burp is Graham Keeling.
COPYRIGHT
See the LICENCE file included with the source distribution.
Burp Burp(8)