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