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.Dd January 3, 2016 34.Dt HAMMER 8 35.Os 36.Sh NAME 37.Nm hammer 38.Nd HAMMER file system utility 39.Sh SYNOPSIS 40.Nm 41.Fl h 42.Nm 43.Op Fl 2ABFqrvXy 44.Op Fl b Ar bandwidth 45.Op Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead 46.Op Fl R Ar restrictcmd 47.Op Fl T Ar restrictpath 48.Op Fl c Ar cyclefile 49.Op Fl e Ar scoreboardfile 50.Op Fl f Ar blkdevs 51.\" .Op Fl s Ar linkpath 52.Op Fl i Ar delay 53.Op Fl p Ar ssh-port 54.Op Fl S Ar splitsize 55.Op Fl t Ar seconds 56.Op Fl m Ar memlimit 57.Ar command 58.Op Ar argument ... 59.Sh DESCRIPTION 60This manual page documents the 61.Nm 62utility which provides miscellaneous functions related to managing a 63.Nm HAMMER 64file system. 65For a general introduction to the 66.Nm HAMMER 67file system, its features, and 68examples on how to set up and maintain one, see 69.Xr HAMMER 5 . 70.Pp 71The options are as follows: 72.Bl -tag -width indent 73.It Fl 2 74Tell the mirror commands to use a 2-way protocol, which allows 75automatic negotiation of transaction id ranges. 76This option is automatically enabled by the 77.Cm mirror-copy 78command. 79.It Fl A 80Make per PFS commands perform on all PFSs if possible. 81If the command supports this option, it targets all PFSs of the 82.Nm HAMMER 83filesystem that the 84.Ar filesystem 85argument (of that command) belongs to. 86Currently 87.Cm rebalance , 88.Cm reblock , 89.Cm reblock-btree , 90.Cm reblock-inodes , 91.Cm reblock-dirs 92and 93.Cm reblock-data 94commands support this option. 95If the command does not support this option, it does nothing. 96.It Fl B 97Bulk transfer. 98.Cm Mirror-stream 99will not attempt to break-up large initial bulk transfers into smaller 100pieces. 101This can save time but if the link is lost in the middle of the 102initial bulk transfer you will have to start over from scratch. 103For more information see the 104.Fl S 105option. 106.It Fl b Ar bandwidth 107Specify a bandwidth limit in bytes per second for mirroring streams. 108This option is typically used to prevent batch mirroring operations from 109loading down the machine. 110The bandwidth may be suffixed with 111.Cm k , m , 112or 113.Cm g 114to specify values in kilobytes, megabytes, and gigabytes per second. 115If no suffix is specified, bytes per second is assumed. 116.Pp 117Unfortunately this is only applicable to the pre-compression bandwidth 118when compression is used, so a better solution would probably be to 119use a 120.Xr ipfw 8 121pipe or a 122.Xr pf 4 123queue. 124.It Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead 125Set the memory cache size for any raw 126.Tn I/O . 127The default is 16MB. 128A suffix of 129.Cm k 130for kilobytes and 131.Cm m 132for megabytes is allowed, 133else the cache size is specified in bytes. 134.Pp 135The read-behind/read-ahead defaults to 4 136.Nm HAMMER 137blocks. 138.Pp 139This option is typically only used with diagnostic commands 140as kernel-supported commands will use the kernel's buffer cache. 141.It Fl R Ar restrictcmd 142This option is used by hammer ssh-remote to restrict the command later 143on in the argument list. Multiple commands may be specified, separated 144by a comma (all one argument). 145.It Fl T Ar restrictpath 146This option is used by hammer ssh-remote to restrict the filesystem path 147specified later on in the argument list. 148.It Fl c Ar cyclefile 149When pruning, rebalancing or reblocking you can tell the utility 150to start at the object id stored in the specified file. 151If the file does not exist 152.Nm 153will start at the beginning. 154If 155.Nm 156is told to run for a specific period of time 157.Pq Fl t 158and is unable to complete the operation it will write out 159the current object id so the next run can pick up where it left off. 160If 161.Nm 162runs to completion it will delete 163.Ar cyclefile . 164.It Fl e Ar scoreboardfile 165Update scoreboard file with progress, primarily used by mirror-stream. 166.It Fl F 167Force operation. 168E.g.\& 169.Cm cleanup 170will not check that time period has elapsed if this option is given. 171.It Fl f Ar blkdevs 172Specify the volumes making up a 173.Nm HAMMER 174file system. 175.Ar Blkdevs 176is a colon-separated list of devices, each specifying a 177.Nm HAMMER 178volume. 179.It Fl h 180Show usage. 181.It Fl i Ar delay 182Specify delay in seconds for 183.Cm mirror-read-stream . 184When maintaining a streaming mirroring this option specifies the 185minimum delay after a batch ends before the next batch is allowed 186to start. 187The default is five seconds. 188.It Fl m Ar memlimit 189Specify the maximum amount of memory 190.Nm 191will allocate during a dedup pass. 192Specify a suffix 'm', 'g', or 't' for megabytes, gigabytes, or terabytes. 193By default 194.Nm 195will allocate up to 1G of ram to hold CRC/SHA tables while running dedup. 196When the limit is reached the dedup code restricts the range of CRCs to 197keep memory use within bounds and runs multiple passes as necessary until 198the entire filesystem has been deduped. 199.It Fl p Ar ssh-port 200Pass the 201.Fl p Ar ssh-port 202option to 203.Xr ssh 1 204when using a remote 205specification for the source and/or destination. 206.It Fl q 207Decrease verboseness. 208May be specified multiple times. 209.It Fl r 210Specify recursion for those commands which support it. 211.It Fl S Ar splitsize 212Specify the bulk splitup size in bytes for mirroring streams. 213When a 214.Cm mirror-stream 215is first started 216.Nm 217will do an initial run-through of the data to calculate good 218transaction ids to cut up the bulk transfers, creating 219restart points in case the stream is interrupted. 220If we don't do this and the stream is interrupted it might 221have to start all over again. 222The default is a 223.Ar splitsize 224of 4GB. 225.Pp 226At the moment the run-through is disk-bandwidth-heavy but some 227future version will limit the run-through to just the B-Tree 228records and not the record data. 229.Pp 230The splitsize may be suffixed with 231.Cm k , m , 232or 233.Cm g 234to specify values in kilobytes, megabytes, or gigabytes. 235If no suffix is specified, bytes is assumed. 236.Pp 237When mirroring very large filesystems the minimum recommended 238split size is 4GB. 239A small split size may wind up generating a great deal of overhead 240but very little actual incremental data and is not recommended. 241.It Fl t Ar seconds 242Specify timeout in seconds. 243When pruning, rebalancing, reblocking or mirror-reading 244you can tell the utility to stop after a certain period of time. 245A value of 0 means unlimited. 246This option is used along with the 247.Fl c Ar cyclefile 248option to prune, rebalance or reblock incrementally. 249.It Fl v 250Increase verboseness. 251May be specified multiple times. 252.It Fl X 253Enable compression for any remote ssh specifications. 254This option is typically used with the mirroring directives. 255.It Fl y 256Force 257.Dq yes 258for interactive questions. 259.El 260.Pp 261The commands are as follows: 262.Bl -tag -width indent 263.\" ==== synctid ==== 264.It Cm synctid Ar filesystem Op Cm quick 265Generate a guaranteed, formal 64-bit transaction id representing the 266current state of the specified 267.Nm HAMMER 268file system. 269The file system will be synced to the media. 270.Pp 271If the 272.Cm quick 273keyword is specified the file system will be soft-synced, meaning that a 274crash might still undo the state of the file system as of the transaction 275id returned but any new modifications will occur after the returned 276transaction id as expected. 277.Pp 278This operation does not create a snapshot. 279It is meant to be used 280to track temporary fine-grained changes to a subset of files and 281will only remain valid for 282.Ql @@ 283access purposes for the 284.Cm prune-min 285period configured for the PFS. 286If you desire a real snapshot then the 287.Cm snapq 288directive may be what you are looking for. 289.\" ==== bstats ==== 290.It Cm bstats Op Ar interval 291Output 292.Nm HAMMER 293B-Tree statistics until interrupted. 294Pause 295.Ar interval 296seconds between each display. 297The default interval is one second. 298.\" ==== iostats ==== 299.It Cm iostats Op Ar interval 300Output 301.Nm HAMMER 302.Tn I/O 303statistics until interrupted. 304Pause 305.Ar interval 306seconds between each display. 307The default interval is one second. 308.\" ==== stats ==== 309.It Cm stats Op Ar interval 310Output 311.Nm HAMMER 312B-Tree and 313.Tn I/O 314statistics until interrupted. 315Pause 316.Ar interval 317seconds between each display. 318The default interval is one second. 319.\" ==== history ==== 320.It Cm history Ns Oo Cm @ Ns Ar offset Ns Oo Cm \&, Ns Ar length Oc Oc Ar path Ns Oo Cm @ Ns Ar offset Ns Oo Cm \&, Ns Ar length Oc Oc Ar ... 321Show the modification history for inode and data of 322.Nm HAMMER 323files. 324If 325.Ar offset 326is given history is shown for data block at given offset, 327otherwise history is shown for inode. 328If 329.Fl v 330is specified 331.Ar length 332data bytes at given offset are dumped for each version, 333default is 32. 334.Pp 335For each 336.Ar path 337this directive shows object id and sync status, 338and for each object version it shows transaction id and time stamp. 339Files has to exist for this directive to be applicable, 340to track inodes which has been deleted or renamed see 341.Xr undo 1 . 342.Pp 343Different 344.Ar offset 345and 346.Ar length 347can be used for each 348.Ar path 349by specifying 350.Ar offset 351and 352.Ar length 353for each 354.Ar path . 355.\" ==== blockmap ==== 356.It Cm blockmap 357Dump the blockmap for the file system. 358The 359.Nm HAMMER 360blockmap is two-layer 361blockmap representing the maximum possible file system size of 1 Exabyte. 362Needless to say the second layer is only present for blocks which exist. 363.Nm HAMMER Ns 's 364blockmap represents 8-Megabyte blocks, called big-blocks. 365Each big-block has an append 366point, a free byte count, and a typed zone id which allows content to be 367reverse engineered to some degree. 368.Pp 369In 370.Nm HAMMER 371allocations are essentially appended to a selected big-block using 372the append offset and deducted from the free byte count. 373When space is freed the free byte count is adjusted but 374.Nm HAMMER 375does not track holes in big-blocks for reallocation. 376A big-block must be completely freed, either 377through normal file system operations or through reblocking, before 378it can be reused. 379.Pp 380Data blocks can be shared by deducting the space used from the free byte 381count for each shared references. 382This means the free byte count can legally go negative. 383.Pp 384This command needs the 385.Fl f Ar blkdevs 386option. 387.\" ==== checkmap ==== 388.It Cm checkmap 389Check the blockmap allocation count. 390.Nm 391will scan the freemap, B-Tree, UNDO FIFO, then collect allocation information, 392and construct a blockmap in-memory. 393It will then check that blockmap against the on-disk blockmap. 394.Pp 395This command needs the 396.Fl f Ar blkdevs 397option. 398.\" ==== show ==== 399.It Cm show Op Ar localization Ns Op Cm \&: Ns Ar object_id Ns Op Cm \&: Ns Ar rec_type Ns Op Cm \&: Ns Ar key Ns Op Cm \&: Ns Ar create_tid 400Dump the B-Tree. 401By default this command will validate all B-Tree 402linkages and CRCs, including data CRCs, and will report the most verbose 403information it can dig up. 404Any errors will show up with a 405.Ql B 406in column 1 along with various 407other error flags. 408.Pp 409If you specify 410.Ar localization 411or 412.Ar localization Ns Cm \&: Ns Ar object_id 413or 414.Ar localization Ns Cm \&: Ns Ar object_id Ns Cm \&: Ns Ar rec_type 415or 416.Ar localization Ns Cm \&: Ns Ar object_id Ns Cm \&: Ns Ar rec_type Ns Cm \&: Ns Ar key 417or 418.Ar localization Ns Cm \&: Ns Ar object_id Ns Cm \&: Ns Ar rec_type Ns Cm \&: Ns Ar key Ns Cm \&: Ns Ar create_tid 419the dump will 420search for the key printing nodes as it recurses down, and then 421will iterate forwards. 422These fields are specified in HEX. 423Note that the PFS id is the top 16 bits of the 32-bit localization 424field so PFS #1 would be 00010000. 425.Pp 426If you use 427.Fl q 428the command will report less information about the inode contents. 429.Pp 430If you use 431.Fl qq 432the command will not report the content of the inode or other typed 433data at all. 434.Pp 435If you use 436.Fl qqq 437the command will not report volume header information, big-block fill 438ratios, mirror transaction ids, or report or check data CRCs. 439B-Tree CRCs and linkages are still checked. 440.Pp 441This command needs the 442.Fl f Ar blkdevs 443option. 444.\" ==== show-undo ==== 445.It Cm show-undo 446.Nm ( HAMMER 447VERSION 4+) 448Dump the UNDO/REDO map. 449.Pp 450This command needs the 451.Fl f Ar blkdevs 452option. 453.\" .It Ar blockmap 454.\" Dump the B-Tree, record, large-data, and small-data blockmaps, showing 455.\" physical block assignments and free space percentages. 456.\" ==== ssh-remote ==== 457.It Cm ssh-remote Ar command Ar targetdir 458Used in a ssh authorized_keys line such as 459command="/sbin/hammer ssh-remote mirror-read /fubarmount" ... to allow 460mirror-read or mirror-write access to a particular subdirectory tree. 461This way you do not have to give shell access to the remote box. 462.Nm 463will obtain the original command line from the SSH_ORIGINAL_COMMAND 464environment variable, validate it against the restriction, and then 465re-exec hammer with the validated arguments. 466.Pp 467The remote hammer command does not allow the 468.Fl c 469or 470.Fl f 471options to be passed in. 472.\" ==== recover ==== 473.It Cm recover Ar targetdir 474Recover data from a corrupted 475.Nm HAMMER 476filesystem. 477This is a low level command which operates on the filesystem image and 478attempts to locate and recover files from a corrupted filesystem. 479The entire image is scanned linearly looking for B-Tree nodes. 480Any node 481found which passes its CRC test is scanned for file, inode, and directory 482fragments and the target directory is populated with the resulting data. 483files and directories in the target directory are initially named after 484the object id and are renamed as fragmentary information is processed. 485.Pp 486This command keeps track of filename/object_id translations and may eat a 487considerably amount of memory while operating. 488.Pp 489This command is literally the last line of defense when it comes to 490recovering data from a dead filesystem. 491.Pp 492This command needs the 493.Fl f Ar blkdevs 494option. 495.\" ==== namekey1 ==== 496.It Cm namekey1 Ar filename 497Generate a 498.Nm HAMMER 49964-bit directory hash for the specified file name, using 500the original directory hash algorithm in version 1 of the file system. 501The low 32 bits are used as an iterator for hash collisions and will be 502output as 0. 503.\" ==== namekey2 ==== 504.It Cm namekey2 Ar filename 505Generate a 506.Nm HAMMER 50764-bit directory hash for the specified file name, using 508the new directory hash algorithm in version 2 of the file system. 509The low 32 bits are still used as an iterator but will start out containing 510part of the hash key. 511.\" ==== namekey32 ==== 512.It Cm namekey32 Ar filename 513Generate the top 32 bits of a 514.Nm HAMMER 51564 bit directory hash for the specified file name. 516.\" ==== info ==== 517.It Cm info Ar dirpath ... 518Show extended information about all 519.Nm HAMMER 520file systems mounted in the system or the one mounted in 521.Ar dirpath 522when this argument is specified. 523.Pp 524The information is divided into sections: 525.Bl -tag -width indent 526.It Volume identification 527General information, like the label of the 528.Nm HAMMER 529filesystem, the number of volumes it contains, the FSID, and the 530.Nm HAMMER 531version being used. 532.It Big-block information 533Big-block statistics, such as total, used, reserved and free big-blocks. 534.It Space information 535Information about space used on the filesystem. 536Currently total size, used, reserved and free space are displayed. 537.It PFS information 538Basic information about the PFSs currently present on a 539.Nm HAMMER 540filesystem. 541.Pp 542.Dq PFS ID 543is the ID of the PFS, with 0 being the root PFS. 544.Dq Snaps 545is the current snapshot count on the PFS. 546.Dq Mounted on 547displays the mount point of the PFS is currently mounted on (if any). 548.El 549.\" ==== cleanup ==== 550.It Cm cleanup Op Ar filesystem ... 551This is a meta-command which executes snapshot, prune, rebalance, dedup 552and reblock commands on the specified 553.Nm HAMMER 554file systems. 555If no 556.Ar filesystem 557is specified this command will clean-up all 558.Nm HAMMER 559file systems in use, including PFS's. 560To do this it will scan all 561.Nm HAMMER 562and 563.Nm null 564mounts, extract PFS id's, and clean-up each PFS found. 565.Pp 566This command will access a snapshots 567directory and a configuration file for each 568.Ar filesystem , 569creating them if necessary. 570.Bl -tag -width indent 571.It Nm HAMMER No version 2- 572The configuration file is 573.Pa config 574in the snapshots directory which defaults to 575.Pa <pfs>/snapshots . 576.It Nm HAMMER No version 3+ 577The configuration file is saved in file system meta-data, see 578.Nm 579.Cm config . 580The snapshots directory defaults to 581.Pa /var/hammer/<pfs> 582.Pa ( /var/hammer/root 583for root mount). 584.El 585.Pp 586The format of the configuration file is: 587.Bd -literal -offset indent 588snapshots <period> <retention-time> [any] 589prune <period> <max-runtime> 590rebalance <period> <max-runtime> 591dedup <period> <max-runtime> 592reblock <period> <max-runtime> 593recopy <period> <max-runtime> 594.Ed 595.Pp 596Defaults are: 597.Bd -literal -offset indent 598snapshots 1d 60d # 0d 0d for PFS /tmp, /var/tmp, /usr/obj 599prune 1d 5m 600rebalance 1d 5m 601dedup 1d 5m 602reblock 1d 5m 603recopy 30d 10m 604.Ed 605.Pp 606Time is given with a suffix of 607.Cm d , 608.Cm h , 609.Cm m 610or 611.Cm s 612meaning day, hour, minute and second. 613.Pp 614If the 615.Cm snapshots 616directive has a period of 0 and a retention time of 0 617then snapshot generation is disabled, removal of old snapshots are 618disabled, and prunes will use 619.Cm prune-everything . 620.Pp 621If the 622.Cm snapshots 623directive has a period of 0 but a non-zero retention time 624then this command will not create any new snapshots but will remove old 625snapshots it finds based on the retention time. 626This form should be 627used on PFS masters where you are generating your own snapshot softlinks 628manually and on PFS slaves when all you wish to do is prune away existing 629snapshots inherited via the mirroring stream. 630.Pp 631By default only snapshots in the form 632.Ql snap- Ns Ar yyyymmdd Ns Op - Ns Ar HHMM 633are processed. 634If the 635.Cm any 636directive is specified as a third argument on the 637.Cm snapshots 638config line then any softlink of the form 639.Ql *- Ns Ar yyyymmdd Ns Op - Ns Ar HHMM 640or 641.Ql *. Ns Ar yyyymmdd Ns Op - Ns Ar HHMM 642will be processed. 643.Pp 644A period of 0 for prune, rebalance, dedup, reblock or recopy disables the directive. 645A max-runtime of 0 means unlimited. 646.Pp 647If period hasn't passed since the previous 648.Cm cleanup 649run nothing is done. 650For example a day has passed when midnight is passed (localtime). 651If the 652.Fl F 653flag is given the period is ignored. 654By default, 655.Dx 656is set up to run 657.Nm Cm cleanup 658nightly via 659.Xr periodic 8 . 660.Pp 661The default configuration file will create a daily snapshot, do a daily 662pruning, rebalancing, deduping and reblocking run and a monthly recopy run. 663Reblocking is defragmentation with a level of 95%, 664and recopy is full defragmentation. 665.Pp 666By default prune, dedup and rebalance operations are time limited to 5 minutes, 667and reblock operations to a bit over 5 minutes, 668and recopy operations to a bit over 10 minutes. 669Reblocking and recopy runs are each broken down into four separate functions: 670B-Tree, inodes, dirs and data. 671Each function is time limited to the time given in the configuration file, 672but the B-Tree, inodes and dirs functions usually does not take very long time, 673full defragmentation is always used for these three functions. 674Also note that this directive will by default disable snapshots on 675the following PFS's: 676.Pa /tmp , 677.Pa /var/tmp 678and 679.Pa /usr/obj . 680.Pp 681The defaults may be adjusted by modifying the configuration file. 682The pruning and reblocking commands automatically maintain a cyclefile 683for incremental operation. 684If you interrupt (^C) the program the cyclefile will be updated, 685but a sub-command 686may continue to run in the background for a few seconds until the 687.Nm HAMMER 688ioctl detects the interrupt. 689The 690.Cm snapshots 691PFS option can be set to use another location for the snapshots directory. 692.Pp 693Work on this command is still in progress. 694Expected additions: 695An ability to remove snapshots dynamically as the 696file system becomes full. 697.\" ==== abort-cleanup ==== 698.It Cm abort-cleanup 699This command will terminate all active 700.Cm cleanup 701processes. 702.\" ==== config ==== 703.It Cm config Op Ar filesystem Op Ar configfile 704.Nm ( HAMMER 705VERSION 3+) 706Show or change configuration for 707.Ar filesystem . 708If zero or one arguments are specified this function dumps the current 709configuration file to stdout. 710Zero arguments specifies the PFS containing the current directory. 711This configuration file is stored in file system meta-data. 712If two arguments are specified this function installs a new config file. 713.Pp 714In 715.Nm HAMMER 716versions less than 3 the configuration file is by default stored in 717.Pa <pfs>/snapshots/config , 718but in all later versions the configuration file is stored in file system 719meta-data. 720.\" ==== viconfig ==== 721.It Cm viconfig Op Ar filesystem 722.Nm ( HAMMER 723VERSION 3+) 724Edit the configuration file and reinstall into file system meta-data when done. 725Zero arguments specifies the PFS containing the current directory. 726.\" ==== volume-add ==== 727.It Cm volume-add Ar device Ar filesystem 728Add volume 729.Ar device 730to 731.Ar filesystem . 732This will format 733.Ar device 734and add all of its space to 735.Ar filesystem . 736A 737.Nm HAMMER 738file system can use up to 256 volumes. 739.Pp 740.Em NOTE! 741All existing data contained on 742.Ar device 743will be destroyed by this operation! 744If 745.Ar device 746contains a valid 747.Nm HAMMER 748file system, formatting will be denied. 749You can overcome this sanity check by using 750.Xr dd 1 751to erase the beginning sectors of the device. 752.Pp 753Remember that you have to specify 754.Ar device , 755together with any other device that make up the file system, 756colon-separated to 757.Pa /etc/fstab 758and 759.Xr mount_hammer 8 . 760If 761.Ar filesystem 762is root file system, also remember to add 763.Ar device 764to 765.Va vfs.root.mountfrom 766in 767.Pa /boot/loader.conf , 768see 769.Xr loader 8 . 770.\" ==== volume-del ==== 771.It Cm volume-del Ar device Ar filesystem 772Remove volume 773.Ar device 774from 775.Ar filesystem . 776.Pp 777Remember that you have to remove 778.Ar device 779from the colon-separated list in 780.Pa /etc/fstab 781and 782.Xr mount_hammer 8 . 783If 784.Ar filesystem 785is root file system, also remember to remove 786.Ar device 787from 788.Va vfs.root.mountfrom 789in 790.Pa /boot/loader.conf , 791see 792.Xr loader 8 . 793.Pp 794It is not possible to remove the 795.Ar root-volume 796as it contains 797.Ar filesystem 798meta data such as 799.Nm HAMMER Ns 's 800layer1 blockmap and UNDO FIFO. 801.Pp 802This command may 803.Cm reblock 804filesystem before it attempts to remove the volume if the volume is not empty. 805.\" ==== volume-list ==== 806.It Cm volume-list Ar filesystem 807List the volumes that make up 808.Ar filesystem . 809.\" ==== volume-blkdevs ==== 810.It Cm volume-blkdevs Ar filesystem 811List the volumes that make up 812.Ar filesystem 813in 814.Ar blkdevs 815format. 816.\" ==== snapshot ==== 817.It Cm snapshot Oo Ar filesystem Oc Ar snapshot-dir 818.It Cm snapshot Ar filesystem Ar snapshot-dir Op Ar note 819Take a snapshot of the file system either explicitly given by 820.Ar filesystem 821or implicitly derived from the 822.Ar snapshot-dir 823argument and creates a symlink in the directory provided by 824.Ar snapshot-dir 825pointing to the snapshot. 826If 827.Ar snapshot-dir 828is not a directory, it is assumed to be a format string passed to 829.Xr strftime 3 830with the current time as parameter. 831If 832.Ar snapshot-dir 833refers to an existing directory, a default format string of 834.Ql snap-%Y%m%d-%H%M 835is assumed and used as name for the newly created symlink. 836.Pp 837Snapshot is a per PFS operation, so each PFS in a 838.Nm HAMMER 839file system have to be snapshot separately. 840.Pp 841Example, assuming that 842.Pa /mysnapshots 843is on file system 844.Pa / 845and that 846.Pa /obj 847and 848.Pa /usr 849are file systems on their own, the following invocations: 850.Bd -literal -offset indent 851hammer snapshot /mysnapshots 852 853hammer snapshot /mysnapshots/%Y-%m-%d 854 855hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d 856 857hammer snapshot /usr /my/snaps/usr "note" 858.Ed 859.Pp 860Would create symlinks similar to: 861.Bd -literal -offset indent 862/mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16 863 864/mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16 865 866/mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16 867 868/my/snaps/usr/snap-20080627-1210 -> /usr@@0x10d2cd05b7270d16 869.Ed 870.Pp 871When run on a 872.Nm HAMMER 873version 3+ file system the snapshot is also recorded in file system meta-data 874along with the optional 875.Ar note . 876See the 877.Cm snapls 878directive. 879.\" ==== snap* ==== 880.It Cm snap Ar path Op Ar note 881.Nm ( HAMMER 882VERSION 3+) 883Create a snapshot for the PFS containing 884.Ar path 885and create a snapshot softlink. 886If the path specified is a 887directory a standard snapshot softlink will be created in the directory. 888The snapshot softlink points to the base of the mounted PFS. 889.It Cm snaplo Ar path Op Ar note 890.Nm ( HAMMER 891VERSION 3+) 892Create a snapshot for the PFS containing 893.Ar path 894and create a snapshot softlink. 895If the path specified is a 896directory a standard snapshot softlink will be created in the directory. 897The snapshot softlink points into the directory it is contained in. 898.It Cm snapq Ar dir Op Ar note 899.Nm ( HAMMER 900VERSION 3+) 901Create a snapshot for the PFS containing the specified directory but do 902not create a softlink. 903Instead output a path which can be used to access 904the directory via the snapshot. 905.Pp 906An absolute or relative path may be specified. 907The path will be used as-is as a prefix in the path output to stdout. 908As with the other 909snap and snapshot directives the snapshot transaction id will be registered 910in the file system meta-data. 911.It Cm snaprm Ar path Ar ... 912.It Cm snaprm Ar transaction_id Ar ... 913.It Cm snaprm Ar filesystem Ar transaction_id Ar ... 914.Nm ( HAMMER 915VERSION 3+) 916Remove a snapshot given its softlink or transaction id. 917If specifying a transaction id 918the snapshot is removed from file system meta-data but you are responsible 919for removing any related softlinks. 920.Pp 921If a softlink path is specified the filesystem and transaction id 922is derived from the contents of the softlink. 923If just a transaction id is specified it is assumed to be a snapshot in the 924.Nm HAMMER 925filesystem you are currently chdir'd into. 926You can also specify the filesystem and transaction id explicitly. 927.It Cm snapls Op Ar path ... 928.Nm ( HAMMER 929VERSION 3+) 930Dump the snapshot meta-data for PFSs containing each 931.Ar path 932listing all available snapshots and their notes. 933If no arguments are specified snapshots for the PFS containing the 934current directory are listed. 935This is the definitive list of snapshots for the file system. 936.\" ==== prune ==== 937.It Cm prune Ar softlink-dir 938Prune the file system based on previously created snapshot softlinks. 939Pruning is the act of deleting file system history. 940The 941.Cm prune 942command will delete file system history such that 943the file system state is retained for the given snapshots, 944and all history after the latest snapshot. 945By setting the per PFS parameter 946.Cm prune-min , 947history is guaranteed to be saved at least this time interval. 948All other history is deleted. 949.Pp 950The target directory is expected to contain softlinks pointing to 951snapshots of the file systems you wish to retain. 952The directory is scanned non-recursively and the mount points and 953transaction ids stored in the softlinks are extracted and sorted. 954The file system is then explicitly pruned according to what is found. 955Cleaning out portions of the file system is as simple as removing a 956snapshot softlink and then running the 957.Cm prune 958command. 959.Pp 960As a safety measure pruning only occurs if one or more softlinks are found 961containing the 962.Ql @@ 963snapshot id extension. 964Currently the scanned softlink directory must contain softlinks pointing 965to a single 966.Nm HAMMER 967mount. 968The softlinks may specify absolute or relative paths. 969Softlinks must use 20-character 970.Ql @@0x%016llx 971transaction ids, as might be returned from 972.Nm Cm synctid Ar filesystem . 973.Pp 974Pruning is a per PFS operation, so each PFS in a 975.Nm HAMMER 976file system have to be pruned separately. 977.Pp 978Note that pruning a file system may not immediately free-up space, 979though typically some space will be freed if a large number of records are 980pruned out. 981The file system must be reblocked to completely recover all available space. 982.Pp 983Example, lets say your that you didn't set 984.Cm prune-min , 985and snapshot directory contains the following links: 986.Bd -literal -offset indent 987lrwxr-xr-x 1 root wheel 29 May 31 17:57 snap1 -> 988/usr/obj/@@0x10d2cd05b7270d16 989 990lrwxr-xr-x 1 root wheel 29 May 31 17:58 snap2 -> 991/usr/obj/@@0x10d2cd13f3fde98f 992 993lrwxr-xr-x 1 root wheel 29 May 31 17:59 snap3 -> 994/usr/obj/@@0x10d2cd222adee364 995.Ed 996.Pp 997If you were to run the 998.Cm prune 999command on this directory, then the 1000.Nm HAMMER 1001.Pa /usr/obj 1002mount will be pruned to retain the above three snapshots. 1003In addition, history for modifications made to the file system older than 1004the oldest snapshot will be destroyed and history for potentially fine-grained 1005modifications made to the file system more recently than the most recent 1006snapshot will be retained. 1007.Pp 1008If you then delete the 1009.Pa snap2 1010softlink and rerun the 1011.Cm prune 1012command, 1013history for modifications pertaining to that snapshot would be destroyed. 1014.Pp 1015In 1016.Nm HAMMER 1017file system versions 3+ this command also scans the snapshots stored 1018in the file system meta-data and includes them in the prune. 1019.\" ==== prune-everything ==== 1020.It Cm prune-everything Ar filesystem 1021Remove all historical records from 1022.Ar filesystem . 1023Use this directive with caution on PFSs where you intend to use history. 1024.Pp 1025This command does not remove snapshot softlinks but will delete all 1026snapshots recorded in file system meta-data (for file system version 3+). 1027The user is responsible for deleting any softlinks. 1028.Pp 1029Pruning is a per PFS operation, so each PFS in a 1030.Nm HAMMER 1031file system have to be pruned separately. 1032.\" ==== rebalance ==== 1033.It Cm rebalance Ar filesystem Op Ar saturation_percentage 1034Rebalance the B-Tree, nodes with small number of 1035elements will be combined and element counts will be smoothed out 1036between nodes. 1037.Pp 1038The saturation percentage is between 50% and 100%. 1039The default is 85% (the 1040.Sq % 1041suffix is not needed). 1042.Pp 1043Rebalancing is a per PFS operation, so each PFS in a 1044.Nm HAMMER 1045file system have to be rebalanced separately. 1046.\" ==== dedup ==== 1047.It Cm dedup Ar filesystem 1048.Nm ( HAMMER 1049VERSION 5+) 1050Perform offline (post-process) deduplication. 1051Deduplication occurs at 1052the block level, currently only data blocks of the same size can be 1053deduped, metadata blocks can not. 1054The hash function used for comparing 1055data blocks is CRC-32 (CRCs are computed anyways as part of 1056.Nm HAMMER 1057data integrity features, so there's no additional overhead). 1058Since CRC is a weak hash function a byte-by-byte comparison is done 1059before actual deduping. 1060In case of a CRC collision (two data blocks have the same CRC 1061but different contents) the checksum is upgraded to SHA-256. 1062.Pp 1063Currently 1064.Nm HAMMER 1065reblocker may partially blow up (re-expand) dedup (reblocker's normal 1066operation is to reallocate every record, so it's possible for deduped 1067blocks to be re-expanded back). 1068.Pp 1069Deduplication is a per PFS operation, so each PFS in a 1070.Nm HAMMER 1071file system have to be deduped separately. 1072This also 1073means that if you have duplicated data in two different PFSs that data 1074won't be deduped, however the addition of such feature is planned. 1075.Pp 1076The 1077.Fl m Ar memlimit 1078option should be used to limit memory use during the dedup run if the 1079default 1G limit is too much for the machine. 1080.\" ==== dedup-simulate ==== 1081.It Cm dedup-simulate Ar filesystem 1082Shows potential space savings (simulated dedup ratio) one can get after 1083running 1084.Cm dedup 1085command. 1086If the estimated dedup ratio is greater than 1.00 you will see 1087dedup space savings. 1088Remember that this is an estimated number, in 1089practice real dedup ratio will be slightly smaller because of 1090.Nm HAMMER 1091big-block underflows, B-Tree locking issues and other factors. 1092.Pp 1093Note that deduplication currently works only on bulk data so if you 1094try to run 1095.Cm dedup-simulate 1096or 1097.Cm dedup 1098commands on a PFS that contains metadata only (directory entries, 1099softlinks) you will get a 0.00 dedup ratio. 1100.Pp 1101The 1102.Fl m Ar memlimit 1103option should be used to limit memory use during the dedup run if the 1104default 1G limit is too much for the machine. 1105.\" ==== reblock* ==== 1106.It Cm reblock Ar filesystem Op Ar fill_percentage 1107.It Cm reblock-btree Ar filesystem Op Ar fill_percentage 1108.It Cm reblock-inodes Ar filesystem Op Ar fill_percentage 1109.It Cm reblock-dirs Ar filesystem Op Ar fill_percentage 1110.It Cm reblock-data Ar filesystem Op Ar fill_percentage 1111Attempt to defragment and free space for reuse by reblocking a live 1112.Nm HAMMER 1113file system. 1114Big-blocks cannot be reused by 1115.Nm HAMMER 1116until they are completely free. 1117This command also has the effect of reordering all elements, effectively 1118defragmenting the file system. 1119.Pp 1120The default fill percentage is 100% and will cause the file system to be 1121completely defragmented. 1122All specified element types will be reallocated and rewritten. 1123If you wish to quickly free up space instead try specifying 1124a smaller fill percentage, such as 90% or 80% (the 1125.Sq % 1126suffix is not needed). 1127.Pp 1128Since this command may rewrite the entire contents of the disk it is 1129best to do it incrementally from a 1130.Xr cron 8 1131job along with the 1132.Fl c Ar cyclefile 1133and 1134.Fl t Ar seconds 1135options to limit the run time. 1136The file system would thus be defragmented over long period of time. 1137.Pp 1138It is recommended that separate invocations be used for each data type. 1139B-Tree nodes, inodes, and directories are typically the most important 1140elements needing defragmentation. 1141Data can be defragmented over a longer period of time. 1142.Pp 1143Reblocking is a per PFS operation, so each PFS in a 1144.Nm HAMMER 1145file system have to be reblocked separately. 1146.\" ==== pfs-status ==== 1147.It Cm pfs-status Ar dirpath ... 1148Retrieve the mirroring configuration parameters for the specified 1149.Nm HAMMER 1150file systems or pseudo-filesystems (PFS's). 1151.\" ==== pfs-master ==== 1152.It Cm pfs-master Ar dirpath Op Ar options 1153Create a pseudo-filesystem (PFS) inside a 1154.Nm HAMMER 1155file system. 1156Up to 65536 PFSs can be created. 1157Each PFS uses an independent inode numbering space making it suitable 1158for replication. 1159.Pp 1160The 1161.Cm pfs-master 1162directive creates a PFS that you can read, write, and use as a mirroring 1163source. 1164.Pp 1165A PFS can only be truly destroyed with the 1166.Cm pfs-destroy 1167directive. 1168Removing the softlink will not destroy the underlying PFS. 1169.Pp 1170A PFS can only be created in the root PFS (PFS# 0), 1171not in a PFS created by 1172.Cm pfs-master 1173or 1174.Cm pfs-slave 1175(PFS# >0). 1176.Pp 1177It is recommended that 1178.Ar dirpath 1179is of the form 1180.Pa <fs>/pfs/<name> 1181(i.e.\& located in 1182.Pa PFS 1183directory at root of 1184.Nm HAMMER 1185file system). 1186.Pp 1187It is recommended to use a 1188.Nm null 1189mount to access a PFS, except for root PFS, for more information see 1190.Xr HAMMER 5 . 1191.\" ==== pfs-slave ==== 1192.It Cm pfs-slave Ar dirpath Op Ar options 1193Create a pseudo-filesystem (PFS) inside a 1194.Nm HAMMER 1195file system. 1196Up to 65536 PFSs can be created. 1197Each PFS uses an independent inode numbering space making it suitable 1198for replication. 1199.Pp 1200The 1201.Cm pfs-slave 1202directive creates a PFS that you can use as a mirroring source or target. 1203You will not be able to access a slave PFS until you have completed the 1204first mirroring operation with it as the target (its root directory will 1205not exist until then). 1206.Pp 1207Access to the pfs-slave via the special softlink, as described in the 1208.Sx PSEUDO-FILESYSTEM (PFS) NOTES 1209below, allows 1210.Nm HAMMER 1211to 1212dynamically modify the snapshot transaction id by returning a dynamic result 1213from 1214.Xr readlink 2 1215calls. 1216.Pp 1217A PFS can only be truly destroyed with the 1218.Cm pfs-destroy 1219directive. 1220Removing the softlink will not destroy the underlying PFS. 1221.Pp 1222A PFS can only be created in the root PFS (PFS# 0), 1223not in a PFS created by 1224.Cm pfs-master 1225or 1226.Cm pfs-slave 1227(PFS# >0). 1228.Pp 1229It is recommended that 1230.Ar dirpath 1231is of the form 1232.Pa <fs>/pfs/<name> 1233(i.e.\& located in 1234.Pa PFS 1235directory at root of 1236.Nm HAMMER 1237file system). 1238.Pp 1239It is recommended to use a 1240.Nm null 1241mount to access a PFS, except for root PFS, for more information see 1242.Xr HAMMER 5 . 1243.\" ==== pfs-update ==== 1244.It Cm pfs-update Ar dirpath Op Ar options 1245Update the configuration parameters for an existing 1246.Nm HAMMER 1247file system or pseudo-filesystem. 1248Options that may be specified: 1249.Bl -tag -width indent 1250.It Cm sync-beg-tid= Ns Ar 0x16llx 1251This is the automatic snapshot access starting transaction id for 1252mirroring slaves. 1253This parameter is normally updated automatically by the 1254.Cm mirror-write 1255directive. 1256.Pp 1257It is important to note that accessing a mirroring slave 1258with a transaction id greater than the last fully synchronized transaction 1259id can result in an unreliable snapshot since you will be accessing 1260data that is still undergoing synchronization. 1261.Pp 1262Manually modifying this field is dangerous and can result in a broken mirror. 1263.It Cm sync-end-tid= Ns Ar 0x16llx 1264This is the current synchronization point for mirroring slaves. 1265This parameter is normally updated automatically by the 1266.Cm mirror-write 1267directive. 1268.Pp 1269Manually modifying this field is dangerous and can result in a broken mirror. 1270.It Cm shared-uuid= Ns Ar uuid 1271Set the shared UUID for this file system. 1272All mirrors must have the same shared UUID. 1273For safety purposes the 1274.Cm mirror-write 1275directives will refuse to operate on a target with a different shared UUID. 1276.Pp 1277Changing the shared UUID on an existing, non-empty mirroring target, 1278including an empty but not completely pruned target, 1279can lead to corruption of the mirroring target. 1280.It Cm unique-uuid= Ns Ar uuid 1281Set the unique UUID for this file system. 1282This UUID should not be used anywhere else, 1283even on exact copies of the file system. 1284.It Cm label= Ns Ar string 1285Set a descriptive label for this file system. 1286.It Cm snapshots= Ns Ar string 1287Specify the snapshots directory which 1288.Nm 1289.Cm cleanup 1290will use to manage this PFS. 1291.Bl -tag -width indent 1292.It Nm HAMMER No version 2- 1293The snapshots directory does not need to be configured for 1294PFS masters and will default to 1295.Pa <pfs>/snapshots . 1296.Pp 1297PFS slaves are mirroring slaves so you cannot configure a snapshots 1298directory on the slave itself to be managed by the slave's machine. 1299In fact, the slave will likely have a 1300.Pa snapshots 1301sub-directory mirrored 1302from the master, but that directory contains the configuration the master 1303is using for its copy of the file system, not the configuration that we 1304want to use for our slave. 1305.Pp 1306It is recommended that 1307.Pa <fs>/var/slaves/<name> 1308be configured for a PFS slave, where 1309.Pa <fs> 1310is the base 1311.Nm HAMMER 1312file system, and 1313.Pa <name> 1314is an appropriate label. 1315.It Nm HAMMER No version 3+ 1316The snapshots directory does not need to be configured for PFS masters or 1317slaves. 1318The snapshots directory defaults to 1319.Pa /var/hammer/<pfs> 1320.Pa ( /var/hammer/root 1321for root mount). 1322.El 1323.Pp 1324You can control snapshot retention on your slave independent of the master. 1325.It Cm snapshots-clear 1326Zero out the 1327.Cm snapshots 1328directory path for this PFS. 1329.It Cm prune-min= Ns Ar N Ns Cm d 1330.It Cm prune-min= Ns Oo Ar N Ns Cm d/ Oc Ns \ 1331Ar hh Ns Op Cm \&: Ns Ar mm Ns Op Cm \&: Ns Ar ss 1332Set the minimum fine-grained data retention period. 1333.Nm HAMMER 1334always retains fine-grained history up to the most recent snapshot. 1335You can extend the retention period further by specifying a non-zero 1336pruning minimum. 1337Any snapshot softlinks within the retention period are ignored 1338for the purposes of pruning (i.e.\& the fine grained history is retained). 1339Number of days, hours, minutes and seconds are given as 1340.Ar N , hh , mm 1341and 1342.Ar ss . 1343.Pp 1344Because the transaction id in the snapshot softlink cannot be used 1345to calculate a timestamp, 1346.Nm HAMMER 1347uses the earlier of the 1348.Fa st_ctime 1349or 1350.Fa st_mtime 1351field of the softlink to 1352determine which snapshots fall within the retention period. 1353Users must be sure to retain one of these two fields when manipulating 1354the softlink. 1355.El 1356.\" ==== pfs-upgrade ==== 1357.It Cm pfs-upgrade Ar dirpath 1358Upgrade a PFS from slave to master operation. 1359The PFS will be rolled back to the current end synchronization transaction id 1360(removing any partial synchronizations), and will then become writable. 1361.Pp 1362.Em WARNING! 1363.Nm HAMMER 1364currently supports only single masters and using 1365this command can easily result in file system corruption 1366if you don't know what you are doing. 1367.Pp 1368This directive will refuse to run if any programs have open descriptors 1369in the PFS, including programs chdir'd into the PFS. 1370.\" ==== pfs-downgrade ==== 1371.It Cm pfs-downgrade Ar dirpath 1372Downgrade a master PFS from master to slave operation. 1373The PFS becomes read-only and access will be locked to its 1374.Cm sync-end-tid . 1375.Pp 1376This directive will refuse to run if any programs have open descriptors 1377in the PFS, including programs chdir'd into the PFS. 1378.\" ==== pfs-destroy ==== 1379.It Cm pfs-destroy Ar dirpath 1380This permanently destroys a PFS. 1381.Pp 1382This directive will refuse to run if any programs have open descriptors 1383in the PFS, including programs chdir'd into the PFS. 1384As safety measure the 1385.Fl y 1386flag have no effect on this directive. 1387.\" ==== mirror-read ==== 1388.It Cm mirror-read Ar filesystem Op Ar begin-tid 1389Generate a mirroring stream to stdout. 1390The stream ends when the transaction id space has been exhausted. 1391.Ar filesystem 1392may be a master or slave PFS. 1393.\" ==== mirror-read-stream ==== 1394.It Cm mirror-read-stream Ar filesystem Op Ar begin-tid 1395Generate a mirroring stream to stdout. 1396Upon completion the stream is paused until new data is synced to the 1397.Ar filesystem , 1398then resumed. 1399Operation continues until the pipe is broken. 1400See the 1401.Cm mirror-stream 1402command for more details. 1403.\" ==== mirror-write ==== 1404.It Cm mirror-write Ar filesystem 1405Take a mirroring stream on stdin. 1406.Ar filesystem 1407must be a slave PFS. 1408.Pp 1409This command will fail if the 1410.Cm shared-uuid 1411configuration field for the two file systems do not match. 1412See the 1413.Cm mirror-copy 1414command for more details. 1415.Pp 1416If the target PFS does not exist this command will ask you whether 1417you want to create a compatible PFS slave for the target or not. 1418.\" ==== mirror-dump ==== 1419.It Ar mirror-dump Ar [header] 1420A 1421.Cm mirror-read 1422can be piped into a 1423.Cm mirror-dump 1424to dump an ASCII representation of the mirroring stream. 1425If the keyword 1426.Ar header 1427is specified, only the header information is shown. 1428.\" ==== mirror-copy ==== 1429.\".It Cm mirror-copy Ar [[user@]host:]filesystem [[user@]host:]filesystem 1430.It Cm mirror-copy \ 1431Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem \ 1432Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem 1433This is a shortcut which pipes a 1434.Cm mirror-read 1435command to a 1436.Cm mirror-write 1437command. 1438If a remote host specification is made the program forks a 1439.Xr ssh 1 1440(or other program as specified by the 1441.Ev HAMMER_RSH 1442environment variable) and execs the 1443.Cm mirror-read 1444and/or 1445.Cm mirror-write 1446on the appropriate host. 1447The source may be a master or slave PFS, and the target must be a slave PFS. 1448.Pp 1449This command also establishes full duplex communication and turns on 1450the 2-way protocol feature 1451.Fl ( 2 ) 1452which automatically negotiates transaction id 1453ranges without having to use a cyclefile. 1454If the operation completes successfully the target PFS's 1455.Cm sync-end-tid 1456will be updated. 1457Note that you must re-chdir into the target PFS to see the updated information. 1458If you do not you will still be in the previous snapshot. 1459.Pp 1460If the target PFS does not exist this command will ask you whether 1461you want to create a compatible PFS slave for the target or not. 1462.\" ==== mirror-stream ==== 1463.\".It Cm mirror-stream Ar [[user@]host:]filesystem [[user@]host:]filesystem 1464.It Cm mirror-stream \ 1465Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem \ 1466Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem 1467This is a shortcut which pipes a 1468.Cm mirror-read-stream 1469command to a 1470.Cm mirror-write 1471command. 1472This command works similarly to 1473.Cm mirror-copy 1474but does not exit after the initial mirroring completes. 1475The mirroring operation will resume as changes continue to be made to the 1476source. 1477The command is commonly used with 1478.Fl i Ar delay 1479and 1480.Fl b Ar bandwidth 1481options to keep the mirroring target in sync with the source on a continuing 1482basis. 1483.Pp 1484If the pipe is broken the command will automatically retry after sleeping 1485for a short while. 1486The time slept will be 15 seconds plus the time given in the 1487.Fl i 1488option. 1489.Pp 1490This command also detects the initial-mirroring case and spends some 1491time scanning the B-Tree to find good break points, allowing the initial 1492bulk mirroring operation to be broken down into 4GB pieces. 1493This means that the user can kill and restart the operation and it will 1494not have to start from scratch once it has gotten past the first chunk. 1495The 1496.Fl S 1497option may be used to change the size of pieces and the 1498.Fl B 1499option may be used to disable this feature and perform an initial bulk 1500transfer instead. 1501.\" ==== version ==== 1502.It Cm version Ar filesystem 1503This command returns the 1504.Nm HAMMER 1505file system version for the specified 1506.Ar filesystem 1507as well as the range of versions supported in the kernel. 1508The 1509.Fl q 1510option may be used to remove the summary at the end. 1511.\" ==== version-upgrade ==== 1512.It Cm version-upgrade Ar filesystem Ar version Op Cm force 1513Upgrade the 1514.Nm HAMMER 1515.Ar filesystem 1516to the specified 1517.Ar version . 1518Once upgraded a file system may not be downgraded. 1519If you wish to upgrade a file system to a version greater or equal to the 1520work-in-progress (WIP) version number you must specify the 1521.Cm force 1522directive. 1523Use of WIP versions should be relegated to testing and may require wiping 1524the file system as development progresses, even though the WIP version might 1525not change. 1526.Pp 1527.Em NOTE! 1528This command operates on the entire 1529.Nm HAMMER 1530file system and is not a per PFS operation. 1531All PFS's will be affected. 1532.Bl -tag -width indent 1533.It 1 1534.Dx 2.0 1535default version, first 1536.Nm HAMMER 1537release. 1538.It 2 1539.Dx 2.3 . 1540New directory entry layout. 1541This version is using a new directory hash key. 1542.It 3 1543.Dx 2.5 . 1544New snapshot management, using file system meta-data for saving 1545configuration file and snapshots (transaction ids etc.). 1546Also default snapshots directory has changed. 1547.It 4 1548.Dx 2.6 1549default version. 1550New undo/redo/flush, giving 1551.Nm HAMMER 1552a much faster sync and fsync. 1553.It 5 1554.Dx 2.9 . 1555Deduplication support. 1556.It 6 1557.Dx 2.9 . 1558Directory hash ALG1. 1559Tends to maintain inode number / directory name entry ordering better 1560for files after minor renaming. 1561.El 1562.El 1563.Sh PSEUDO-FILESYSTEM (PFS) NOTES 1564The root of a PFS is not hooked into the primary 1565.Nm HAMMER 1566file system as a directory. 1567Instead, 1568.Nm HAMMER 1569creates a special softlink called 1570.Ql @@PFS%05d 1571(exactly 10 characters long) in the primary 1572.Nm HAMMER 1573file system. 1574.Nm HAMMER 1575then modifies the contents of the softlink as read by 1576.Xr readlink 2 , 1577and thus what you see with an 1578.Nm ls 1579command or if you were to 1580.Nm cd 1581into the link. 1582If the PFS is a master the link reflects the current state of the PFS. 1583If the PFS is a slave the link reflects the last completed snapshot, and the 1584contents of the link will change when the next snapshot is completed, and 1585so forth. 1586.Pp 1587The 1588.Nm 1589utility employs numerous safeties to reduce user foot-shooting. 1590The 1591.Cm mirror-copy 1592directive requires that the target be configured as a slave and that the 1593.Cm shared-uuid 1594field of the mirroring source and target match. 1595The 1596.Cm pfs-master 1597and 1598.Cm pfs-slave 1599directives require that the PFS softlink be created under the main 1600.Nm 1601filesystem mount. You may only access PFS softlinks via the main 1602.Nm 1603filesystem mount. 1604.Sh DOUBLE_BUFFER MODE 1605There is a limit to the number of vnodes the kernel can cache, and because 1606file buffers are associated with a vnode the related data cache can get 1607blown away when operating on large numbers of files even if the system has 1608sufficient memory to hold the file data. 1609.Pp 1610If you turn on 1611.Nm HAMMER Ns 's 1612double buffer mode by setting the 1613.Xr sysctl 8 1614node 1615.Va vfs.hammer.double_buffer 1616to 1 1617.Nm HAMMER 1618will cache file data via the block device and copy it into the per-file 1619buffers as needed. The data will be double-cached at least until the 1620buffer cache throws away the file buffer. 1621This mode is typically used in conjunction with 1622.Xr swapcache 8 1623when 1624.Va vm.swapcache.data_enable 1625is turned on in order to prevent unnecessary re-caching of file data 1626due to vnode recycling. 1627The swapcache will save the cached VM pages related to 1628.Nm HAMMER Ns 's 1629block 1630device (which doesn't recycle unless you umount the filesystem) instead 1631of the cached VM pages backing the file vnodes. 1632.Pp 1633Double buffering is normally desirable when working with large filesystems, 1634particularly when swapcache is used. 1635The swapcache can only back active VM objects, including the block device, 1636and large filesystems often have far more inodes than the kernel can support. 1637In addition, when using this mode, you may wish to reduce the 1638.Va kern.maxvnodes 1639setting for the system to force the system to do less caching of logical 1640file buffers and more caching of device buffers, since the device buffers 1641are backing the logical file buffers. 1642.Sh UPGRADE INSTRUCTIONS HAMMER V1 TO V2 1643This upgrade changes the way directory entries are stored. 1644It is possible to upgrade a V1 file system to V2 in place, but 1645directories created prior to the upgrade will continue to use 1646the old layout. 1647.Pp 1648Note that the slave mirroring code in the target kernel had bugs in 1649V1 which can create an incompatible root directory on the slave. 1650Do not mix a 1651.Nm HAMMER 1652master created after the upgrade with a 1653.Nm HAMMER 1654slave created prior to the upgrade. 1655.Pp 1656Any directories created after upgrading will use a new layout. 1657.Sh UPGRADE INSTRUCTIONS HAMMER V2 TO V3 1658This upgrade adds meta-data elements to the B-Tree. 1659It is possible to upgrade a V2 file system to V3 in place. 1660After issuing the upgrade be sure to run a 1661.Nm 1662.Cm cleanup 1663to perform post-upgrade tasks. 1664.Pp 1665After making this upgrade running a 1666.Nm 1667.Cm cleanup 1668will move the 1669.Pa <pfs>/snapshots 1670directory for each PFS mount into 1671.Pa /var/hammer/<pfs> . 1672A 1673.Nm HAMMER 1674root mount will migrate 1675.Pa /snapshots 1676into 1677.Pa /var/hammer/root . 1678Migration occurs only once and only if you have not specified 1679a snapshots directory in the PFS configuration. 1680If you have specified a snapshots directory in the PFS configuration no 1681automatic migration will occur. 1682.Pp 1683For slaves, if you desire, you can migrate your snapshots 1684config to the new location manually and then clear the 1685snapshot directory configuration in the slave PFS. 1686The new snapshots hierarchy is designed to work with 1687both master and slave PFSs equally well. 1688.Pp 1689In addition, the old config file will be moved to file system meta-data, 1690editable via the new 1691.Nm 1692.Cm viconfig 1693directive. 1694The old config file will be deleted. 1695Migration occurs only once. 1696.Pp 1697The V3 file system has new 1698.Cm snap* 1699directives for creating snapshots. 1700All snapshot directives, including the original, will create 1701meta-data entries for the snapshots and the pruning code will 1702automatically incorporate these entries into its list and 1703expire them the same way it expires softlinks. 1704If you by accident blow away your snapshot softlinks you can use the 1705.Cm snapls 1706directive to get a definitive list from the file system meta-data and 1707regenerate them from that list. 1708.Pp 1709.Em WARNING! 1710If you are using 1711.Nm 1712to backup file systems your scripts may be using the 1713.Cm synctid 1714directive to generate transaction ids. 1715This directive does not create a snapshot. 1716You will have to modify your scripts to use the 1717.Cm snapq 1718directive to generate the linkbuf for the softlink you create, or 1719use one of the other 1720.Cm snap* 1721directives. 1722The older 1723.Cm snapshot 1724directive will continue to work as expected and in V3 it will also 1725record the snapshot transaction id in file system meta-data. 1726You may also want to make use of the new 1727.Ar note 1728tag for the meta-data. 1729.Pp 1730.Em WARNING! 1731If you used to remove snapshot softlinks with 1732.Nm rm 1733you should probably start using the 1734.Cm snaprm 1735directive instead to also remove the related meta-data. 1736The pruning code scans the meta-data so just removing the 1737softlink is not sufficient. 1738.Sh UPGRADE INSTRUCTIONS HAMMER V3 TO V4 1739This upgrade changes undo/flush, giving faster sync. 1740It is possible to upgrade a V3 file system to V4 in place. 1741This upgrade reformats the UNDO/REDO FIFO (typically 1GB), 1742so upgrade might take a minute or two depending. 1743.Pp 1744Version 4 allows the UNDO/REDO FIFO to be flushed without also having 1745to flush the volume header, removing 2 of the 4 disk syncs typically 1746required for an 1747.Fn fsync 1748and removing 1 of the 2 disk syncs typically 1749required for a flush sequence. 1750Version 4 also implements the REDO log (see 1751.Sx FSYNC FLUSH MODES 1752below) which is capable 1753of fsync()ing with either one disk flush or zero disk flushes. 1754.Sh UPGRADE INSTRUCTIONS HAMMER V4 TO V5 1755This upgrade brings in deduplication support. 1756It is possible to upgrade a V4 file system to V5 in place. 1757Technically it makes the layer2 1758.Va bytes_free 1759field a signed value instead of unsigned, allowing it to go negative. 1760A version 5 filesystem is required for dedup operation. 1761.Sh UPGRADE INSTRUCTIONS HAMMER V5 TO V6 1762It is possible to upgrade a V5 file system to V6 in place. 1763.Sh FSYNC FLUSH MODES 1764.Nm HAMMER 1765implements five different fsync flush modes via the 1766.Va vfs.hammer.fsync_mode 1767sysctl, for 1768.Nm HAMMER 1769version 4+ file systems. 1770.Pp 1771As of 1772.Dx 2.6 1773fsync mode 3 is set by default. 1774REDO operation and recovery is enabled by default. 1775.Bl -tag -width indent 1776.It mode 0 1777Full synchronous fsync semantics without REDO. 1778.Pp 1779.Nm HAMMER 1780will not generate REDOs. 1781A 1782.Fn fsync 1783will completely sync 1784the data and meta-data and double-flush the FIFO, including 1785issuing two disk synchronization commands. 1786The data is guaranteed 1787to be on the media as of when 1788.Fn fsync 1789returns. 1790Needless to say, this is slow. 1791.It mode 1 1792Relaxed asynchronous fsync semantics without REDO. 1793.Pp 1794This mode works the same as mode 0 except the last disk synchronization 1795command is not issued. 1796It is faster than mode 0 but not even remotely 1797close to the speed you get with mode 2 or mode 3. 1798.Pp 1799Note that there is no chance of meta-data corruption when using this 1800mode, it simply means that the data you wrote and then 1801.Fn fsync Ns 'd 1802might not have made it to the media if the storage system crashes at a bad 1803time. 1804.It mode 2 1805Full synchronous fsync semantics using REDO. 1806NOTE: If not running a 1807.Nm HAMMER 1808version 4 filesystem or later mode 0 is silently used. 1809.Pp 1810.Nm HAMMER 1811will generate REDOs in the UNDO/REDO FIFO based on a heuristic. 1812If this is sufficient to satisfy the 1813.Fn fsync 1814operation the blocks will be written out and 1815.Nm HAMMER 1816will wait for the I/Os to complete, 1817and then followup with a disk sync command to guarantee the data 1818is on the media before returning. 1819This is slower than mode 3 and can result in significant disk or 1820SSDs overheads, though not as bad as mode 0 or mode 1. 1821.It mode 3 1822Relaxed asynchronous fsync semantics using REDO. 1823NOTE: If not running a 1824.Nm HAMMER 1825version 4 filesystem or later mode 1 is silently used. 1826.Pp 1827.Nm HAMMER 1828will generate REDOs in the UNDO/REDO FIFO based on a heuristic. 1829If this is sufficient to satisfy the 1830.Fn fsync 1831operation the blocks 1832will be written out and 1833.Nm HAMMER 1834will wait for the I/Os to complete, 1835but will 1836.Em NOT 1837issue a disk synchronization command. 1838.Pp 1839Note that there is no chance of meta-data corruption when using this 1840mode, it simply means that the data you wrote and then 1841.Fn fsync Ns 'd 1842might 1843not have made it to the media if the storage system crashes at a bad 1844time. 1845.Pp 1846This mode is the fastest production fsyncing mode available. 1847This mode is equivalent to how the UFS fsync in the 1848.Bx Ns s 1849operates. 1850.It mode 4 1851fsync is ignored. 1852.Pp 1853Calls to 1854.Fn fsync 1855will be ignored. 1856This mode is primarily designed 1857for testing and should not be used on a production system. 1858.El 1859.Sh RESTORING FROM A SNAPSHOT BACKUP 1860You restore a snapshot by copying it over to live, but there is a caveat. 1861The mtime and atime fields for files accessed via a snapshot is locked 1862to the ctime in order to keep the snapshot consistent, because neither 1863mtime nor atime changes roll any history. 1864.Pp 1865In order to avoid unnecessary copying it is recommended that you use 1866.Nm cpdup 1867.Fl VV 1868.Fl v 1869when doing the copyback. 1870Also make sure you traverse the snapshot softlink by appending a ".", 1871as in "<snapshotpath>/.", and you match up the directory properly. 1872.Sh RESTORING A PFS FROM A MIRROR 1873A PFS can be restored from a mirror with 1874.Cm mirror-copy . 1875.Cm config 1876data must be copied separately. 1877At last the PFS can be upgraded to master using 1878.Cm pfs-upgrade . 1879.Pp 1880It is not possible to restore the root PFS (PFS# 0) by using mirroring, 1881as the root PFS is always a master PFS. 1882A normal copy (e.g.\& using 1883.Xr cpdup 1 ) 1884must be done, ignoring history. 1885If history is important, old root PFS can me restored to a new PFS, and 1886important directories/files can be 1887.Nm null 1888mounted to the new PFS. 1889.Sh ENVIRONMENT 1890The following environment variables affect the execution of 1891.Nm : 1892.Bl -tag -width ".Ev EDITOR" 1893.It Ev EDITOR 1894The editor program specified in the variable 1895.Ev EDITOR 1896will be invoked instead of the default editor, which is 1897.Xr vi 1 . 1898.It Ev HAMMER_RSH 1899The command specified in the variable 1900.Ev HAMMER_RSH 1901will be used to initiate remote operations for the mirror-copy and 1902mirror-stream commands instead of the default command, which is 1903.Xr ssh 1 . 1904The program will be invoked via 1905.Xr execvp 3 1906using a typical 1907.Xr rsh 1 1908style 1909.Cm -l user host <remote-command> 1910command line. 1911.It Ev VISUAL 1912Same effect as 1913.Ev EDITOR 1914variable. 1915.El 1916.Sh FILES 1917.Bl -tag -width ".It Pa <fs>/var/slaves/<name>" -compact 1918.It Pa <pfs>/snapshots 1919default per PFS snapshots directory 1920.Nm ( HAMMER 1921VERSION 2-) 1922.It Pa /var/hammer/<pfs> 1923default per PFS snapshots directory (not root) 1924.Nm ( HAMMER 1925VERSION 3+) 1926.It Pa /var/hammer/root 1927default snapshots directory for root directory 1928.Nm ( HAMMER 1929VERSION 3+) 1930.It Pa <snapshots>/config 1931per PFS 1932.Nm 1933.Cm cleanup 1934configuration file 1935.Nm ( HAMMER 1936VERSION 2-) 1937.It Pa <fs>/var/slaves/<name> 1938recommended slave PFS snapshots directory 1939.Nm ( HAMMER 1940VERSION 2-) 1941.It Pa <fs>/pfs 1942recommended PFS directory 1943.El 1944.Sh EXIT STATUS 1945.Ex -std 1946.Sh SEE ALSO 1947.Xr ssh 1 , 1948.Xr undo 1 , 1949.Xr HAMMER 5 , 1950.Xr periodic.conf 5 , 1951.Xr loader 8 , 1952.Xr mount_hammer 8 , 1953.Xr mount_null 8 , 1954.Xr newfs_hammer 8 , 1955.Xr swapcache 8 , 1956.Xr sysctl 8 1957.Sh HISTORY 1958The 1959.Nm 1960utility first appeared in 1961.Dx 1.11 . 1962.Sh AUTHORS 1963.An Matthew Dillon Aq Mt dillon@backplane.com 1964