rfreezefs.8: Fix some misformatting and other minor bogosity.

[rsync-backup] / rfreezefs.8

.TH rfreezefs 8 "October 2011" "rsync-backup"
.SH NAME
rfreezefs \- freeze a filesystem safely
.SH SYNOPSIS
.B rfreezefs
.RB [ \-n ]
.RB [ \-a
.IR address ]
.RB [ \-p
.IR loport [\fB\- hiport ]]
.I filesystem
\&...
.SH DESCRIPTION
The
.B rfreezefs
program freezes one or more mounted filesystems for a period of time,
and then thaws them.  For more detail on what this means, why you'd want
to, and how you might go about using
.B rfreezefs
to do it, see below.
.PP
The following command-line options are recognized.
.TP
.B "\-h, \-\-help"
Writes a help message to standard output, and exits with status 0.
.TP
.B "\-v, \-\-version"
Writes the version number to standard output, and exits with status 0.
.TP
.B "\-u, \-\-usage"
Writes a command-line usage synopsis to standard output, and exits with
status 0.
.TP
.BI "\-a, \-\-address=" address
Listen only for incoming connections to the given
.IR address .
The default is to listen for connections to any local address.
.TP
.B "\-n, \-\-not-really"
Don't actually freeze or thaw any filesystems; instead, write messages
to standard error explaining what would be done.
.TP
.BI "\-p, \-\-port-range=" loport\fR[ \- hiport \fR]]
Listen for incoming connections on a port between
.I loport
and
.IR hiport .
If
.I hiport
is omitted, listen for connections only on
.IR loport .
The default is to allow the kernel a free choice of local port number.
.PP
The
.I filesystem
arguments name the filesystems to be frozen.  There must be at least one
such argument.  It's conventional to name the filesystem mount points,
though actually any file or directory in the filesystem will do.  The
files are opened read-only.
.PP
The
.B rfreezefs
program starts, parses its command line, opens the named files, and
creates a listening TCP socket according to the command-line options.
It then prints a sequence of lines to standard output, which may have
one of the following forms.
.TP
.BI "PORT " port
Announces the TCP
.I port
number on which that
.B rfreezefs
is listening for incoming connections.
.TP
.BI "TOKEN " label " " token
Declares a `token': a randomly chosen string which is to be used in the
network connection.  The token's value is
.IR token :
token values are a sequence of non-whitespace printable ASCII
characters, but their precise structure is not specified.  The token
value will have the meaning given by the
.IR label ,
which is one of the token labels described below.
.TP
.B READY
Marks the end of the lines and announces that
.B rfreezefs
is ready to accept connections.
.PP
These lines may be sent in any order, except that
.B READY
is always last.  There may be many
.B TOKEN
lines.
.PP
Network communications use a simple plain-text line-oriented protocol.
Each line consists of a token, optionally followed by a carriage return
(code 13), followed by a linefeed (code 10).  No other whitespace is
permitted.  The tokens allowed are precisely those announced in the
.B TOKEN
lines written to
.BR rfreezefs 's
standard output.  Furthermore, only certain tokens are valid at
particular points in the protocol.  For reference, the token labels, and
the meanings of the corresponding tokens, are as follows.
.TP
.B FREEZE
Sent by a client to freeze the filesystems.  This must be the first
token transmitted by the client.  On receipt,
.B rfreezefs
will close its listening socket and any other client connections.  It
will then freeze the filesystems.
.TP
.B FROZEN
Sent by
.B rfreezefs
to indicate successful freezing of the filesystem.
.TP
.B KEEPALIVE
Sent periodically by the client to prevent filesystems being thawed due
to a timeout.  No explicit acknowledgement is sent.
.TP
.B THAW
Sent by the client to request thawing of the filesystems.
.TP
.B THAWED
Sent by
.B rfreezefs
to indicate successful thawing of the filesystems in response to
.BR THAW .
.PP
The high-level structure of the protocol is then as follows: the client
sends
.BR FREEZE ;
the server freezes and responds with
.BR FROZEN ;
the client optionally sends
.B KEEPALIVE
at intervals; the client finally sends
.BR THAW ;
and the server responds with
.B THAWED
and drops the connection.
.PP
If sufficient time passes without
.B rfreezefs
receiving either
.B THAW
or
.B KEEPALIVE
tokens, or an invalid token is received, or it receives one of a number
of signals \(en currently
.BR SIGINT ,
.BR SIGQUIT ,
.BR SIGTERM ,
.BR SIGHUP ,
.BR SIGALRM ,
.BR SIGILL ,
.BR SIGSEGV ,
.BR SIGBUS ,
.BR SIGFPE ,
or
.B SIGABRT
\(en then
.B rfreezefs
will thaw the filesystems and report a failure.
.PP
Diagnostics are reported to standard error.  Exit statuses have specific
meanings:
.TP
.B 0
Successful completion.  Filesystems were frozen and thawed as required.
.TP
.B 1
Problem with command-line arguments.  No filesystems were frozen.
.TP
.B 2
Environmental problem, typically a system call failure: e.g., a file
failed to open, or there was a problem with the network communications.
Either no filesystems were frozen, or all filesystems were successfully
thawed again.
.TP
.B 3
Timeout or invalid data.  Either no connections containing the cookie
were made in time, or no data was received for a long enough period
after the filesystems were frozen, or an invalid token was received.  In
the first case, no filesystems were frozen; in the other two cases, the
filesystems were successfully thawed.
.TP
.B 4
Crash.  The
.B rfreezefs
program received a fatal signal after it had started to freeze
filesystems.  Under these circumstances, it thaws the filesystems,
removes the signal handler, and sends itself the signal again, but if
that doesn't work then
.B rfreezefs
exits with this status code.  All frozen filesystems were successfully
thawed again.
.TP
.B 112
Failure during filesystem thaw (mnemonic: European emergency number).
Some filesystems
.I failed
to thaw, and are still frozen.  You might have some joy with
.BR SysRq-j ,
though in the author's experience that doesn't work and you'll probably
have to reboot.  At least your filesystems are consistent...
.SS Background
When frozen, a filesystem's backing block device is put in a consistent
state (as if unmounted), and write operations to it are delayed until
the filesystem is thawed again.  In the meantime, it's possible to take
a consistent snapshot of the block device.  When a filesystem is
directly mounted on an LVM logical volume, the kernel detects this
situation and automatically freezes the filesystem while the snapshot is
being prepared.  If the logical volume and filesystem are on separate
hosts, though, the filesystem must be frozen manually, which is why
.B rfreezefs
is useful.
.PP
The idea is to run
.B rfreezefs
using
.BR ssh (1)
or
.BR userv (1),
or some other means of acquiring the necessary privilege level.  You
read the port number and tokens, connect to the socket, and send the
.B FREEZE
token followed by a newline.  You now wait to receive the
.B FROZEN
token from
.BR rfreezefs .
Once you have received this, the filesystems are frozen: you can safely
take snapshots.  If this will take an extended amount of time, you
should send
.B KEEPALIVE
tokens to the connection at intervals in order to prevent
.B rfreezefs
from timing out and thawing the filesystems (but see the
.B "Security notes"
below).  When your snapshot is prepared, sent the
.B THAW
token, and wait for the
.B THAWED
token in response.  If this is received, the snapshot was completed
successfully and the filesystems are properly thawed again.  If you
don't receive the
.B THAWED
token then something bad might have happened (e.g., the filesystem might
have been prematurely thawed) and the snapshot is suspect.  If the exit
status is 112 then at least one filesystem is still frozen and some
emergency action is needed.  If you can't retrieve the exit status then
it's possible that your transport is blocked for trying to write to the
frozen filesystem (this especially likely if
.B /
or
.B /var
is frozen) and you should react as if the status was 112.
.SS Security notes
The
.B rfreezefs
program uses randomly chosen tokens to form a simple code which is
revealed to the caller.  It is assumed that this information is kept
secret from adversaries, e.g., by ensuring that it is only transmitted
over local pipes (as used by
.BR userv (1))
and/or secure network transports such as SSH (see
.BR ssh (1)).
The author believes that the worst possible outcome is that the host
wedges up because an important filesystem is frozen, and
.B rfreezefs
therefore strives to prevent that from happening.  In particular,
cryptographic transport implementations such as SSH may attempt to log
messages to frozen filesystems or otherwise wedge themselves:
.B rfreezefs
deliberately uses only kernel-implemented transports for its
communication needs once the filesystems are frozen.
.PP
Most of the tokens are used at most once in the protocol.  In
particular, the
.B FROZEN
token can't be sent by an adversary in advance of the filesystem being
frozen, since (under the assumption that the tokens are kept secret) it
only revealed in the clear after a successful freeze.  Similarly, the
.B THAWED
token is only transmitted if the filesystems are thawed as a result of a
.B THAW
request (rather than a dropped connection, timeout, or some other
problem).  If the client only sends the
.B THAW
request once its snapshot is complete, then a
.B THAWED
response indicates that the filesystems remained frozen until the
snapshot was indeed completed and therefore the snapshot is consistent.
.PP
The exception is the
.B KEEPALIVE
token, which may be sent repeatedly.  After it is first revealed, an
adversary can hijack the connection and replay the
.B KEEPALIVE
token to keep the filesystems frozen indefinitely.  You can recover from
this by severing the connection somehow, or by sending
.B rfreezefs
a signal.  It is therefore recommended that
.B KEEPALIVE
tokens not be sent unless necessary.  The timeout is currently set to
60s, which ought to be adequate for most snapshot mechanisms.
.SH BUGS
There ought to be a better one-time-token protocol for keepalives.  I
want to keep cryptography out of this program, though.
.SH SEE ALSO
.BR fsfreeze (8),
.BR random (4),
.BR lvm (8),
.BR ssh (1),
.BR userv (1).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>