.TH rfreezefs 8 "October 2011" "distorted.org.uk 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, currently .BR SIGINT , .BR SIGQUIT , .BR SIGTERM , .BR SIGHUP , .BR SIGALRM , .BR SIGILL , .BR SIGSEGV , .BR SIGBUS , .BR SIGFPE , or .BR SIGABRT , .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,