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.58 2008/11/13 02:04:27 dillon Exp $ 34.\" 35.Dd October 22, 2008 36.Dt HAMMER 8 37.Os 38.Sh NAME 39.Nm hammer 40.Nd HAMMER file system utility 41.Sh SYNOPSIS 42.Nm 43.Op Fl h2qrv 44.Op Fl b Ar bandwidth 45.Op Fl c Ar cyclefile 46.Op Fl f Ar blkdev[:blkdev]* 47.\" .Op Fl s Ar linkpath 48.Op Fl i Ar delay 49.Op Fl t Ar seconds 50.Op Fl C Ar cachesize[:readahead] 51.Ar command 52.Op Ar argument ... 53.Sh DESCRIPTION 54This manual page documents the 55.Nm 56utility which provides miscellaneous functions related to managing a 57.Nm HAMMER 58file system. 59For a general introduction to the 60.Nm HAMMER 61file system, its features, and 62examples on how to set up and maintain one, see 63.Xr HAMMER 5 . 64.Pp 65The options are as follows: 66.Bl -tag -width indent 67.It Fl h 68Get help. 69.It Fl 2 70Tell the mirror commands to use a 2-way protocol, which allows 71automatic negotiation of transaction id ranges. 72This option is automatically enabled by the 73.Ar mirror-copy 74command. 75.It Fl b Ar bandwidth 76Specify a bandwidth limit in bytes per second for mirroring streams. 77This option is typically used to prevent batch mirroring operations from 78loading down the machine. 79The bandwidth may be suffixed with 80.Sq k , 81.Sq m , 82or 83.Sq g 84to specify values in kilobytes, megabytes, and gigabytes per second. 85If no suffix is specified, bytes per second is assumed. 86.It Fl c Ar cyclefile 87When pruning and reblocking you can instruction 88.Nm 89to start at the object id stored in the specified file. 90If the file does not exist 91.Nm 92will start at the beginning. 93If 94.Nm 95is told to run for a 96specific period of time and is unable to complete the operation it will 97write out the current object id so the next run can pick up where it left off. 98If 99.Nm 100runs to completion it will delete 101.Ar cyclefile . 102.It Fl f Ar blkdev[:blkdev]* 103Specify the volumes making up a 104.Nm HAMMER 105file system. 106.It Fl i Ar delay 107When maintaining a streaming mirroring this option specifies the 108minimum delay after a batch ends before the next batch is allowed 109to start. 110The default is five seconds. 111.It Fl q 112Decrease verboseness. 113May be specified multiple times. 114.It Fl r 115Specify recursion for those commands which support it. 116.It Fl t Ar seconds 117When pruning and reblocking you can tell the utility to stop after a 118certain period of time. 119This option is used along with the 120.Fl c Ar cyclefile 121option to prune or reblock a portion of the file system incrementally. 122.It Fl v 123Increase verboseness. 124May be specified multiple times. 125.It Fl y 126Force "yes" for any interactive question. 127.It Fl C Ar cachesize[:readahead] 128Set the memory cache size for any raw I/O. The default is 16m. 129A suffix of 'k' for kilobytes and 'm' for megabytes is allowed, 130else the cache size is specified in bytes. 131.Pp 132The read-behind/read-ahead defaults to 4 hammer blocks. 133.Pp 134This option is typically only used with diagnostic commands 135as kernel-supported commands will use the kernel's buffer cache. 136.El 137.Pp 138The commands are as follows: 139.Bl -tag -width indent 140.\" ==== synctid ==== 141.It Ar synctid Ar filesystem Op quick 142Generates a guaranteed, formal 64 bit transaction id representing the 143current state of the specified 144.Nm HAMMER 145file system. 146The file system will be synced to the media. 147.Pp 148If the 149.Ar quick 150keyword is specified the file system will be soft-synced, meaning that a 151crash might still undo the state of the file system as of the transaction 152id returned but any new modifications will occur after the returned 153transaction id as expected. 154.\" ==== bstats ==== 155.It Ar bstats Op interval 156Output 157.Nm HAMMER 158B-tree statistics until interrupted. 159Pause 160.Ar interval 161seconds between each display. 162The default interval is one second. 163.\" ==== iostats ==== 164.It Ar iostats Op interval 165Output 166.Nm HAMMER 167I/O statistics until interrupted. 168Pause 169.Ar interval 170seconds between each display. 171The default interval is one second. 172.\" ==== history ==== 173.It Ar history Ar path ... 174Show the modification history for 175.Nm HAMMER 176file's inode and data. 177.\" ==== blockmap ==== 178.It Ar blockmap 179Dump the blockmap for the filesystem. The HAMMER blockmap is two-layer 180blockmap representing the maximum possible filesystem size of 1 Exabyte. 181Needless to say the second layer is only present for blocks which exist. 182HAMMER's blockmap represents 8-Megabyte blocks. Each block has an append 183point, a free byte count, and a typed zone id which allows content to be 184reverse engineered to some degree. 185.Pp 186In HAMMER allocations essentially appended to a selected big-block using 187the append offset and deducted from the free byte count. When space is 188freed the free byte count is adjusted but HAMMER does not track holes in 189big-blocks for reallocation. A big-block must be completely freed, either 190through normal filesystem operations or through reblocking, before 191it can be reused. 192.Pp 193Data blocks can be shared by deducting the space used from the free byte 194count for each shared references, though HAMMER does not yet make use of 195this feature. This means the free byte count can legally go negative. 196.Pp 197This command needs the 198.Fl f 199flag. 200.\" ==== show ==== 201.It Ar show 202Dump the B-tree. By default this command will validate all B-Tree 203linkages and CRCs, including data CRCs, and will report the most verbose 204information it can dig up. 205Any errors will show up with a 'B' in column 1 along with various 206other error flags. 207.Pp 208If you use 209.Fl q 210the command will report less information about the inode contents. 211.Pp 212If you use 213.Fl qq 214the command will not report the content of the inode or other typed 215data at all. 216.Pp 217If you use 218.Fl qqq 219the command will not report volume header information, big-block fill 220ratios, mirror TIDs, or report or check data CRCs. B-Tree CRCs and 221linkages are still checked. 222.Pp 223This command needs the 224.Fl f 225flag. 226.\" .It Ar blockmap 227.\" Dump the B-tree, record, large-data, and small-data blockmaps, showing 228.\" physical block assignments and free space percentages. 229.\" ==== namekey1 ==== 230.It Ar namekey1 Ar filename 231Generate a 232.Nm HAMMER 23364 bit directory hash for the specified file name, using 234the original directory hash algorithm in version 1 of the filesystem. 235The low 32 bits are used as an iterator for hash collisions and will be 236output as 0. 237.\" ==== namekey2 ==== 238.It Ar namekey2 Ar filename 239Generate a 240.Nm HAMMER 24164 bit directory hash for the specified file name, using 242the new directory hash algorithm in version 2 of the filesystem. 243The low 32 bits are still used as an iterator but will start out containing 244part of the hash key. 245.\" ==== namekey32 ==== 246.It Ar namekey32 Ar filename 247Generate the top 32 bits of a 248.Nm HAMMER 24964 bit directory hash for the specified file name. 250.\" ==== cleanup ==== 251.It Ar cleanup Op Ar filesystem ... 252This is a meta-command which executes snapshot, pruning, and reblocking 253commands on the specified 254.Nm HAMMER 255file system. 256If no 257.Ar filesystem 258is specified this command will clean-up all 259.Nm HAMMER 260file systems in use, including PFS's. 261To do this it will scan all 262.Nm HAMMER 263and 264.Nm null 265mounts, extract PFS id's, and clean-up each PFS found. 266.Pp 267This command will by default access a 268.Pa snapshots 269subdirectory and a 270.Pa snapshots/config 271file for each 272.Ar filesystem , 273creating them if necessary. 274The format of the configuration file is: 275.Bd -literal -offset indent 276snapshots <period> <retention-time> [any] 277prune <period> <max-runtime> 278rebalance <period> <max-runtime> 279reblock <period> <1/3 max-runtime> 280recopy <period> <1/3 max-runtime> 281 282Defaults are: 283snapshots 1d 60d # 0d 60d for PFS /tmp, /var/tmp, /usr/obj 284prune 1d 5m 285rebalance 1d 5m 286reblock 1d 5m 287recopy 30d 10m 288.Ed 289.Pp 290Time is given with a suffix of 291.Cm d , 292.Cm h , 293.Cm m 294or 295.Cm s 296meaning day, hour, minute and second. 297.Pp 298If the snapshots directive has a period of 0 and a retention time of 0 299then snapshot generation is disabled, removal of old snapshots are 300disabled, and prunes will use 301.Ar prune-everything . 302If the snapshots directive has a period of 0 but a non-zero retention time 303then this command will not create any new snapshots but will remove old 304snapshots it finds based on the retention time. 305.Pp 306By default only snapshots in the form: snap-yyyymmdd[-hhmm] are processed. 307If the 308.Ar any 309directive is specified as a third argument on the snapshots config line 310then any softlink of the form *[- or .]yyyymmdd[-hhmm] will be processed. 311.Pp 312A prune max-runtime of 0 means unlimited. 313.Pp 314If period hasn't passed since the previous 315.Ar cleanup 316run nothing is done. 317For example a day has passed when midnight is passed (localtime). 318By default, 319.Dx 320is set up to run 321.Nm Ar cleanup 322nightly via 323.Xr periodic 8 . 324.Pp 325The default configuration file will create a daily snapshot, do a daily 326pruning and reblocking run and a monthly recopy run. 327Reblocking is defragmentation with a level of 95%, 328and recopy is full defragmentation. 329.Pp 330By default prune and reblock operations are limited to 5 minutes per function, 331and recopy operations are limited to 10 minutes per function. 332Reblocking and recopy runs are each broken down into three separate functions 333(btree, inodes and data) 334and are thus by default limited to 15 and 30 minutes respectively. 335Also note that this directive will by default disable snapshots on 336the following PFS's: 337.Pa /tmp , 338.Pa /var/tmp 339and 340.Pa /usr/obj . 341.Pp 342The defaults may be adjusted by modifying the 343.Pa config 344file. 345The pruning and reblocking commands automatically maintain a cyclefile 346for incremental operation. 347If you interrupt (^C) the program the cyclefile will be updated, but a sub-command 348may continue to run in the background for a few seconds until the 349.Nm HAMMER 350ioctl detects the interrupt. 351The 352.Ar snapshots 353PFS option can be set to use another location for the snapshots directory. 354.Pp 355Work on this command is still in progress. 356Expected additions: An ability to remove snapshots dynamically as the 357file system becomes full. 358.\" ==== snapshot ==== 359.It Ar snapshot Oo Ar filesystem Oc Ar snapshot-dir 360Takes a snapshot of the file system either explicitly given by 361.Ar filesystem 362or implicitly derived from the 363.Ar snapshot-dir 364argument and creates a symlink in the directory provided by 365.Ar snapshot-dir 366pointing to the snapshot. 367If 368.Ar snapshot-dir 369is not a directory, it is assumed to be a format string passed to 370.Xr strftime 3 371with the current time as parameter. 372If 373.Ar snapshot-dir 374refers to an existing directory, a default format string of "snap-%Y%d%m-%H%M" 375is assumed and used as name for the newly created symlink. 376.Pp 377Snapshot is a per PFS operation, so a 378.Nm HAMMER 379file system and each PFS in it have to be snapshot separately. 380.Pp 381Example, assuming that 382.Pa /mysnapshots 383is on file system 384.Pa / 385and that 386.Pa /obj 387is a file system on its own, the following invocations: 388.Bd -literal -offset indent 389hammer snapshot /mysnapshots 390 391hammer snapshot /mysnapshots/%Y-%m-%d 392 393hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d 394.Ed 395.Pp 396would create symlinks similar to: 397.Bd -literal -offset indent 398/mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16 399 400/mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16 401 402/mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16 403.Ed 404.\" ==== prune ==== 405.It Ar prune Ar softlink-dir 406Prune the file system based on previously created snapshot softlinks. 407Pruning is the act of deleting file system history. 408The 409.Ar prune 410command 411will delete file system history such that 412the file system state is retained for the given snapshots, 413and all history after the latest snapshot, 414but all other history is deleted. 415.Pp 416The target directory is expected to contain softlinks pointing to 417snapshots of the file systems you wish to retain. 418The directory is scanned non-recursively and the mount points and 419transaction ids stored in the softlinks are extracted and sorted. 420The file system is then explicitly pruned according to what is found. 421Cleaning out portions of the file system is as simple as removing a softlink 422and then running the 423.Ar prune 424command. 425.Pp 426As a safety measure pruning only occurs if one or more softlinks are found 427containing the @@ snapshot id extension. 428Currently the scanned softlink directory must contain softlinks pointing 429to a single 430.Nm HAMMER 431mount. 432The softlinks may specify absolute or relative paths. 433Softlinks must use 20-character (@@0x%016llx) transaction ids, 434as might be returned from 435.Dq Nm Ar synctid filesystem . 436.Pp 437Pruning is a per PFS operation, so a 438.Nm HAMMER 439file system and each PFS in it have to be pruned separately. 440.Pp 441Note that pruning a file system may not immediately free-up space, 442though typically some space will be freed if a large number of records are 443pruned out. 444The file system must be reblocked to completely recover all available space. 445.Pp 446Example, lets say your snapshot directory contains the following links: 447.Bd -literal -offset indent 448lrwxr-xr-x 1 root wheel 29 May 31 17:57 snap1 -> 449/usr/obj/@@0x10d2cd05b7270d16 450 451lrwxr-xr-x 1 root wheel 29 May 31 17:58 snap2 -> 452/usr/obj/@@0x10d2cd13f3fde98f 453 454lrwxr-xr-x 1 root wheel 29 May 31 17:59 snap3 -> 455/usr/obj/@@0x10d2cd222adee364 456.Ed 457.Pp 458If you were to run the 459.Ar prune 460command on this directory, then the 461.Nm HAMMER 462.Pa /usr/obj 463mount will be pruned to retain the above three snapshots. 464In addition, history for modifications made to the file system older than 465the oldest snapshot will be destroyed and history for potentially fine-grained 466modifications made to the file system more recently than the most recent 467snapshot will be retained. 468.Pp 469If you then delete the 470.Pa snap2 471softlink and rerun the 472.Ar prune 473command, 474history for modifications pertaining to that snapshot would be destroyed. 475.\" ==== prune-everything ==== 476.It Ar prune-everything Ar filesystem 477This command will remove all historical records from the file system. 478This directive is not normally used on a production system. 479.\" ==== rebalance ==== 480.It Ar rebalance Ar filesystem Op Ar saturation_level 481This command will rebalance the B-Tree, nodes with small numbers of 482elements will be combined and element counts will be smoothed out 483between nodes. 484.Pp 485The saturation level is a percentage between 50 and 100. The default 486is 75 percent. 487.\" ==== reblock ==== 488.It Ar reblock Ar filesystem Op Ar fill_percentage 489.It Ar reblock-btree Ar filesystem Op Ar fill_percentage 490.It Ar reblock-inodes Ar filesystem Op Ar fill_percentage 491.It Ar reblock-dirs Ar filesystem Op Ar fill_percentage 492.It Ar reblock-data Ar filesystem Op Ar fill_percentage 493Attempt to defragment and free space for reuse by reblocking a live 494.Nm HAMMER 495file system. 496Big blocks cannot be reused by 497.Nm HAMMER 498until they are completely free. 499This command also has the effect of reordering all elements, effectively 500defragmenting the file system. 501.Pp 502The default fill percentage is 100% and will cause the file system to be 503completely defragmented. 504All specified element types will be reallocated and rewritten. 505If you wish to quickly free up space instead try specifying 506a smaller fill percentage, such as 90% or 80% (the 507.Sq % 508suffix is not needed). 509.Pp 510Since this command may rewrite the entire contents of the disk it is 511best to do it incrementally from a 512.Xr cron 8 513job along with the 514.Fl c Ar cyclefile 515and 516.Fl t Ar seconds 517options to limit the run time. 518The file system would thus be defragmented over long period of time. 519.Pp 520It is recommended that separate invocations be used for each data type. 521B-tree nodes, inodes, and directories are typically the most important 522elements needing defragmentation. 523Data can be defragmented over a longer period of time. 524.Pp 525Reblocking is a per PFS operation, so a 526.Nm HAMMER 527file system and each PFS in it have to be reblocked separately. 528.\" ==== pfs-status ==== 529.It Ar pfs-status Ar dirpath ... 530Retrieve the mirroring configuration parameters for the specified 531.Nm HAMMER 532file systems or pseudo-filesystems (PFS's). 533.\" ==== pfs-master ==== 534.It Ar pfs-master Ar dirpath Op options 535Create a pseudo-filesystem (PFS) inside a 536.Nm HAMMER 537file system. 538Up to 65535 such file systems can be created. 539Each PFS uses an independent inode numbering space making it suitable 540for use as a replication source or target. 541.Pp 542The 543.Ar pfs-master 544directive creates a PFS that you can read, write, and use as a mirroring 545source. 546.Pp 547It is recommended to use a 548.Nm null 549mount to access a PFS, for more information see 550.Xr HAMMER 5 . 551.\" ==== pfs-slave ==== 552.It Ar pfs-slave Ar dirpath Op options 553Create a pseudo-filesystem (PFS) inside a 554.Nm HAMMER 555file system. 556Up to 65535 such file systems can be created. 557Each PFS uses an independent inode numbering space making it suitable 558for use as a replication source or target. 559.Pp 560The 561.Ar pfs-slave 562directive creates a PFS that you can use as a mirroring target. 563You will not be able to access a slave PFS until you have completed the 564first mirroring operation with it as the target (its root directory will 565not exist until then). 566.Pp 567Access to the pfs-slave via the special softlink, 568as described in the 569.Sx PFS NOTES 570below, allows 571.Nm HAMMER 572to 573dynamically modify the snapshot transaction id by returning a dynamic result 574from 575.Xr readlink 2 576calls. 577.Pp 578A PFS can only be truly destroyed with the 579.Ar pfs-destroy 580directive. 581Removing the softlink will not destroy the underlying PFS. 582.Pp 583It is recommended to use a 584.Nm null 585mount to access a PFS, for more information see 586.Xr HAMMER 5 . 587.\" ==== pfs-update ==== 588.It Ar pfs-update Ar dirpath Op options 589Update the configuration parameters for an existing 590.Nm HAMMER 591file system 592or pseudo-filesystem. 593Options that may be specified: 594.Bl -tag -width indent 595.It sync-beg-tid=0x16llx 596This is the automatic snapshot access starting transaction id for 597mirroring slaves. 598This parameter is normally updated automatically by the 599.Ar mirror-write 600directive. 601.Pp 602It is important to note that accessing a mirroring slave 603with a transaction id greater than the last fully synchronized transaction 604id can result in an unreliable snapshot since you will be accessing 605data that is still undergoing synchronization. 606.Pp 607Manually modifying this field is dangerous and can result in a broken 608mirror. 609.It sync-end-tid=0x16llx 610This is the current synchronization point for mirroring slaves. 611This parameter is normally updated automatically by the 612.Ar mirror-write 613directive. 614.Pp 615Manually modifying this field is dangerous and can result in a broken mirror. 616.It shared-uuid=<uuid> 617Set the shared UUID for this file system. 618All mirrors must have the same shared UUID. 619For safety purposes the 620.Ar mirror-write 621directives will refuse to operate on a target with a different shared UUID. 622.Pp 623Changing the shared UUID on an existing, non-empty mirroring target, 624including an empty but not completely pruned target, 625can lead to corruption of the mirroring target. 626.It unique-uuid=<uuid> 627Set the unique UUID for this file system. 628This UUID should not be used anywhere else, 629even on exact copies of the file system. 630.It label=<string> 631Set a descriptive label for this file system. 632.It snapshots=<string> 633Specify the snapshots directory which 634.Nm 635.Ar cleanup 636will use to manage this PFS. 637The snapshots directory does not need to be configured for 638PFS masters and will default to 639.Pa <pfs>/snapshots . 640.Pp 641PFS slaves are mirroring slaves so you cannot configure a snapshots 642directory on the slave itself to be managed by the slave's machine. 643In fact, the slave will likely have a 644.Pa snapshots 645sub-directory mirrored 646from the master, but that directory contains the configuration the master 647is using for its copy of the file system, not the configuration that we 648want to use for our slave. 649.Pp 650It is recommended that 651.Pa <fs>/var/slaves/<name> 652be configured for a PFS slave, where 653.Pa <fs> 654is the base 655.Nm HAMMER 656file system, and 657.Pa <name> 658is an appropriate label. 659You can control snapshot retention on your slave independent of the master. 660.It snapshots-clear 661Zero out the snapshots directory path for this PFS. 662.El 663.\" ==== pfs-upgrade ==== 664.It Ar pfs-upgrade Ar dirpath 665Upgrade a PFS from slave to master operation. 666The PFS will be rolled back to the current end synchronization tid 667(removing any partial synchronizations), and will then become writable. 668.Pp 669.Em WARNING! 670.Nm HAMMER 671currently supports only single masters and using 672this command can easily result in file system corruption 673if you don't know what you are doing. 674.Pp 675This directive will refuse to run if any programs have open descriptors 676in the PFS, including programs chdir'd into the PFS. 677.\" ==== pfs-downgrade ==== 678.It Ar pfs-downgrade Ar dirpath 679Downgrade a master PFS from master to slave operation 680The PFS becomes read-only and access will be locked to its 681.Ar sync-end-tid . 682.Pp 683This directive will refuse to run if any programs have open descriptors 684in the PFS, including programs chdir'd into the PFS. 685.\" ==== pfs-destroy ==== 686.It Ar pfs-destroy Ar dirpath 687This permanently destroys a PFS. 688.Pp 689This directive will refuse to run if any programs have open descriptors 690in the PFS, including programs chdir'd into the PFS. 691.\" ==== mirror-read ==== 692.It Ar mirror-read Ar filesystem Op Ar <begin-tid> 693Generate a mirroring stream to stdout. 694The stream ends when the transaction id space has been exhausted. 695.\" ==== mirror-read-stream ==== 696.It Ar mirror-read-stream Ar filesystem Op Ar <begin-tid> 697Generate a mirroring stream to stdout. 698Upon completion the stream is paused until new data is synced to the 699master, then resumed. 700Operation continues until the pipe is broken. 701.\" ==== mirror-write ==== 702.It Ar mirror-write Ar filesystem 703Take a mirroring stream on stdin. 704.Pp 705This command will fail if the 706.Ar shared-uuid 707configuration field for the two file systems do not match. 708.Pp 709If the target PFS does not exist this command will ask you whether 710you want to create a compatible PFS slave for the target or not. 711.\" ==== mirror-dump ==== 712.It Ar mirror-dump 713A 714.Ar mirror-read 715can be piped into a 716.Ar mirror-dump 717to dump an ASCII representation of the mirroring stream. 718.\" ==== mirror-copy ==== 719.It Ar mirror-copy Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem 720This is a shortcut which pipes a 721.Ar mirror-read 722command to a 723.Ar mirror-write 724command. 725If a remote host specification is made the program forks a 726.Xr ssh 1 727and execs the 728.Ar mirror-read 729and/or 730.Ar mirror-write 731on the appropriate host. 732The source may be a master or slave PFS, and the target must be a slave PFS. 733.Pp 734This command also established full duplex communication and turns on 735the two-way protocol feature which automatically negotiates transaction id 736ranges without having to use a cyclefile. 737If the operation completes successfully the target PFS's 738.Ar sync-end-tid 739will be updated. 740Note that you must re-chdir into the target PFS to see the updated information. 741If you do not you will still be in the previous snapshot. 742.Pp 743If the target PFS does not exist this command will ask you whether 744you want to create a compatible PFS slave for the target or not. 745.\" ==== mirror-stream ==== 746.It Ar mirror-stream Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem 747This command works similarly to 748.Ar mirror-copy 749but does not exit unless the pipe is broken. 750This command will resume the mirroring operation whenever the master is synced. 751The command is commonly used with 752.Fl i Ar delay 753and 754.Fl b Ar bandwidth 755options to keep the mirroring target in sync with the source on a continuing 756basis. 757.\" ==== version ==== 758.It Ar version Ar filesystem 759This command returns the 760.Nm HAMMER 761filesystem version for the specified 762filesystem as well as the range of versions supported in the kernel. 763The 764.Fl q 765option may be used to remove the summary at the end. 766.\" ==== version-upgrade ==== 767.It Ar version-upgrade Ar filesystem Ar version Op Ar force 768This command upgrades the 769.Nm HAMMER 770filesystem to the specified version. 771Once upgraded a filesystem may not be downgraded. 772If you wish to upgrade a filesystem to a version greater or equal to the 773work-in-progress version number you must specify the 774.Ar force 775directive. 776Use of WIP versions should be relegated to testing and may require wiping 777the filesystem as development progresses, even though the WIP version might 778not change. 779.Pp 780NOTE! This command operates on the entire 781.Nm HAMMER 782filesystem and is not a per-PFS operation. 783All PFS's will be affected. 784.Bl -tag -width indent 785.It 1 786.Dx 2.0 787default version, first 788.Nm HAMMER 789release. 790.It 2 791Work-in-progress version. 792This version is developing a new directory hash key. 793.El 794.El 795.\".Sh EXAMPLES 796.Sh PSEUDO FILESYSTEM (PFS) NOTES 797The root of a PFS is not hooked into the primary 798.Nm HAMMER 799file system as a directory. 800Instead, 801.Nm HAMMER 802creates a special softlink called "@@PFS%05d" (exactly 10 characters long) 803in the primary 804.Nm HAMMER 805file system. 806.Nm HAMMER 807then modifies the contents of the softlink as read by 808.Xr readlink 2 , 809and thus what you see with an 810.Xr ls 1 811command or if you were to 812.Xr cd 1 813into the link. 814If the PFS is a master the link reflects the current state of the PFS. 815If the PFS is a slave the link reflects the last completed snapshot, and the 816contents of the link will change when the next snapshot is completed, and 817so forth. 818.Pp 819PFS support is currently very new and experimental. 820The 821.Nm 822utility employs numerous safeties to reduce user foot-shooting. 823The 824.Ar mirror-copy 825directive requires that the target be configured as a slave and that the 826.Ar shared-uuid 827field of the mirroring source and target match. 828.Sh FILES 829.Bl -tag -width ".It Pa <fs>/var/slaves/<name>" -compact 830.It Pa snapshots 831default per PFS snapshots directory 832.It Pa <snapshots>/config 833.Nm 834.Ar cleanup 835configuration file 836.It Pa <fs>/var/slaves/<name> 837recommended slave PFS snapshots directory 838.El 839.Sh EXIT STATUS 840.Ex -std 841.Sh SEE ALSO 842.Xr undo 1 , 843.Xr HAMMER 5 , 844.Xr periodic.conf 5 , 845.Xr mount_hammer 8 , 846.Xr mount_null 8 , 847.Xr newfs_hammer 8 848.Sh HISTORY 849The 850.Nm 851utility first appeared in 852.Dx 1.11 . 853.Sh AUTHORS 854.An Matthew Dillon Aq dillon@backplane.com 855