|
NOTE: The following is the latest version of the man page.
Some features may be different in the version of burp that you are using.
Burp(8) System Manager's Manual 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.
-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 pro‐
duce, 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'.
-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|R|l|L|p|v|V|delete|e|T|d|D]
Short for 'action'. The arguments mean backup, timed backup, re‐
store, Restore, list, long list, parseable list, verify, 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 %PROGRAM‐
FILES%\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'
and 'super_client' options.
-d [path]
Short for 'directory'. When restoring, the argument is a path to
an alternative directory to restore to. When listing, the argu‐
ment 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 pro‐
duce, and exit.
-q [max secs]
When running a timed backup, sleep for a random number of sec‐
onds (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 case sensitive
regular expression with which to match backup files. Use it for
lists, restores and verifies.
-R [regex]
Case insensitive alternative to '-r'.
-s [number]
For use with restores - strip a number of leading path compo‐
nents.
-t Dry-run mode to test config file syntax.
-v Log to stdout (overrides config file 'stdout' setting).
-x On restore, do not use the Windows VSS API, and strip out the
VSS data. Works both on Windows and non-Windows.
-X (Windows only)
On restore, do not use the Windows VSS API and do not attempt to
strip out the VSS data. Give this option when you are restoring
a backup that contains no 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.
ADDITIONAL CLIENT OPTIONS TO USE WITH '-a b'
-o seed_src=<directory> -o seed_dst=<directory>
Make a seeding backup. The source directory is replaced with the
destination directory on completion. Both paths need to be abso‐
lute. Your configured include paths need to be the same as the
source directory, or within the source directory. There must be
no other existing backups of the client running the seed job. A
use case might be to make an initial backup of a local hard
drive, and then to ship the hard drive to a remote location for
subsequent backups.
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 regu‐
lar 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 'alt‐
client'.
burp -a r -d /tmp/restoredir
Restores all the files in the most recent backup into the direc‐
tory /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 p -b 1
Lists all the files in backup number 1, in burp-parsable list
format. You may append something like '>/tmp/restore_list' to
send to a file, edit, then use as an input for restoring. As in
the following command:
burp -a r -b 1 -o restore_list=/tmp/restore_list
Restores from backup 7, matching the list of files given in
/tmp/restore_list. The files given must be ordered as they would
be in the output of a burp list command.
burp -a p -b 6 | burp -a R -b 7
Restores from backup 7, matching the list of files on standard
input, which is provided by burp's list of backup 6 ('-a R' is
shorthand for '-a r -o restore_list=-').
burp -a p -b 6 | burp -a V -b 7
Verifies from backup 7, matching the list of files on standard
input, which is provided by burp's list of backup 6 ('-a V' is
shorthand for '-a v -o restore_list=-').
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. Specify multiple 'listen' entries on separate lines in order
to listen on multiple addresses and ports. Each pair can be con‐
figured 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_sta‐
tus_children' value. Comment out to have no status server.
network_allow=[string]
Allows access for the specified network or address. For example:
'::1' or '127.0.0.1/8'. Specify multiple 'network_allow' entries
on separate lines to allow multiple networks or addresses. If
this option is not given, all networks are allowed. This option
can be overridden by the client configuration files in client‐
confdir on the server.
network_allow_status=[string]
Allows access for the specified network or address to the status
server. For example: '::1' or '127.0.0.1/8'. Specify multiple
'network_allow' entries on separate lines to allow multiple net‐
works or addresses. If this option is not given, all networks
are allowed. This option can be overridden by the client config‐
uration files in clientconfdir on the server.
cname_lowercase=[0|1]
Whether to force lowercase cname when looking-up in client‐
confdir. 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 authenticat‐
ing 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 ver‐
sion 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 indi‐
vidual backups. See 'man strftime' to see available substitu‐
tions. 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 de‐
fault is on. SSL certificates will still be checked if you turn
passwords off. This option can be overridden by the client con‐
figuration files in clientconfdir on the server.
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.
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 client‐
confdir 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 exam‐
ple, 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 your‐
self. 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). 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 re‐
duced.
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 de‐
fault 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 op‐
tion is off. This option can be overridden by the client config‐
uration files in clientconfdir on the server.
compression=zlib[0-9] (or gzip[0-9])
Choose the level of zlib compression for files stored in back‐
ups. 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. Ex‐
ample: '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' op‐
tion.
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.
readall=[0|1]
Keep readall capability when dropping root privileges (default
0). When enabled changes default atime to 1.
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 re‐
ceived 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 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.
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 automati‐
cally 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 back‐
ups. 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. Re‐
store 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. Re‐
store clients can override this setting.
client_can_monitor=[0|1]
Turn this off to prevent clients from being able to run the sta‐
tus monitor. The default is that clients can run the status mon‐
itor. 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 re‐
stores. 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.
super_client=[client]
A client that is permitted to list, verify, restore, delete, and
diff files belonging to any other client, according to the su‐
per_client's client_can permissions (eg, 'client_can_list'). You
may specify multiple super_clients. If this is too permissive,
you may set a super_client for individual original clients in
the individual clientconfdir files, or look at the 're‐
store_client' option.
restore_client=[client]
A client that is permitted to list, verify, restore, delete, and
diff files belonging to any other client, according to the
client_can permissions on both the restore_client and the origi‐
nal_client (eg, 'client_can_list'). You may specify multiple re‐
store_clients. If this is too permissive, you may set a re‐
store_client for individual original clients in the individual
clientconfdir 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. 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_parallel_backups=[number]
Defines the number of max parallel backups (the number of
clients that are in a "working" state). The default is 0 - un‐
limited.
max_children=[number]
Defines the number of child processes to fork (the number of
clients that can simultaneously connect. The default is 5. Spec‐
ify 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 exam‐
ple 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.
timer_repeat_interval=[m]
During a timed backup, the timer script can be run at regular
intervals. If the client is out of timeband, the backup will be
interrupted. For example, setting 5 will cause burp to check ev‐
ery five minutes. The default is 0, which means that the script
will only run once at the start of the backup.
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 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 when there were warnings.
If this and notify_success_changes_only are not turned on, suc‐
cess 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.
notify_failure_on_backup_with_failovers_left=[0|1]
In the case where there are server_failover entries left to try,
you may not wish to notify on backup failure. The default is on.
notify_failure_on_backup_working_dir_deletion=[0|1]
On the next backup attempt after a backup was interrupted, it
may not be possible to resume the previous backup. In this case
(or if working_dir_recovery_method is 'delete'), the previous
backup will be deleted. You may wish to be notified about this.
The default is off.
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 gen‐
erated. Requires the notify_failure options to be set.
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)',
'(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 op‐
tions 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 re‐
lated 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 in‐
cluded in the email. The default is off. Requires the no‐
tify_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 down‐
loaded. 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 config‐
uration file will usually be /etc/burp/CA.cnf. The CA direc‐
tory 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 overwrit‐
ten. 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 certificates
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 re‐
vocation 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. Dis‐
advantage: 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 arbitrary
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 con‐
figuration 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 overridden 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=[host:port]
Defines the server to connect to. If you don't specify a port
here, you will need to specify it separately.
server_failover=[host:port]
Defines a failover server to connect to. You can provide more
than one 'server_failover' entry. The client will try the next
failover server if it fails to connect. IMPORTANT: The burp
client currently does not have the capability to have a differ‐
ent SSL profile for each server, so for this to work for you,
you will need to have the same CA and certificates on each
server.
failover_on_backup_error=[0|1]
Failover to failover servers on backup errors as well as fail‐
ures to connect. The default is off.
port=[port]
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]
Defines the TCP port on the server that we will send backup re‐
quests to. If not set, it defaults to the port option.
port_restore=[port]
Defines the TCP port on the server that we will send restore re‐
quests to. If not set, it defaults to the port option.
port_verify=[port]
Defines the TCP port on the server that we will send verify re‐
quests to. If not set, it defaults to the port_restore option.
port_list=[port]
Defines the TCP port on the server that we will send list re‐
quests to. If not set, it defaults to the port option.
port_delete=[port]
Defines the TCP port on the server that we will send delete re‐
quests to. If not set, it defaults to the port option.
status_port=[port]
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 automati‐
cally (ie. no cname provided above). The default is 0. When set
to 1 the name returned by the get_fqdn function will be lower‐
cased.
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').
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 can‐
not 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 sec‐
onds (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 re‐
ceived 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 con‐
tain 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 in‐
clude/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 set‐
ting is required if you are using server initiated restores.
encryption_password=[password]
Set this to enable client side file AES-CBC-256 encryption. If
you do not want encryption, leave this field out of your config
file. IMPORTANT: Configuring an encryption_password renders
delta differencing pointless, since the smallest real change to
a file will make the whole file look different. Therefore, acti‐
vating 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 en‐
cryption 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. Take care when copying and pasting special characters
between client conf files, as the encoding of the config file
matters. 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 de‐
fined by backup_script_pre_arg - unless the option
'backup_script_reserved_args' is off, then only arguments de‐
fined 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_re‐
served_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 de‐
fined by restore_script_pre_arg - unless the option 're‐
store_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 re‐
store_script_post_arg - unless the option 'restore_script_re‐
served_args' is off, then only arguments defined by re‐
store_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 re‐
store_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 de‐
fault 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 de‐
fault is on.
autoupgrade_dir=[path]
Path to autoupgrade directory into which upgrades are down‐
loaded. 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 mon‐
itor 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=' or
'include_glob=' 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 de‐
limiters.
exclude=[path]
Path to exclude from the backup. You can have multiple exclude
lines. Use forward slashes '/', not backslashes '\' as path de‐
limiters.
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 limits the ex‐
pression to contain only one '*', with one exception - you may
also specify '*:' to expand to detected fixed drives.
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 'in‐
clude_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 ex‐
pression' may contain several tests chained with boolean opera‐
tors. 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 pa‐
rameter, example: 'file_ext=pst'. Finally, the 'file_match' and
'path_match' tests take a regular expression as parameter, exam‐
ple: file_match=b$. 'file_match' is ran against the filename
(example 'file1') while 'path_match' is ran against the full
path of the file (example: '/home/test/file1'). A complete ex‐
pression 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 es‐
caping 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 in‐
clude 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 sys‐
tem 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. Ex‐
ample: '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 content of 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, this option allows you to
save the VSS header data separate from the file data. The de‐
fault is off, which means that the VSS header data is saved
prepended to the file data.
strip_vss=[0|1]
When backing up Windows computers, 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.
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 de‐
cide 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 de‐
cide 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 en‐
ables 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:
client_can_delete client_can_force_backup client_can_list
client_can_monitor client_can_restore client_can_verify
client_lockdir compression dedup_group directory directory_tree
enabled fail_on_warning hard_quota keep label librsync li‐
brsync_max_size manual_delete network_allow network_allow_status
notify_failure_arg notify_failure_on_backup_with_failovers_left
notify_failure_on_backup_working_dir_deletion notify_fail‐
ure_script notify_success_arg notify_success_script notify_suc‐
cess_warnings_only password_check path_length_warn rblk_mem‐
ory_max restore_client server_script_arg server_script
server_script_notify server_script_post_arg server_script_post
server_script_post_notify server_script_post_run_on_fail
server_script_pre_arg server_script_pre server_script_pre_notify
soft_quota super_client syslog timer_arg timer_repeat_interval
timer_script timestamp_format version_warn working_dir_recov‐
ery_method
Additionally, the includes and excludes can be overridden here, as de‐
scribed in the section above.
As with the other configuration files, extra configuration can be in‐
cluded 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 ap‐
plied 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 're‐
store_client' and 'super_client' server options.
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 un‐
necessary as the server will pick up changes "on-the-fly". Sending sig‐
nal 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
5: max parallel backups reached
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)
|
