.\" This file is in the public domain.
.Dd December 16, 2005
.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.  Each line of the config file is a comment (a blank line,
or a line whose first nonblank character is a \&#); a line whose first
nonblank character is a \&*, which specfies special configuration
settings; or any other line, in which case the line specifies a backup
point.  Backup point lines have four required fields and optional
additional fields:
.Pp
.Ar backupfile
is 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 reasonable to use a raw disk device as
a
.Ar backupfile . )
Since this field is a pathname, if you would like it to begin with a
\&*, simply prepend
.Pa ./
to it.
.Pp
.Ar keyfile
is 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 around permanently by
.Nm lbd . )
.Pp
.Ar host
and
.Ar port
indicate where
.Nm
should listen for connections from the corresponding
.Xr lb 8
process.
.Ar host
can be a \&* to indicate that the daemon is to listen on all available
addresses.
.Pp
.Ar conflict-tag Ns s ,
the optional fields, 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 lines here have any of
their conflict-tag 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
.Ar conflict-tag Ns s
is given, there are two possibilities: if the
.Ar backupfile
ends in a digit and then a letter, the letter is stripped off and the
rest is used as a
.Ar conflict-tag ;
otherwise, the line has no conflict tags.  (This defaulting algorithm
is designed for
.Ar backupfile
names ending with disk partition names like
.Sq Pa ccd0a
or
.Sq Pa wd12f . )
.Pp
If
.Ar backupfile
and
.Ar keyfile
are both
.Sq \&- ,
.Nm
will take the line as specifying an additional listen-on address and
port for the previous line.  (In this case, the
.Ar conflict-tags ,
if present, are ignored.)
.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
.Ar keyfile
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.
.Pp
Lines beginning with a \&* specify other configuration.  Currently,
there is only one such line.  Its first field is
.Sq \&*admin
and its other two fields specify a listen-on address and port (like the
host and port fields described above).
.Nm
will listen on this address for administrative connections, as
described below (see the
.Sx ADMINISTRATIVE INTERFACE
section).
.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
lines 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
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 the
.Ar 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 .