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.51 2008/09/30 23:13:08 dillon Exp $
  34 .Dd September 28, 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 i Ar delay
 108 When maintaining a streaming mirroring this option specifies the
 109 minimum delay after a batch ends before the next batch is allowed
 110 to start.
 111 The default is five seconds.
 112 .It Fl q
 113 Decrease verbosement.  May be specified multiple times.
 114 .It Fl t Ar seconds
 115 When pruning and reblocking you can tell the utility to stop after a
 116 certain period of time.  This option is used along with the cycle file
 117 option to prune or reblock a portion of the file system incrementally.
 118 .It Fl v
 119 Increase verboseness.  May be specified multiple times.
 120 .El
 121 .Pp
 122 The commands are as follows:
 123 .Bl -tag -width indent
 124 .\" ==== synctid ====
 125 .It Ar synctid Ar filesystem Op quick
 126 Generates a guaranteed, formal 64 bit transaction id representing the
 127 current state of the specified
 128 .Nm HAMMER
 129 file system.  The file system will
 130 be synced to the media.
 131 .Pp
 132 If the
 133 .Ar quick
 134 keyword is specified the file system will be soft-synced, meaning that a
 135 crash might still undo the state of the file system as of the transaction
 136 id returned but any new modifications will occur after the returned
 137 transaction id as expected.
 138 .\" ==== bstats ====
 139 .It Ar bstats Op interval
 140 Output
 141 .Nm HAMMER
 142 B-tree statistics until interrupted.
 143 Pause
 144 .Ar interval
 145 seconds between each display.
 146 The default interval is one second.
 147 .\" ==== iostats ====
 148 .It Ar iostats Op interval
 149 Output
 150 .Nm HAMMER
 151 I/O statistics until interrupted.
 152 Pause
 153 .Ar interval
 154 seconds between each display.
 155 The default interval is one second.
 156 .\" ==== history ====
 157 .It Ar history Ar path ...
 158 Show the modification history for
 159 .Nm HAMMER
 160 file's inode and data.
 161 .\" ==== show ====
 162 .It Ar show
 163 Dump the B-tree. This command needs the
 164 .Fl f
 165 flag.
 166 .\" .It Ar blockmap
 167 .\" Dump the B-tree, record, large-data, and small-data blockmaps, showing
 168 .\" physical block assignments and free space percentages.
 169 .\" ==== namekey ====
 170 .It Ar namekey Ar filename
 171 Generate a
 172 .Nm HAMMER
 173 64 bit directory hash for the specified file name.
 174 The low 32 bits are used as an iterator for hash collisions and will be
 175 output as 0.
 176 .\" ==== namekey32 ====
 177 .It Ar namekey32 Ar filename
 178 Generate the top 32 bits of a
 179 .Nm HAMMER
 180 64 bit directory hash for the specified
 181 file name.
 182 .\" ==== cleanup ====
 183 .It Ar cleanup Op Ar filesystem ...
 184 This is a meta-command which executes snapshot, pruning, and reblocking
 185 commands on the specified
 186 .Nm HAMMER
 187 file system.
 188 If no
 189 .Ar filesystem
 190 is specified this command will clean-up all
 191 .Nm HAMMER
 192 file systems in use, including PFS's.
 193 To do this it will scan all
 194 .Nm HAMMER
 195 and
 196 .Nm null
 197 mounts, extract PFS id's, and clean-up each PFS found.
 198 .Pp
 199 This command will by default access a
 200 .Pa snapshots
 201 subdirectory and a
 202 .Pa snapshots/config
 203 file for each
 204 .Ar filesystem ,
 205 creating them if necessary.
 206 The format of the configuration file is:
 207 .Bd -literal -offset indent
 208 snapshots  <period> <retensiontime>
 209 prune      <period> <max-runtime>
 210 reblock    <period> <1/3 max-runtime>
 211 recopy     <period> <1/3 max-runtime>
 212
 213 Defaults are:
 214 snapshots  1d 60d  # 0 60d  for PFS /tmp, /var/tmp, /usr/obj
 215 prune      1d 5m
 216 reblock    1d 5m
 217 recopy     30d 10m
 218 .Ed
 219 .Pp
 220 Time is in seconds, it can be given with a suffix of
 221 .Cm d ,
 222 .Cm h ,
 223 .Cm m
 224 and
 225 .Cm s
 226 meaning day, hour, minute and second.
 227 A snapshots period of 0 disables snapshot generation and prunes using
 228 .Ar prune-everything ,
 229 if no snapshots exists.
 230 A prune max-runtime of 0 means unlimited.
 231 .Pp
 232 It is recommended to run
 233 .Ar cleanup
 234 once a day, depending on the configured period,
 235 from a
 236 .Xr cron 8
 237 job.
 238 For example:
 239 .Bd -literal -offset indent
 240 15 2 * * * hammer cleanup >>/var/log/hammer.log 2>&1
 241 .Ed
 242 .Pp
 243 The default configuration file will create a daily snapshot, do a daily
 244 pruning and reblocking run and a monthly recopy run.
 245 Reblocking is defragmentation with a level of 95%,
 246 and recopy is full defragmentation.
 247 .Pp
 248 By default prune and reblock operations are limited to 5 minutes per function,
 249 and recopy operations are limited to 10 minutes per function.
 250 Reblocking and recopy runs are each broken down into three separate functions
 251 (btree, inodes and data)
 252 and are thus by default limited to 15 and 30 minutes respectively.
 253 Also note that this directive will by default disable snapshots on
 254 the following PFSs:
 255 .Pa /tmp ,
 256 .Pa /var/tmp
 257 and
 258 .Pa /usr/obj .
 259 .Pp
 260 The defaults may be adjusted by modifying the
 261 .Pa config
 262 file.
 263 The pruning and reblocking commands automatically maintain a cyclefile
 264 for incremental operation.
 265 If you interrupt (^C) the program the cyclefile will be updated, but a sub-command
 266 may continue to run in the background for a few seconds until the
 267 .Nm HAMMER
 268 ioctl detects the interrupt.
 269 The
 270 .Ar snapshots
 271 PFS option can be set to use another location for the snapshots directory.
 272 .Pp
 273 Work on this command is still in progress.
 274 Expected additions:  An ability to remove snapshots dynamically as the
 275 file system becomes full.
 276 .\" ==== prune ====
 277 .It Ar prune Ar softlink-dir
 278 Prune the file system based on previously created snapshot softlinks.
 279 Pruning is the act of deleting file system history.
 280 The
 281 .Ar prune
 282 command
 283 will delete file system history such that
 284 the file system state is retained for the given snapshots,
 285 and all history after the latest snapshot,
 286 but all other history is deleted.
 287 .Pp
 288 The target directory is expected to contain softlinks pointing to
 289 snapshots of the file systems you wish to retain.  The directory is scanned
 290 non-recursively and the mount points and transaction ids stored in the
 291 softlinks are extracted and sorted.
 292 The file system is then explicitly pruned according to what is found.
 293 Cleaning out portions of the file system is as simple as removing a softlink
 294 and then running the
 295 .Ar prune
 296 command.
 297 .Pp
 298 As a safety measure pruning only occurs if one or more softlinks are found
 299 containing the @@ snapshot id extension.
 300 Currently the scanned softlink directory must contain softlinks pointing
 301 to a single
 302 .Nm HAMMER
 303 mount.  The softlinks may specify absolute or relative
 304 paths.  Softlinks must use 20-character (@@0x%016llx) transaction ids,
 305 as might be returned from
 306 .Dq Nm Ar synctid filesystem .
 307 .Pp
 308 Pruning is a per PFS operation, so a
 309 .Nm HAMMER
 310 file system and each PFS in it have to be pruned separately.
 311 .Pp
 312 Note that pruning a file system may not immediately free-up space,
 313 though typically some space will be freed if a large number of records are
 314 pruned out.  The file system must be reblocked to completely recover all
 315 available space.
 316 .Pp
 317 Example, lets say your snapshot directory contains the following links:
 318 .Bd -literal -offset indent
 319 lrwxr-xr-x  1 root  wheel  29 May 31 17:57 snap1 ->
 320 /usr/obj/@@0x10d2cd05b7270d16
 321
 322 lrwxr-xr-x  1 root  wheel  29 May 31 17:58 snap2 ->
 323 /usr/obj/@@0x10d2cd13f3fde98f
 324
 325 lrwxr-xr-x  1 root  wheel  29 May 31 17:59 snap3 ->
 326 /usr/obj/@@0x10d2cd222adee364
 327 .Ed
 328 .Pp
 329 If you were to run the
 330 .Ar prune
 331 command on this directory, then the
 332 .Nm HAMMER
 333 .Pa /usr/obj
 334 mount will be pruned to retain the above three snapshots.
 335 In addition, history for modifications made to the file system older than the oldest
 336 snapshot will be destroyed and history for potentially fine-grained modifications made
 337 to the file system more recently than the most recent snapshot will be
 338 retained.
 339 .Pp
 340 If you then delete the snap2 softlink and rerun the
 341 .Ar prune
 342 command,
 343 history for modifications pertaining to that snapshot would be destroyed.
 344 .\" ==== prune-everything ====
 345 .It Ar prune-everything Ar filesystem
 346 This command will remove all historical records from the file system.
 347 This directive is not normally used on a production system.
 348 .\" ==== snapshot ====
 349 .It Ar snapshot Ar snapshot-dir
 350 .It Ar snapshot Ar filesystem snapshot-dir
 351 Takes a snapshot of the file system either explicitly given by
 352 .Ar filesystem
 353 or implicitly derived from the
 354 .Ar snapshot-dir
 355 argument and creates a symlink in the directory provided by
 356 .Ar snapshot-dir
 357 pointing to the snapshot.
 358 If
 359 .Ar snapshot-dir
 360 is not a directory, it is assumed to be a format string
 361 passed to
 362 .Xr strftime 3
 363 with the current time as parameter.
 364 If
 365 .Ar snapshot-dir
 366 refers to an existing directory, a default format string of "snap-%Y%d%m-%H%M"
 367 is assumed and used as name for the newly created symlink.
 368 .Pp
 369 Snapshot is a per PFS operation, so a
 370 .Nm HAMMER
 371 file system and each PFS in it have to be snapshot separately.
 372 .Pp
 373 Example, assuming that
 374 .Pa /mysnapshots
 375 is on file system
 376 .Pa /
 377 and that
 378 .Pa /obj
 379 is a file system on its own, the following invocations:
 380 .Bd -literal -offset indent
 381 hammer snapshot /mysnapshots
 382
 383 hammer snapshot /mysnapshots/%Y-%m-%d
 384
 385 hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d
 386 .Ed
 387 .Pp
 388 would create symlinks similar to:
 389 .Bd -literal -offset indent
 390 /mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16
 391
 392 /mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16
 393
 394 /mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16
 395 .Ed
 396 .\" ==== reblock ====
 397 .It Ar reblock Ar filesystem Op Ar fill_percentage
 398 .It Ar reblock-btree Ar filesystem Op Ar fill_percentage
 399 .It Ar reblock-inodes Ar filesystem Op Ar fill_percentage
 400 .It Ar reblock-dirs Ar filesystem Op Ar fill_percentage
 401 .It Ar reblock-data Ar filesystem Op Ar fill_percentage
 402 Attempt to defragment and free space for reuse by reblocking a live
 403 .Nm HAMMER
 404 file system.
 405 Big blocks cannot be reused by
 406 .Nm HAMMER
 407 until they are completely free.
 408 This command also has the effect of reordering all elements, effectively
 409 defragmenting the file system.
 410 .Pp
 411 The default fill percentage is 100% and will cause the file system to be
 412 completely defragmented.  All specified element types will be reallocated
 413 and rewritten.  If you wish to quickly free up space instead try specifying
 414 a smaller fill percentage, such as 90% or 80% (the
 415 .Sq %
 416 suffix is not needed).
 417 .Pp
 418 Since this command may rewrite the entire contents of the disk it is
 419 best to do it incrementally from a
 420 .Xr cron 8
 421 job along with the
 422 .Fl c Ar cyclefile
 423 and
 424 .Fl t Ar seconds
 425 options to limit the run time.
 426 The file system would thus be defragmented over long period of time.
 427 .Pp
 428 It is recommended that separate invocations be used for each data type.
 429 B-tree nodes, inodes, and directories are typically the most important
 430 elements needing defragmentation.  Data can be defragmented over a longer
 431 period of time.
 432 .Pp
 433 Reblocking is a per PFS operation, so a
 434 .Nm HAMMER
 435 file system and each PFS in it have to be reblocked separately.
 436 .\" ==== pfs-status ====
 437 .It Ar pfs-status Ar dirpath ...
 438 Retrieve the mirroring configuration parameters for the specified
 439 .Nm HAMMER
 440 file systems or pseudo-filesystems.
 441 .\" ==== pfs-master ====
 442 .It Ar pfs-master Ar dirpath Op options
 443 Create a pseudo-filesystem (PFS) inside a
 444 .Nm HAMMER
 445 file system.
 446 Up to 65535 such file systems can be created.
 447 Each PFS uses an independent inode numbering space making it suitable
 448 for use as a replication source or target.
 449 .Pp
 450 The
 451 .Ar pfs-master
 452 directive creates a PFS that you can read, write, and use as a mirroring
 453 source.
 454 .\" ==== pfs-slave ====
 455 .It Ar pfs-slave Ar dirpath Op options
 456 Create a pseudo-filesystem (PFS) inside a
 457 .Nm HAMMER
 458 file system.
 459 Up to 65535 such file systems can be created.
 460 Each PFS uses an independent inode numbering space making it suitable
 461 for use as a replication source or target.
 462 .Pp
 463 The
 464 .Ar pfs-slave
 465 directive creates a PFS that you can use as a mirroring target.
 466 You will not be able to access a slave PFS until you have completed the
 467 first mirroring operation with it as the target (its root directory will
 468 not exist until then).
 469 .Pp
 470 Access to the pfs-slave via the special softlink,
 471 as described in the PFS NOTES below, allows
 472 .Nm HAMMER
 473 to
 474 dynamically modify the snapshot transaction id by returning a dynamic result
 475 from
 476 .Xr readlink 2
 477 calls.
 478 .Pp
 479 A PFS can only be truly destroyed with the
 480 .Ar pfs-destroy
 481 directive.
 482 Removing the softlink will not destroy the underlying PFS.
 483 .\" ==== pfs-update ====
 484 .It Ar pfs-update Ar dirpath Op options
 485 Update the configuration parameters for an existing
 486 .Nm HAMMER
 487 file system
 488 or pseudo-filesystem.  Options that may be specified:
 489 .Bl -tag -width indent
 490 .It sync-beg-tid=0x16llx
 491 This is the automatic snapshot access starting transaction id for mirroring slaves.
 492 This parameter is normally updated automatically by the
 493 .Ar mirror-write
 494 directive.
 495 .Pp
 496 It is important to note that accessing a mirroring slave
 497 with a transaction id greater than the last fully synchronized transaction
 498 id can result in an unreliable snapshot since you will be accessing
 499 data that is still undergoing synchronization.
 500 .Pp
 501 Manually modifying this field is dangerous and can result in a broken
 502 mirror.
 503 .It sync-end-tid=0x16llx
 504 This is the current synchronization point for mirroring slaves.
 505 This parameter is normally updated automatically by the
 506 .Ar mirror-write
 507 directive.
 508 .Pp
 509 Manually modifying this field is dangerous and can result in a broken
 510 mirror.
 511 .It shared-uuid=<uuid>
 512 Set the shared UUID for this file system.  All mirrors must have the same
 513 shared UUID.  For safety purposes the
 514 .Ar mirror-write
 515 directives will refuse
 516 to operate on a target with a different shared UUID.
 517 .Pp
 518 Changing the shared UUID on an existing, non-empty mirroring target,
 519 including an empty but not completely pruned target, can lead
 520 to corruption of the mirroring target.
 521 .It unique-uuid=<uuid>
 522 Set the unique UUID for this file system.  This UUID should not be used
 523 anywhere else, even on exact copies of the file system.
 524 .It label=<string>
 525 Set a descriptive label for this file system.
 526 .It snapshots=<string>
 527 Specify the snapshots directory which
 528 .Nm
 529 .Ar cleanup
 530 will use to manage
 531 this PFS.  The snapshots directory does not need to be configured for
 532 PFS masters and will default to
 533 .Pa <pfs>/snapshots .
 534 .Pp
 535 PFS slaves are mirroring slaves so you cannot configure a snapshots
 536 directory on the slave itself to be managed by the slave's machine.
 537 In fact, the slave will likely have a
 538 .Pa snapshots
 539 sub-directory mirrored
 540 from the master, but that directory contains the configuration the master
 541 is using for its copy of the file system, not the configuration that we
 542 want to use for our slave.
 543 .Pp
 544 It is recommended that
 545 .Pa <fs>/var/slaves/<name>
 546 be configured for a PFS slave, where
 547 .Pa <fs>
 548 is the base
 549 .Nm HAMMER
 550 file system, and
 551 .Pa <name>
 552 is an appropriate label.
 553 You can control snapshot
 554 retention on your slave independent of the master.
 555 .It snapshots-clear
 556 Zero out the snapshots directory path for this PFS.
 557 .El
 558 .\" ==== pfs-upgrade ====
 559 .It Ar pfs-upgrade Ar dirpath
 560 Upgrade a PFS from slave to master operation.  The PFS will be rolled back
 561 to the current end synchronization tid (removing any partial synchronizations),
 562 and will then becomes writable.
 563 .Pp
 564 .Em WARNING!
 565 .Nm HAMMER
 566 currently supports only single masters and using
 567 this command can easily result in file system corruption if you don't
 568 know what you are doing.
 569 .Pp
 570 This directive will refuse to run if any programs have open descriptors
 571 in the PFS, including programs chdir'd into the PFS.
 572 .\" ==== pfs-downgrade ====
 573 .It Ar pfs-downgrade Ar dirpath
 574 Downgrade a master PFS from master to slave operation.  The PFS becomes
 575 read-only and access will be locked to its
 576 .Ar sync-end-tid .
 577 .Pp
 578 This directive will refuse to run if any programs have open descriptors
 579 in the PFS, including programs chdir'd into the PFS.
 580 .\" ==== pfs-destroy ====
 581 .It Ar pfs-destroy Ar dirpath
 582 This permanently destroys a PFS.
 583 .Pp
 584 This directive will refuse to run if any programs have open descriptors
 585 in the PFS, including programs chdir'd into the PFS.
 586 .\" ==== mirror-read ====
 587 .It Ar mirror-read Ar filesystem Op Ar <begin-tid>
 588 Generate a mirroring stream to stdout.
 589 The stream ends when the transaction id space has been exhausted.
 590 .\" ==== mirror-read-stream ====
 591 .It Ar mirror-read-stream Ar filesystem Op Ar <begin-tid>
 592 Generate a mirroring stream to stdout.
 593 Upon completion the stream is paused until new data is synced to the
 594 master, then resumed.
 595 Operation continues until the pipe is broken.
 596 .\" ==== mirror-write ====
 597 .It Ar mirror-write Ar filesystem
 598 Take a mirroring stream on stdin.
 599 .Pp
 600 This command will fail if the
 601 .Ar shared-uuid
 602 configuration field for the two file systems do not match.
 603 .\" ==== mirror-dump ====
 604 .It Ar mirror-dump
 605 A
 606 .Ar mirror-read
 607 can be piped into a
 608 .Ar mirror-dump
 609 to dump an ascii
 610 representation of the mirroring stream.
 611 .\" ==== mirror-copy ====
 612 .It Ar mirror-copy Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem
 613 This is a shortcut which pipes a
 614 .Ar mirror-read
 615 command to a
 616 .Ar mirror-write
 617 command.  If a remote host specification is made the program forks a
 618 .Xr ssh 1
 619 and execs the
 620 .Ar mirror-read
 621 and/or
 622 .Ar mirror-write
 623 on the appropriate host.
 624 The source may be a master or slave PFS, and the target must be a slave PFS.
 625 .Pp
 626 This command also established full duplex communication and turns on
 627 the two-way protocol feature which automatically negotiates transaction id ranges
 628 without having to use a cycle file.
 629 If the operation completes successfully the target PFS's
 630 .Ar sync-end-tid
 631 will
 632 be updated.  Note that you must re-chdir into the target PFS to see the
 633 updated information.  If you do not you will still be in the previous snapshot.
 634 .\" ==== mirror-stream ====
 635 .It Ar mirror-stream Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem
 636 This command works similarly to
 637 .Ar mirror-copy
 638 but does not exit unless the pipe is broken.
 639 This command will resume the mirroring operation whenever the master is
 640 synced.  The command is commonly used with
 641 .Fl i Ar delay
 642 and
 643 .Fl b Ar bandwidth
 644 options to keep the mirroring target in sync with the source on a continuing
 645 basis.
 646 .El
 647 .\".Sh EXAMPLES
 648 .Sh PSEUDO FILESYSTEM (PFS) NOTES
 649 The root of a PFS is not hooked into the primary
 650 .Nm HAMMER
 651 file system as a
 652 directory.
 653 Instead,
 654 .Nm HAMMER
 655 creates a special softlink called "@@PFS%05d" (exactly 10
 656 characters long) in the primary
 657 .Nm HAMMER
 658 file system.
 659 .Nm HAMMER
 660 then modifies the contents of the softlink as read by
 661 .Xr readlink 2 ,
 662 and thus what you see with an
 663 .Xr ls 1
 664 command or if you were to
 665 .Xr cd 1
 666 into the link.
 667 If the PFS is a master the link reflects the current state of the PFS.
 668 If the PFS is a slave the link reflects the last completed snapshot, and the
 669 contents of the link will change when the next snapshot is completed, and
 670 so forth.
 671 .Pp
 672 PFS support is currently very new and experimental.  The
 673 .Nm
 674 utility
 675 employs numerous safeties to reduce user foot-shooting.
 676 The
 677 .Ar mirror-copy
 678 directive requires that the target be configured as a slave and that the
 679 .Ar shared-uuid
 680 field of the mirroring source and target match.
 681 .Sh DIAGNOSTICS
 682 .Ex -std
 683 .Sh FILES
 684 .Bl -tag -width ".It Pa <fs>/var/slaves/<name>" -compact
 685 .It Pa snapshots
 686 default per PFS snapshots directory
 687 .It Pa <snapshots>/config
 688 .Nm
 689 .Ar cleanup
 690 configuration file
 691 .It Pa <fs>/var/slaves/<name>
 692 recommended slave PFS snapshots directory
 693 .El
 694 .Sh SEE ALSO
 695 .Xr undo 1 ,
 696 .Xr HAMMER 5 ,
 697 .Xr mount_hammer 8 ,
 698 .Xr newfs_hammer 8
 699 .Sh HISTORY
 700 The
 701 .Nm
 702 utility first appeared in
 703 .Dx 1.11 .
 704 .Sh AUTHORS
 705 .An Matthew Dillon Aq dillon@backplane.com