sbin/jscan/jscan.8

   1 .\" Copyright (c) 2004,2005 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 February 8, 2009
  35 .Dt JSCAN 8
  36 .Os
  37 .Sh NAME
  38 .Nm jscan
  39 .Nd journal file processing program
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Op Fl 2dfuvF
  43 .Op Fl c Ar count[k,m,g,t]
  44 .Op Fl D Ar directory
  45 .Op Fl m Ar mirror_transid_file/none
  46 .Op Fl o/O Ar output_transid_file/none
  47 .Op Fl s Ar size[k,m,g,t]
  48 .Op Fl w/W Ar journal_prefix
  49 .Op Ar journal_prefix/file
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 utility scans journal file or input stream for the purposes of debugging
  54 dumps, restoration, undo, mirroring, and other journaling features.
  55 .Bl -tag -width indent
  56 .It Fl 2
  57 Implement the full-duplex acknowledgement protocol on the input descriptor.
  58 Note that shell pipes are full-duplex and can be used with this option.
  59 .It Fl c Ar count
  60 Specify the number of transaction records which should be scanned, then exit.
  61 This option is typically used along with
  62 .Fl m
  63 to limit the amount of work that
  64 .Nm
  65 does, giving you the ability to incrementally run a mirror forwards or
  66 backwards.  It is not usually used when piping in a live journal, but it
  67 can be.
  68 .It Fl d
  69 Display the contents of the journaling file or stream in a human readable
  70 format on stderr.  Note that stdout is used only for
  71 .Fl o .
  72 .It Fl f
  73 .Nm
  74 will sleep for 5 seconds and loop when it hits EOF on file or prefix
  75 set input rather than exit.  This option is typically used when running
  76 on an input file or prefix set which is live (being written to by
  77 another
  78 .Nm
  79 instance).
  80 .It Fl D Ar directory
  81 Specify the base directory for the mirroring option.
  82 .It Fl m Ar mirror_transid_file/none
  83 Generate a mirror in the directory specified by
  84 .Fl D
  85 or, if not specified, the current directory.
  86 The
  87 .Ar mirror_transid_file
  88 will be used to track the transaction id representing the current
  89 synchronization point for the mirror.  The keyword
  90 .Ar none
  91 may be specified if no tracking file is desired.  However, if no tracking
  92 file is specified it will not be possible to roll the mirror forwards or
  93 backwards or restart the journaling stream being used to generate the mirror.
  94 .Pp
  95 It is important to note that journaling streams can contain meta-transactions
  96 representing huge, multi-gigabyte operations.  If the journaling data is
  97 not being recorded to regular files via
  98 .Fl w/W
  99 it is possible that
 100 .Nm
 101 could run itself out of memory trying to record the meta-transactions.
 102 In addition, the mirror would not be restartable.  If the journaling data
 103 is being recorded via
 104 .Fl w/W
 105 and a mirroring transaction id file is being kept, the mirror can be
 106 restarted.
 107 .Pp
 108 While it is possible to run a journaling stream directly into a mirror,
 109 it is more typical to file the jornaling stream with
 110 .Fl w
 111 and catch the mirror up as a batch job with the journaling file set prefix
 112 specified as the input every so often.  This way the system operator can
 113 use other
 114 .Nm
 115 commands to, for example, run a mirror backwards and forwards in time.
 116 .It Fl o/O Ar output_transid_file/none
 117 Generate a journaling stream on stdout using the specified file to track
 118 the transaction id to help with restarts.
 119 The
 120 .Fl o
 121 option indicates a half-duplex output stream while the
 122 .Fl O
 123 option indicates a full-duplex (ACK protocol) output stream.
 124 .Pp
 125 This option is not really designed to output to regular files because it
 126 does NOT necessarily weed out duplicate records.  When both the input
 127 stream and output stream are full-duplex and
 128 .Fl w/W
 129 is not specified,
 130 .Nm
 131 acts as a stateless transceiver and the input stream is not acked until
 132 an ack is received from the output stream.
 133 .Pp
 134 This option is most typically used in conjunction with
 135 .Fl w/W .
 136 In this case the ACK protocol is handled independently for the input side
 137 and the output side uses the journaling data recorded by
 138 .Fl w/W
 139 as a buffer.
 140 .Pp
 141 In half-duplex output mode the output transaction id file is updated
 142 after a raw transaction record has been successfully written to stdout.
 143 In full-duplex output mode the file is only updated with ACK data returned
 144 on the stdout descriptor.
 145 .Pp
 146 As with the
 147 .Fl m
 148 option, you can combine
 149 .Fl o
 150 in a journaling pipe with other options, but if you are trying to use it
 151 as a buffer it may be better to have it separately pull its data off of
 152 a journaling file set generated via
 153 .Fl w .
 154 .It Fl s Ar size
 155 Change the size limit for rotating files created via
 156 .Fl w .
 157 The default is 100M.  Values are in bytes or may be suffixed with k,
 158 m, or g.
 159 If a raw transaction causes the file's size limit to be exceeded, a new file
 160 will be created.  If a raw transaction is, in-whole, larger than the file's
 161 size limit, the raw transaction will still be fully written to the file before
 162 a new file is created.  Raw transactions are typically limited to the size
 163 of the source system's memory FIFO.  This option is typically used to size
 164 journaling files to fit onto the appropriate backup media or to provide
 165 bite-sized chunks for other programs to ingest.
 166 .Pp
 167 When restarting a journal, a new sequence number will always be chosen for
 168 the resumption of data recording.  No existing file will be appended to when
 169 .Nm
 170 is reinvoked.
 171 .It Fl u
 172 Will cause the journal to be scanned backwards (requires seekable media).
 173 Transactions will be dumped in reverse order.  If mirroring, the UNDO
 174 data will be executed.  If not specified, 1 hour's worth of data will be
 175 undone.  Can only be used with a journaling file or journaling prefix
 176 as the input.
 177 .It Fl v
 178 Increase verbosity on stderr.  This option is primarily used for debugging.
 179 .It Fl w Ar prefix
 180 The received journaling stream is recorded in journaling files named
 181 .Ar <prefix>.<seq>
 182 and the current transaction id is tracked in a file named
 183 .Ar <prefix>.transid .
 184 A journaling file is closed out and a new file with the next sequence
 185 number is created once the file surpasses 100MB.
 186 .Pp
 187 This option is robust across restarts.  The current transaction id
 188 will be read and the input stream will be skipped until it is reached.
 189 If the input is a journaling file or prefix set,
 190 .Nm
 191 will be able to quickly seek to the restart point.
 192 .Pp
 193 NOTE: If
 194 you are generating a mirror with the same command via
 195 .Fl m ,
 196 and the journaling data input is a stream rather than a file or prefix
 197 set, you must use
 198 .Fl w/W
 199 if you want the mirror to be restartable.  This is because while we can
 200 pick up the transaction id where we left off, that raw transaction id may
 201 have cut a larger meta-transaction in half and the mirroring code will
 202 not be able to access the whole of the transaction unless it has a file
 203 or prefix set to work with.
 204 .It Fl W Ar prefix
 205 Similar to
 206 .Fl w
 207 except that the journaling files created are strictly temporary and will
 208 be deleted once they exceed the size limit AND the related meta-transactions
 209 have been completed.
 210 .Pp
 211 If combined with
 212 .Fl m ,
 213 the meta-transactions are considered to be completed only when the mirror
 214 finishes executing them.  It is possible for several sequence number files
 215 to build if a particularly large meta-transaction is coming down the pipe.
 216 .Pp
 217 If combined with
 218 .Fl o/O ,
 219 the meta-transactions are considered to be completed when the data has
 220 been successfully written out to the pipe in half duplex mode, or when
 221 the ACK has been received in full-duplex mode.
 222 .Pp
 223 If both
 224 .Fl m
 225 and
 226 .Fl w/W
 227 is used, the journaling data files are only deleted when both actions
 228 no longer need the data.
 229 .It Fl F
 230 Forces
 231 .Nm
 232 to
 233 .Fn fsync
 234 after updating a journaling file prior to acknowledging the
 235 data or updating a transaction-id-tracking file.  If specified twice,
 236 .Nm
 237 will also
 238 .Fn fsync
 239 after updating the transaction-id-tracking file.
 240 .It Ar journal_prefix/file
 241 Specify the input to
 242 .Nm .
 243 This can be a journaling file set prefix
 244 or it can be a plain file.  If no input file is specified, stdin is
 245 assumed.  Note that when generating a mirror from a stdin stream, the
 246 mirror will not be restartable unless
 247 .Fl w/W
 248 is also used.
 249 .El
 250 .Sh OPERATIONAL NOTES
 251 It is often important to be able to quickly stage journaled data through
 252 a dedicated backup machine on a LAN.  There are several places where data
 253 can be buffered and staged out.
 254 .Pp
 255 The machine generating the journal typically buffers several megabytes of
 256 journal data in the kernel.  This local machine can pipe that data to
 257 .Nm
 258 or some other locally run program to add another buffering stage, or you
 259 can directly attach a TCP connection to the kernel's journaling output.
 260 .Pp
 261 The LAN backup box typically buffers gigabytes worth of data by running
 262 multiple jscans.  The
 263 .Nm
 264 on the receiving end of the TCP or pipe (for
 265 example, via ssh) typically records the data via the
 266 .Fl w
 267 option, and then runs other
 268 .Nm
 269 programs from scripts or cron to take that data and copy it to your
 270 off-site backup machine.  Other
 271 .Nm
 272 programs may use the same data
 273 set to generate mirrors or other backup streams.
 274 .Pp
 275 It should be noted that if
 276 .Fl w/W
 277 is specified, both mirroring mode and output mode will internally
 278 fork the program once the appropriate synchronization point has been reached,
 279 effectively decoupling their operation, and read all of their data via
 280 the journaling files written out by the master program.  In particular,
 281 blockages in the mirroring and output code will not affect our ability
 282 to buffer the journaling input data via
 283 .Fl w/W .
 284 If
 285 .Fl w/W
 286 is not specified then neither the mirroring or output modes will fork.  Under
 287 these conditions, if the input is a stream rather than a file
 288 .Nm
 289 will be forced to buffer meta-transactions (for mirroring) entirely in
 290 memory, which could present a serious problem since a single meta-transaction
 291 can exceed a gigabyte (e.g. if someone were to do a single
 292 .Fn write
 293 system call writing a gigabyte all in one go).
 294 .Sh SEE ALSO
 295 .Xr mountctl 8
 296 .Sh CAVEATS
 297 This utility is currently under construction and not all features have been
 298 implemented yet.
 299 In fact, most have not.
 300 .Sh HISTORY
 301 The
 302 .Nm
 303 utility first appeared in
 304 .Dx 1.3 .