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