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