1 .TH rfreezefs 8 "October 2011" "rsync-backup"
3 rfreezefs \- freeze a filesystem safely
10 .IR loport [\fB\- hiport ]]
16 program freezes one or more mounted filesystems for a period of time,
17 and then thaws them. For more detail on what this means, why you'd want
18 to, and how you might go about using
22 The following command-line options are recognized.
25 Writes a help message to standard output, and exits with status 0.
28 Writes the version number to standard output, and exits with status 0.
31 Writes a command-line usage synopsis to standard output, and exits with
34 .BI "\-a, \-\-address=" address
35 Listen only for incoming connections to the given
37 The default is to listen for connections to any local address.
39 .B "\-n, \-\-not-really"
40 Don't actually freeze or thaw any filesystems; instead, write messages
41 to standard error explaining what would be done.
43 .BI "\-p, \-\-port-range=" loport\fR[ \- hiport \fR]]
44 Listen for incoming connections on a port between
50 is omitted, listen for connections only on
52 The default is to allow the kernel a free choice of local port number.
56 arguments name the filesystems to be frozen. There must be at least one
57 such argument. It's conventional to name the filesystem mount points,
58 though actually any file or directory in the filesystem will do. The
59 files are opened read-only.
63 program starts, parses its command line, opens the named files, and
64 creates a listening TCP socket according to the command-line options.
65 It then prints a sequence of lines to standard output, which may have
66 one of the following forms.
73 is listening for incoming connections.
75 .BI "TOKEN " label " " token
76 Declares a `token': a randomly chosen string which is to be used in the
77 network connection. The token's value is
79 token values are a sequence of non-whitespace printable ASCII
80 characters, but their precise structure is not specified. The token
81 value will have the meaning given by the
83 which is one of the token labels described below.
86 Marks the end of the lines and announces that
88 is ready to accept connections.
90 These lines may be sent in any order, except that
92 is always last. There may be many
96 Network communications use a simple plain-text line-oriented protocol.
97 Each line consists of a token, optionally followed by a carriage return
98 (code 13), followed by a linefeed (code 10). No other whitespace is
99 permitted. The tokens allowed are precisely those announced in the
103 standard output. Furthermore, only certain tokens are valid at
104 particular points in the protocol. For reference, the token labels, and
105 the meanings of the corresponding tokens, are as follows.
108 Sent by a client to freeze the filesystems. This must be the first
109 token transmitted by the client. On receipt,
111 will close its listening socket and any other client connections. It
112 will then freeze the filesystems.
117 to indicate successful freezing of the filesystem.
120 Sent periodically by the client to prevent filesystems being thawed due
121 to a timeout. No explicit acknowledgement is sent.
124 Sent by the client to request thawing of the filesystems.
129 to indicate successful thawing of the filesystems in response to
132 The high-level structure of the protocol is then as follows: the client
135 the server freezes and responds with
137 the client optionally sends
139 at intervals; the client finally sends
141 and the server responds with
143 and drops the connection.
145 If sufficient time passes without
151 tokens, or an invalid token is received, or it receives one of a number
152 of signals \(en currently
166 will thaw the filesystems and report a failure.
168 Diagnostics are reported to standard error. Exit statuses have specific
172 Successful completion. Filesystems were frozen and thawed as required.
175 Problem with command-line arguments. No filesystems were frozen.
178 Environmental problem, typically a system call failure: e.g., a file
179 failed to open, or there was a problem with the network communications.
180 Either no filesystems were frozen, or all filesystems were successfully
184 Timeout or invalid data. Either no connections containing the
186 token were made in time, or no data was received for a long enough
187 period after the filesystems were frozen, or an invalid token was
188 received. In the first case, no filesystems were frozen; in the other
189 two cases, the filesystems were successfully thawed.
194 program received a fatal signal after it had started to freeze
195 filesystems. Under these circumstances, it thaws the filesystems,
196 removes the signal handler, and sends itself the signal again, but if
197 that doesn't work then
199 exits with this status code. All frozen filesystems were successfully
203 Failure during filesystem thaw (mnemonic: European emergency number).
206 to thaw, and are still frozen. You might have some joy with
208 though in the author's experience that doesn't work and you'll probably
209 have to reboot. At least your filesystems are consistent...
211 When frozen, a filesystem's backing block device is put in a consistent
212 state (as if unmounted), and write operations to it are delayed until
213 the filesystem is thawed again. In the meantime, it's possible to take
214 a consistent snapshot of the block device. When a filesystem is
215 directly mounted on an LVM logical volume, the kernel detects this
216 situation and automatically freezes the filesystem while the snapshot is
217 being prepared. If the logical volume and filesystem are on separate
218 hosts, though, the filesystem must be frozen manually, which is why
228 or some other means of acquiring the necessary privilege level. You
229 read the port number and tokens, connect to the socket, and send the
231 token followed by a newline. You now wait to receive the
235 Once you have received this, the filesystems are frozen: you can safely
236 take snapshots. If this will take an extended amount of time, you
239 tokens to the connection at intervals in order to prevent
241 from timing out and thawing the filesystems (but see the
243 below). When your snapshot is prepared, sent the
245 token, and wait for the
247 token in response. If this is received, the snapshot was completed
248 successfully and the filesystems are properly thawed again. If you
251 token then something bad might have happened (e.g., the filesystem might
252 have been prematurely thawed) and the snapshot is suspect. If the exit
253 status is 112 then at least one filesystem is still frozen and some
254 emergency action is needed. If you can't retrieve the exit status then
255 it's possible that your transport is blocked for trying to write to the
256 frozen filesystem (this especially likely if
260 is frozen) and you should react as if the status was 112.
264 program uses randomly chosen tokens to form a simple code which is
265 revealed to the caller. It is assumed that this information is kept
266 secret from adversaries, e.g., by ensuring that it is only transmitted
267 over local pipes (as used by
269 and/or secure network transports such as SSH (see
271 The author believes that the worst possible outcome is that the host
272 wedges up because an important filesystem is frozen, and
274 therefore strives to prevent that from happening. In particular,
275 cryptographic transport implementations such as SSH may attempt to log
276 messages to frozen filesystems or otherwise wedge themselves:
278 deliberately uses only kernel-implemented transports for its
279 communication needs once the filesystems are frozen.
281 Most of the tokens are used at most once in the protocol. In
284 token can't be sent by an adversary in advance of the filesystem being
285 frozen, since (under the assumption that the tokens are kept secret) it
286 only revealed in the clear after a successful freeze. Similarly, the
288 token is only transmitted if the filesystems are thawed as a result of a
290 request (rather than a dropped connection, timeout, or some other
291 problem). If the client only sends the
293 request once its snapshot is complete, then a
295 response indicates that the filesystems remained frozen until the
296 snapshot was indeed completed and therefore the snapshot is consistent.
300 token, which may be sent repeatedly. After it is first revealed, an
301 adversary can hijack the connection and replay the
303 token to keep the filesystems frozen indefinitely. You can recover from
304 this by severing the connection somehow, or by sending
306 a signal. It is therefore recommended that
308 tokens not be sent unless necessary. The timeout is currently set to
309 60s, which ought to be adequate for most snapshot mechanisms.
311 There ought to be a better one-time-token protocol for keepalives. I
312 want to keep cryptography out of this program, though.
320 Mark Wooding, <mdw@distorted.org.uk>
~mdw / rsync-backup / blob