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