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