.\" This file is in the public domain.
.Dd April 30, 2004
.Dt LB 1
.Os NetBSD 1.4
.Sh NAME
.Nm lb
.Nd live backup
.Sh SYNOPSIS
.Nm
.Ar diskwatchunit
.Ar diskdev
.Ar daemon-host
.Ar daemon-port
.Ar keyfile
.Sh DESCRIPTION
.Nm
is the client 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; each invocation manages backups for one disk
partition (normally, one filesystem).  The arguments are:
.Pp
.Ar diskwatchunit
is the unit number of the
.Xr diskwatch 4
unit to use for this run.  These will usually be small numbers starting
at zero.
.Pp
.Ar diskdev
is the disk device to back up.  It must name the raw (character
special) device, not the block device.
.Pp
.Ar daemon-host
and
.Ar daemon-port
are the host name or address and port number at which to contact the
.Xr lbd 8
daemon for this filesystem.  Make sure these are right; if they name a
valid machine and port, but not the correct one,
.Nm
will not produce errors (it assumes the
.Xr lbd 8
hasn't been started yet), but of course it will not work.
.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 lbd 8 ,
but there is no other particualr restriction.  (The file usually should
not be very large; a couple of hundred bits of entropy is plenty, and
this file's contents are kept around permanently by
.Nm lb . )
.Pp
If various startup checks (such as opening devices) succeed,
.Nm
will first make a complete pass over the disk, checking what's actually
on the disk against what's in the backup file and updating any blocks
that don't match.  Once that's finished, it will drop into a mode
wherein it simply mirrors writes as they occur, with proper handling in
case something writes large amounts of data to disk faster than it can
be mirrored over the network.
.Nm
normally does not exit until the system is shut down.  It backs up disk
devices, completely blind to any filesystem structure that may be
present; if you are repartitioning the disk, you should shut down any
.Nm
process that's monitoring a partition you're changing.  If at any point
it loses its connection to the
.Xr lbd 8 ,
.Nm
will retry until it manages to reestablish the connection, at which
point it will start over from the comparison phase.
.Pp
.Nm
sets its process title (see
.Xr setproctitle 3 )
to show the device name and the current state of the process; if
.Nm
is scanning and comparing the whole disk, it also includes a
percent-done figure.  The process title is updated whenever the state
changes, or, when scanning the whole disk, whenever the percent-done
figure changes.
.Sh BUGS
The network protocol is not documented here; see the source code.
.Pp
The comparison phase can take a long time if the disk partition is
large, the network is slow, or one of the CPUs involved is slow.  For
tens-of-gigabytes disks or very slow machinse (eg, 68020s) this phase
has been known to take hours.
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents.montreal.qc.ca .