mountctl(8): Improve Synopsis & sync usage(), also improve markup
[dragonfly.git] / sbin / mountctl / mountctl.8
CommitLineData
e5a066b0 1.\" Copyright (c) 2003,2004 The DragonFly Project. All rights reserved.
1bf4b486 2.\"
e5a066b0
MD
3.\" This code is derived from software contributed to The DragonFly Project
4.\" by Matthew Dillon <dillon@backplane.com>
1bf4b486
SW
5.\"
6.\"
e5a066b0
MD
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
1bf4b486 10.\"
e5a066b0
MD
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
16.\" distribution.
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.
1bf4b486 20.\"
e5a066b0
MD
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
32.\" SUCH DAMAGE.
33.\"
9acb7645 34.\" $DragonFly: src/sbin/mountctl/mountctl.8,v 1.15 2008/10/16 23:08:30 swildner Exp $
e5a066b0 35.\"
9ef84c09 36.Dd September 28, 2009
e5a066b0
MD
37.Dt MOUNTCTL 8
38.Os
39.Sh NAME
40.Nm mountctl
41.Nd control journaling and other features on mounted file systems
42.Sh SYNOPSIS
43.Nm
44.Fl l
9ef84c09 45.Brq Ar mountpt | tag | mountpt Ns : Ns Ar tag
e5a066b0
MD
46.Nm
47.Fl a
7d344f83 48.Op Fl 2
243d58ba
MD
49.Op Fl w/W Ar output_path
50.Op Fl x/X Ar filedesc
9ef84c09
TN
51.Op Fl o Ar options
52.Ar mountpt Ns Cm \&: Ns Ar tag
e5a066b0 53.Nm
500b6a22
MD
54.Fl r
55.Op Fl 2
243d58ba
MD
56.Op Fl w/W Ar output_path
57.Op Fl x/X Ar filedesc
9ef84c09 58.Ar mountpt Ns Cm \&: Ns Ar tag
500b6a22 59.Nm
e5a066b0 60.Fl d
9ef84c09 61.Brq Ar mountpt | tag | mountpt Ns Cm \&: Ns Ar tag
e5a066b0
MD
62.Nm
63.Fl m
9ef84c09
TN
64.Op Fl o Ar options
65.Brq Ar mountpt | tag | mountpt Ns Cm \&: Ns Ar tag
e5a066b0
MD
66.Nm
67.Fl FZSCA
9ef84c09 68.Brq Ar mountpt | tag | mountpt Ns Cm \&: Ns Ar tag
e5a066b0
MD
69.Sh DESCRIPTION
70The
71.Nm
72utility manages journaling and (eventually) other features on a mounted
7ced4a1a 73filesystem.
9ef84c09
TN
74Note that a mount point path must begin with
75.Ql / ,
76and tag names must not
77begin with
78.Ql / .
e5a066b0
MD
79.Pp
80.Nm
81.Fl l
82will list all installed journals in the system or on a particular mount point
83or tag, including their current state of operation.
84.Pp
85.Nm
86.Fl a
9ef84c09
TN
87will add a new journal to a mount point.
88A mount may have any number of journals associated with it.
89If no output path is specified the journal
90will be written to the standard output.
91Options may be specified as described in the
92.Sx OPTION KEYWORDS
93section.
e5a066b0
MD
94The tag is required and must be unique
95relative to any given mount, but you can use the same tag on multiple
96mount points if you wish (and control them all together by referencing that
97tag).
9ef84c09
TN
98The output path may represent any streamable entity.
99You can, for example,
e5a066b0
MD
100output to a pipe into a program which does further buffering or processing
101of the journal.
102.Em WARNING
9ef84c09
TN
103A stalled journaling descriptor will stall the filesystem.
104Eventually a
e5a066b0
MD
105kernel-implemented swap backing will be available for journals but that is
106not the case at the moment.
107.Pp
108.Nm
500b6a22
MD
109.Fl r
110will restart an existing journal, directing it to a new file descriptor.
111A shutdown is sent to the old journal and the system waits for the return
9ef84c09
TN
112direction (if running full-duplex) to EOF.
113The new descriptor is then
500b6a22
MD
114installed and the FIFO index is reset to the last acknowledged transaction.
115Clients scanning a journal across such a disconnect must check for repeated
116transaction ids since some overlap between the old and new journal may occur.
117.Pp
118.Nm
e5a066b0 119.Fl d
9ef84c09
TN
120will remove the specified journal(s).
121A mount point, a tag, or both may be specified.
122This function will operate on all matching journals.
e5a066b0
MD
123.Pp
124.Nm
125.Fl m
9ef84c09
TN
126will modify the options associated with an existing journal.
127Options are specified in the
128.Sx OPTION KEYWORDS
129section.
e5a066b0
MD
130.Sh OTHER OPTIONS
131.Bl -tag -width indent
7d344f83 132.It Fl 2
9ef84c09
TN
133Specify full-duplex operation.
134The kernel will not throw away journal
135data in its internal FIFO until the transaction id is acknowledged.
136This requires a full-duplex journaling descriptor.
137Note that shell pipes are full-duplex-capable.
e5a066b0 138.It Fl F
9ef84c09
TN
139Flush a journal, equivalent to the
140.Cm flush
141keyword.
e5a066b0
MD
142This option implies
143.Fl m .
144.It Fl Z
9ef84c09
TN
145Freeze a journal, equivalent to the
146.Cm freeze
147keyword.
e5a066b0
MD
148This option implies
149.Fl m
150if
151.Fl a
152or
153.Fl d
154are not specified.
155.It Fl S
9ef84c09
TN
156Start a stopped journal, equivalent to the
157.Cm start
158keyword.
e5a066b0
MD
159This option implies
160.Fl m .
161.It Fl C
9ef84c09
TN
162Close a journal, equivalent to the
163.Cm close
164keyword.
e5a066b0
MD
165This option implies
166.Fl m .
167.It Fl A
9ef84c09
TN
168Abort a journal, equivalent to the
169.Cm abort
170keyword.
e5a066b0
MD
171This option implies
172.Fl m .
173.It Fl w Ar output_path
174Change a journal's stream descriptor to the specified path.
175This option implies
176.Fl m
177if
178.Fl a
179or
180.Fl d
9ef84c09
TN
181are not specified.
182The target file must not reside on the same filesystem being journaled.
243d58ba
MD
183.It Fl W Ar output_path
184Same as
185.Fl w
186but overrides target safety checks.
e5a066b0
MD
187.It Fl x Ar filedesc
188Change a journal's stream descriptor to the specified file descriptor number.
189This option implies
190.Fl m
191if
192.Fl a
193or
194.Fl d
9ef84c09
TN
195are not specified.
196The target file must not reside on the same filesystem being journaled.
243d58ba
MD
197.It Fl X Ar filedesc
198Same as
199.Fl x
200but overrides target safety checks.
9ef84c09
TN
201.It Fl o Ar options
202Specify options, see
203.Sx OPTION KEYWORDS .
e5a066b0
MD
204.El
205.Sh OPTION KEYWORDS
206Options keywords may be comma delimited without whitespace within a single
207.Fl o
208or via multiple
209.Fl o
9ef84c09
TN
210options.
211Some keywords require a value which is specified as
212.Ar keyword Ns = Ns Ar value .
213Any option may be prefixed with
214.Ql no
215or
216.Ql non
217to turn off the option.
218Some options are one-shot and have no
219.Ql no
220or
221.Ql non
222equivalent.
e5a066b0
MD
223.Pp
224The options are as follows:
225.Bl -tag -width indent
9ef84c09
TN
226.It Cm reversable
227Generate a reversable journaling stream.
228This allows the target to run
229the journal backwards as well as forwards to
230.Ql undo
231operations.
232This is the default.
233.It Cm twoway
e5a066b0 234Indicate that the journaling stream is a two-way stream and that transaction
9ef84c09
TN
235id acknowledgements will be returned.
236This option is the same as the
7d344f83
MD
237.Fl 2
238option.
9ef84c09 239.It Cm memfifo= Ns Ar size Ns Op Cm k Ns , Ns Cm m
e5a066b0
MD
240Specify the size of the in-kernel memory FIFO used to buffer the journaling
241stream between processes doing filesystem operations and the worker thread
9ef84c09
TN
242writing out the journal.
243Since the kernel has limited virtual memory
9acb7645 244buffers larger than 4MB are not recommended.
9ef84c09 245.It Cm swapfifo= Ns Ar size Ns Op Cm k Ns , Ns Cm m Ns , Ns Cm g
e5a066b0
MD
246Specify the size of the kernel-managed swap-backed FIFO used to buffer
247overflows.
9ef84c09 248.It Cm path= Ns Ar filepath
1bf4b486 249Specify where the journal's output stream should be directed.
e5a066b0
MD
250Note that the
251.Fl w
9ef84c09
TN
252option is equivalent to specifying the path option.
253Both should not be specified.
254.It Cm fd= Ns Ar filedesc
500b6a22 255Specify where the journal's output stream should be directed by handing over
3f5e28f4 256a file descriptor.
9ef84c09 257Use file descriptor 1 if you wish to output the journal to the current stdout.
e5a066b0
MD
258Note that the
259.Fl w
9ef84c09
TN
260option is equivalent to specifying the path option.
261Both should not be specified.
262.It Cm freeze
263Freeze the worker thread.
264This may cause the filesystem to stall once
265the memory fifo has filled up.
266A freeze point record will be written to the journal.
267If used as part of the creation of a new journal via
e5a066b0
MD
268.Fl a ,
269this option will prevent any initial output to the journal and a freeze
9ef84c09
TN
270point record will NOT be written.
271Again, the filesystem will stall if the memory fifo fills up.
272.It Cm start
e5a066b0 273Start or restart the worker thread after a freeze.
9ef84c09
TN
274.It Cm close
275Close the journal.
276Any transactions still under way will be allowed to
e5a066b0 277complete, a closing record will be generated, and the journaling descriptor
9ef84c09
TN
278will be closed.
279If the connection is two-way the journal will away a final
e5a066b0 280acknowledgement of the closing record before closing the descriptor.
9ef84c09
TN
281.It Cm abort
282Close the journal.
283Any currently buffered data will be aborted.
284No close record is written.
285The journaling stream is immediately closed.
286.It Cm flush
287Flush the journal.
288All currently buffered data is flushed.
289The command
3f5e28f4 290does not return until the write succeeds and, if the connection is two-way,
e5a066b0
MD
291and acknowledgement has been returned for journaled data buffered at the
292time the flush was issued.
293.El
a9cfaf7c 294.\".Sh FILES
e5a066b0
MD
295.Sh SEE ALSO
296.Xr mount 2 ,
c27eed25 297.Xr mountctl 2 ,
7d344f83 298.Xr jscan 8
e5a066b0
MD
299.Sh CAVEATS
300This utility is currently under construction and not all features have been
9ef84c09
TN
301implemented yet.
302In fact, most have not.
e5a066b0
MD
303.Sh HISTORY
304The
305.Nm
a3220ac5 306utility first appeared in
9ef84c09 307.Dx 1.2 .
e1f9247f 308.\".Sh BUGS