1Burp(8) System Manager's Manual Burp(8)
2
6 Burp - BackUp and Restore Program
7
9 burp [OPTIONS]
10
12 BackUp and Restore Program.
13
16 -a c Run as a stand-alone champion chooser process (useful for debug‐
17 ging protocol2 style backups).
18 -c [path]
20 Short for 'config file'. The argument is a path to the config
21 file. The default is /etc/burp/burp.conf.
22 -F Foreground mode. The server will fork into the background and
24 run as a daemon if you do not give this option.
25 -g Generate initial CA keys and certificates, and then exit.
27 -h Print help and then exit.
29 -? Print help and then exit.
31 -i Print an index table of symbols that humans may see burp pro‐
33 duce, and exit.
34 -n No forking mode. The program will accept a single query, deal
36 with it, and then exit. This is useful for debugging. Implies
37 '-F'. If you intend to debug a protocol2 session, you will also
38 want to run a separate champion chooser process ('-a c' below).
39 -Q Do not log to stdout (overrides config file 'stdout' setting).
41 -t Dry-run mode to test config file syntax.
43 -v Print version and exit.
45 ADDITIONAL SERVER OPTIONS TO USE WITH '-a c'
47 -C [client]
49 Run as if forked via a connection from this client.
50
53 -a [b|t|r|l|L|v|delete|e|T|d|D]
54 Short for 'action'. The arguments mean backup, timed backup,
55 restore, list, long list, verify, delete, estimate, timer check,
56 diff, or long diff, respectively.
57 -b [number|a]
59 Short for 'backup number'. The argument is a number, or 'a' to
60 select all backups.
61 -c [path]
63 Short for 'config file'. The argument is a path to the config
64 file. The default is /etc/burp/burp.conf, or %PROGRAM‐
65 FILES%\Burp\burp.conf on Windows.
66 -C [client]
68 Allows you to specify an alternative client to list or restore
69 from. Requires that the server configuration of the alternative
70 client permits your client to do this. See the 'restore_client'
71 option.
72 -d [path]
74 Short for 'directory'. When restoring, the argument is a path to
75 an alternative directory to restore to. When listing, the argu‐
76 ment is the directory to list.
77 -f Short for 'force overwrite'. Without this option set, a restore
79 will not overwrite existing files.
80 -h Print help and then exit.
82 -? Print help and then exit.
84 -i Print an index table of symbols that humans may see burp pro‐
86 duce, and exit.
87 -q [max secs]
89 When running a timed backup, sleep for a random number of sec‐
90 onds (between 0 and the number given) before contacting the
91 server. Alternatively, this can be specified by the 'randomise'
92 configuration file option.
93 -Q Do not log to stdout (overrides config file 'stdout' setting).
95 -r [regex]
97 Short for 'regular expression'. The argument is a regular
98 expression with which to match backup files. Use it for lists
99 and restores.
100 -s [number]
102 For use with restores - strip a number of leading path compo‐
103 nents.
104 -t Dry-run mode to test config file syntax.
106 -x (on Windows)
108 On restore, do not use the Windows VSS API on restore - give
109 this option when you are restoring a backup that contains no VSS
110 data.
111 -x (on non-Windows)
113 On restore, strip the Windows VSS data - give this option when
114 you are restoring a backup that contains VSS data.
115 -a s Run this to connect to a running server to get a live monitor of
117 the status of all your backup clients. The live monitor requires
118 ncurses support at compile time.
119 -a S Similar to '-a s', but it prints the main status monitor summary
121 screen to stdout. One application is that a script can run this
122 and email an administrator the output on a cron job. This
123 doesn't require ncurses support. There are additional options
124 that can be given with both these options, listed below.
125 ADDITIONAL CLIENT OPTIONS TO USE WITH '-a s' and '-a S'
128 -C [client]
130 Limit the output to a single client.
131 -b [number]
133 Show listable files in a particular backup (requires -C).
134 -z [file]
136 Dump a particular log file in a backup (requires -C and -b).
137 -d [path]
139 Show a particular path in a backup (requires -C and -b).
140 -l [path]
142 Log file for status monitor - useful for debugging.
143
146 burp -a b
147 Runs a backup.
148 burp -a l
150 Lists the available backups and dates.
151 burp -a l -b 1
153 Lists all the files in backup number 1.
154 burp -a l -b a
156 Lists all the files in all the backups.
157 burp -a l -b c
159 Lists all the files in the current backup.
160 burp -a l -b 1 -r myregex
162 Lists all the files in backup number 1 that match the regular
163 expression 'myregex'.
164 burp -a L -b 1 -r myregex
166 Long lists all the files in backup number 1 that match the regu‐
167 lar expression 'myregex'. This is like doing an 'ls -l'.
168 burp -a r -b 1 -r myregex
170 Restores all the files in backup number 1 that match the regular
171 expression 'myregex' back to their original location.
172 burp -a r -b 1 -r myregex -d /tmp/restoredir
174 Restores all the files in backup number 1 that match the regular
175 expression 'myregex' into the directory /tmp/restoredir.
176 burp -a r -b 1 -r myregex -d /tmp/restoredir -s 2
178 Restores all the files in backup number 1 that match the regular
179 expression 'myregex' into the directory /tmp/restoredir and
180 strip 2 leading path components.
181 burp -a r
183 Restores all the files in the most recent backup to their origi‐
184 nal location.
185 burp -a v
187 Verifies the most recent backup.
188 burp -a v -b 1 -r myregex
190 Verifies everything in backup number 1 that matches the regular
191 expression 'myregex'.
192 burp -a delete -b 1
194 Deletes backup number 1. Note that burp will not delete backup
195 directories that other backup directories depend upon.
196 burp -a t
198 Timed backup. The same as 'burp -a b', except that a script is
199 run on the server before deciding to go ahead. The intention is
200 that this command will be run on a repeating cron job with a
201 short interval, and that the server will decide when it is time
202 for a new backup.
203 burp -a L -b 1 -d ''
205 Long list the top level directory of backup 1.
206 burp -a L -b 1 -d '/home/graham'
208 Long list the /home/graham directory of backup 1. These '-d'
209 versions of the list function provide the ability to 'browse'
210 backups.
211 burp -a d
213 Report the differences between the current backup and the backup
214 that will be made next. DIFF OPTIONS NOT FULLY IMPLEMENTED YET.
215 burp -a D
217 A more verbose report of the differences between the current
218 backup and the backup that will be made next.
219 burp -a d -b 1 -b 2
221 Report the differences between backups 1 and 2 (use -a D for
222 more verbosity).
223 burp -a d -b 2 -b n
225 Report the differences between backup 1 and the backup that will
226 be made next (use -a D for more verbosity).
227 burp -C altclient -a L
229 Long list the top level directory of backup 1 on client 'alt‐
230 client'.
231 burp -C altclient -a r -b 1 -r myregex -d /tmp/restoredir
233 Restores all the files in backup number 1 from client 'alt‐
234 client' that match the regular expression 'myregex' into the
235 directory /tmp/restoredir.
236 burp -a s
238 Run the ncurses status monitor.
239 burp -a S
241 Print a status monitor snapshot, summarising all clients.
242 burp -a S -C testclient
244 Print a status monitor snapshot, showing client 'testclient'
245 only.
246
249 . [glob]
250 Read additional configuration files.
251 mode=server
253 Required to run in server mode.
254 address=[address]
256 Defines the main TCP address that the server listens on. The
257 default is either '::' or '0.0.0.0', dependent upon compile time
258 options.
259 port=[port number]
261 Defines the main TCP port that the server listens on. Specify
262 multiple 'port' entries on separate lines in order to listen on
263 multiple ports. Each port can be configured with its own
264 'max_children' value.
265 status_address=[address|localhost]
267 Defines the main TCP address that the server listens on for sta‐
268 tus requests. The default is special value 'localhost' that
269 includes both '::1' (if available) and '127.0.0.1' (always).
270 status_port=[port number]
272 Defines the TCP port that the server listens on for status
273 requests. Comment this out to have no status server. Specify
274 multiple 'status_port' entries on separate lines in order to
275 listen on multiple ports. Each port can be configured with its
276 own 'max_status_children' value.
277 cname_lowercase=[0|1]
279 Whether to force lowercase cname when looking-up in client‐
280 confdir. This also affects the fqdn lookup on the client (see
281 client configuration options for details). The default is 0.
282 When set to 1 the name provided by the client while authenticat‐
283 ing will be lowercased.
284 cname_fqdn=[0|1]
286 Whether to keep fqdn cname (like 'testclient.example.com') when
287 looking-up in clientconfdir. This also affects the fqdn lookup
288 on the client (see client configuration options for details).
289 The default is 1. When set to 0, the fqdn provided by the client
290 while authenticating will be stripped ('testclient.example.com'
291 becomes 'testclient').
292 daemon=[0|1]
294 Whether to daemonise. The default is 1.
295 fork=[0|1]
297 Whether to fork children. The default is 1.
298 directory=[path]
300 Path to the directory in which to store backups.
301 directory_tree=[0|1]
303 When turned on (which is the default) and the client is on ver‐
304 sion 1.3.6 or greater, the structure of the storage directory
305 will mimic that of the original filesystem on the client.
306 timestamp_format=[strftime format]
308 This allows you to tweak the format of the timestamps of indi‐
309 vidual backups. See 'man strftime' to see available substitu‐
310 tions. If this option is unset, burp uses "%Y-%m-%d %H:%M:%S
311 %z".
312 password_check=[0|1]
314 Allows you to turn client password checking on or off. The
315 default is on. SSL certificates will still be checked if you
316 turn passwords off. This option can be overridden by the client
317 configuration files in clientconfdir on the server.
318 clientconfdir=[path]
320 Path to the directory that contains client configuration files.
321 protocol=[0|1|2]
323 Choose which style of backups and restores to use. 0 (the
324 default) automatically decides based on the client version and
325 which protocol is set on the client side. 1 forces protocol1
326 style (file level granularity with a pseudo mirrored storage on
327 the server and optional rsync). 2 forces protocol2 style (inline
328 deduplication with variable length blocks). If you choose a
329 forced setting, it will be an error if the client also chooses a
330 forced setting. This option can be overridden by the client con‐
331 figuration files in clientconfdir on the server.
332 lockfile=[path]
334 Path to the lockfile that ensures that two server processes can‐
335 not run simultaneously.
336 pidfile=[path]
338 Synonym for lockfile.
339 syslog=[0|1]
341 Log to syslog. Defaults to off.
342 stdout=[0|1]
344 Log to stdout. Defaults to on.
345 keep=[number]
347 Number of backups to keep. This can be overridden by the client‐
348 confdir configuration files in clientconfdir on the server.
349 Specify multiple 'keep' entries on separate lines in order to
350 keep multiple periods of backups. For example, assuming that you
351 are doing a backup a day, keep=7 keep=4 keep=6 (on separate
352 lines) will keep 7 daily backups, 4 weekly backups (7x4=28), and
353 6 multiples of 4 weeks (7x4x6=168) - roughly 6 monthly backups.
354 Effectively, you will be guaranteed to be able to restore up to
355 168 days ago, with the number of available backups exponentially
356 decreasing as you go back in time to that point. In this exam‐
357 ple, every 7th backup will be hardlinked to allow burp to safely
358 delete intermediate backups when necessary. You can have as many
359 'keep' lines as you like, as long as they don't exceed 52560000
360 when multiplied together. That is, a backup every minute for 100
361 years.
362 manual_delete=[path]
364 This can be overridden by the clientconfdir configuration files
365 in clientconfdir on the server. When the server needs to delete
366 old backups, or rubble left over from generating reverse patches
367 with librsync=1, it will normally delete them in place. If you
368 use the 'manual_delete' option, the files will be moved to the
369 path specified for deletion at a later point. You will then need
370 to configure a cron job, or similar, to delete the files your‐
371 self. Do not specify a path that is not on the same filesystem
372 as the client storage directory.
373 hardlinked_archive=[0|1]
375 On the server, defines whether to keep hardlinked files in the
376 backups, or whether to generate reverse deltas and delete the
377 original files. Can be set to either 0 (off) or 1 (on). Disad‐
378 vantage: More disk space will be used Advantage: Restores will
379 be faster, and since no reverse deltas need to be generated, the
380 time and effort the server needs at the end of a backup is
381 reduced.
382 max_hardlinks=[number]
384 On the server, the number of times that a single file can be
385 hardlinked. The bedup program also obeys this setting. The
386 default is 10000.
387 librsync=[0|1]
389 When set to 0, delta differencing will not take place. That is,
390 when a file changes, the server will request the whole new file.
391 The default is 1. This option can be overridden by the client
392 configuration files in clientconfdir on the server.
393 librsync_max_size=[B/KB/MB/GB]
395 Only use librsync when a file is less than the given size. Both
396 the most recently backed up version of a file and the version to
397 be backed up are checked. The default is 0, which means the
398 option is off. This option can be overridden by the client con‐
399 figuration files in clientconfdir on the server.
400 compression=zlib[0-9] (or gzip[0-9])
402 Choose the level of zlib compression for files stored in back‐
403 ups. Setting 0 or zlib0 turns compression off. The default is
404 zlib9. This option can be overridden by the client configuration
405 files in clientconfdir on the server. 'gzip' is a synonym of
406 'zlib'.
407 hard_quota=[B/KB/MB/GB]
409 Do not back up the client if the estimated size of all files is
410 greater than the specified size. Example: 'hard_quota = 100GB'.
411 Set to 0 (the default) to have no limit.
412 soft_quota=[B/KB/MB/GB]
414 A warning will be issued when the estimated size of all files is
415 greater than the specified size and smaller than hard_quota.
416 Example: 'soft_quota = 95GB'. Set to 0 (the default) to have no
417 warning.
418 version_warn=[0|1]
420 When this is on, which is the default, a warning will be issued
421 when the client version does not match the server version. This
422 option can be overridden by the client configuration files in
423 clientconfdir on the server.
424 path_length_warn=[0|1]
426 When this is on, which is the default, a warning will be issued
427 when the client sends a path that is too long to replicate in
428 the storage area tree structure. The file will still be saved in
429 a numbered file outside of the tree structure, regardless of the
430 setting of this option. This option can be overridden by the
431 client configuration files in clientconfdir on the server.
432 client_lockdir=[path]
434 Path to the directory in which to keep per-client lock files. By
435 default, this is set to the path given by the 'directory'
436 option.
437 user=[username]
439 Run as a particular user. This can be overridden by the client
440 configuration files in clientconfdir on the server.
441 group=[groupname]
443 Run as a particular group. This can be overridden by the client
444 configuration files in clientconfdir on the server.
445 umask=[umask]
447 Set the file creation umask. Default is 0022.
448 ratelimit=[Mb/s]
450 Set the network send rate limit, in Mb/s. If this option is not
451 given, burp will send data as fast as it can. If you want the
452 server's sending speed to be limited, you will also need to set
453 this option on the server side.
454 network_timeout=[s]
456 Set the network timeout in seconds. If no data is sent or
457 received over a period of this length, burp will give up. The
458 default is 7200 seconds (2 hours).
459 working_dir_recovery_method=[resume|delete]
461 This option tells the server what to do when it finds the work‐
462 ing directory of an interrupted backup (perhaps somebody pulled
463 the plug on the server, or something). This can be overridden by
464 the client configurations files in clientconfdir on the server.
465 Options are...
466 delete: Just delete the old working directory.
468 resume: Continue the previous backup from the point at which it left
470 off. NOTE: If the client has changed its include/exclude configuration
471 since the backup was interrupted, the recovery method will automati‐
472 cally switch to 'delete'.
473 client_can_delete=[0|1]
475 Turn this off to prevent clients from deleting backups with the
476 '-a delete' option. The default is that clients can delete back‐
477 ups. Restore clients can override this setting.
478 client_can_diff=[0|1]
480 Turn this off to prevent clients from diffing backups with the
481 '-a d' option. The default is that clients can diff backups.
482 Restore clients can override this setting.
483 client_can_force_backup=[0|1]
486 Turn this off to prevent clients from forcing backups
487 with the '-a b' option. Timed backups will still work.
488 The default is that clients can force backups.
489 client_can_list=[0|1]
491 Turn this off to prevent clients from listing backups
492 with the '-a l' option. The default is that clients can
493 list backups. Restore clients can override this setting.
494 client_can_restore=[0|1]
496 Turn this off to prevent clients from initiating restores
497 with the '-a r' option. The default is that clients can
498 initiate restores. Restore clients can override this set‐
499 ting.
500 client_can_verify=[0|1]
502 Turn this off to prevent clients from initiating a verify
503 job with the '-a v' option. The default is that clients
504 can initiate a verify job. Restore clients can override
505 this setting.
506 restore_client=[client]
508 A client that is permitted to list, verify, restore,
509 delete, and diff files belonging to any other client. You
510 may specify multiple restore_clients. If this is too per‐
511 missive, you may set a restore_client for individual
512 original clients in the individual clientconfdir files.
513 Note that restoring a backup from a Windows computer onto
514 a Linux computer will currently leave the VSS headers in
515 place at the beginning of each file. This will be
516 addressed in a future version of burp.
517 ssl_cert_ca=[path]
519 The path to the SSL CA certificate. This file will proba‐
520 bly be the same on both the server and the client. The
521 file should contain just the certificate in PEM format.
522 For more information on this, and the other ssl_*
523 options, please see docs/burp_ca.txt.
524 ssl_cert=[path]
526 The path to the server SSL certificate. It works for me
527 when the file contains the concatenation of the certifi‐
528 cate and private key in PEM format.
529 ssl_key=[path]
531 The path to the server SSL private key in PEM format.
532 ssl_key_password=[password]
534 Only needed for loading an encrypted certificate.
535 ssl_cert_password=[password]
537 Synonym for ssl_key_password.
538 ssl_ciphers=[cipher list]
540 Allowed SSL ciphers. See openssl ciphers for details.
541 ssl_compression=zlib[0|5] (or gzip[0|5])
543 Choose the level of zlib compression over SSL. Setting 0
544 or zlib0 turns SSL compression off. Setting non-zero
545 gives zlib5 compression (it is not currently possible for
546 openssl to set any other level). The default is 5. 'gzip'
547 is a synonym of 'zlib'.
548 ssl_dhfile=[path]
551 Path to Diffie-Hellman parameter file. To generate
552 one with openssl, use a command like this: openssl
553 dhparam -dsaparam -out dhfile.pem 2048
554 max_children=[number]
556 Defines the number of child processes to fork (the
557 number of clients that can simultaneously connect.
558 The default is 5. Specify multiple 'max_children'
559 entries on separate lines if you have configured
560 multiple port entries.
561 max_status_children=[number]
563 Defines the number of status child processes to
564 fork (the number of status clients that can simul‐
565 taneously connect. The default is 5. Specify mul‐
566 tiple 'max_status_children' entries on separate
567 lines if you have configured multiple status_port
568 entries.
569 max_storage_subdirs=[number]
571 Defines the number of subdirectories in the data
572 storage areas. The maximum number of subdirecto‐
573 ries that ext3 allows is 32000. If you do not set
574 this option, it defaults to 30000.
575 timer_script=[path]
577 Path to the script to run when a client connects
578 with the timed backup option. If the script exits
579 with code 0, a backup will run. The first three
580 arguments are the client name, the path to the
581 'current' storage directory, and the path to the
582 top level storage directories. The next two argu‐
583 ments are reserved, and user arguments (see
584 timer_arg) are appended after that. An example
585 timer script is provided. The timer_script option
586 can be overridden by the client configuration
587 files in clientconfdir on the server. If this
588 option is not set, equivalent code internal to
589 Burp will be run instead. The internal code also
590 uses the timer_arg parameters.
591 timer_arg=[string]
593 A user-definable argument to the timer script. You
594 can have many of these. The timer_arg options can
595 be overridden by the client configuration files in
596 clientconfdir on the server.
597 notify_success_script=[path]
599 Path to the script to run when a backup succeeds.
600 User arguments are appended after the first five
601 reserved arguments. An example notify script is
602 provided. The notify_success_script option can be
603 overriddden by the client configuration files in
604 clientconfdir on the server.
605 notify_success_arg=[string]
607 A user-definable argument to the notify success
608 script. You can have many of these. The
609 notify_success_arg options can be overriddden by
610 the client configuration files in clientconfdir on
611 the server.
612 notify_success_warnings_only=[0|1]
614 Set to 1 to send success notifications when there
615 were warnings. If this and notify_suc‐
616 cess_changes_only are not turned on, success noti‐
617 fications are always sent.
618 notify_success_changes_only=[0|1]
620 Set to 1 to send success notifications when there
621 were new or changed files. If this and notify_suc‐
622 cess_warnings_only are not turned on, success
623 notifications are always sent.
624 notify_failure_script=[path]
626 The same as notify_success_script, but for backups
627 that failed.
628 notify_failure_arg=[string]
630 The same as notify_success_arg, but for backups
631 that failed.
632 dedup_group=[string]
634 Enables you to group clients together for file
635 deduplication purposes. For example, you might
636 want to set 'dedup_group=xp' for each Windows XP
637 client, and then run the bedup program on a cron
638 job every other day with the option '-g xp'.
639 server_script_pre=[path]
641 Path to a script to run on the server after each
642 successfully authenticated connection but before
643 any work is carried out. The arguments to it are
644 'pre', '(client command)', '(client name)', '(0 or
645 1 for success or failure)', '(timer script exit
646 code)', and then arguments defined by
647 server_script_pre_arg. If the script returns non-
648 zero, the task asked for by the client will not be
649 run. This command and related options can be over‐
650 riddden by the client configuration files in
651 clientconfdir on the server.
652 server_script_pre_arg=[string]
654 A user-definable argument to the server pre
655 script. You can have many of these.
656 server_script_pre_notify=[0|1]
658 Turn on to send a notification email when the
659 server pre script returns non-zero. The output of
660 the script will be included in the email. The
661 default is off. Most people will not want this
662 turned on because clients usually contact the
663 server at 20 minute intervals and this could cause
664 a lot of emails to be generated. Requires the
665 notify_failure options to be set.
666 server_script_post=[path]
668 Path to a script to run on the server before the
669 client disconnects. The arguments to it are
670 'post', '(client command)', '(client name), '(0 or
671 1 for success or failure)', '(timer script exit
672 code)', and then arguments defined by
673 server_script_post_arg. This command and related
674 options can be overriddden by the client configu‐
675 ration files in clientconfdir on the server.
676 server_script_post_arg=[string]
678 A user-definable argument to the server post
679 script. You can have many of these.
680 server_script_post_notify=[0|1]
682 Turn on to send a notification email when the
683 server post script returns non-zero. The output of
684 the script will be included in the email. The
685 default is off. Requires the notify_failure
686 options to be set.
687 server_script=[path]
689 You can use this to save space in your config file
690 when you want to run the same server script twice.
691 It overrides server_script_pre and
692 server_script_post. This command and related
693 options can be overriddden by the client configu‐
694 ration files in clientconfdir on the server.
695 server_script_arg=[path]
697 Goes with server_script and overrides
698 server_script_pre_arg and server_script_post_arg.
699 server_script_notify=[0|1]
701 Turn on to send notifications email when the
702 server pre and post scripts return non-zero. The
703 output of the script will be included in the
704 email. The default is off. Requires the
705 notify_failure options to be set.
706 server_script_post_run_on_fail=[0|1]
708 If this is set to 1, server_script_post will
709 always be run. The default is 0, which means that
710 if the task asked for by the client fails,
711 server_script_post will not be run.
712 autoupgrade_dir=[path]
714 Path to autoupgrade directory from which upgrades
715 are downloaded. The option can be left unset in
716 order not to autoupgrade clients. Please see
717 docs/autoupgrade.txt in the source package for
718 more help with this option.
719 ca_conf=[path]
721 Path to certificate authority configuration file.
722 The CA configuration file will usually be
723 /etc/burp/CA.cnf. The CA directory indicated by
724 CA.cnf will usually be /etc/burp/CA. If ca_conf is
725 set and the CA directory does not exist, the
726 server will create, populate it, and the paths
727 indicated by ssl_cert_ca, ssl_cert, ssl_key and
728 ssl_dhfile will be overwritten. For more detailed
729 information on this and the other ca_* options,
730 please see docs/burp_ca.txt.
731 ca_name=[name]
733 Name of the CA that the server will generate when
734 using the ca_conf option.
735 ca_server_name=[name]
737 The name that the server will put into its own SSL
738 certficates when using the ca_conf option.
739 ca_burp_ca=[path]
741 Path to the burp_ca script when using the ca_conf
742 option.
743 ca_crl=[path]
745 Override the default path to the certificate revo‐
746 cation list.
747 ca_crl_check=[0|1]
749 Whether to check for revoked certificates in the
750 certificate revocation list.
751 monitor_browse_cache=[0|1]
753 Whether or not the server should cache the direc‐
754 tory tree when a monitor client is browsing.
755 Advantage: browsing is faster. Disadvantage: more
756 memory is used.
757 label=[string]
759 You can have multiple labels, and they can be
760 overridden in the client configuration files in
761 clientconfdir on the server. They will appear as
762 an array of strings in the server status monitor
763 JSON output. The idea is to provide a mechanism
764 for arbirtrary values to be passed to clients of
765 the server status monitor.
766 enabled=[0|1]
768 Set this to 0 if you want to disable all clients.
769 The default is 1. This option can be overridden
770 per-client in the client configuration files in
771 clientconfdir on the server.
772 rblk_memory_max=[b/Kb/Mb/Gb]
774 The maximum amount of data from the disk cached in
775 server memory during a protocol2 restore/verify.
776 The default is 256Mb. This option can be overriden
777 per-client in the client configuration files in
778 clientconfdir on the server.
779
782 . [glob]
783 Read additional configuration files. On Windows,
784 the glob is unimplemented - you will need to spec‐
785 ify an actual file.
786 mode=client
788 Required to run in client mode.
789 server=[IP address or hostname]
791 Defines the server to connect to.
792 port=[port number]
794 Defines the TCP port on the server that we will
795 send requests to. If this option is set, it is the
796 default for these options, which can be overridden
797 individually: port_backup, port_restore, port_ver‐
798 ify, port_list, port_delete. If this option is not
799 set, you will need to set all of the port options
800 separately.
801 port_backup=[port number]
803 Defines the TCP port on the server that we will
804 send backup requests to. If not set, it defaults
805 to the port option.
806 port_restore=[port number]
808 Defines the TCP port on the server that we will
809 send restore requests to. If not set, it defaults
810 to the port option.
811 port_verify=[port number]
813 Defines the TCP port on the server that we will
814 send verify requests to. If not set, it defaults
815 to the port_restore option.
816 port_list=[port number]
818 Defines the TCP port on the server that we will
819 send list requests to. If not set, it defaults to
820 the port option.
821 port_delete=[port number]
823 Defines the TCP port on the server that we will
824 send delete requests to. If not set, it defaults
825 to the port option.
826 status_port=[port number]
828 Defines the TCP port that the server is listening
829 on for status requests.
830 cname=[client name]
832 Defines the client name to identify as to the
833 server.
834 cname_lowercase=[0|1]
836 Whether to force lowercase cname when detecting
837 cname automatically (ie. no cname provided above).
838 The default is 0. When set to 1 the name returned
839 by the get_fqdn function will be lowercased.
840 cname_fqdn=[0|1]
842 Whether to keep fqdn cname (like 'testclient.exam‐
843 ple.com') when detecting cname automatically (ie.
844 no cname provided above). The default is 1. When
845 set to 0, the fqdn returned by the get_fqdn func‐
846 tion will be stripped ('testclient.example.com'
847 becomes 'testclient').
848 protocol=[0|1|2]
850 Choose which style of backups and restores to use.
851 0 (the default) automatically decides based on the
852 server version and which protocol is set on the
853 server side. 1 forces protocol1 style (file level
854 granularity with a pseudo mirrored storage on the
855 server and optional rsync). 2 forces protocol2
856 style (inline deduplication with variable length
857 blocks). If you choose a forced setting, it will
858 be an error if the server also chooses a forced
859 setting.
860 password=[password]
862 Defines the password to send to the server.
863 enabled=[0|1]
865 Set this to 0 if you want to disable a client. The
866 default is 1. This option can also be set in the
867 client configuration files in clientconfdir on the
868 server.
869 lockfile=[path]
871 Path to the lockfile that ensures that two client
872 processes cannot run simultaneously (this cur‐
873 rently doesn't work on Windows).
874 pidfile=[path]
876 Synonym for lockfile.
877 syslog=[0|1]
879 Log to syslog. Defaults to off.
880 stdout=[0|1]
882 Log to stdout. Defaults to on.
883 progress_counter=[0|1]
885 Print progress counters on stdout. Defaults to on.
886 randomise=[max secs]
888 When running a timed backup, sleep for a random
889 number of seconds (between 0 and the number given)
890 before contacting the server. Alternatively, this
891 can be specified by the '-q' command line option.
892 user=[username]
894 Run as a particular user (not supported on Win‐
895 dows).
896 group=[groupname]
898 Run as a particular group (not supported on Win‐
899 dows).
900 ratelimit=[Mb/s]
902 Set the network send rate limit, in Mb/s. If this
903 option is not given, burp will send data as fast
904 as it can. If you want the client's sending speed
905 to be limited, you will also need to set this
906 option on the client side.
907 network_timeout=[s]
909 Set the network timeout in seconds. If no data is
910 sent or received over a period of this length,
911 burp will give up. The default is 7200 seconds (2
912 hours).
913 ca_burp_ca=[path]
915 Path to the burp_ca script (burp_ca.bat on Win‐
916 dows). For more information on this, please see
917 docs/burp_ca.txt.
918 ca_csr_dir=[path]
920 Directory where certificate signing requests are
921 generated. For more information on this, please
922 see docs/burp_ca.txt.
923 ssl_cert_ca=[path]
925 The path to the SSL CA certificate. This file will
926 probably be the same on both the server and the
927 client. The file should contain just the certifi‐
928 cate in PEM format. For more information on this
929 and the other ssl_* options, please see
930 docs/burp_ca.txt.
931 ssl_cert=[path]
933 The path to the client SSL certificate. It works
934 for me when the file contains the concatenation of
935 the certificate and private key in PEM format.
936 ssl_key=[path]
938 The path to the client SSL private key in PEM for‐
939 mat.
940 ssl_key_password=[password]
942 Only needed for loading an encrypted certificate.
943 ssl_cert_password=[password]
945 Synonym for ssl_key_password.
946 ssl_peer_cn=[string]
948 Must match the common name in the SSL certificate
949 that the server gives when it connects. If
950 ssl_peer_cn is not set, the server name will be
951 used instead.
952 ssl_ciphers=[cipher list]
954 Allowed SSL ciphers. See openssl ciphers for
955 details.
956 server_can_restore=[0|1]
958 To prevent the server from initiating restores,
959 set this to 0. The default is 1.
960 server_can_override_includes=[0|1]
962 To prevent the server from being able to override
963 your local include/exclude list, set this to 0.
964 The default is 1.
965 encryption_password=[password]
967 Set this to enable client side file Blowfish
968 encryption. If you do not want encryption, leave
969 this field out of your config file. IMPORTANT:
970 Configuring this renders delta differencing point‐
971 less, since the smallest real change to a file
972 will make the whole file look different. There‐
973 fore, activating this option turns off delta dif‐
974 ferencing so that whenever a client file changes,
975 the whole new file will be uploaded on the next
976 backup. ALSO IMPORTANT: If you manage to lose your
977 encryption password, you will not be able to unen‐
978 crypt your files. You should therefore think about
979 having a copy of the encryption password somewhere
980 off-box, in case of your client hard disk failing.
981 FINALLY: If you change your encryption password,
982 you will end up with a mixture of files on the
983 server with different encryption and it may become
984 tricky to restore more than one file at a time.
985 For this reason, if you change your encryption
986 password, you may want to start a fresh chain of
987 backups (by moving the original set aside, for
988 example). Burp will cope fine with turning the
989 same encryption password on and off between back‐
990 ups, and will restore a backup of mixed encrypted
991 and unencrypted files without a problem.
992 glob_after_script_pre=[0|1]
994 Set this to 0 if you do not want include_glob set‐
995 tings to be evaluated after the pre script is run.
996 The default is 1.
997 backup_script_pre=[path]
999 Path to a script to run before a backup. It is not
1000 run if the server decides it is not yet time for a
1001 backup. The arguments to it are 'pre', 'reserved2'
1002 to 'reserved5', and then arguments defined by
1003 backup_script_pre_arg - unless the option
1004 'backup_script_reserved_args' is off, then only
1005 arguments defined by backup_script_pre_arg are
1006 passed to it.
1007 backup_script_pre_arg=[string]
1009 A user-definable argument to the backup pre
1010 script. You can have many of these.
1011 backup_script_post=[path]
1013 Path to a script to run after a backup. The argu‐
1014 ments to it are 'post', [0|1] if the backup failed
1015 or succeeded, 'reserved3' to 'reserved5', and then
1016 arguments defined by backup_script_post_arg -
1017 unless the option 'backup_script_reserved_args' is
1018 off, then only arguments defined by
1019 backup_script_post_arg are passed to it.
1020 backup_script_post_arg=[string]
1022 A user-definable argument to the backup post
1023 script. You can have many of these.
1024 backup_script_post_run_on_fail=[0|1]
1026 If this is set to 1, backup_script_post will be
1027 run whether the backup succeeds or not. The
1028 default is 0, which means that backup_script_post
1029 will only be run if the backup succeeds.
1030 restore_script_pre=[path]
1032 Path to a script to run before a restore. The
1033 arguments to it are 'pre', 'reserved2' to
1034 'reserved5', and then arguments defined by
1035 restore_script_pre_arg - unless the option
1036 'restore_script_reserved_args' is off, then only
1037 arguments defined by restore_script_pre_arg are
1038 passed to it.
1039 restore_script_pre_arg=[string]
1041 A user-definable argument to the restore pre
1042 script. You can have many of these.
1043 restore_script_post=[path]
1045 Path to a script to run after a restore. The argu‐
1046 ments to it are 'post', [0|1] if the restore
1047 failed or succeeded, 'reserved3' to 'reserved5',
1048 and then arguments defined by
1049 restore_script_post_arg - unless the option
1050 'restore_script_reserved_args' is off, then only
1051 arguments defined by restore_script_post_arg are
1052 passed to it.
1053 restore_script_post_arg=[string]
1055 A user-definable argument to the restore post
1056 script. You can have many of these.
1057 restore_script_post_run_on_fail=[0|1]
1059 If this is set to 1, restore_script_post will be
1060 run whether the restore succeeds or not. The
1061 default is 0, which means that restore_script_post
1062 will only be run if the restore succeeds.
1063 backup_script=[path]
1065 You can use this to save space in your config file
1066 when you want to run the same script before and
1067 after a backup. It overrides backup_script_pre and
1068 backup_script_post.
1069 backup_script_arg=[path]
1071 Goes with backup_script and overrides
1072 backup_script_pre_arg and backup_script_post_arg.
1073 backup_script_reserved_args=[0|1]
1075 Whether to pass reserved arguments to backup
1076 scripts. The default is on.
1077 restore_script=[path]
1079 You can use this to save space in your config file
1080 when you want to run the same script before and
1081 after a restore. It overrides restore_script_pre
1082 and restore_script_post.
1083 restore_script_arg=[path]
1085 Goes with restore_script and overrides
1086 restore_script_pre_arg and
1087 restore_script_post_arg.
1088 restore_script_reserved_args=[0|1]
1090 Whether to pass reserved arguments to restore
1091 scripts. The default is on.
1092 autoupgrade_dir=[path]
1094 Path to autoupgrade directory into which upgrades
1095 are downloaded. Please see docs/autoupgrade.txt in
1096 the source package for more help with this option.
1097 If you do not want your client to autoupgrade, do
1098 not set this option.
1099 autoupgrade_os=[string]
1101 Name of the client operating system. Should match
1102 a directory name in the server's autoupgrade_dir.
1103 If you do not want your client to autoupgrade, do
1104 not set this option.
1105 monitor_exe=[path]
1107 Where to look to find the burp binary to use when
1108 forking a monitor client. This might be needed on
1109 systems that don't have any sensible way to self-
1110 determine a process' own path, such as openbsd.
1111
1114 The following options specify exactly what is backed up.
1115 The client can specify these options, or if you include
1116 at least one 'include=' in the client configuration files
1117 on the server, the server will override them all.
1118 include=[path]
1120 Path to include in the backup. You can have multi‐
1121 ple include lines. Use forward slashes '/', not
1122 backslashes '\' as path delimiters.
1123 exclude=[path]
1125 Path to exclude from the backup. You can have mul‐
1126 tiple exclude lines. Use forward slashes '/', not
1127 backslashes '\' as path delimiters.
1128 include_glob=[glob expression]
1130 Include paths that match the glob expression. For
1131 example, '/home/*/Documents' will include
1132 '/home/user1/Documents' and '/home/user2/Docu‐
1133 ments' if directories 'user1' and 'user2' exist in
1134 '/home'. The Windows implementation currently
1135 limit the expression to contain only one '*'.
1136 include_regex=[regular expression]
1138 Not implemented.
1139 exclude_regex=[regular expression]
1141 Exclude paths that match the regular expression.
1142 include_ext=[extension]
1144 Extensions to include in the backup. Case insensi‐
1145 tive. Nothing else will be included in the backup.
1146 You can have multiple include extension lines. For
1147 example, set 'txt' to include files that end in
1148 '.txt'. You need to specify an 'include' line so
1149 that burp knows where to start looking.
1150 exclude_ext=[extension]
1152 Extensions to exclude from the backup. Case insen‐
1153 sitive. You can have multiple exclude extension
1154 lines. For example, set 'vdi' to exclude Virtual‐
1155 Box disk images.
1156 exclude_comp=[extension]
1158 Extensions to exclude from compression. Case
1159 insensitive. You can have multiple exclude com‐
1160 pression lines. For example, set 'gz' to exclude
1161 gzipped files from compression.
1162 exclude_fs=[fstype]
1164 File systems to exclude from the backup. Case
1165 insensitive. You can have multiple exclude file
1166 system lines. For example, set 'tmpfs' to exclude
1167 tmpfs. Burp has an internal mapping of file system
1168 names to file system IDs. If you know the file
1169 system ID, you can use that instead. For example,
1170 'exclude_fs = 0x01021994' will also exclude tmpfs.
1171 include_fs=[fstype]
1173 File systems to include into the backup. Case
1174 insensitive. You can have multiple include file
1175 system lines. For example, set 'ext4' to include
1176 ext4. Burp has an internal mapping of file system
1177 names to file system IDs. If you know the file
1178 system ID, you can use that instead. For example,
1179 'include_fs = 0x01021994' will also include tmpfs.
1180 If at least one file system is included, all other
1181 filesystems will be excluded per default. Included
1182 directories that do not live on an included file
1183 system will be skipped, even if cross_all_filesys‐
1184 tems is enabled and they contain subdirectories
1185 with included file systems.
1186 Note that on SunOS systems include_fs and
1188 exclude_fs will do a case sensitive compare of the
1189 string descriptors of the file systems instead of
1190 the numeric IDs (see f_basetype member is struct
1191 statvfs).
1192 min_file_size=[b/Kb/Mb/Gb]
1194 Do not back up files that are less than the speci‐
1195 fied size. Example: 'min_file_size = 10Mb'. Set to
1196 0 (the default) to have no limit.
1197 max_file_size=[b/Kb/Mb/Gb]
1199 Do not back up files that are greater than the
1200 specified size. Example: 'max_file_size = 10Mb'.
1201 Set to 0 (the default) to have no limit.
1202 cross_filesystem=[path]
1204 Allow backups to cross a particular filesystem
1205 mountpoint.
1206 cross_all_filesystems=[0|1]
1208 Allow backups to cross all filesystem mountpoints.
1209 nobackup=[file name]
1211 If this file system entry exists, the directory
1212 containing it will not be backed up.
1213 read_fifo=[path]
1215 Do not back up the given fifo itself, but open it
1216 for reading and back up the contents as if it were
1217 a regular file.
1218 read_all_fifos=[0|1]
1220 Open all fifos for reading and back up the con‐
1221 tents as if they were regular files.
1222 read_blockdev=[path]
1224 Do not back up the given block device itself, but
1225 open it for reading and back up the contents as if
1226 it were a regular file.
1227 read_all_blockdevs=[0|1]
1229 Open all block devices for reading and back up the
1230 contents as if they were regular files.
1231 split_vss=[0|1]
1233 When backing up Windows computers with burp proto‐
1234 col 1, this option allows you to save the VSS
1235 header data separate from the file data. The
1236 default is off, which means that the VSS header
1237 data is saved prepended to the file data. This
1238 option has no effect in protocol 2.
1239 strip_vss=[0|1]
1241 When backing up Windows computers with burp proto‐
1242 col 1, this option allows you to prevent the VSS
1243 header data being backed up. The default is off.
1244 To restore a backup that has no VSS information on
1245 Windows, you need to give the client the '-x' com‐
1246 mand line option. This option has no effect in
1247 protocol 2.
1248 vss_drives=[list of drive letters]
1250 When backing up Windows computers, this option
1251 allows you to specify which drives have VSS snap‐
1252 shots taken of them. If you omit this option, burp
1253 will automatically decide based on the 'include'
1254 options. If you want no drives to have snapshots
1255 taken of them, you can specify '0'.
1256 acl=[0|1]
1258 If acl support is compiled into burp, this allows
1259 you to decide whether or not to backup acls at
1260 runtime. The default is '1'.
1261 xattr=[0|1]
1263 If xattr support is compiled into burp, this
1264 allows you to decide whether or not to backup xat‐
1265 trs at runtime. The default is '1'.
1266 atime=[0|1]
1268 This allows you to control whether the client uses
1269 O_NOATIME when opening files and directories. The
1270 default is 0, which enables O_NOATIME. This means
1271 that the client can read files and directories
1272 without updating the access times. However, this
1273 is only possible if you are running as root, or
1274 are the owner of the file or directory. If this is
1275 not the case (perhaps you only have group or world
1276 access to the files), you will get errors until
1277 you set atime=1. With atime=1, the access times
1278 will be updated on the files and directories that
1279 get backed up.
1280 scan_problem_raises_error=[0|1]
1282 When enabled, this causes problems in the phase1
1283 scan (such as an 'include' being missing) to be
1284 treated as fatal errors. The default is off.
1285
1288 For the server to know about clients that can contact it,
1289 you need to place a file named after the client in
1290 clientconfdir. Files beginning with '.' or ending with
1291 '~' are ignored. Directories are also ignored.
1292 The file name must match the name in the 'cname' field on
1294 the client.
1295 ssl_peer_cn=[string] must match the common name in the
1297 SSL certificate that the client gives when it connects.
1298 If ssl_peer_cn is not set, the client name will be used
1299 instead (the clientconfdir file name).
1300 The file needs to contain a line like password=[password]
1302 that matches the same field on the client, or
1303 passwd=[hash] - where the plain text password on the
1304 client will be tested against a hash of the kind you
1305 might find in /etc/passwd.
1306 Additionally, the following options can be overridden
1308 here for each client:
1309 enabled protocol directory client_lockdir direc‐
1310 tory_tree timestamp_format password_check keep
1311 manual_delete working_dir_recovery_method librsync
1312 librsync_max_size version_warn path_length_warn
1313 syslog client_can_delete client_can_force_backup
1314 client_can_list client_can_restore client_can_ver‐
1315 ify restore_client compression hard_quota
1316 soft_quota label timer_script timer_arg
1317 notify_success_script notify_success_arg
1318 notify_success_warnings_only notify_failure_script
1319 notify_failure_arg dedup_group server_script_pre
1320 server_script_pre_arg server_script_pre_notify
1321 server_script_post server_script_post_arg
1322 server_script_post_notify server_script
1323 server_script_arg server_script_notify
1324 server_script_post_run_on_fail
1325 Additionally, the includes and excludes can be overridden
1327 here, as described in the section above.
1328 As with the other configuration files, extra configura‐
1330 tion can be included with the '. path/to/config/file'
1331 syntax.
1332
1335 The burp example configs come with example SSL certifi‐
1336 cates and keys. You can use these and burp will work. But
1337 if you are worried about network security, you should
1338 generate your own certificates and keys and point your
1339 config files to them. To create the example files, I used
1340 a handy interface to openssl, called 'tinyca'
1341 (http://tinyca.sm-zone.net/). If you are using Debian,
1342 you can run 'apt-get install tinyca' to get it. There is
1343 also the option of using burp_ca, which you can find in
1344 the source distribution, courtesy of Patrick Koppen.
1345
1348 As well as using the client list options described above,
1349 you can go directly to the storage directory on the
1350 server. The backups for a client are in the directory
1351 named after the client. Inside each backup directory is a
1352 file called manifest.gz.
1353 This contains a list of all the files in the backup, and
1355 where they originally came from on the client.
1356 There is also a 'log.gz' file in the backup directory,
1358 which contains the output generated by the server during
1359 the backup.
1360 The 'data' directory contains complete backup files.
1362 The 'deltas.reverse' directory contains reverse deltas
1364 that can be applied to the data from the next backup in
1365 the sequence (indicated by the contents of the 'forward'
1366 file).
1367 Anything with a .gz suffix is compressed in zlib (gzip)
1369 format. You can use standard tools, such as zcat, zless
1370 or cp, to view them or copy them elsewhere. Files from
1371 Windows backups will probably contain VSS headers and/or
1372 footers. For help stripping these, see the vss_strip man
1373 page.
1374
1377 You can queue a backup on the server, to be performed
1378 when the client next makes contact. To do this, you put a
1379 file called 'backup' into the top level of the client
1380 storage directory. The contents of the file are ignored.
1381
1384 You can queue a restore on the server, to be performed
1385 when the client next makes contact. To do this, you put a
1386 file called 'restore' into the top level of the client
1387 storage directory. The client can deny server initiated
1388 restores by setting "server_can_restore=0" in its
1389 burp.conf. Valid fields to include in the restore file
1390 are:
1391 orig_client=[client]
1393 The original client to restore from. Equivalent to
1394 '-C' when initiating a restore from a client. Do
1395 not include this line when restoring to the origi‐
1396 nal client. See also the 'restore_client' server
1397 option.
1398 backup=[number|a]
1400 The number of the backup to restore from. Equiva‐
1401 lent to '-b' when initiating a restore from the
1402 client.
1403 overwrite=[0|1]
1405 Whether to overwrite existing files. Equivalent to
1406 '-f' when initiating a restore from the client.
1407 strip=[number]
1409 Number of leading path components to strip. Equiv‐
1410 alent to '-s' when initiating a restore from the
1411 client.
1412 restoreprefix=[path]
1414 Prefix to the restore path. Equivalent to '-d'
1415 when initiating a restore from the client.
1416 stripfrompath=[string]
1418 Strip matching string from restore paths (before
1419 prefix is prepended).
1420 regex=[regular expression]
1422 Only restore files matching the regular expres‐
1423 sion. Equivalent to '-r' when initiating a restore
1424 from the client.
1425 include=[path]
1427 Restore directories and files that match the path.
1428 If it is a directory, the contents of the direc‐
1429 tory will be restored. You can have multiple
1430 'include' lines. There is no equivalent when ini‐
1431 tiating a restore from the client.
1432
1435 Sending signal 1 (HUP) to the main server process will
1436 cause it to reload. For the vast majority of configura‐
1437 tion changes, a reload is unnecessary as the server will
1438 pick up changes "on-the-fly". Sending signal 12 (USR2) to
1439 the main server process will cause it to wait until there
1440 are no longer any child processes, and then exit. The
1441 intention is to help with upgrades without interrupting
1442 current backups. if you are running upstart, a new burp
1443 server process will start up when the old one exits.
1444
1447 0: success
1448 1: error
1449
1452 0: success
1453 1: error
1454 2: restore gave warnings
1455 3: timer conditions on the server were not met
1456 4: could not connect to server
1457
1460 If you find bugs, please report them to the email list.
1461 See the website <http://burp.grke.net/> for details.
1462
1465 The main author of Burp is Graham Keeling.
1466
1469 See the LICENCE file included with the source distribu‐
1470 tion.
1471 Burp Burp(8)