sbin/mountctl/mountctl.8

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