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