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.2 2005/01/09 03:06:14 dillon 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 w Ar output_path
  49 .Op Fl x Ar filedesc
  50 .Op Fl o Ar option
  51 .Op Fl o Ar option ...
  52 .Ar mountpt:tag
  53 .Nm
  54 .Fl d
  55 .Op Ar tag/mountpt | mountpt:tag
  56 .Nm
  57 .Fl m
  58 .Op Fl o Ar option
  59 .Op Fl o Ar option ...
  60 .Op Ar tag/mountpt | mountpt:tag
  61 .Nm
  62 .Fl FZSCA
  63 .Op Ar tag/mountpt | mountpt:tag
  64 .Pp
  65
  66 .Sh DESCRIPTION
  67 The
  68 .Nm
  69 utility manages journaling and (eventually) other features on a mounted
  70 filesystem.
  71 Note that a mount point path must begin with '/', and tag names must not
  72 begin with '/'.
  73 .Pp
  74 .Nm
  75 .Fl l
  76 will list all installed journals in the system or on a particular mount point
  77 or tag, including their current state of operation.
  78 .Pp
  79 .Nm
  80 .Fl a
  81 will add a new journal to a mount point.  A mount may have any number of
  82 journals associated with it.  If no output path is specified the journal
  83 will be written to the standard output.  Options may be specified as
  84 described in the OPTION KEYWORDS section.
  85 The tag is required and must be unique
  86 relative to any given mount, but you can use the same tag on multiple
  87 mount points if you wish (and control them all together by referencing that
  88 tag).
  89 The output path may represent any streamable entity.  You can, for example,
  90 output to a pipe into a program which does further buffering or processing
  91 of the journal.
  92 .Em WARNING
  93 A stalled journaling descriptor will stall the filesystem.  Eventually a
  94 kernel-implemented swap backing will be available for journals but that is
  95 not the case at the moment.
  96 .Pp
  97 .Nm
  98 .Fl d
  99 will remove the specified journal(s).  A mount point, a tag, or both may be
 100 specified.  This function will operate on all matching journals.
 101 .Pp
 102 .Nm
 103 .Fl m
 104 will modify the options associated with an existing journal.  Options are
 105 specified in the OPTION KEYWORDS section.
 106 .Sh OTHER OPTIONS
 107 .Bl -tag -width indent
 108 .It Fl F
 109 Flush a journal, equivalent to the 'flush' keyword.
 110 This option implies
 111 .Fl m .
 112 .It Fl Z
 113 Freeze a journal, equivalent to the 'freeze' keyword.
 114 This option implies
 115 .Fl m
 116 if
 117 .Fl a
 118 or
 119 .Fl d
 120 are not specified.
 121 .It Fl S
 122 Start or restart a journal, equivalent to the 'start' keyword.
 123 This option implies
 124 .Fl m .
 125 .It Fl C
 126 Close a journal, equivalent to the 'close' keyword.
 127 This option implies
 128 .Fl m .
 129 .It Fl A
 130 Abort a journal, equivalent to the 'abort' keyword.
 131 This option implies
 132 .Fl m .
 133 .It Fl w Ar output_path
 134 Change a journal's stream descriptor to the specified path.
 135 This option implies
 136 .Fl m
 137 if
 138 .Fl a
 139 or
 140 .Fl d
 141 are not specified.
 142 .It Fl x Ar filedesc
 143 Change a journal's stream descriptor to the specified file descriptor number.
 144 This option implies
 145 .Fl m
 146 if
 147 .Fl a
 148 or
 149 .Fl d
 150 are not specified.
 151 .El
 152 .Sh OPTION KEYWORDS
 153 Options keywords may be comma delimited without whitespace within a single
 154 .Fl o
 155 or via multiple
 156 .Fl o
 157 options.  Some keywords require a value which is specified as
 158 .Ar keyword=value .
 159 Any option may be prefixed with 'no' or 'non' to turn off the option.
 160 Some options are one-shot and have no 'no' or 'non' equivalent.
 161 .Pp
 162 The options are as follows:
 163 .Bl -tag -width indent
 164 .It Ar reversable
 165 Generate a reversable journaling stream.  This allows the target to run
 166 the journal backwards as well as forwards to 'undo' operations.  This is the
 167 default.
 168 .It Ar twoway
 169 Indicate that the journaling stream is a two-way stream and that transaction
 170 id acknowledgements will be returned.
 171 .It Ar memfifo=size[k,m]
 172 Specify the size of the in-kernel memory FIFO used to buffer the journaling
 173 stream between processes doing filesystem operations and the worker thread
 174 writing out the journal.  Since the kernel has limited virtual memory
 175 buffers larger then 4MB are not recommended.
 176 .It Ar swapfifo=size[k,m,g]
 177 Specify the size of the kernel-managed swap-backed FIFO used to buffer
 178 overflows.
 179 .It Ar path=filepath
 180 Switch the journal's output stream to a new file.  This feature is typically
 181 used to restart a dead stream.
 182 Note that the
 183 .Fl w
 184 option is equivalent to specifying the path option.  Both should not be
 185 specified.
 186 .It Ar fd=filedesc
 187 Switch the journal's output stream to a file descriptor specified by number.
 188 Use file descriptor 1 if you wish to reopen the journal to the current
 189 stdout.  This feature is typically used to restart a dead stream (for example
 190 if a TCP stream fails).
 191 Note that the
 192 .Fl w
 193 option is equivalent to specifying the path option.  Both should not be
 194 specified.
 195 .It Ar freeze
 196 Freeze the worker thread.  This may cause the filesystem to stall once
 197 the memory fifo has filled up.  A freeze point record will be written to
 198 the journal.  If used as part of the creation of a new journal via
 199 .Fl a ,
 200 this option will prevent any initial output to the journal and a freeze
 201 point record will NOT be written.  Again, the filesystem will stall if
 202 the memory fifo fills up.
 203 .It Ar start
 204 Start or restart the worker thread after a freeze.
 205 .It Ar close
 206 Close the journal.  Any transactions still under way will be allowed to
 207 complete, a closing record will be generated, and the journaling descriptor
 208 will be closed.  If the connection is two-way the journal will away a final
 209 acknowledgement of the closing record before closing the descriptor.
 210 .It Ar abort
 211 Close the journal.  Any currently buffered data will be aborted.  No close
 212 record is written.  The journaling stream is immediately closed.
 213 .It Ar flush
 214 Flush the journal.  All currently buffered data is flushed.  The command
 215 does not return until the write suceeds and, if the connection is two-way,
 216 and acknowledgement has been returned for journaled data buffered at the
 217 time the flush was issued.
 218 .El
 219 .Pp
 220 .Sh FILES
 221 .Sh SEE ALSO
 222 .Xr mount 2 ,
 223 .Sh BUGS
 224 .Sh CAVEATS
 225 This utility is currently under construction and not all features have been
 226 implemented yet.  In fact, most have not.
 227 .Sh HISTORY
 228 The
 229 .Nm
 230 utility first appeared in DragonFly .