Timed backups
-------------

The usual case is that the client is running the 'burp -a t' command
regularly (via cron or the Windows scheduler) at a rate of three times an hour.

The server will then decide whether or not it needs a backup of the client
at that moment, and will accept or reject the request as appropriate.
This means that an interrupted backup will be reattempted promptly.

The decision as to whether it is time to backup is made by the 'timer script',
as described below.


Timer script
------------

The location of the timer script is defined in /etc/burp/burp-server.conf:

timer_script = /etc/burp/timer_script

It may be overridden per-client in individual /etc/burp/clientconfdir files.

The server will treat a return code of 0 as meaning that it is time to backup.
Any other return code means that it is not time to backup.

Note: As of 2.1.22, the timer script has been internalised as part of the
main C code. You may still use an external timer script though.
To use the internal version, don't define a timer_script option. Both versions
use the same timer_arg parameters described below.


Timer script arguments
----------------------

The server reserves the first five arguments for itself.
These are:
1) The name of the client.
2) Path to the latest backup.
3) Path to the backup storage directory for the client.
4) Reserved for future use.
5) Reserved for future use.

Arguments after these five can be controlled by the user via the server
configuration files. The defaults are found in /etc/burp/burp-server.conf
and can be overridden per-client in individual /etc/burp/clientconfdir files.

These are the defaults from /etc/burp/burp-server.conf:

timer_arg = 20h
timer_arg = Mon,Tue,Wed,Thu,Fri,00,01,02,03,04,05,19,20,21,22,23
timer_arg = Sat,Sun,00,01,02,03,04,05,06,07,08,17,18,19,20,21,22,23

They are passed to the timer script in the order in which they are found in
the configuration file.
Any number of timer_arg settings in a clientconfdir file will overrides all of
the timer_arg settings in burp-server.conf.


Interval
--------

The default timer_script treats the first timer_arg as the minimum interval
since the last successful backup. The example above is setting 20 hours.
If there was no previous successful backup, it is time to backup now (dependent
upon the time band arguments below).
The following are valid time unit specifiers for the interval:
s (seconds)
m (minutes)
h (hours)
d (days)
w (weeks)
n (months)


Time bands
----------

The default timer script treats every argument after the interval as a time
band.
When it runs, it will create a glob expression for the current day and hour,
using the command: 'LANG=C LC_TIME=C date +"*%a*%H*"'
For example, this may return '*Mon*10*'.
If this glob expression matches one of the time band arguments, the timer
script decides that it is time to backup.


Customisation
-------------

You may customise your timer script so that it makes the decision to back up
based on whatever you like. An example is in the default timer script, where
it will decide that it is time to back up based on the presence of a file
called 'backup' within the client's storage directory.


Forcing backups
---------------

A client may attempt to force a backup at any time with 'burp -a b'.

Some cases where attempting to force a backup will not work:
*) The server is configured with 'client_can_force_backup=0'.
*) The server is already dealing with a connection from the same client.
*) The server is already dealing with a connection from a super_client or
   restore_client that is using the same client.