Fix some groff warnings.
[dragonfly.git] / sbin / mountctl / mountctl.8
CommitLineData
e5a066b0
MD
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.\"
cb65615c 34.\" $DragonFly: src/sbin/mountctl/mountctl.8,v 1.3 2005/03/08 20:29:55 swildner Exp $
e5a066b0
MD
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
7ced4a1a 45.Op Ar tag/mountpt | mountpt:tag
e5a066b0
MD
46.Nm
47.Fl a
48.Op Fl w Ar output_path
49.Op Fl x Ar filedesc
50.Op Fl o Ar option
51.Op Fl o Ar option ...
7ced4a1a 52.Ar mountpt:tag
e5a066b0
MD
53.Nm
54.Fl d
7ced4a1a 55.Op Ar tag/mountpt | mountpt:tag
e5a066b0
MD
56.Nm
57.Fl m
58.Op Fl o Ar option
59.Op Fl o Ar option ...
7ced4a1a 60.Op Ar tag/mountpt | mountpt:tag
e5a066b0
MD
61.Nm
62.Fl FZSCA
7ced4a1a
MD
63.Op Ar tag/mountpt | mountpt:tag
64.Pp
e5a066b0
MD
65.Sh DESCRIPTION
66The
67.Nm
68utility manages journaling and (eventually) other features on a mounted
7ced4a1a
MD
69filesystem.
70Note that a mount point path must begin with '/', and tag names must not
71begin with '/'.
e5a066b0
MD
72.Pp
73.Nm
74.Fl l
75will list all installed journals in the system or on a particular mount point
76or tag, including their current state of operation.
77.Pp
78.Nm
79.Fl a
80will add a new journal to a mount point. A mount may have any number of
81journals associated with it. If no output path is specified the journal
82will be written to the standard output. Options may be specified as
83described in the OPTION KEYWORDS section.
84The tag is required and must be unique
85relative to any given mount, but you can use the same tag on multiple
86mount points if you wish (and control them all together by referencing that
87tag).
88The output path may represent any streamable entity. You can, for example,
89output to a pipe into a program which does further buffering or processing
90of the journal.
91.Em WARNING
92A stalled journaling descriptor will stall the filesystem. Eventually a
93kernel-implemented swap backing will be available for journals but that is
94not the case at the moment.
95.Pp
96.Nm
97.Fl d
98will remove the specified journal(s). A mount point, a tag, or both may be
99specified. This function will operate on all matching journals.
100.Pp
101.Nm
102.Fl m
103will modify the options associated with an existing journal. Options are
104specified in the OPTION KEYWORDS section.
105.Sh OTHER OPTIONS
106.Bl -tag -width indent
107.It Fl F
108Flush a journal, equivalent to the 'flush' keyword.
109This option implies
110.Fl m .
111.It Fl Z
112Freeze a journal, equivalent to the 'freeze' keyword.
113This option implies
114.Fl m
115if
116.Fl a
117or
118.Fl d
119are not specified.
120.It Fl S
121Start or restart a journal, equivalent to the 'start' keyword.
122This option implies
123.Fl m .
124.It Fl C
125Close a journal, equivalent to the 'close' keyword.
126This option implies
127.Fl m .
128.It Fl A
129Abort a journal, equivalent to the 'abort' keyword.
130This option implies
131.Fl m .
132.It Fl w Ar output_path
133Change a journal's stream descriptor to the specified path.
134This option implies
135.Fl m
136if
137.Fl a
138or
139.Fl d
140are not specified.
141.It Fl x Ar filedesc
142Change a journal's stream descriptor to the specified file descriptor number.
143This option implies
144.Fl m
145if
146.Fl a
147or
148.Fl d
149are not specified.
150.El
151.Sh OPTION KEYWORDS
152Options keywords may be comma delimited without whitespace within a single
153.Fl o
154or via multiple
155.Fl o
156options. Some keywords require a value which is specified as
157.Ar keyword=value .
158Any option may be prefixed with 'no' or 'non' to turn off the option.
159Some options are one-shot and have no 'no' or 'non' equivalent.
160.Pp
161The options are as follows:
162.Bl -tag -width indent
163.It Ar reversable
164Generate a reversable journaling stream. This allows the target to run
165the journal backwards as well as forwards to 'undo' operations. This is the
166default.
167.It Ar twoway
168Indicate that the journaling stream is a two-way stream and that transaction
169id acknowledgements will be returned.
170.It Ar memfifo=size[k,m]
171Specify the size of the in-kernel memory FIFO used to buffer the journaling
172stream between processes doing filesystem operations and the worker thread
173writing out the journal. Since the kernel has limited virtual memory
174buffers larger then 4MB are not recommended.
175.It Ar swapfifo=size[k,m,g]
176Specify the size of the kernel-managed swap-backed FIFO used to buffer
177overflows.
178.It Ar path=filepath
179Switch the journal's output stream to a new file. This feature is typically
180used to restart a dead stream.
181Note that the
182.Fl w
183option is equivalent to specifying the path option. Both should not be
184specified.
185.It Ar fd=filedesc
186Switch the journal's output stream to a file descriptor specified by number.
187Use file descriptor 1 if you wish to reopen the journal to the current
188stdout. This feature is typically used to restart a dead stream (for example
189if a TCP stream fails).
190Note that the
191.Fl w
192option is equivalent to specifying the path option. Both should not be
193specified.
194.It Ar freeze
195Freeze the worker thread. This may cause the filesystem to stall once
196the memory fifo has filled up. A freeze point record will be written to
197the journal. If used as part of the creation of a new journal via
198.Fl a ,
199this option will prevent any initial output to the journal and a freeze
200point record will NOT be written. Again, the filesystem will stall if
201the memory fifo fills up.
202.It Ar start
203Start or restart the worker thread after a freeze.
204.It Ar close
205Close the journal. Any transactions still under way will be allowed to
206complete, a closing record will be generated, and the journaling descriptor
207will be closed. If the connection is two-way the journal will away a final
208acknowledgement of the closing record before closing the descriptor.
209.It Ar abort
210Close the journal. Any currently buffered data will be aborted. No close
211record is written. The journaling stream is immediately closed.
212.It Ar flush
213Flush the journal. All currently buffered data is flushed. The command
214does not return until the write suceeds and, if the connection is two-way,
215and acknowledgement has been returned for journaled data buffered at the
216time the flush was issued.
217.El
218.Pp
219.Sh FILES
220.Sh SEE ALSO
221.Xr mount 2 ,
222.Sh BUGS
223.Sh CAVEATS
224This utility is currently under construction and not all features have been
225implemented yet. In fact, most have not.
226.Sh HISTORY
227The
228.Nm
229utility first appeared in DragonFly .