BURP - BackUp and Restore Program

ABOUT
WHY
FEATURES
REQUESTS
CHANGELOG
PROTOCOL 1
PROTOCOL 2
NEWS
FAQ
DOCS
BURP-UI
DOWNLOAD
LICENCE
CONTRIBUTORS
DONATIONS
SPONSORS
CONTACT

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
       -a c   Run as a stand-alone champion chooser process (useful for debug‐
	      ging 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  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'.  If you intend to debug a protocol2 session, you will also
	      want to run a separate champion chooser process ('-a c' below).

       -Q     Do not log to stdout (overrides config file 'stdout' setting).

       -t     Dry-run mode to test config file syntax.

       -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   %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'
	      option.

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

       -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 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 compo‐
	      nents.

       -t     Dry-run mode to test config file syntax.

       -x     For Windows clients only - do not use the  Windows  VSS  API  on
	      restore.	Give  this option when you are restoring a backup that
	      contains no VSS information.

       -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 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 r -b 1 -r myregex
	      Restores all the files in backup number 1 that match the regular
	      expression 'myregex' back to their original location.

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

       burp -a r -b 1 -r myregex -d /tmp/restoredir -s 2
	      Restores all the files in backup number 1 that match the regular
	      expression  'myregex'  into  the	directory  /tmp/restoredir and
	      strip 2 leading path components.

       burp -a r
	      Restores all the files in the most recent backup to their origi‐
	      nal location.

       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 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 -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 -a d
	      Report the differences between the current backup and the backup
	      that will be made next. DIFF OPTIONS NOT FULLY IMPLEMENTED YET.

       burp -a D
	      A more verbose report of the  differences  between  the  current
	      backup and the backup that will be made next.

       burp -a d -b 1 -b 2
	      Report  the  differences	between  backups 1 and 2 (use -a D for
	      more verbosity).

       burp -a d -b 2 -b n
	      Report the differences between backup 1 and the backup that will
	      be made next (use -a D for more verbosity).

       burp -C altclient -a L
	      Long  list  the  top level directory of backup 1 on client 'alt‐
	      client'.

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

       burp -a s
	      Run the ncurses status monitor.

       burp -a S
	      Print a status monitor snapshot, summarising all clients.

       burp -a S -C testclient
	      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.

       address=[address]
	      Defines  the  main  TCP  address that the server listens on. The
	      default is either '::' or '0.0.0.0', dependent upon compile time
	      options.

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

       status_address=[address]
	      Defines the main TCP address that the server listens on for sta‐
	      tus requests. The default is either '::1' or '127.0.0.1', depen‐
	      dent upon compile time options.

       status_port=[port number]
	      Defines  the  TCP  port  that  the  server listens on for status
	      requests. Comment this out to have no status 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".

       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 con‐
	      figuration files in clientconfdir on the server.

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

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

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

       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.
	      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 set‐
	      ting.

       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 per‐
	      missive, 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 proba‐
	      bly 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  certifi‐
	      cate 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_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.

       max_status_children=[number]
	      Defines  the  number  of status child processes to
	      fork (the number of status clients that can simul‐
	      taneously connect. The default is 5.

       max_storage_subdirs=[number]
	      Defines  the  number of subdirectories in the data
	      storage areas. The maximum number  of  subdirecto‐
	      ries  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 argu‐
	      ments  are  reserved,  and  user	 arguments   are
	      appended	after  that.  An example timer script is
	      provided. The timer_script option can be	overrid‐
	      den  by  the client configuration files in client‐
	      confdir on the server.

       timer_arg=[string]
	      A user-definable argument to the timer script. You
	      can  have many of these. The timer_arg options can
	      be 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  five
	      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_suc‐
	      cess_changes_only are not turned on, success noti‐
	      fications 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_suc‐
	      cess_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 over‐
	      riddden  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	configu‐
	      ration 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	configu‐
	      ration 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 revo‐
	      cation 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 direc‐
	      tory 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.


CLIENT CONFIGURATION FILE OPTIONS
       . [glob]
	      Read  additional	configuration files. On Windows,
	      the glob is unimplemented - you will need to spec‐
	      ify 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 that the server is listening
	      on.

       cname=[password]
	      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.exam‐
	      ple.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 func‐
	      tion 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  cur‐
	      rently 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  Win‐
	      dows).

       group=[groupname]
	      Run  as  a particular group (not supported on Win‐
	      dows).

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

       network_timeout=[s]
	      Set the network timeout in seconds. If no data  is
	      sent  or	received  over	a period of this length,
	      burp will give up. The default is 7200 seconds  (2
	      hours).

       ca_burp_ca=[path]
	      Path  to	the  burp_ca script (burp_ca.bat on Win‐
	      dows). 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 certifi‐
	      cate 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 for‐
	      mat.

       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_restore=[0|1]
	      To  prevent  the	server from initiating restores,
	      set this to 0. The default is 1.

       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.

       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 point‐
	      less, since the smallest real  change  to  a  file
	      will  make  the  whole file look different. There‐
	      fore, activating this option turns off delta  dif‐
	      ferencing  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 unen‐
	      crypt 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  back‐
	      ups,  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 set‐
	      tings 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. The argu‐
	      ments 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.

       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 argu‐
	      ments 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 argu‐
	      ments  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.


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 multi‐
	      ple  include  lines.  Use forward slashes '/', not
	      backslashes '\' as path delimiters.

       exclude=[path]
	      Path to exclude from the backup. You can have mul‐
	      tiple  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/Docu‐
	      ments' if directories 'user1' and 'user2' exist in
	      '/home'.	The  Windows  implementation   currently
	      limit the expression to contain only one '*'.

       include_regex=[regular expression]
	      Not implemented.

       exclude_regex=[regular expression]
	      Exclude paths that match the regular expression.

       include_ext=[extension]
	      Extensions to include in the backup. Case insensi‐
	      tive. 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 insen‐
	      sitive.  You  can  have multiple exclude extension
	      lines. For example, set 'vdi' to exclude	Virtual‐
	      Box disk images.

       exclude_comp=[extension]
	      Extensions   to  exclude	from  compression.  Case
	      insensitive. You can have  multiple  exclude  com‐
	      pression	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,
	      'exclude_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_filesys‐
	      tems  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 speci‐
	      fied 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  con‐
	      tents 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 proto‐
	      col  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.

       strip_vss=[0|1]
	      When backing up Windows computers with burp proto‐
	      col  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' com‐
	      mand line option.

       vss_drives=[list of drive letters]
	      When  backing  up  Windows  computers, this option
	      allows you to specify which drives have VSS  snap‐
	      shots 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 xat‐
	      trs 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  directory_tree time‐
	      stamp_format  password_check  keep   manual_delete
	      working_dir_recovery_method  librsync 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 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 configura‐
       tion can be included  with  the	'.  path/to/config/file'
       syntax.


Some notes on SSL certificates
       The  burp  example configs come with example SSL certifi‐
       cates 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.  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 origi‐
	      nal  client.  See also the 'restore_client' server
	      option.

       backup=[number|a]
	      The number of the backup to restore from.  Equiva‐
	      lent  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. Equiv‐
	      alent to '-s' when initiating a restore  from  the
	      client.

       restoreprefix=[path]
	      Prefix  to  the  restore	path. Equivalent to '-d'
	      when initiating a restore from the client.

       stripfrompath=[string]
	      Strip matching string from restore  paths  (before
	      prefix is prepended).

       regex=[regular expression]
	      Only  restore  files  matching the regular expres‐
	      sion. 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  direc‐
	      tory  will  be  restored.  You  can  have multiple
	      'include' lines. There is no equivalent when  ini‐
	      tiating 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  configura‐
       tion  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  distribu‐
       tion.



				     Burp			       Burp(8)


Donate with Bitcoin

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


Burp, don't suck. Last updated: April 2017
By Graham Keeling
Hosted by Natcoweb