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