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