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