.\" This file is in the public domain.
.Dd September 28, 2008
.Dt LBD 1
.Os NetBSD 1.4
.Sh NAME
.Nm lbd
.Nd live backup daemon
.Sh SYNOPSIS
.Nm
.Ar configfile
.Sh DESCRIPTION
.Nm
is the server side of a
.Sq live
backup system, one which backs up all changes more or less immediately
after they are made.
.Nm
is a long-running daemon, managing the server side of backups.
.Ar configfile
names a file containing a configuration, describing the backups
.Nm
is to handle.  The config file has comments removed (a comment is a
line that's entirely blank or whose first nonblank character is \&#);
then, each line's first string of nonblank characters controls what it
specifies.  Non-comment lines may be continued by ending the line with
a \&\e; the \&\e and the following newline are deleted, concatenating
the line with the following line.  (Comment lines cannot be continued.
Continuation lines, ones that are preceded by a lines ending with a
\&\e, cannot normally be comments, but if all continued lines contain
nothing but whitespace before their trailing \&\es, a \&# will be
recognized as beginning a comment.)  The rest of the line takes the
form of key=value pairs.  The keywords, and what keys they support,
are:
.Bl -tag -width indent
.It client
Specifies a client.  The keys are
.Bl -tag -width indent
.It file
Specifies the file in which the backup is kept.  This will normally be
an ordinary file, but in some circumstances you may want to make it a
real disk partition device; it probably can be anything on which
.Xr pwrite 2
works as it does on files.
.Nm
is careful to write only multiples of 512 bytes at offsets that are
multiples of 512 bytes, so it is not unreasonable to use a raw disk
device.
.Pp
This must be specified exactly once for each client.
.It key
Specifies the name of a file containing a shared secret used both to
authenticate the server and client to one another and to derive keys to
encrypt all communication.  The contents of this file must match the
contents of the corresponding file named to
.Xr lb 8 ,
but there is no other particular restriction.  (The file usually should
not be very large; a few hundred bits of entropy is plenty, and this
file's contents are kept in memory permanently by
.Nm lbd . )
.Pp
This must be specified exactly once for each client.
.It listen
Specifies the host and port (in the form
.Ar host Ns No \&/ Ns Ar port )
on which
.Nm
is to listen for connections from the corresponding
.Xr lb 8
process.  The
.Ar host
part can be a \&* to indicate that the daemon is to listen on all
available addresses.
.Pp
This must be specified at least once for each client.  If multiple
listen specs are given,
.Nm
listens on all of them.
.It conflict
Specifies a conflict tag.  These are used to prevent multiple
.Xr lb 8
processes from thrashing a disk spindle at startup when monitoring
multiple partitions on the same spindle.  If two client specs have any
of their conflict strings in common, they will never be scanning the
whole drive at the same time, or, more precisely, all but one of the
scans will be suspended; as each scan finishes, one other scan is
released, until none are scanning any longer.  Client processes blocked
for this reason will show as
.Dq scanning ,
but will remain at 0% done until they get released.  If no conflict
strings are given, there are two possibilities: if the backing-file
pathname ends in a digit and then a letter, the letter is stripped off
and the rest is used as a conflict tag; otherwise, the line has no
conflict tags.  (This defaulting algorithm is designed for backing file
names ending with disk partition names like
.Sq Pa ccd0a
or
.Sq Pa wd12f . )
.Pp
This may be specified any number of times, including zero.
.It bwclass
Specifies a bandwidth class for this client.  See the
.Sq bwclass
line type for more.
.Pp
This may be specified any number of times, including zero.
.Pp
BANDWIDTH LIMITS ARE NOT YET IMPLEMENTED.
.It bandwidth
Specifies a bandwidth limit for this client.  This is semantically
equivalent to specifying bwclass with a class unique to this client,
then specifying this bandwidth limit for that class; it is just a
convenient way of doing that.  Like
.Sq bwclass ,
it may be specified any number of times, but doing so multiple times is
equivalent to specifying it only once with the lowest of the various
values.
.Pp
BANDWIDTH LIMITS ARE NOT YET IMPLEMENTED.
.El
.Pp
It is normally safe to use an address and port that are reachable from
untrusted hosts, because there is a cryptographic exchange that should
prevent anyone without a copy of the data in the key file from
disrupting operation, but it may be wise (on
.Sq belt and suspenders
grounds) to allow only the desired client to communicate with the
daemon, possibly through choice of address, packet filtering rules, or
some such mechanism.
.It bwclass
Specifies a bandwidth class.  These serve to group clients together for
purposes of limiting the network bandwidth they use; clients with the
same
.Sq bwclass
string are part of the same bandwidth class.  A client may belong to
multiple bandwidth classes; the limit applied to a client is the lowest
of the limits computed for each of its classes.  (What those limits are
may vary from moment to moment as the bandwidth demands of other
clients in the same bandwidth classes vary.)  Within a bandwidth class,
a client is guaranteed to be allowed at least 1/N of that class's
bandwidth, where N is the number of clients in the class; however, it
may be allocated more bandwidth if other clients in the class don't
want theirs.  In no case, though, will it be permitted more than the
total bandwidth limit specified for the class.
.Pp
Bandwidth limits are applied independently in each direction on each
connection; that is, there are actually two limits, one for data
flowing each way.
.Pp
There is no particular ordering restriction between declaration of
bandwidth classes and the use of them in client specifications;
however, every bandwidth class named by a client specification must be
described by a
.Sq bwclass
line.
.Pp
It is an error for multiple
.Sq bwclass
lines to attempt to describe the same class, even if the values
specified are identical.
.Pp
BANDWIDTH LIMITS ARE NOT YET IMPLEMENTED.
.Pp
Keys for a
.Sq bwclass
line are
.Bl -tag -width indent
.It name
The bandwidth class's name.  By definition, this bandwidth class
consists of exactly those client specifications giving this same string
in a
.Sq bwclass
clause.
.Pp
This must be specified exactly once.
.It bandwidth
The total bandwidth for this class, in bytes per second.  The number
may have a trailing k, m, g, or t to indicate multiplication by 1000,
1000000, 1000000000, or 1000000000000 respectively (in keeping with
tradition for data rates, powers of ten rather than powers of two are
used here).  A trailing
.Sq bps
(after the multiplier letter, if any) indicates division by 8
.Pf ( Sq bits per second ) .
All suffixes are case-independent, even though this is arguably wrong
for
.Sq bps
(since
.Sq Bps
normally means
.Sq bytes per second ) .
This number must be strictly greater than zero.
.Pp
Bandwidth limits are applied at the TCP end-to-end
.Sq goodput
level.  This means that TCP, IP, and link-layer overhead msut be taken
into account if you wish to accurately model a physical-layer bandwidth
limit.
.Pp
This must be specified exactly once.
.El
.It admin
Specifies a listen-at address for administrative connections.  The keys
are
.Bl -tag -width indent
.It listen
Specifies the host and port at which to listen for administrative
connections, in the same format as the
.Sq listen
key in a client spec.
.Pp
This is specified zero or more times in each admin spec.  It is a
matter of taste whether to use multiple admin specs or multiple listen
specs in a single admin spec to cause
.Nm
to listen at multiple addresses.
.Pp
See the
.Sx ADMINISTRATIVE INTERFACE
section for more on the administrative interface.
.El
.El
.Pp
On startup,
.Nm
simply listens for connections, waiting for clients to initiate
operation.  If a connection sits idle for a long time (approximately
ten minutes),
.Nm
will try to ping the client
.Xr lb 8
process; the intent of this is to provoke a disconnect if the client
machine has crashed or gone unreachable.
.Pp
On receipt of a
.Dv SIGHUP
signal,
.Nm
will reread its configuration.  Previous connections will be preserved,
provided the
.Ar backupfile
refers to the same file (regardless of whether the name is the same),
the
.Ar keyfile
contents are the same (the
.Ar keyfile
name may change, as long as the contents are the same), and the server
end of the connection is one that the server is still configured to
listen on for that client.  Previous connections not meeting these
conditions are dropped.
.Pp
When reloading the config, lines provoking errors are skipped; if the
file cannot be opened, if the file is completely empty, or if there are
errors and the resulting config is completely empty, the reload fails
and nothing is changed.  Otherwise, the newly loaded configuration
replaces the active configuration, with effects on previously existing
connections as described.
.Sh ADMINISTRATIVE INTERFACE
Connections to listen-on addresses specified with
.Sq admin
specs are put into a simple interactive interface.  This interface has
only a few commands:
.Bl -tag -width indent
.It \&?
(Also
.Sq help . )
This produces a help message, briefly describing the available
commands.
.It quit
(Also
.Sq exit . )
Disconnects from
.Nm lbd .
You can also simply drop the network connection to disconnect.
.It all
Prints status for all configured clients, giving the backupfile name,
the file descriptor
.Nm
has it open on, and an indication of whether that client is connected.
If the client is connected, the file descriptor for the connection is
printed as well, along with any status string the client has set.
.It up
Just like
.Sq all
except that disconnected clients are not printed.
.It drain
Blocks until all queued output has been written to the network
connection.
.It prompt Aq str
Change the prompt to
.Aq str ,
which is considered to begin with the first non-whitespace character
after the
.Sq prompt .
(If there is no such non-whitespace character, the prompt is set to a
zero-length string.)
.It echo Aq str
Prints
.Aq str .
.El
.Lp
The last three commands are designed to ease mechanized use of this
interface; they are not intended to be useful to interactive human
users.
.Sh BUGS
The network protocol is not documented here; see the source code.
.Pp
There is no quoting convention for any of the fields in the config file
and thus no way to get a whitespace character into any of the fields.
.Pp
If you use names in host fields,
.Nm
will lock up while it does name-to-address lookups on those names.  To
avoid problems because of this, either use numeric addresses or make
certain you have fast lookups available for those names.
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents.montreal.qc.ca .