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