1 .\" Copyright (c) 2003,2004 The DragonFly Project. All rights reserved.
3 .\" This code is derived from software contributed to The DragonFly Project
4 .\" by Matthew Dillon <dillon@backplane.com>
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in
15 .\" the documentation and/or other materials provided with the
17 .\" 3. Neither the name of The DragonFly Project nor the names of its
18 .\" contributors may be used to endorse or promote products derived
19 .\" from this software without specific, prior written permission.
21 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
25 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
27 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
29 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
31 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .Dd September 28, 2009
39 .Nd control journaling and other features on mounted file systems
43 .Brq Ar mountpt | tag | mountpt : Ns Ar tag
47 .Op Fl w/W Ar output_path
48 .Op Fl x/X Ar filedesc
50 .Ar mountpt Ns Cm \&: Ns Ar tag
54 .Op Fl w/W Ar output_path
55 .Op Fl x/X Ar filedesc
56 .Ar mountpt Ns Cm \&: Ns Ar tag
59 .Brq Ar mountpt | tag | mountpt Ns Cm \&: Ns Ar tag
63 .Brq Ar mountpt | tag | mountpt Ns Cm \&: Ns Ar tag
66 .Brq Ar mountpt | tag | mountpt Ns Cm \&: Ns Ar tag
70 utility manages journaling and (eventually) other features on a mounted
72 Note that a mount point path must begin with
74 and tag names must not
80 will list all installed journals in the system or on a particular mount point
81 or tag, including their current state of operation.
85 will add a new journal to a mount point.
86 A mount may have any number of journals associated with it.
87 If no output path is specified the journal
88 will be written to the standard output.
89 Options may be specified as described in the
92 The tag is required and must be unique
93 relative to any given mount, but you can use the same tag on multiple
94 mount points if you wish (and control them all together by referencing that
96 The output path may represent any streamable entity.
98 output to a pipe into a program which does further buffering or processing
101 A stalled journaling descriptor will stall the filesystem.
103 kernel-implemented swap backing will be available for journals but that is
104 not the case at the moment.
108 will restart an existing journal, directing it to a new file descriptor.
109 A shutdown is sent to the old journal and the system waits for the return
110 direction (if running full-duplex) to EOF.
111 The new descriptor is then
112 installed and the FIFO index is reset to the last acknowledged transaction.
113 Clients scanning a journal across such a disconnect must check for repeated
114 transaction ids since some overlap between the old and new journal may occur.
118 will remove the specified journal(s).
119 A mount point, a tag, or both may be specified.
120 This function will operate on all matching journals.
124 will modify the options associated with an existing journal.
125 Options are specified in the
129 .Bl -tag -width indent
131 Specify full-duplex operation.
132 The kernel will not throw away journal
133 data in its internal FIFO until the transaction id is acknowledged.
134 This requires a full-duplex journaling descriptor.
135 Note that shell pipes are full-duplex-capable.
137 Flush a journal, equivalent to the
143 Freeze a journal, equivalent to the
154 Start a stopped journal, equivalent to the
160 Close a journal, equivalent to the
166 Abort a journal, equivalent to the
171 .It Fl w Ar output_path
172 Change a journal's stream descriptor to the specified path.
180 The target file must not reside on the same filesystem being journaled.
181 .It Fl W Ar output_path
184 but overrides target safety checks.
186 Change a journal's stream descriptor to the specified file descriptor number.
194 The target file must not reside on the same filesystem being journaled.
198 but overrides target safety checks.
201 .Sx OPTION KEYWORDS .
204 Options keywords may be comma delimited without whitespace within a single
209 Some keywords require a value which is specified as
210 .Ar keyword Ns = Ns Ar value .
211 Any option may be prefixed with
215 to turn off the option.
216 Some options are one-shot and have no
222 The options are as follows:
223 .Bl -tag -width indent
225 Generate a reversable journaling stream.
226 This allows the target to run
227 the journal backwards as well as forwards to
232 Indicate that the journaling stream is a two-way stream and that transaction
233 id acknowledgements will be returned.
234 This option is the same as the
237 .It Cm memfifo= Ns Ar size Ns Op Cm k , Ns Cm m
238 Specify the size of the in-kernel memory FIFO used to buffer the journaling
239 stream between processes doing filesystem operations and the worker thread
240 writing out the journal.
241 Since the kernel has limited virtual memory
242 buffers larger than 4MB are not recommended.
243 .It Cm swapfifo= Ns Ar size Ns Op Cm k , Ns Cm m , Ns Cm g
244 Specify the size of the kernel-managed swap-backed FIFO used to buffer
246 .It Cm path= Ns Ar filepath
247 Specify where the journal's output stream should be directed.
250 option is equivalent to specifying the path option.
251 Both should not be specified.
252 .It Cm fd= Ns Ar filedesc
253 Specify where the journal's output stream should be directed by handing over
255 Use file descriptor 1 if you wish to output the journal to the current stdout.
258 option is equivalent to specifying the path option.
259 Both should not be specified.
261 Freeze the worker thread.
262 This may cause the filesystem to stall once
263 the memory fifo has filled up.
264 A freeze point record will be written to the journal.
265 If used as part of the creation of a new journal via
267 this option will prevent any initial output to the journal and a freeze
268 point record will NOT be written.
269 Again, the filesystem will stall if the memory fifo fills up.
271 Start or restart the worker thread after a freeze.
274 Any transactions still under way will be allowed to
275 complete, a closing record will be generated, and the journaling descriptor
277 If the connection is two-way the journal will away a final
278 acknowledgement of the closing record before closing the descriptor.
281 Any currently buffered data will be aborted.
282 No close record is written.
283 The journaling stream is immediately closed.
286 All currently buffered data is flushed.
288 does not return until the write succeeds and, if the connection is two-way,
289 and acknowledgement has been returned for journaled data buffered at the
290 time the flush was issued.
300 utility first appeared in
303 This utility is currently under construction and not all features have been
305 In fact, most have not.