| blob | c5bdf850d36469a1e790065f1b1d5c1c55c8c9ac |
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 .Dd September 28, 2009
35 .Dt MOUNTCTL 8
36 .Os
37 .Sh NAME
38 .Nm mountctl
39 .Nd control journaling and other features on mounted file systems
40 .Sh SYNOPSIS
41 .Nm
42 .Fl l
43 .Brq Ar mountpt | tag | mountpt : Ns Ar tag
44 .Nm
45 .Fl a
46 .Op Fl 2
47 .Op Fl w/W Ar output_path
48 .Op Fl x/X Ar filedesc
49 .Op Fl o Ar options
50 .Ar mountpt Ns Cm \&: Ns Ar tag
51 .Nm
52 .Fl r
53 .Op Fl 2
54 .Op Fl w/W Ar output_path
55 .Op Fl x/X Ar filedesc
56 .Ar mountpt Ns Cm \&: Ns Ar tag
57 .Nm
58 .Fl d
59 .Brq Ar mountpt | tag | mountpt Ns Cm \&: Ns Ar tag
60 .Nm
61 .Fl m
62 .Op Fl o Ar options
63 .Brq Ar mountpt | tag | mountpt Ns Cm \&: Ns Ar tag
64 .Nm
65 .Fl FZSCA
66 .Brq Ar mountpt | tag | mountpt Ns Cm \&: Ns Ar tag
67 .Sh DESCRIPTION
68 The
69 .Nm
70 utility manages journaling and (eventually) other features on a mounted
71 filesystem.
72 Note that a mount point path must begin with
73 .Ql / ,
74 and tag names must not
75 begin with
76 .Ql / .
77 .Pp
78 .Nm
79 .Fl l
80 will list all installed journals in the system or on a particular mount point
81 or tag, including their current state of operation.
82 .Pp
83 .Nm
84 .Fl a
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
90 .Sx OPTION KEYWORDS
91 section.
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
95 tag).
96 The output path may represent any streamable entity.
97 You can, for example,
98 output to a pipe into a program which does further buffering or processing
99 of the journal.
100 .Em WARNING
101 A stalled journaling descriptor will stall the filesystem.
102 Eventually a
103 kernel-implemented swap backing will be available for journals but that is
104 not the case at the moment.
105 .Pp
106 .Nm
107 .Fl r
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.
115 .Pp
116 .Nm
117 .Fl d
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.
121 .Pp
122 .Nm
123 .Fl m
124 will modify the options associated with an existing journal.
125 Options are specified in the
126 .Sx OPTION KEYWORDS
127 section.
128 .Sh OTHER OPTIONS
129 .Bl -tag -width indent
130 .It Fl 2
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.
136 .It Fl F
137 Flush a journal, equivalent to the
138 .Cm flush
139 keyword.
140 This option implies
141 .Fl m .
142 .It Fl Z
143 Freeze a journal, equivalent to the
144 .Cm freeze
145 keyword.
146 This option implies
147 .Fl m
148 if
149 .Fl a
150 or
151 .Fl d
152 are not specified.
153 .It Fl S
154 Start a stopped journal, equivalent to the
155 .Cm start
156 keyword.
157 This option implies
158 .Fl m .
159 .It Fl C
160 Close a journal, equivalent to the
161 .Cm close
162 keyword.
163 This option implies
164 .Fl m .
165 .It Fl A
166 Abort a journal, equivalent to the
167 .Cm abort
168 keyword.
169 This option implies
170 .Fl m .
171 .It Fl w Ar output_path
172 Change a journal's stream descriptor to the specified path.
173 This option implies
174 .Fl m
175 if
176 .Fl a
177 or
178 .Fl d
179 are not specified.
180 The target file must not reside on the same filesystem being journaled.
181 .It Fl W Ar output_path
182 Same as
183 .Fl w
184 but overrides target safety checks.
185 .It Fl x Ar filedesc
186 Change a journal's stream descriptor to the specified file descriptor number.
187 This option implies
188 .Fl m
189 if
190 .Fl a
191 or
192 .Fl d
193 are not specified.
194 The target file must not reside on the same filesystem being journaled.
195 .It Fl X Ar filedesc
196 Same as
197 .Fl x
198 but overrides target safety checks.
199 .It Fl o Ar options
200 Specify options, see
201 .Sx OPTION KEYWORDS .
202 .El
203 .Sh OPTION KEYWORDS
204 Options keywords may be comma delimited without whitespace within a single
205 .Fl o
206 or via multiple
207 .Fl o
208 options.
209 Some keywords require a value which is specified as
210 .Ar keyword Ns = Ns Ar value .
211 Any option may be prefixed with
212 .Ql no
213 or
214 .Ql non
215 to turn off the option.
216 Some options are one-shot and have no
217 .Ql no
218 or
219 .Ql non
220 equivalent.
221 .Pp
222 The options are as follows:
223 .Bl -tag -width indent
224 .It Cm reversable
225 Generate a reversable journaling stream.
226 This allows the target to run
227 the journal backwards as well as forwards to
228 .Ql undo
229 operations.
230 This is the default.
231 .It Cm twoway
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
235 .Fl 2
236 option.
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
245 overflows.
246 .It Cm path= Ns Ar filepath
247 Specify where the journal's output stream should be directed.
248 Note that the
249 .Fl w
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
254 a file descriptor.
255 Use file descriptor 1 if you wish to output the journal to the current stdout.
256 Note that the
257 .Fl w
258 option is equivalent to specifying the path option.
259 Both should not be specified.
260 .It Cm freeze
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
266 .Fl a ,
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.
270 .It Cm start
271 Start or restart the worker thread after a freeze.
272 .It Cm close
273 Close the journal.
274 Any transactions still under way will be allowed to
275 complete, a closing record will be generated, and the journaling descriptor
276 will be closed.
277 If the connection is two-way the journal will away a final
278 acknowledgement of the closing record before closing the descriptor.
279 .It Cm abort
280 Close the journal.
281 Any currently buffered data will be aborted.
282 No close record is written.
283 The journaling stream is immediately closed.
284 .It Cm flush
285 Flush the journal.
286 All currently buffered data is flushed.
287 The command
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.
291 .El
292 .\".Sh FILES
293 .Sh SEE ALSO
294 .Xr mount 2 ,
295 .Xr mountctl 2 ,
296 .Xr jscan 8
297 .Sh HISTORY
298 The
299 .Nm
300 utility first appeared in
301 .Dx 1.2 .
302 .Sh CAVEATS
303 This utility is currently under construction and not all features have been
304 implemented yet.
305 In fact, most have not.
306 .\".Sh BUGS