1.\" Copyright (c) 2007 The DragonFly Project. All rights reserved. 2.\" 3.\" This code is derived from software contributed to The DragonFly Project 4.\" by Matthew Dillon <dillon@backplane.com> 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in 14.\" the documentation and/or other materials provided with the 15.\" distribution. 16.\" 3. Neither the name of The DragonFly Project nor the names of its 17.\" contributors may be used to endorse or promote products derived 18.\" from this software without specific, prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 24.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 26.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 30.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" $DragonFly: src/sbin/hammer/hammer.8,v 1.58 2008/11/13 02:04:27 dillon Exp $ 34.\" 35.Dd September 28, 2009 36.Dt HAMMER 8 37.Os 38.Sh NAME 39.Nm hammer 40.Nd HAMMER file system utility 41.Sh SYNOPSIS 42.Nm 43.Fl h 44.Nm 45.Op Fl 2Bqrvy 46.Op Fl b Ar bandwidth 47.Op Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead 48.Op Fl c Ar cyclefile 49.Op Fl f Ar blkdev Ns Oo Ns Cm \&: Ns Ar blkdev Oc Ns * 50.\" .Op Fl s Ar linkpath 51.Op Fl i Ar delay 52.Op Fl t Ar seconds 53.Ar command 54.Op Ar argument ... 55.Sh DESCRIPTION 56This manual page documents the 57.Nm 58utility which provides miscellaneous functions related to managing a 59.Nm HAMMER 60file system. 61For a general introduction to the 62.Nm HAMMER 63file system, its features, and 64examples on how to set up and maintain one, see 65.Xr HAMMER 5 . 66.Pp 67The options are as follows: 68.Bl -tag -width indent 69.It Fl h 70Get help. 71.It Fl 2 72Tell the mirror commands to use a 2-way protocol, which allows 73automatic negotiation of transaction id ranges. 74This option is automatically enabled by the 75.Cm mirror-copy 76command. 77.It Fl B 78Bulk Transfer. 79.Cm Mirror-stream 80will not attempt to break-up large initial bulk transfers into smaller pieces. 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. 83.It Fl b Ar bandwidth 84Specify a bandwidth limit in bytes per second for mirroring streams. 85This option is typically used to prevent batch mirroring operations from 86loading down the machine. 87The bandwidth may be suffixed with 88.Cm k , m , 89or 90.Cm g 91to specify values in kilobytes, megabytes, and gigabytes per second. 92If no suffix is specified, bytes per second is assumed. 93.It Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead 94Set the memory cache size for any raw 95.Tn I/O . 96The default is 16m. 97A suffix of 98.Cm k 99for kilobytes and 100.Cm m 101for megabytes is allowed, 102else the cache size is specified in bytes. 103.Pp 104The read-behind/read-ahead defaults to 4 hammer blocks. 105.Pp 106This option is typically only used with diagnostic commands 107as kernel-supported commands will use the kernel's buffer cache. 108.It Fl c Ar cyclefile 109When pruning and reblocking you can instruction 110.Nm 111to start at the object id stored in the specified file. 112If the file does not exist 113.Nm 114will start at the beginning. 115If 116.Nm 117is told to run for a 118specific period of time and is unable to complete the operation it will 119write out the current object id so the next run can pick up where it left off. 120If 121.Nm 122runs to completion it will delete 123.Ar cyclefile . 124.It Fl f Ar blkdev Ns Oo Ns Cm \&: Ns Ar blkdev Oc Ns * 125Specify the volumes making up a 126.Nm HAMMER 127file system. 128.It Fl i Ar delay 129When maintaining a streaming mirroring this option specifies the 130minimum delay after a batch ends before the next batch is allowed 131to start. 132The default is five seconds. 133.It Fl q 134Decrease verboseness. 135May be specified multiple times. 136.It Fl r 137Specify recursion for those commands which support it. 138.It Fl t Ar seconds 139When pruning and reblocking you can tell the utility to stop after a 140certain period of time. 141This option is used along with the 142.Fl c Ar cyclefile 143option to prune or reblock a portion of the file system incrementally. 144.It Fl v 145Increase verboseness. 146May be specified multiple times. 147.It Fl y 148Force "yes" for any interactive question. 149.El 150.Pp 151The commands are as follows: 152.Bl -tag -width indent 153.\" ==== synctid ==== 154.It Cm synctid Ar filesystem Op Cm quick 155Generates a guaranteed, formal 64 bit transaction id representing the 156current state of the specified 157.Nm HAMMER 158file system. 159The file system will be synced to the media. 160.Pp 161If the 162.Cm quick 163keyword is specified the file system will be soft-synced, meaning that a 164crash might still undo the state of the file system as of the transaction 165id returned but any new modifications will occur after the returned 166transaction id as expected. 167.Pp 168This operation does not create a snapshot. It is meant to be used 169to track temporary fine-grained changes to a subset of files and 170will only remain valid for @@ snapshot access purposes for the 171.Cm prune-min 172period configured for the PFS. If you desire a real snapshot then 173the 174.Cm snapq 175directive may be what you are looking for. 176.\" ==== bstats ==== 177.It Cm bstats Op Ar interval 178Output 179.Nm HAMMER 180B-tree statistics until interrupted. 181Pause 182.Ar interval 183seconds between each display. 184The default interval is one second. 185.\" ==== iostats ==== 186.It Cm iostats Op Ar interval 187Output 188.Nm HAMMER 189.Tn I/O 190statistics until interrupted. 191Pause 192.Ar interval 193seconds between each display. 194The default interval is one second. 195.\" ==== history ==== 196.It Cm history Ar path ... 197Show the modification history for 198.Nm HAMMER 199file's inode and data. 200.\" ==== blockmap ==== 201.It Cm blockmap 202Dump the blockmap for the file system. 203The 204.Nm HAMMER 205blockmap is two-layer 206blockmap representing the maximum possible file system size of 1 Exabyte. 207Needless to say the second layer is only present for blocks which exist. 208.Nm HAMMER Ns 's 209blockmap represents 8-Megabyte blocks, called big-blocks. 210Each big-block has an append 211point, a free byte count, and a typed zone id which allows content to be 212reverse engineered to some degree. 213.Pp 214In 215.Nm HAMMER 216allocations essentially appended to a selected big-block using 217the append offset and deducted from the free byte count. 218When space is freed the free byte count is adjusted but 219.Nm HAMMER 220does not track holes in big-blocks for reallocation. 221A big-block must be completely freed, either 222through normal file system operations or through reblocking, before 223it can be reused. 224.Pp 225Data blocks can be shared by deducting the space used from the free byte 226count for each shared references, though 227.Nm HAMMER 228does not yet make use of this feature. 229This means the free byte count can legally go negative. 230.Pp 231This command needs the 232.Fl f 233flag. 234.\" ==== show ==== 235.It Cm show Op Ar lo Ns Cm \&: Ns Ar objid 236Dump the B-tree. 237By default this command will validate all B-Tree 238linkages and CRCs, including data CRCs, and will report the most verbose 239information it can dig up. 240Any errors will show up with a 'B' in column 1 along with various 241other error flags. 242.Pp 243If you specify a localization and object id field the dump will 244search for the key printing nodes as it recurses down, and then 245will iterate forwards. 246.Pp 247If you use 248.Fl q 249the command will report less information about the inode contents. 250.Pp 251If you use 252.Fl qq 253the command will not report the content of the inode or other typed 254data at all. 255.Pp 256If you use 257.Fl qqq 258the command will not report volume header information, big-block fill 259ratios, mirror transaction ids, or report or check data CRCs. 260B-tree CRCs and linkages are still checked. 261.Pp 262This command needs the 263.Fl f 264flag. 265.\" .It Ar blockmap 266.\" Dump the B-tree, record, large-data, and small-data blockmaps, showing 267.\" physical block assignments and free space percentages. 268.\" ==== namekey1 ==== 269.It Cm namekey1 Ar filename 270Generate a 271.Nm HAMMER 27264 bit directory hash for the specified file name, using 273the original directory hash algorithm in version 1 of the file system. 274The low 32 bits are used as an iterator for hash collisions and will be 275output as 0. 276.\" ==== namekey2 ==== 277.It Cm namekey2 Ar filename 278Generate a 279.Nm HAMMER 28064 bit directory hash for the specified file name, using 281the new directory hash algorithm in version 2 of the file system. 282The low 32 bits are still used as an iterator but will start out containing 283part of the hash key. 284.\" ==== namekey32 ==== 285.It Cm namekey32 Ar filename 286Generate the top 32 bits of a 287.Nm HAMMER 28864 bit directory hash for the specified file name. 289.\" ==== info ==== 290.It Cm info 291Shows extended information about all the mounted 292.Nm HAMMER 293file systems. 294At the moment volume identification, big-blocks information and space details 295are shown. 296.\" ==== cleanup ==== 297.It Cm cleanup Op Ar filesystem ... 298This is a meta-command which executes snapshot, prune, rebalance and reblock 299commands on the specified 300.Nm HAMMER 301file system(s). 302If no 303.Ar filesystem 304is specified this command will clean-up all 305.Nm HAMMER 306file systems in use, including PFS's. 307To do this it will scan all 308.Nm HAMMER 309and 310.Nm null 311mounts, extract PFS id's, and clean-up each PFS found. 312.Pp 313This command will by default access a 314.Pa snapshots 315subdirectory and a 316.Pa snapshots/config 317file for each 318.Ar filesystem , 319creating them if necessary. 320The format of the configuration file is: 321.Bd -literal -offset indent 322snapshots <period> <retention-time> [any] 323prune <period> <max-runtime> 324rebalance <period> <max-runtime> 325reblock <period> <max-runtime> 326recopy <period> <max-runtime> 327.Ed 328.Pp 329Defaults are: 330.Bd -literal -offset indent 331snapshots 1d 60d # 0d 0d for PFS /tmp, /var/tmp, /usr/obj 332prune 1d 5m 333rebalance 1d 5m 334reblock 1d 5m 335recopy 30d 10m 336.Ed 337.Pp 338Time is given with a suffix of 339.Cm d , 340.Cm h , 341.Cm m 342or 343.Cm s 344meaning day, hour, minute and second. 345.Pp 346If the 347.Cm snapshots 348directive has a period of 0 and a retention time of 0 349then snapshot generation is disabled, removal of old snapshots are 350disabled, and prunes will use 351.Cm prune-everything . 352If the 353.Cm snapshots 354directive has a period of 0 but a non-zero retention time 355then this command will not create any new snapshots but will remove old 356snapshots it finds based on the retention time. 357.Pp 358By default only snapshots in the form 359.Ql snap- Ns Ar yyyymmdd Ns Op - Ns Ar HHMM 360are processed. 361If the 362.Cm any 363directive is specified as a third argument on the 364.Cm snapshots 365config line then any softlink of the form 366.Ql *- Ns Ar yyyymmdd Ns Op - Ns Ar HHMM 367or 368.Ql *. Ns Ar yyyymmdd Ns Op - Ns Ar HHMM 369will be processed. 370.Pp 371A prune max-runtime of 0 means unlimited. 372.Pp 373If period hasn't passed since the previous 374.Cm cleanup 375run nothing is done. 376For example a day has passed when midnight is passed (localtime). 377By default, 378.Dx 379is set up to run 380.Nm Ar cleanup 381nightly via 382.Xr periodic 8 . 383.Pp 384The default configuration file will create a daily snapshot, do a daily 385pruning, rebalancing and reblocking run and a monthly recopy run. 386Reblocking is defragmentation with a level of 95%, 387and recopy is full defragmentation. 388.Pp 389By default prune and rebalance operations are time limited to 5 minutes, 390reblock operations to a bit over 5 minutes, 391and recopy operations to a bit over 10 minutes. 392Reblocking and recopy runs are each broken down into four separate functions: 393btree, inodes, dirs and data. 394Each function is time limited to the time given in the configuration file, 395but the btree, inodes and dirs functions usually does not take very long time, 396full defragmentation is always used for these three functions. 397Also note that this directive will by default disable snapshots on 398the following PFS's: 399.Pa /tmp , 400.Pa /var/tmp 401and 402.Pa /usr/obj . 403.Pp 404The defaults may be adjusted by modifying the 405.Pa config 406file. 407The pruning and reblocking commands automatically maintain a cyclefile 408for incremental operation. 409If you interrupt (^C) the program the cyclefile will be updated, 410but a sub-command 411may continue to run in the background for a few seconds until the 412.Nm HAMMER 413ioctl detects the interrupt. 414The 415.Cm snapshots 416PFS option can be set to use another location for the snapshots directory. 417.Pp 418Work on this command is still in progress. 419Expected additions: 420An ability to remove snapshots dynamically as the 421file system becomes full. 422.\" ==== config ==== 423.It Cm config Ar filesystem Op configfile 424(HAMMER VERSION 3+) 425If one argument is specified this function dumps the current configuration 426file to stdout. This configuration file is stored in filesystem meta-data. 427If two arguments are specified this function installs a new config file. 428.Pp 429In 430.Nm HAMMER 431versions less then 3 the configuration file is stored in 432.Pa <fs>/snapshots/config , 433but in all later versions the configuration file is stored in filesystem 434meta-data. 435.It Cm viconfig Ar filesystem 436(HAMMER VERSION 3+) 437Edit the configuration file and reinstall into filesystem meta-data when 438done. 439.\" ==== expand ==== 440.It Cm expand Ar filesystem Ar device 441This command will format 442.Ar device 443and add all of its space to 444.Ar filesystem . 445.Pp 446.Em NOTE! 447All existing data contained on 448.Ar device 449will be destroyed by this operation! 450If 451.Ar device 452contains a valid 453.Nm HAMMER 454filesystem, formatting will be denied. You can overcome this sanity check 455by using 456.Xr dd 1 457to erase the beginning sectors of the device. 458Also remember that you have to specify 459.Ar device , 460together with any other device that make the filesystem, colon-separated to 461.Xr mount_hammer 8 . 462.\" ==== snapshot ==== 463.It Cm snapshot Oo Ar filesystem Oc Ar snapshot-dir 464.It Cm snapshot Ar filesystem Ar snapshot-dir Ar note 465Takes a snapshot of the file system either explicitly given by 466.Ar filesystem 467or implicitly derived from the 468.Ar snapshot-dir 469argument and creates a symlink in the directory provided by 470.Ar snapshot-dir 471pointing to the snapshot. 472If 473.Ar snapshot-dir 474is not a directory, it is assumed to be a format string passed to 475.Xr strftime 3 476with the current time as parameter. 477If 478.Ar snapshot-dir 479refers to an existing directory, a default format string of 480.Ql snap-%Y%d%m-%H%M 481is assumed and used as name for the newly created symlink. 482.Pp 483Snapshot is a per PFS operation, so a 484.Nm HAMMER 485file system and each PFS in it have to be snapshot separately. 486.Pp 487Example, assuming that 488.Pa /mysnapshots 489is on file system 490.Pa / 491and that 492.Pa /obj 493is a file system on its own, the following invocations: 494.Bd -literal -offset indent 495hammer snapshot /mysnapshots 496 497hammer snapshot /mysnapshots/%Y-%m-%d 498 499hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d 500 501hammer snapshot /usr /my/snaps/for/usr "note" 502.Ed 503.Pp 504Would create symlinks similar to: 505.Bd -literal -offset indent 506/mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16 507 508/mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16 509 510/mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16 511.Ed 512.Pp 513When run on a 514.Nm HAMMER 515version 3+ filesystem the snapshot is also recorded in meta-data 516along with the optional note. See the 517.Cm snapls 518directive. 519.\" ==== snap* ==== 520.It Cm snap Ar path Op "note" 521(HAMMER VERSION 3+) 522Create the named snapshot softlink. If the path specified is a 523directory a standard snapshot softlink will be created in the directory. 524The snapshot softlink points to the base of the mounted PFS. 525.It Cm snaplo Ar path Op "note" 526(HAMMER VERSION 3+) 527Create the named snapshot softlink. If the path specified is a 528directory a standard snapshot softlink will be created in the directory. 529The snapshot softlink points into the directory it is contained in. 530.It Cm snapq Ar dir Op "note" 531(HAMMER VERSION 3+) 532Create a snapshot for the PFS containing the specified directory but do 533not create a softlink. Instead output a path which can be used to access 534the directory via the snapshot. 535.Pp 536An absolute or relative path may be specified. The path will be used 537as-is as a prefix in the path output to stdout. As with the other 538snap and snapshot directives the snapshot transaction id will be registered 539in the filesystem meta-data. 540.It Cm snaprm Op fs Ar path/transid 541(HAMMER VERSION 3+) 542Remove a snapshot given its softlink. If specifying a transaction id 543the snapshot is removed from filesystem meta-data but you are responsible 544for removing any related softlinks. 545.It Cm snapls 546(HAMMER VERSION 3+) 547Dump the snapshot meta-data in the filesystem, listing all available 548snapshots and their notes. This is the definitive list of snapshots 549for the filesystem. 550.\" ==== prune ==== 551.It Cm prune Ar softlink-dir 552Prune the file system based on previously created snapshot softlinks. 553Pruning is the act of deleting file system history. 554The 555.Cm prune 556command will delete file system history such that 557the file system state is retained for the given snapshots, 558and all history after the latest snapshot. 559By setting the per PFS parameter 560.Cm prune-min , 561history is guaranteed to be saved at least this time interval. 562All other history is deleted. 563.Pp 564The target directory is expected to contain softlinks pointing to 565snapshots of the file systems you wish to retain. 566The directory is scanned non-recursively and the mount points and 567transaction ids stored in the softlinks are extracted and sorted. 568The file system is then explicitly pruned according to what is found. 569Cleaning out portions of the file system is as simple as removing a 570snapshot softlink and then running the 571.Cm prune 572command. 573.Pp 574As a safety measure pruning only occurs if one or more softlinks are found 575containing the 576.Ql @@ 577snapshot id extension. 578Currently the scanned softlink directory must contain softlinks pointing 579to a single 580.Nm HAMMER 581mount. 582The softlinks may specify absolute or relative paths. 583Softlinks must use 20-character 584.Ql @@0x%016llx 585transaction ids, as might be returned from 586.Nm Cm synctid Ar filesystem . 587.Pp 588Pruning is a per PFS operation, so a 589.Nm HAMMER 590file system and each PFS in it have to be pruned separately. 591.Pp 592Note that pruning a file system may not immediately free-up space, 593though typically some space will be freed if a large number of records are 594pruned out. 595The file system must be reblocked to completely recover all available space. 596.Pp 597Example, lets say your that you didn't set 598.Cm prune-min , 599and snapshot directory contains the following links: 600.Bd -literal -offset indent 601lrwxr-xr-x 1 root wheel 29 May 31 17:57 snap1 -> 602/usr/obj/@@0x10d2cd05b7270d16 603 604lrwxr-xr-x 1 root wheel 29 May 31 17:58 snap2 -> 605/usr/obj/@@0x10d2cd13f3fde98f 606 607lrwxr-xr-x 1 root wheel 29 May 31 17:59 snap3 -> 608/usr/obj/@@0x10d2cd222adee364 609.Ed 610.Pp 611If you were to run the 612.Cm prune 613command on this directory, then the 614.Nm HAMMER 615.Pa /usr/obj 616mount will be pruned to retain the above three snapshots. 617In addition, history for modifications made to the file system older than 618the oldest snapshot will be destroyed and history for potentially fine-grained 619modifications made to the file system more recently than the most recent 620snapshot will be retained. 621.Pp 622If you then delete the 623.Pa snap2 624softlink and rerun the 625.Cm prune 626command, 627history for modifications pertaining to that snapshot would be destroyed. 628.Pp 629In 630.Nm HAMMER 631filesystem versions 3+ this command also scans the snapshots stored 632in the filesystem meta-data and includes them in the prune. 633.\" ==== prune-everything ==== 634.It Cm prune-everything Ar filesystem 635This command will remove all historical records from the file system. 636This directive is not normally used on a production system. 637.Pp 638This command does not remove snapshot softlinks but will delete all 639snapshots recorded in filesystem meta-data (for filesystem version 3+). 640The user is responsible for deleting any softlinks. 641.\" ==== rebalance ==== 642.It Cm rebalance Ar filesystem Op Ar saturation_level 643This command will rebalance the B-tree, nodes with small number of 644elements will be combined and element counts will be smoothed out 645between nodes. 646.Pp 647The saturation level is a percentage between 50 and 100. 648The default is 75 percent. 649.\" ==== reblock ==== 650.It Cm reblock Ar filesystem Op Ar fill_percentage 651.It Cm reblock-btree Ar filesystem Op Ar fill_percentage 652.It Cm reblock-inodes Ar filesystem Op Ar fill_percentage 653.It Cm reblock-dirs Ar filesystem Op Ar fill_percentage 654.It Cm reblock-data Ar filesystem Op Ar fill_percentage 655Attempt to defragment and free space for reuse by reblocking a live 656.Nm HAMMER 657file system. 658Big-blocks cannot be reused by 659.Nm HAMMER 660until they are completely free. 661This command also has the effect of reordering all elements, effectively 662defragmenting the file system. 663.Pp 664The default fill percentage is 100% and will cause the file system to be 665completely defragmented. 666All specified element types will be reallocated and rewritten. 667If you wish to quickly free up space instead try specifying 668a smaller fill percentage, such as 90% or 80% (the 669.Sq % 670suffix is not needed). 671.Pp 672Since this command may rewrite the entire contents of the disk it is 673best to do it incrementally from a 674.Xr cron 8 675job along with the 676.Fl c Ar cyclefile 677and 678.Fl t Ar seconds 679options to limit the run time. 680The file system would thus be defragmented over long period of time. 681.Pp 682It is recommended that separate invocations be used for each data type. 683B-tree nodes, inodes, and directories are typically the most important 684elements needing defragmentation. 685Data can be defragmented over a longer period of time. 686.Pp 687Reblocking is a per PFS operation, so a 688.Nm HAMMER 689file system and each PFS in it have to be reblocked separately. 690.\" ==== pfs-status ==== 691.It Cm pfs-status Ar dirpath ... 692Retrieve the mirroring configuration parameters for the specified 693.Nm HAMMER 694file systems or pseudo-filesystems (PFS's). 695.\" ==== pfs-master ==== 696.It Cm pfs-master Ar dirpath Op Ar options 697Create a pseudo-filesystem (PFS) inside a 698.Nm HAMMER 699file system. 700Up to 65535 such file systems can be created. 701Each PFS uses an independent inode numbering space making it suitable 702for use as a replication source or target. 703.Pp 704The 705.Cm pfs-master 706directive creates a PFS that you can read, write, and use as a mirroring 707source. 708.Pp 709It is recommended to use a 710.Nm null 711mount to access a PFS, for more information see 712.Xr HAMMER 5 . 713.\" ==== pfs-slave ==== 714.It Cm pfs-slave Ar dirpath Op Ar options 715Create a pseudo-filesystem (PFS) inside a 716.Nm HAMMER 717file system. 718Up to 65535 such file systems can be created. 719Each PFS uses an independent inode numbering space making it suitable 720for use as a replication source or target. 721.Pp 722The 723.Cm pfs-slave 724directive creates a PFS that you can use as a mirroring target. 725You will not be able to access a slave PFS until you have completed the 726first mirroring operation with it as the target (its root directory will 727not exist until then). 728.Pp 729Access to the pfs-slave via the special softlink, as described in the 730.Sx PFS NOTES 731below, allows 732.Nm HAMMER 733to 734dynamically modify the snapshot transaction id by returning a dynamic result 735from 736.Xr readlink 2 737calls. 738.Pp 739A PFS can only be truly destroyed with the 740.Cm pfs-destroy 741directive. 742Removing the softlink will not destroy the underlying PFS. 743.Pp 744It is recommended to use a 745.Nm null 746mount to access a PFS, for more information see 747.Xr HAMMER 5 . 748.\" ==== pfs-update ==== 749.It Cm pfs-update Ar dirpath Op Ar options 750Update the configuration parameters for an existing 751.Nm HAMMER 752file system or pseudo-filesystem. 753Options that may be specified: 754.Bl -tag -width indent 755.It Cm sync-beg-tid= Ns Ar 0x16llx 756This is the automatic snapshot access starting transaction id for 757mirroring slaves. 758This parameter is normally updated automatically by the 759.Cm mirror-write 760directive. 761.Pp 762It is important to note that accessing a mirroring slave 763with a transaction id greater than the last fully synchronized transaction 764id can result in an unreliable snapshot since you will be accessing 765data that is still undergoing synchronization. 766.Pp 767Manually modifying this field is dangerous and can result in a broken mirror. 768.It Cm sync-end-tid= Ns Ar 0x16llx 769This is the current synchronization point for mirroring slaves. 770This parameter is normally updated automatically by the 771.Cm mirror-write 772directive. 773.Pp 774Manually modifying this field is dangerous and can result in a broken mirror. 775.It Cm shared-uuid= Ns Ar uuid 776Set the shared UUID for this file system. 777All mirrors must have the same shared UUID. 778For safety purposes the 779.Cm mirror-write 780directives will refuse to operate on a target with a different shared UUID. 781.Pp 782Changing the shared UUID on an existing, non-empty mirroring target, 783including an empty but not completely pruned target, 784can lead to corruption of the mirroring target. 785.It Cm unique-uuid= Ns Ar uuid 786Set the unique UUID for this file system. 787This UUID should not be used anywhere else, 788even on exact copies of the file system. 789.It Cm label= Ns Ar string 790Set a descriptive label for this file system. 791.It Cm snapshots= Ns Ar string 792Specify the snapshots directory which 793.Nm 794.Cm cleanup 795will use to manage this PFS. 796The snapshots directory does not need to be configured for 797PFS masters and will default to 798.Pa <pfs>/snapshots . 799.Pp 800PFS slaves are mirroring slaves so you cannot configure a snapshots 801directory on the slave itself to be managed by the slave's machine. 802In fact, the slave will likely have a 803.Pa snapshots 804sub-directory mirrored 805from the master, but that directory contains the configuration the master 806is using for its copy of the file system, not the configuration that we 807want to use for our slave. 808.Pp 809It is recommended that 810.Pa <fs>/var/slaves/<name> 811be configured for a PFS slave, where 812.Pa <fs> 813is the base 814.Nm HAMMER 815file system, and 816.Pa <name> 817is an appropriate label. 818You can control snapshot retention on your slave independent of the master. 819.It Cm snapshots-clear 820Zero out the 821.Cm snapshots 822directory path for this PFS. 823.It Cm prune-min= Ns Ar N Ns Cm d 824.It Cm prune-min= Ns Xo 825.Op Ar N Ns Cm d/ Ns 826.Ar hh Ns Op Cm \&: Ns Ar mm Ns Op Cm \&: Ns Ar ss 827.Xc 828Set the minimum fine-grained data retention period. 829.Nm HAMMER 830always retains fine-grained history up to the most recent snapshot. 831You can extend the retention period further by specifying a non-zero 832pruning minimum. 833Any snapshot softlinks within the retention period are ignored 834for the purposes of pruning (the fine grained history is retained). 835Number of days, hours, minutes and seconds are given as 836.Ar N , hh , mm 837and 838.Ar ss . 839.Pp 840Because the transaction id in the snapshot softlink cannot be used 841to calculate a timestamp, 842.Nm HAMMER 843uses the earlier of the 844.Fa st_ctime 845or 846.Fa st_mtime 847field of the softlink to 848determine which snapshots fall within the retention period. 849Users must be sure to retain one of these two fields when manipulating 850the softlink. 851.El 852.\" ==== pfs-upgrade ==== 853.It Cm pfs-upgrade Ar dirpath 854Upgrade a PFS from slave to master operation. 855The PFS will be rolled back to the current end synchronization transaction id 856(removing any partial synchronizations), and will then become writable. 857.Pp 858.Em WARNING! 859.Nm HAMMER 860currently supports only single masters and using 861this command can easily result in file system corruption 862if you don't know what you are doing. 863.Pp 864This directive will refuse to run if any programs have open descriptors 865in the PFS, including programs chdir'd into the PFS. 866.\" ==== pfs-downgrade ==== 867.It Cm pfs-downgrade Ar dirpath 868Downgrade a master PFS from master to slave operation 869The PFS becomes read-only and access will be locked to its 870.Cm sync-end-tid . 871.Pp 872This directive will refuse to run if any programs have open descriptors 873in the PFS, including programs chdir'd into the PFS. 874.\" ==== pfs-destroy ==== 875.It Cm pfs-destroy Ar dirpath 876This permanently destroys a PFS. 877.Pp 878This directive will refuse to run if any programs have open descriptors 879in the PFS, including programs chdir'd into the PFS. 880.\" ==== mirror-read ==== 881.It Cm mirror-read Ar filesystem Op Ar begin-tid 882Generate a mirroring stream to stdout. 883The stream ends when the transaction id space has been exhausted. 884.\" ==== mirror-read-stream ==== 885.It Cm mirror-read-stream Ar filesystem Op Ar begin-tid 886Generate a mirroring stream to stdout. 887Upon completion the stream is paused until new data is synced to the 888master, then resumed. 889Operation continues until the pipe is broken. 890.\" ==== mirror-write ==== 891.It Cm mirror-write Ar filesystem 892Take a mirroring stream on stdin. 893.Pp 894This command will fail if the 895.Cm shared-uuid 896configuration field for the two file systems do not match. 897.Pp 898If the target PFS does not exist this command will ask you whether 899you want to create a compatible PFS slave for the target or not. 900.\" ==== mirror-dump ==== 901.It Cm mirror-dump 902A 903.Cm mirror-read 904can be piped into a 905.Cm mirror-dump 906to dump an ASCII representation of the mirroring stream. 907.\" ==== mirror-copy ==== 908.\".It Cm mirror-copy Ar [[user@]host:]filesystem [[user@]host:]filesystem 909.It Cm mirror-copy Xo 910.Oo Oo Ar user Oc Ns Cm @ Ns Ar host Ns Cm \&: Oc Ns Ar filesystem 911.Oo Oo Ar user Oc Ns Cm @ Ns Ar host Ns Cm \&: Oc Ns Ar filesystem 912.Xc 913This is a shortcut which pipes a 914.Cm mirror-read 915command to a 916.Cm mirror-write 917command. 918If a remote host specification is made the program forks a 919.Xr ssh 1 920and execs the 921.Cm mirror-read 922and/or 923.Cm mirror-write 924on the appropriate host. 925The source may be a master or slave PFS, and the target must be a slave PFS. 926.Pp 927This command also established full duplex communication and turns on 928the two-way protocol feature which automatically negotiates transaction id 929ranges without having to use a cyclefile. 930If the operation completes successfully the target PFS's 931.Cm sync-end-tid 932will be updated. 933Note that you must re-chdir into the target PFS to see the updated information. 934If you do not you will still be in the previous snapshot. 935.Pp 936If the target PFS does not exist this command will ask you whether 937you want to create a compatible PFS slave for the target or not. 938.\" ==== mirror-stream ==== 939.\".It Cm mirror-stream Ar [[user@]host:]filesystem [[user@]host:]filesystem 940.It Cm mirror-stream Xo 941.Oo Oo Ar user Oc Ns Cm @ Ns Ar host Ns Cm \&: Oc Ns Ar filesystem 942.Oo Oo Ar user Oc Ns Cm @ Ns Ar host Ns Cm \&: Oc Ns Ar filesystem 943.Xc 944This command works similarly to 945.Cm mirror-copy 946but does not exit after the initial mirroring completes. 947The mirroring operation will resume as changes continue to be made to the 948master. 949The command is commonly used with 950.Fl i Ar delay 951and 952.Fl b Ar bandwidth 953options to keep the mirroring target in sync with the source on a continuing 954basis. 955.Pp 956If the pipe is broken the command will automatically retry after sleeping 957for a short while. 958The time slept will be 15 seconds plus the time given in the 959.Fl i 960option. 961.Pp 962This command also detects the initial-mirroring case and spends some 963time scanning the B-Tree to find good break points, allowing the initial 964bulk mirroring operation to be broken down into about 20 separate pieces. 965This means that the user can kill and restart the operation and it will 966not have to start from scratch once it has gotten past the first chunk. 967The 968.Fl B 969option may be used to disable this feature and perform an initial bulk 970transfer instead. 971.\" ==== version ==== 972.It Cm version Ar filesystem 973This command returns the 974.Nm HAMMER 975file system version for the specified 976.Ar filesystem 977as well as the range of versions supported in the kernel. 978The 979.Fl q 980option may be used to remove the summary at the end. 981.\" ==== version-upgrade ==== 982.It Cm version-upgrade Ar filesystem Ar version Op Cm force 983This command upgrades the 984.Nm HAMMER 985.Ar filesystem 986to the specified 987.Ar version . 988Once upgraded a file system may not be downgraded. 989If you wish to upgrade a file system to a version greater or equal to the 990work-in-progress version number you must specify the 991.Cm force 992directive. 993Use of WIP versions should be relegated to testing and may require wiping 994the filesystem as development progresses, even though the WIP version might 995not change. 996.Pp 997.Em NOTE! 998This command operates on the entire 999.Nm HAMMER 1000file system and is not a per PFS operation. 1001All PFS's will be affected. 1002.Bl -tag -width indent 1003.It 1 1004.Dx 2.0 1005default version, first 1006.Nm HAMMER 1007release. 1008.It 2 1009.Dx 2.3 1010default version, new directory entry layout. 1011This version is using a new directory hash key. 1012.El 1013.El 1014.\".Sh EXAMPLES 1015.Sh PSEUDO-FILESYSTEM (PFS) NOTES 1016The root of a PFS is not hooked into the primary 1017.Nm HAMMER 1018file system as a directory. 1019Instead, 1020.Nm HAMMER 1021creates a special softlink called 1022.Ql @@PFS%05d 1023(exactly 10 characters long) in the primary 1024.Nm HAMMER 1025file system. 1026.Nm HAMMER 1027then modifies the contents of the softlink as read by 1028.Xr readlink 2 , 1029and thus what you see with an 1030.Xr ls 1 1031command or if you were to 1032.Xr cd 1 1033into the link. 1034If the PFS is a master the link reflects the current state of the PFS. 1035If the PFS is a slave the link reflects the last completed snapshot, and the 1036contents of the link will change when the next snapshot is completed, and 1037so forth. 1038.Pp 1039The 1040.Nm 1041utility employs numerous safeties to reduce user foot-shooting. 1042The 1043.Cm mirror-copy 1044directive requires that the target be configured as a slave and that the 1045.Cm shared-uuid 1046field of the mirroring source and target match. 1047.Sh UPGRADE INSTRUCTIONS HAMMER V1 TO V2 1048This upgrade changes the way directory entries are stored. It 1049is possible to upgrade a V1 filesystem to V2 in place, but 1050directories created prior to the upgrade will continue to use 1051the old layout. 1052.Pp 1053Note that the slave mirroring code in the target kernel had bugs in 1054V1 which can create an incompatible root directory on the slave. 1055Do not mix a HAMMER master created after the upgrade with a HAMMER 1056slave created prior to the upgrade. 1057.Pp 1058Any directories created after upgrading will use a new layout. 1059.Sh UPGRADE INSTRUCTIONS HAMMER V2 TO V3 1060This upgrade adds meta-data elements to the B-Tree. It is 1061possible to upgrade a V2 filesystem to V3 in place. After 1062issuing the upgrade be sure to run a 'hammer cleanup' to 1063perform post-upgrade tasks. 1064.Pp 1065After making this upgrade running a hammer cleanup will move the 1066.Pa <fs>/snapshots 1067directory for each PFS mount into 1068.Pa /var/hammer/<path-from-root> . 1069A HAMMER root mount will migrated 1070.Pa /snapshots 1071into 1072.Pa /var/hammer/root . 1073Migration occurs only once and only if you have not specified 1074a snapshots directory in the PFS configuration. If you have 1075specified a snapshots directory in the PFS configuration no 1076automatic migration will occur. 1077.Pp 1078For slaves, if you desire, you can migrate your snapshots 1079config to the new location manually and then clear the 1080snapshot directory configuration in the slave PFS. 1081The new snapshots hierarchy is designed to work with 1082both master and slave PFSs equally well. 1083.Pp 1084In addition, the old config file will be moved to meta-data, 1085editable via the new hammer 1086.Cm viconfig 1087directive. The old config file will be deleted. 1088Migration occurs only once. 1089.Pp 1090The V3 filesystem has new 1091.Cm snap* 1092directives for creating snapshots. 1093All snapshot directives, including the original, will create 1094meta-data entries for the snapshots and the pruning code will 1095automatically incorporate these entries into its list and 1096expire them the same way it expires softlinks. 1097If you accidently blow away your snapshot softlinks you can use 1098the 1099.Cm snapls 1100directive to get a definitive list from the meta-data and 1101regenerate them from that list. 1102.Pp 1103WARNING! If you are using hammer to backup filesystems your scripts 1104may be using the 1105.Cm synctid 1106directive to generate transaction ids. This directive does not create 1107a snapshot. You will have to modify your scripts to use the 1108.Cm snapq 1109directive to generate the linkbuf for the softlink you create, or 1110use one of the other 1111.Cm snap* 1112directives. 1113The older 1114.Cm snapshot 1115directive will continue to work as expected and in V3 it will also 1116record the snapshot transaction id in meta-data. You may also want 1117to make use of the new 'note' tag for the meta-data. 1118.Pp 1119WARNING! If you used to remove snapshot softlinks with 1120.Nm rm 1121you should probably start using the 1122.Cm snaprm 1123directive instead to also remove the related meta-data. 1124The pruning code scans the meta-data so just removing the 1125softlink is not sufficient. 1126.Sh FILES 1127.Bl -tag -width ".It Pa <fs>/var/slaves/<name>" -compact 1128.It Pa <pfs>/snapshots 1129default per PFS snapshots directory 1130.It Pa <snapshots>/config 1131per PFS 1132.Nm 1133.Cm cleanup 1134configuration file 1135.It Pa <fs>/var/slaves/<name> 1136recommended slave PFS snapshots directory 1137.El 1138.Sh EXIT STATUS 1139.Ex -std 1140.Sh SEE ALSO 1141.Xr ssh 1 , 1142.Xr undo 1 , 1143.Xr HAMMER 5 , 1144.Xr periodic.conf 5 , 1145.Xr mount_hammer 8 , 1146.Xr mount_null 8 , 1147.Xr newfs_hammer 8 1148.Sh HISTORY 1149The 1150.Nm 1151utility first appeared in 1152.Dx 1.11 . 1153.Sh AUTHORS 1154.An Matthew Dillon Aq dillon@backplane.com 1155