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