sbin/hammer/hammer.8

   1 .\" Copyright (c) 2007 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 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\"
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in
  14 .\"    the documentation and/or other materials provided with the
  15 .\"    distribution.
  16 .\" 3. Neither the name of The DragonFly Project nor the names of its
  17 .\"    contributors may be used to endorse or promote products derived
  18 .\"    from this software without specific, prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  23 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  24 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  25 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  26 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  27 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  28 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  29 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  30 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\" $DragonFly: src/sbin/hammer/hammer.8,v 1.48 2008/09/24 01:42:50 dillon Exp $
  34 .Dd July 27, 2008
  35 .Dt HAMMER 8
  36 .Os
  37 .Sh NAME
  38 .Nm hammer
  39 .Nd HAMMER file system utility
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Op Fl h2rv
  43 .Op Fl b Ar bandwidth
  44 .Op Fl c Ar cyclefile
  45 .Op Fl f Ar blkdev[:blkdev]*
  46 .\" .Op Fl s Ar linkpath
  47 .Op Fl i Ar delay
  48 .Op Fl t Ar seconds
  49 .Ar command
  50 .Op Ar argument ...
  51 .Sh DESCRIPTION
  52 This manual page documents the
  53 .Nm
  54 utility which provides miscellaneous functions related to managing a
  55 .Nm HAMMER
  56 file system.
  57 For a general introduction to the
  58 .Nm HAMMER
  59 file system, its features, and
  60 examples on how to set up and maintain one, see
  61 .Xr HAMMER 5 .
  62 .Pp
  63 The options are as follows:
  64 .Bl -tag -width indent
  65 .It Fl h
  66 Get help.
  67 .It Fl 2
  68 Tell the mirror commands to use a 2-way protocol, which allows
  69 automatic negotiation of transaction id ranges.  This option is
  70 automatically enabled by the
  71 .Ar mirror-copy
  72 command.
  73 .It Fl r
  74 Specify recursion for those commands which support it.
  75 .It Fl b Ar bandwidth
  76 Specify a bandwidth limit in bytes per second for mirroring streams.
  77 This option is typically used to prevent batch mirroring operations from
  78 loading down the machine.
  79 The bandwidth may be suffixed with
  80 .Sq k ,
  81 .Sq m ,
  82 or
  83 .Sq g
  84 to specify
  85 values in kilobytes, megabytes, and gigabytes per second.
  86 .It Fl c Ar cyclefile
  87 When pruning and reblocking you can instruction
  88 .Nm
  89 to start at the
  90 object id stored in the specified file.
  91 If the file does not exist
  92 .Nm
  93 will start at the beginning.
  94 If
  95 .Nm
  96 is told to run for a
  97 specific period of time and is unable to complete the operation it will
  98 write out the current object id so the next run can pick up where it left
  99 off.
 100 If
 101 .Nm
 102 runs to completion it will delete the cyclefile.
 103 .It Fl f Ar blkdev[:blkdev]*
 104 Specify the volumes making up a
 105 .Nm HAMMER
 106 file system.
 107 .\" .It Fl s Ar linkpath
 108 .\" When pruning a filesystem you can instruct
 109 .\" .Nm to create softlinks
 110 .\" to available snapshots.
 111 .It Fl i Ar delay
 112 When maintaining a streaming mirroring this option specifies the
 113 minimum delay after a batch ends before the next batch is allowed
 114 to start.
 115 The default is five seconds.
 116 .It Fl t Ar seconds
 117 When pruning and reblocking you can tell the utility to stop after a
 118 certain period of time.  This option is used along with the cycle file
 119 option to prune or reblock a portion of the file system incrementally.
 120 .It Fl v
 121 Increase verboseness.  May be specified multiple times.
 122 .El
 123 .Pp
 124 The commands are as follows:
 125 .Bl -tag -width indent
 126 .\" ==== synctid ====
 127 .It Ar synctid Ar filesystem Op quick
 128 Generates a guaranteed, formal 64 bit transaction id representing the
 129 current state of the specified
 130 .Nm HAMMER
 131 file system.  The file system will
 132 be synced to the media.
 133 .Pp
 134 If the
 135 .Ar quick
 136 keyword is specified the file system will be soft-synced, meaning that a
 137 crash might still undo the state of the file system as of the transaction
 138 id returned but any new modifications will occur after the returned
 139 transaction id as expected.
 140 .\" ==== bstats ====
 141 .It Ar bstats Op interval
 142 Output
 143 .Nm HAMMER
 144 B-tree statistics until interrupted.
 145 Pause
 146 .Ar interval
 147 seconds between each display.
 148 The default interval is one second.
 149 .\" ==== iostats ====
 150 .It Ar iostats Op interval
 151 Output
 152 .Nm HAMMER
 153 I/O statistics until interrupted.
 154 Pause
 155 .Ar interval
 156 seconds between each display.
 157 The default interval is one second.
 158 .\" ==== history ====
 159 .It Ar history Ar path ...
 160 Show the modification history for
 161 .Nm HAMMER
 162 file's inode and data.
 163 .\" ==== show ====
 164 .It Ar show
 165 Dump the B-tree. This command needs the
 166 .Fl f
 167 flag.
 168 .\" .It Ar blockmap
 169 .\" Dump the B-tree, record, large-data, and small-data blockmaps, showing
 170 .\" physical block assignments and free space percentages.
 171 .\" ==== namekey ====
 172 .It Ar namekey Ar filename
 173 Generate a
 174 .Nm HAMMER
 175 64 bit directory hash for the specified file name.
 176 The low 32 bits are used as an iterator for hash collisions and will be
 177 output as 0.
 178 .\" ==== namekey32 ====
 179 .It Ar namekey32 Ar filename
 180 Generate the top 32 bits of a
 181 .Nm HAMMER
 182 64 bit directory hash for the specified
 183 file name.
 184 .\" ==== cleanup ====
 185 .It Ar cleanup Op Ar filesystem
 186 This is a meta-command which executes snapshot, pruning, and reblocking
 187 commands on the specified HAMMER filesystem.
 188 If no filesystem is specified this command will scan all HAMMER and nullfs
 189 mounts, extract PFS id's, and clean-up each PFS found.
 190 .Pp
 191 This command will access a
 192 .Ar snapshots
 193 subdirectory and a
 194 .Ar snapshots/config
 195 file for each filesystem, creating them if necessary.
 196 The default configuration file will create a daily snapshot, do a daily
 197 pruning and reblocking run with a fragmentation level of 95%, and
 198 a monthly unconditional reblocking run.
 199 .Pp
 200 All operations are limited to 5 minutes per function by default.
 201 Reblocking runs are broken down into three separate functions and
 202 take 15 minutes.
 203 Also note that this directive will disable snapshots on
 204 .Pa /tmp ,
 205 .Pa /var/tmp ,
 206 and
 207 .Pa /usr/obj
 208 by default.
 209 .Pp
 210 The defaults may be adjusted by modifying the config file.
 211 The pruning and reblocking commands automatically maintain a cyclefile
 212 for incremental operation.
 213 If you ^C the program the cyclefile will be updated, but a sub-command
 214 may continue to run in the background for a few seconds until the HAMMER
 215 ioctl detects the interrupt.
 216 .Pp
 217 Work on this command is still in progress.
 218 Expected additions:  An ability to remove snapshots dynamically as the
 219 filesystem becomes full.
 220 .\" ==== prune ====
 221 .It Ar prune Ar softlink-dir
 222 Prune the file system based on previously created snapshot softlinks.
 223 Pruning is the act of deleting file system history.
 224 The
 225 .Ar prune
 226 command
 227 will delete file system history such that
 228 the file system state is retained for the given snapshots,
 229 and all history after the latest snapshot,
 230 but all other history is deleted.
 231 .Pp
 232 The target directory is expected to contain softlinks pointing to
 233 snapshots of the file systems you wish to retain.  The directory is scanned
 234 non-recursively and the mount points and transaction ids stored in the
 235 softlinks are extracted and sorted.
 236 The file system is then explicitly pruned according to what is found.
 237 Cleaning out portions of the file system is as simple as removing a softlink
 238 and then running the
 239 .Ar prune
 240 command.
 241 .Pp
 242 As a safety measure pruning only occurs if one or more softlinks are found
 243 containing the @@ snapshot id extension.
 244 Currently the scanned softlink directory must contain softlinks pointing
 245 to a single
 246 .Nm HAMMER
 247 mount.  The softlinks may specify absolute or relative
 248 paths.  Softlinks must use 20-character (@@0x%016llx) transaction ids,
 249 as might be returned from
 250 .Dq Nm Ar synctid filesystem .
 251 .Pp
 252 Pruning is a per-PFS operation, so a
 253 .Nm HAMMER
 254 file system and each PFS in it have to be pruned separately.
 255 .Pp
 256 Note that pruning a file system may not immediately free-up space,
 257 though typically some space will be freed if a large number of records are
 258 pruned out.  The file system must be reblocked to completely recover all
 259 available space.
 260 .Pp
 261 Example, lets say your snapshot directory contains the following links:
 262 .Bd -literal
 263 lrwxr-xr-x  1 root  wheel  29 May 31 17:57 snap1 ->
 264 /usr/obj/@@0x10d2cd05b7270d16
 265
 266 lrwxr-xr-x  1 root  wheel  29 May 31 17:58 snap2 ->
 267 /usr/obj/@@0x10d2cd13f3fde98f
 268
 269 lrwxr-xr-x  1 root  wheel  29 May 31 17:59 snap3 ->
 270 /usr/obj/@@0x10d2cd222adee364
 271 .Ed
 272 .Pp
 273 If you were to run the
 274 .Ar prune
 275 command on this directory, then the
 276 .Nm HAMMER
 277 .Pa /usr/obj
 278 mount will be pruned to retain the above three snapshots.
 279 In addition, history for modifications made to the file system older than the oldest
 280 snapshot will be destroyed and history for potentially fine-grained modifications made
 281 to the file system more recently than the most recent snapshot will be
 282 retained.
 283 .Pp
 284 If you then delete the snap2 softlink and rerun the
 285 .Ar prune
 286 command,
 287 history for modifications pertaining to that snapshot would be destroyed.
 288 .\" ==== prune-everything ====
 289 .It Ar prune-everything Ar filesystem
 290 This command will remove all historical records from the file system.
 291 This directive is not normally used on a production system.
 292 .\" ==== snapshot ====
 293 .It Ar snapshot Ar snapshot-dir
 294 .It Ar snapshot Ar filesystem snapshot-dir
 295 Takes a snapshot of the file system either explicitly given by
 296 .Ar filesystem
 297 or implicitly derived from the
 298 .Ar snapshot-dir
 299 argument and creates a symlink in the directory provided by
 300 .Ar snapshot-dir
 301 pointing to the snapshot.
 302 If
 303 .Ar snapshot-dir
 304 is not a directory, it is assumed to be a format string
 305 passed to
 306 .Xr strftime 3
 307 with the current time as parameter.
 308 If
 309 .Ar snapshot-dir
 310 refers to an existing directory, a default format string of "snap-%Y%d%m-%H%M"
 311 is assumed and used as name for the newly created symlink.
 312 .Pp
 313 Example, assuming that
 314 .Pa /mysnapshots
 315 is on file system
 316 .Pa /
 317 and that
 318 .Pa /obj
 319 is a file system on its own, the following invocations:
 320 .Bd -literal
 321 hammer snapshot /mysnapshots
 322
 323 hammer snapshot /mysnapshots/%Y-%m-%d
 324
 325 hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d
 326 .Ed
 327 .Pp
 328 would create symlinks similar to:
 329 .Bd -literal
 330 /mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16
 331
 332 /mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16
 333
 334 /mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16
 335 .Ed
 336 .\" ==== reblock ====
 337 .It Ar reblock Ar filesystem Op Ar fill_percentage
 338 .It Ar reblock-btree Ar filesystem Op Ar fill_percentage
 339 .It Ar reblock-inodes Ar filesystem Op Ar fill_percentage
 340 .It Ar reblock-dirs Ar filesystem Op Ar fill_percentage
 341 .It Ar reblock-data Ar filesystem Op Ar fill_percentage
 342 Attempt to defragment and free space for reuse by reblocking a live
 343 .Nm HAMMER
 344 file system.
 345 Big blocks cannot be reused by
 346 .Nm HAMMER
 347 until they are completely free.
 348 This command also has the effect of reordering all elements, effectively
 349 defragmenting the file system.
 350 .Pp
 351 The default fill percentage is 100% and will cause the file system to be
 352 completely defragmented.  All specified element types will be reallocated
 353 and rewritten.  If you wish to quickly free up space instead try specifying
 354 a smaller fill percentage, such as 90% or 80% (the
 355 .Sq %
 356 suffix is not needed).
 357 .Pp
 358 Since this command may rewrite the entire contents of the disk it is
 359 best to do it incrementally from a
 360 .Xr cron 8
 361 job along with the
 362 .Fl c Ar cyclefile
 363 and
 364 .Fl t Ar seconds
 365 options to limit the run time.
 366 The file system would thus be defragmented over long period of time.
 367 .Pp
 368 It is recommended that separate invocations be used for each data type.
 369 B-tree nodes, inodes, and directories are typically the most important
 370 elements needing defragmentation.  Data can be defragmented over a longer
 371 period of time.
 372 .Pp
 373 Reblocking is a per-PFS operation, so a
 374 .Nm HAMMER
 375 file system and each PFS in it have to be reblocked separately.
 376 .\" ==== pfs-status ====
 377 .It Ar pfs-status Ar dirpath ...
 378 Retrieve the mirroring configuration parameters for the specified
 379 .Nm HAMMER
 380 file systems or pseudo-filesystems.
 381 .\" ==== pfs-master ====
 382 .It Ar pfs-master Ar dirpath Op options
 383 Create a pseudo-filesystem (PFS) inside a
 384 .Nm HAMMER
 385 file system.
 386 Up to 65535 such file systems can be created.
 387 Each PFS uses an independent inode numbering space making it suitable
 388 for use as a replication source or target.
 389 .Pp
 390 The
 391 .Ar pfs-master
 392 directive creates a PFS that you can read, write, and use as a mirroring
 393 source.
 394 .\" ==== pfs-slave ====
 395 .It Ar pfs-slave Ar dirpath Op options
 396 Create a pseudo-filesystem (PFS) inside a
 397 .Nm HAMMER
 398 file system.
 399 Up to 65535 such file systems can be created.
 400 Each PFS uses an independent inode numbering space making it suitable
 401 for use as a replication source or target.
 402 .Pp
 403 The
 404 .Ar pfs-slave
 405 directive creates a PFS that you can use as a mirroring target.
 406 You will not be able to access a slave PFS until you have completed the
 407 first mirroring operation with it as the target (its root directory will
 408 not exist until then).
 409 .Pp
 410 Access to the pfs-slave via the special softlink,
 411 as described in the PFS NOTES below, allows
 412 .Nm HAMMER
 413 to
 414 dynamically modify the snapshot transaction id by returning a dynamic result
 415 from
 416 .Xr readlink 2
 417 calls.
 418 .Pp
 419 A PFS can only be truly destroyed with the
 420 .Ar pfs-destroy
 421 directive.
 422 Removing the softlink will not destroy the underlying PFS.
 423 .\" ==== pfs-update ====
 424 .It Ar pfs-update Ar dirpath Op options
 425 Update the configuration parameters for an existing
 426 .Nm HAMMER
 427 file system
 428 or pseudo-filesystem.  Options that may be specified:
 429 .Bl -tag -width indent
 430 .It sync-beg-tid=0x16llx
 431 This is the automatic snapshot access starting transaction id for mirroring slaves.
 432 This parameter is normally updated automatically by the
 433 .Ar mirror-write
 434 directive.
 435 .Pp
 436 It is important to note that accessing a mirroring slave
 437 with a transaction id greater than the last fully synchronized transaction
 438 id can result in an unreliable snapshot since you will be accessing
 439 data that is still undergoing synchronization.
 440 .Pp
 441 Manually modifying this field is dangerous and can result in a broken
 442 mirror.
 443 .It sync-end-tid=0x16llx
 444 This is the current synchronization point for mirroring slaves.
 445 This parameter is normally updated automatically by the
 446 .Ar mirror-write
 447 directive.
 448 .Pp
 449 Manually modifying this field is dangerous and can result in a broken
 450 mirror.
 451 .It shared-uuid=<uuid>
 452 Set the shared UUID for this file system.  All mirrors must have the same
 453 shared UUID.  For safety purposes the
 454 .Ar mirror-write
 455 directives will refuse
 456 to operate on a target with a different shared UUID.
 457 .Pp
 458 Changing the shared UUID on an existing, non-empty mirroring target,
 459 including an empty but not completely pruned target, can lead
 460 to corruption of the mirroring target.
 461 .It unique-uuid=<uuid>
 462 Set the unique UUID for this file system.  This UUID should not be used
 463 anywhere else, even on exact copies of the file system.
 464 .It label=<string>
 465 Set a descriptive label for this file system.
 466 .It snapshots=<string>
 467 Specify the snapshots directory which 'hammer cleanup' will use to manage
 468 this PFS.  The snapshots directory does not need to be configured for
 469 PFS masters and will default to "<fs>/snapshots".
 470 .Pp
 471 PFS slaves are mirroring slaves so you cannot configure a snapshots
 472 directory on the slave itself to be managed by the slave's machine.
 473 In fact, the slave will likely have a 'snapshots' sub-directory mirrored
 474 from the master, but that directory contains the configuration the master
 475 is using for its copy of the filesystem, not the configuration that we
 476 want to use for our slave.
 477 .Pp
 478 It is recommended that "/var/slaves/<name>" be configured for a PFS
 479 slave, where <name> is an appropriate label.  You can control snapshot
 480 retention on your slave independant of the master.
 481 .It snapshots-clear
 482 Zero out the snapshots directory path for this PFS.
 483 .El
 484 .\" ==== pfs-upgrade ====
 485 .It Ar pfs-upgrade Ar dirpath
 486 Upgrade a PFS from slave to master operation.  The PFS will be rolled back
 487 to the current end synchronization tid (removing any partial synchronizations),
 488 and will then becomes writable.
 489 .Pp
 490 .Em WARNING!
 491 .Nm HAMMER
 492 currently supports only single masters and using
 493 this command can easily result in file system corruption if you don't
 494 know what you are doing.
 495 .Pp
 496 This directive will refuse to run if any programs have open descriptors
 497 in the PFS, including programs chdir'd into the PFS.
 498 .\" ==== pfs-downgrade ====
 499 .It Ar pfs-downgrade Ar dirpath
 500 Downgrade a master PFS from master to slave operation.  The PFS becomes
 501 read-only and access will be locked to its
 502 .Ar sync-end-tid .
 503 .Pp
 504 This directive will refuse to run if any programs have open descriptors
 505 in the PFS, including programs chdir'd into the PFS.
 506 .\" ==== pfs-destroy ====
 507 .It Ar pfs-destroy Ar dirpath
 508 This permanently destroys a PFS.
 509 .Pp
 510 This directive will refuse to run if any programs have open descriptors
 511 in the PFS, including programs chdir'd into the PFS.
 512 .\" ==== mirror-read ====
 513 .It Ar mirror-read Ar filesystem Op Ar <begin-tid>
 514 Generate a mirroring stream to stdout.
 515 The stream ends when the transaction id space has been exhausted.
 516 .\" ==== mirror-read-stream ====
 517 .It Ar mirror-read-stream Ar filesystem Op Ar <begin-tid>
 518 Generate a mirroring stream to stdout.
 519 Upon completion the stream is paused until new data is synced to the
 520 master, then resumed.
 521 Operation continues until the pipe is broken.
 522 .\" ==== mirror-write ====
 523 .It Ar mirror-write Ar filesystem
 524 Take a mirroring stream on stdin.
 525 .Pp
 526 This command will fail if the
 527 .Ar shared-uuid
 528 configuration field for the two file systems do not match.
 529 .\" ==== mirror-dump ====
 530 .It Ar mirror-dump
 531 A
 532 .Ar mirror-read
 533 can be piped into a
 534 .Ar mirror-dump
 535 to dump an ascii
 536 representation of the mirroring stream.
 537 .\" ==== mirror-copy ====
 538 .It Ar mirror-copy Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem
 539 This is a shortcut which pipes a
 540 .Ar mirror-read
 541 command to a
 542 .Ar mirror-write
 543 command.  If a remote host specification is made the program forks a
 544 .Xr ssh 1
 545 and execs the
 546 .Ar mirror-read
 547 and/or
 548 .Ar mirror-write
 549 on the appropriate host.
 550 The source may be a master or slave PFS, and the target must be a slave PFS.
 551 .Pp
 552 This command also established full duplex communication and turns on
 553 the two-way protocol feature which automatically negotiates transaction id ranges
 554 without having to use a cycle file.
 555 If the operation completes successfully the target PFS's
 556 .Ar sync-end-tid
 557 will
 558 be updated.  Note that you must re-chdir into the target PFS to see the
 559 updated information.  If you do not you will still be in the previous snapshot.
 560 .\" ==== mirror-stream ====
 561 .It Ar mirror-stream Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem
 562 This command works similarly to
 563 .Ar mirror-copy
 564 but does not exit unless the pipe is broken.
 565 This command will resume the mirroring operation whenever the master is
 566 synced.  The command is commonly used with
 567 .Fl i Ar delay
 568 and
 569 .Fl b Ar bandwidth
 570 options to keep the mirroring target in sync with the source on a continuing
 571 basis.
 572 .El
 573 .\".Sh EXAMPLES
 574 .Sh PSEUDO FILESYSTEM (PFS) NOTES
 575 The root of a PFS is not hooked into the primary
 576 .Nm HAMMER
 577 file system as a
 578 directory.
 579 Instead,
 580 .Nm HAMMER
 581 creates a special softlink called "@@PFS%05d" (exactly 10
 582 characters long) in the primary
 583 .Nm HAMMER
 584 file system.
 585 .Nm HAMMER
 586 then modifies the contents of the softlink as read by
 587 .Xr readlink 2 ,
 588 and thus what you see with an
 589 .Xr ls 1
 590 command or if you were to
 591 .Xr cd 1
 592 into the link.
 593 If the PFS is a master the link reflects the current state of the PFS.
 594 If the PFS is a slave the link reflects the last completed snapshot, and the
 595 contents of the link will change when the next snapshot is completed, and
 596 so forth.
 597 .Pp
 598 PFS support is currently very new and experimental.  The
 599 .Nm
 600 utility
 601 employs numerous safeties to reduce user foot-shooting.
 602 The
 603 .Ar mirror-copy
 604 directive requires that the target be configured as a slave and that the
 605 .Ar shared-uuid
 606 field of the mirroring source and target match.
 607 .Sh DIAGNOSTICS
 608 .Ex -std
 609 .Sh SEE ALSO
 610 .Xr undo 1 ,
 611 .Xr HAMMER 5 ,
 612 .Xr mount_hammer 8 ,
 613 .Xr newfs_hammer 8
 614 .Sh HISTORY
 615 The
 616 .Nm
 617 utility first appeared in
 618 .Dx 1.11 .
 619 .Sh AUTHORS
 620 .An Matthew Dillon Aq dillon@backplane.com