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 October 22, 2008 36.Dt HAMMER 8 37.Os 38.Sh NAME 39.Nm hammer 40.Nd HAMMER file system utility 41.Sh SYNOPSIS 42.Nm 43.Op Fl h2qrvB 44.Op Fl b Ar bandwidth 45.Op Fl c Ar cyclefile 46.Op Fl f Ar blkdev[:blkdev]* 47.\" .Op Fl s Ar linkpath 48.Op Fl i Ar delay 49.Op Fl t Ar seconds 50.Op Fl C Ar cachesize[:readahead] 51.Ar command 52.Op Ar argument ... 53.Sh DESCRIPTION 54This manual page documents the 55.Nm 56utility which provides miscellaneous functions related to managing a 57.Nm HAMMER 58file system. 59For a general introduction to the 60.Nm HAMMER 61file system, its features, and 62examples on how to set up and maintain one, see 63.Xr HAMMER 5 . 64.Pp 65The options are as follows: 66.Bl -tag -width indent 67.It Fl h 68Get help. 69.It Fl 2 70Tell the mirror commands to use a 2-way protocol, which allows 71automatic negotiation of transaction id ranges. 72This option is automatically enabled by the 73.Ar mirror-copy 74command. 75.It Fl b Ar bandwidth 76Specify a bandwidth limit in bytes per second for mirroring streams. 77This option is typically used to prevent batch mirroring operations from 78loading down the machine. 79The bandwidth may be suffixed with 80.Sq k , 81.Sq m , 82or 83.Sq g 84to specify values in kilobytes, megabytes, and gigabytes per second. 85If no suffix is specified, bytes per second is assumed. 86.It Fl c Ar cyclefile 87When pruning and reblocking you can instruction 88.Nm 89to start at the object id stored in the specified file. 90If the file does not exist 91.Nm 92will start at the beginning. 93If 94.Nm 95is told to run for a 96specific period of time and is unable to complete the operation it will 97write out the current object id so the next run can pick up where it left off. 98If 99.Nm 100runs to completion it will delete 101.Ar cyclefile . 102.It Fl f Ar blkdev[:blkdev]* 103Specify the volumes making up a 104.Nm HAMMER 105file system. 106.It Fl i Ar delay 107When maintaining a streaming mirroring this option specifies the 108minimum delay after a batch ends before the next batch is allowed 109to start. 110The default is five seconds. 111.It Fl q 112Decrease verboseness. 113May be specified multiple times. 114.It Fl r 115Specify recursion for those commands which support it. 116.It Fl t Ar seconds 117When pruning and reblocking you can tell the utility to stop after a 118certain period of time. 119This option is used along with the 120.Fl c Ar cyclefile 121option to prune or reblock a portion of the file system incrementally. 122.It Fl v 123Increase verboseness. 124May be specified multiple times. 125.It Fl y 126Force "yes" for any interactive question. 127.It Fl B 128Bulk Transfer. 129.Ar Mirror-stream 130will not attempt to break-up large initial bulk transfers into smaller 131pieces. This can save time but if the link is lost in the middle of the 132initial bulk transfer you will have to start over from scratch. 133.It Fl C Ar cachesize[:readahead] 134Set the memory cache size for any raw I/O. The default is 16m. 135A suffix of 'k' for kilobytes and 'm' for megabytes is allowed, 136else the cache size is specified in bytes. 137.Pp 138The read-behind/read-ahead defaults to 4 hammer blocks. 139.Pp 140This option is typically only used with diagnostic commands 141as kernel-supported commands will use the kernel's buffer cache. 142.El 143.Pp 144The commands are as follows: 145.Bl -tag -width indent 146.\" ==== synctid ==== 147.It Ar synctid Ar filesystem Op quick 148Generates a guaranteed, formal 64 bit transaction id representing the 149current state of the specified 150.Nm HAMMER 151file system. 152The file system will be synced to the media. 153.Pp 154If the 155.Ar quick 156keyword is specified the file system will be soft-synced, meaning that a 157crash might still undo the state of the file system as of the transaction 158id returned but any new modifications will occur after the returned 159transaction id as expected. 160.\" ==== bstats ==== 161.It Ar bstats Op interval 162Output 163.Nm HAMMER 164B-tree statistics until interrupted. 165Pause 166.Ar interval 167seconds between each display. 168The default interval is one second. 169.\" ==== iostats ==== 170.It Ar iostats Op interval 171Output 172.Nm HAMMER 173I/O statistics until interrupted. 174Pause 175.Ar interval 176seconds between each display. 177The default interval is one second. 178.\" ==== history ==== 179.It Ar history Ar path ... 180Show the modification history for 181.Nm HAMMER 182file's inode and data. 183.\" ==== blockmap ==== 184.It Ar blockmap 185Dump the blockmap for the filesystem. The HAMMER blockmap is two-layer 186blockmap representing the maximum possible filesystem size of 1 Exabyte. 187Needless to say the second layer is only present for blocks which exist. 188HAMMER's blockmap represents 8-Megabyte blocks. Each block has an append 189point, a free byte count, and a typed zone id which allows content to be 190reverse engineered to some degree. 191.Pp 192In HAMMER allocations essentially appended to a selected big-block using 193the append offset and deducted from the free byte count. When space is 194freed the free byte count is adjusted but HAMMER does not track holes in 195big-blocks for reallocation. A big-block must be completely freed, either 196through normal filesystem operations or through reblocking, before 197it can be reused. 198.Pp 199Data blocks can be shared by deducting the space used from the free byte 200count for each shared references, though HAMMER does not yet make use of 201this feature. This means the free byte count can legally go negative. 202.Pp 203This command needs the 204.Fl f 205flag. 206.\" ==== show ==== 207.It Ar show Op Ar lo:objid 208Dump the B-tree. By default this command will validate all B-Tree 209linkages and CRCs, including data CRCs, and will report the most verbose 210information it can dig up. 211Any errors will show up with a 'B' in column 1 along with various 212other error flags. 213.Pp 214If you specify a localization and object id field the dump will 215search for the key printing nodes as it recurses down, and then 216will iterate forwards. 217.Pp 218If you use 219.Fl q 220the command will report less information about the inode contents. 221.Pp 222If you use 223.Fl qq 224the command will not report the content of the inode or other typed 225data at all. 226.Pp 227If you use 228.Fl qqq 229the command will not report volume header information, big-block fill 230ratios, mirror TIDs, or report or check data CRCs. B-Tree CRCs and 231linkages are still checked. 232.Pp 233This command needs the 234.Fl f 235flag. 236.\" .It Ar blockmap 237.\" Dump the B-tree, record, large-data, and small-data blockmaps, showing 238.\" physical block assignments and free space percentages. 239.\" ==== namekey1 ==== 240.It Ar namekey1 Ar filename 241Generate a 242.Nm HAMMER 24364 bit directory hash for the specified file name, using 244the original directory hash algorithm in version 1 of the filesystem. 245The low 32 bits are used as an iterator for hash collisions and will be 246output as 0. 247.\" ==== namekey2 ==== 248.It Ar namekey2 Ar filename 249Generate a 250.Nm HAMMER 25164 bit directory hash for the specified file name, using 252the new directory hash algorithm in version 2 of the filesystem. 253The low 32 bits are still used as an iterator but will start out containing 254part of the hash key. 255.\" ==== namekey32 ==== 256.It Ar namekey32 Ar filename 257Generate the top 32 bits of a 258.Nm HAMMER 25964 bit directory hash for the specified file name. 260.\" ==== info ==== 261.It Ar info 262Shows extended information about all the mounted HAMMER filesystems. 263At the moment volume identification, big blocks information and space details are shown. 264.\" ==== cleanup ==== 265.It Ar cleanup Op Ar filesystem ... 266This is a meta-command which executes snapshot, pruning, and reblocking 267commands on the specified 268.Nm HAMMER 269file system. 270If no 271.Ar filesystem 272is specified this command will clean-up all 273.Nm HAMMER 274file systems in use, including PFS's. 275To do this it will scan all 276.Nm HAMMER 277and 278.Nm null 279mounts, extract PFS id's, and clean-up each PFS found. 280.Pp 281This command will by default access a 282.Pa snapshots 283subdirectory and a 284.Pa snapshots/config 285file for each 286.Ar filesystem , 287creating them if necessary. 288The format of the configuration file is: 289.Bd -literal -offset indent 290snapshots <period> <retention-time> [any] 291prune <period> <max-runtime> 292.\"rebalance <period> <max-runtime> 293reblock <period> <1/3 max-runtime> 294recopy <period> <1/3 max-runtime> 295 296Defaults are: 297snapshots 1d 60d # 0d 60d for PFS /tmp, /var/tmp, /usr/obj 298prune 1d 5m 299.\"rebalance 1d 5m 300reblock 1d 5m 301recopy 30d 10m 302.Ed 303.Pp 304Time is given with a suffix of 305.Cm d , 306.Cm h , 307.Cm m 308or 309.Cm s 310meaning day, hour, minute and second. 311.Pp 312If the snapshots directive has a period of 0 and a retention time of 0 313then snapshot generation is disabled, removal of old snapshots are 314disabled, and prunes will use 315.Ar prune-everything . 316If the snapshots directive has a period of 0 but a non-zero retention time 317then this command will not create any new snapshots but will remove old 318snapshots it finds based on the retention time. 319.Pp 320By default only snapshots in the form: snap-yyyymmdd[-hhmm] are processed. 321If the 322.Ar any 323directive is specified as a third argument on the snapshots config line 324then any softlink of the form *[- or .]yyyymmdd[-hhmm] will be processed. 325.Pp 326A prune max-runtime of 0 means unlimited. 327.Pp 328If period hasn't passed since the previous 329.Ar cleanup 330run nothing is done. 331For example a day has passed when midnight is passed (localtime). 332By default, 333.Dx 334is set up to run 335.Nm Ar cleanup 336nightly via 337.Xr periodic 8 . 338.Pp 339The default configuration file will create a daily snapshot, do a daily 340pruning and reblocking run and a monthly recopy run. 341Reblocking is defragmentation with a level of 95%, 342and recopy is full defragmentation. 343.Pp 344By default prune and reblock operations are limited to 5 minutes per function, 345and recopy operations are limited to 10 minutes per function. 346Reblocking and recopy runs are each broken down into three separate functions 347(btree, inodes and data) 348and are thus by default limited to 15 and 30 minutes respectively. 349Also note that this directive will by default disable snapshots on 350the following PFS's: 351.Pa /tmp , 352.Pa /var/tmp 353and 354.Pa /usr/obj . 355.Pp 356The defaults may be adjusted by modifying the 357.Pa config 358file. 359The pruning and reblocking commands automatically maintain a cyclefile 360for incremental operation. 361If you interrupt (^C) the program the cyclefile will be updated, but a sub-command 362may continue to run in the background for a few seconds until the 363.Nm HAMMER 364ioctl detects the interrupt. 365The 366.Ar snapshots 367PFS option can be set to use another location for the snapshots directory. 368.Pp 369Work on this command is still in progress. 370Expected additions: An ability to remove snapshots dynamically as the 371file system becomes full. 372.\" ==== expand ==== 373.It Ar expand Ar filesystem Ar device 374This command will format 375.Ar device 376and add all of its space to 377.Ar filesystem . 378.Pp 379NOTE! All existing data contained on 380.Ar device 381will be destroyed by this operation! If 382.Ar device 383contains a valid 384.Nm HAMMER 385filesystem, formatting will be denied. You can overcome this sanity check 386by using 387.Xr dd 1 388to erase the beginning sectors of the device. 389Also remember that you have to specify 390.Ar device , 391together with any other device that make the filesystem, colon-separated to 392.Xr mount_hammer 8 . 393.\" ==== snapshot ==== 394.It Ar snapshot Oo Ar filesystem Oc Ar snapshot-dir 395Takes a snapshot of the file system either explicitly given by 396.Ar filesystem 397or implicitly derived from the 398.Ar snapshot-dir 399argument and creates a symlink in the directory provided by 400.Ar snapshot-dir 401pointing to the snapshot. 402If 403.Ar snapshot-dir 404is not a directory, it is assumed to be a format string passed to 405.Xr strftime 3 406with the current time as parameter. 407If 408.Ar snapshot-dir 409refers to an existing directory, a default format string of "snap-%Y%d%m-%H%M" 410is assumed and used as name for the newly created symlink. 411.Pp 412Snapshot is a per PFS operation, so a 413.Nm HAMMER 414file system and each PFS in it have to be snapshot separately. 415.Pp 416Example, assuming that 417.Pa /mysnapshots 418is on file system 419.Pa / 420and that 421.Pa /obj 422is a file system on its own, the following invocations: 423.Bd -literal -offset indent 424hammer snapshot /mysnapshots 425 426hammer snapshot /mysnapshots/%Y-%m-%d 427 428hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d 429.Ed 430.Pp 431would create symlinks similar to: 432.Bd -literal -offset indent 433/mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16 434 435/mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16 436 437/mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16 438.Ed 439.\" ==== prune ==== 440.It Ar prune Ar softlink-dir 441Prune the file system based on previously created snapshot softlinks. 442Pruning is the act of deleting file system history. 443The 444.Ar prune 445command 446will delete file system history such that 447the file system state is retained for the given snapshots, 448and all history after the latest snapshot, 449but all other history is deleted. 450.Pp 451The target directory is expected to contain softlinks pointing to 452snapshots of the file systems you wish to retain. 453The directory is scanned non-recursively and the mount points and 454transaction ids stored in the softlinks are extracted and sorted. 455The file system is then explicitly pruned according to what is found. 456Cleaning out portions of the file system is as simple as removing a softlink 457and then running the 458.Ar prune 459command. 460.Pp 461As a safety measure pruning only occurs if one or more softlinks are found 462containing the @@ snapshot id extension. 463Currently the scanned softlink directory must contain softlinks pointing 464to a single 465.Nm HAMMER 466mount. 467The softlinks may specify absolute or relative paths. 468Softlinks must use 20-character (@@0x%016llx) transaction ids, 469as might be returned from 470.Dq Nm Ar synctid filesystem . 471.Pp 472Pruning is a per PFS operation, so a 473.Nm HAMMER 474file system and each PFS in it have to be pruned separately. 475.Pp 476Note that pruning a file system may not immediately free-up space, 477though typically some space will be freed if a large number of records are 478pruned out. 479The file system must be reblocked to completely recover all available space. 480.Pp 481Example, lets say your snapshot directory contains the following links: 482.Bd -literal -offset indent 483lrwxr-xr-x 1 root wheel 29 May 31 17:57 snap1 -> 484/usr/obj/@@0x10d2cd05b7270d16 485 486lrwxr-xr-x 1 root wheel 29 May 31 17:58 snap2 -> 487/usr/obj/@@0x10d2cd13f3fde98f 488 489lrwxr-xr-x 1 root wheel 29 May 31 17:59 snap3 -> 490/usr/obj/@@0x10d2cd222adee364 491.Ed 492.Pp 493If you were to run the 494.Ar prune 495command on this directory, then the 496.Nm HAMMER 497.Pa /usr/obj 498mount will be pruned to retain the above three snapshots. 499In addition, history for modifications made to the file system older than 500the oldest snapshot will be destroyed and history for potentially fine-grained 501modifications made to the file system more recently than the most recent 502snapshot will be retained. 503.Pp 504If you then delete the 505.Pa snap2 506softlink and rerun the 507.Ar prune 508command, 509history for modifications pertaining to that snapshot would be destroyed. 510.\" ==== prune-everything ==== 511.It Ar prune-everything Ar filesystem 512This command will remove all historical records from the file system. 513This directive is not normally used on a production system. 514.\" ==== rebalance ==== 515.It Ar rebalance Ar filesystem Op Ar saturation_level 516This command will rebalance the B-Tree, nodes with small numbers of 517elements will be combined and element counts will be smoothed out 518between nodes. 519.Pp 520The saturation level is a percentage between 50 and 100. The default 521is 75 percent. 522.\" ==== reblock ==== 523.It Ar reblock Ar filesystem Op Ar fill_percentage 524.It Ar reblock-btree Ar filesystem Op Ar fill_percentage 525.It Ar reblock-inodes Ar filesystem Op Ar fill_percentage 526.It Ar reblock-dirs Ar filesystem Op Ar fill_percentage 527.It Ar reblock-data Ar filesystem Op Ar fill_percentage 528Attempt to defragment and free space for reuse by reblocking a live 529.Nm HAMMER 530file system. 531Big blocks cannot be reused by 532.Nm HAMMER 533until they are completely free. 534This command also has the effect of reordering all elements, effectively 535defragmenting the file system. 536.Pp 537The default fill percentage is 100% and will cause the file system to be 538completely defragmented. 539All specified element types will be reallocated and rewritten. 540If you wish to quickly free up space instead try specifying 541a smaller fill percentage, such as 90% or 80% (the 542.Sq % 543suffix is not needed). 544.Pp 545Since this command may rewrite the entire contents of the disk it is 546best to do it incrementally from a 547.Xr cron 8 548job along with the 549.Fl c Ar cyclefile 550and 551.Fl t Ar seconds 552options to limit the run time. 553The file system would thus be defragmented over long period of time. 554.Pp 555It is recommended that separate invocations be used for each data type. 556B-tree nodes, inodes, and directories are typically the most important 557elements needing defragmentation. 558Data can be defragmented over a longer period of time. 559.Pp 560Reblocking is a per PFS operation, so a 561.Nm HAMMER 562file system and each PFS in it have to be reblocked separately. 563.\" ==== pfs-status ==== 564.It Ar pfs-status Ar dirpath ... 565Retrieve the mirroring configuration parameters for the specified 566.Nm HAMMER 567file systems or pseudo-filesystems (PFS's). 568.\" ==== pfs-master ==== 569.It Ar pfs-master Ar dirpath Op options 570Create a pseudo-filesystem (PFS) inside a 571.Nm HAMMER 572file system. 573Up to 65535 such file systems can be created. 574Each PFS uses an independent inode numbering space making it suitable 575for use as a replication source or target. 576.Pp 577The 578.Ar pfs-master 579directive creates a PFS that you can read, write, and use as a mirroring 580source. 581.Pp 582It is recommended to use a 583.Nm null 584mount to access a PFS, for more information see 585.Xr HAMMER 5 . 586.\" ==== pfs-slave ==== 587.It Ar pfs-slave Ar dirpath Op options 588Create a pseudo-filesystem (PFS) inside a 589.Nm HAMMER 590file system. 591Up to 65535 such file systems can be created. 592Each PFS uses an independent inode numbering space making it suitable 593for use as a replication source or target. 594.Pp 595The 596.Ar pfs-slave 597directive creates a PFS that you can use as a mirroring target. 598You will not be able to access a slave PFS until you have completed the 599first mirroring operation with it as the target (its root directory will 600not exist until then). 601.Pp 602Access to the pfs-slave via the special softlink, 603as described in the 604.Sx PFS NOTES 605below, allows 606.Nm HAMMER 607to 608dynamically modify the snapshot transaction id by returning a dynamic result 609from 610.Xr readlink 2 611calls. 612.Pp 613A PFS can only be truly destroyed with the 614.Ar pfs-destroy 615directive. 616Removing the softlink will not destroy the underlying PFS. 617.Pp 618It is recommended to use a 619.Nm null 620mount to access a PFS, for more information see 621.Xr HAMMER 5 . 622.\" ==== pfs-update ==== 623.It Ar pfs-update Ar dirpath Op options 624Update the configuration parameters for an existing 625.Nm HAMMER 626file system 627or pseudo-filesystem. 628Options that may be specified: 629.Bl -tag -width indent 630.It sync-beg-tid=0x16llx 631This is the automatic snapshot access starting transaction id for 632mirroring slaves. 633This parameter is normally updated automatically by the 634.Ar mirror-write 635directive. 636.Pp 637It is important to note that accessing a mirroring slave 638with a transaction id greater than the last fully synchronized transaction 639id can result in an unreliable snapshot since you will be accessing 640data that is still undergoing synchronization. 641.Pp 642Manually modifying this field is dangerous and can result in a broken 643mirror. 644.It sync-end-tid=0x16llx 645This is the current synchronization point for mirroring slaves. 646This parameter is normally updated automatically by the 647.Ar mirror-write 648directive. 649.Pp 650Manually modifying this field is dangerous and can result in a broken mirror. 651.It shared-uuid=<uuid> 652Set the shared UUID for this file system. 653All mirrors must have the same shared UUID. 654For safety purposes the 655.Ar mirror-write 656directives will refuse to operate on a target with a different shared UUID. 657.Pp 658Changing the shared UUID on an existing, non-empty mirroring target, 659including an empty but not completely pruned target, 660can lead to corruption of the mirroring target. 661.It unique-uuid=<uuid> 662Set the unique UUID for this file system. 663This UUID should not be used anywhere else, 664even on exact copies of the file system. 665.It label=<string> 666Set a descriptive label for this file system. 667.It snapshots=<string> 668Specify the snapshots directory which 669.Nm 670.Ar cleanup 671will use to manage this PFS. 672The snapshots directory does not need to be configured for 673PFS masters and will default to 674.Pa <pfs>/snapshots . 675.Pp 676PFS slaves are mirroring slaves so you cannot configure a snapshots 677directory on the slave itself to be managed by the slave's machine. 678In fact, the slave will likely have a 679.Pa snapshots 680sub-directory mirrored 681from the master, but that directory contains the configuration the master 682is using for its copy of the file system, not the configuration that we 683want to use for our slave. 684.Pp 685It is recommended that 686.Pa <fs>/var/slaves/<name> 687be configured for a PFS slave, where 688.Pa <fs> 689is the base 690.Nm HAMMER 691file system, and 692.Pa <name> 693is an appropriate label. 694You can control snapshot retention on your slave independent of the master. 695.It snapshots-clear 696Zero out the snapshots directory path for this PFS. 697.It prune-min=Nd 698.It prune-min=Nd/hh[:mm[:ss]] 699.It prune-min=hh[:mm[:ss]] 700Set the minimum fine-grained data retention period. 701.Nm HAMMER 702always retains fine-grained history up to the most recent snapshot. 703You can extend the retention period further by specifying a non-zero 704pruning minimum. Any snapshot softlinks within the retention period 705are ignored for the purposes of pruning (the fine grained history 706is retained). 707.Pp 708Because the transaction id in the snapshot softlink cannot be used 709to calculate a timestamp, 710.Nm HAMMER 711uses the earlier of the st_ctime or st_mtime field of the softlink to 712determine which snapshots fall within the retention period. 713Users must be sure to retain one of these two fields when manipulating 714the softlink. 715.El 716.\" ==== pfs-upgrade ==== 717.It Ar pfs-upgrade Ar dirpath 718Upgrade a PFS from slave to master operation. 719The PFS will be rolled back to the current end synchronization tid 720(removing any partial synchronizations), and will then become writable. 721.Pp 722.Em WARNING! 723.Nm HAMMER 724currently supports only single masters and using 725this command can easily result in file system corruption 726if you don't know what you are doing. 727.Pp 728This directive will refuse to run if any programs have open descriptors 729in the PFS, including programs chdir'd into the PFS. 730.\" ==== pfs-downgrade ==== 731.It Ar pfs-downgrade Ar dirpath 732Downgrade a master PFS from master to slave operation 733The PFS becomes read-only and access will be locked to its 734.Ar sync-end-tid . 735.Pp 736This directive will refuse to run if any programs have open descriptors 737in the PFS, including programs chdir'd into the PFS. 738.\" ==== pfs-destroy ==== 739.It Ar pfs-destroy Ar dirpath 740This permanently destroys a PFS. 741.Pp 742This directive will refuse to run if any programs have open descriptors 743in the PFS, including programs chdir'd into the PFS. 744.\" ==== mirror-read ==== 745.It Ar mirror-read Ar filesystem Op Ar <begin-tid> 746Generate a mirroring stream to stdout. 747The stream ends when the transaction id space has been exhausted. 748.\" ==== mirror-read-stream ==== 749.It Ar mirror-read-stream Ar filesystem Op Ar <begin-tid> 750Generate a mirroring stream to stdout. 751Upon completion the stream is paused until new data is synced to the 752master, then resumed. 753Operation continues until the pipe is broken. 754.\" ==== mirror-write ==== 755.It Ar mirror-write Ar filesystem 756Take a mirroring stream on stdin. 757.Pp 758This command will fail if the 759.Ar shared-uuid 760configuration field for the two file systems do not match. 761.Pp 762If the target PFS does not exist this command will ask you whether 763you want to create a compatible PFS slave for the target or not. 764.\" ==== mirror-dump ==== 765.It Ar mirror-dump 766A 767.Ar mirror-read 768can be piped into a 769.Ar mirror-dump 770to dump an ASCII representation of the mirroring stream. 771.\" ==== mirror-copy ==== 772.It Ar mirror-copy Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem 773This is a shortcut which pipes a 774.Ar mirror-read 775command to a 776.Ar mirror-write 777command. 778If a remote host specification is made the program forks a 779.Xr ssh 1 780and execs the 781.Ar mirror-read 782and/or 783.Ar mirror-write 784on the appropriate host. 785The source may be a master or slave PFS, and the target must be a slave PFS. 786.Pp 787This command also established full duplex communication and turns on 788the two-way protocol feature which automatically negotiates transaction id 789ranges without having to use a cyclefile. 790If the operation completes successfully the target PFS's 791.Ar sync-end-tid 792will be updated. 793Note that you must re-chdir into the target PFS to see the updated information. 794If you do not you will still be in the previous snapshot. 795.Pp 796If the target PFS does not exist this command will ask you whether 797you want to create a compatible PFS slave for the target or not. 798.\" ==== mirror-stream ==== 799.It Ar mirror-stream Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem 800This command works similarly to 801.Ar mirror-copy 802but does not exit after the initial mirroring completes. 803The mirroring operation will resume as changes continue to be made to the 804master. 805The command is commonly used with 806.Fl i Ar delay 807and 808.Fl b Ar bandwidth 809options to keep the mirroring target in sync with the source on a continuing 810basis. 811.Pp 812If the pipe is broken the command will automatically retry after sleeping 813for a short while. The time slept will be 15 seconds plus the time given 814in the 815.Fl i 816option. 817.Pp 818This command also detects the initial-mirroring case and spends some 819time scanning the B-Tree to find good break points, allowing the initial 820bulk mirroring operation to be broken down into about 20 separate pieces. 821This means that the user can kill and restart the operation and it will 822not have to start from scratch once it has gotten past the first chunk. 823The 824.Fl B 825option may be used to disable this feature and perform an initial bulk 826transfer instead. 827.\" ==== version ==== 828.It Ar version Ar filesystem 829This command returns the 830.Nm HAMMER 831filesystem version for the specified 832filesystem as well as the range of versions supported in the kernel. 833The 834.Fl q 835option may be used to remove the summary at the end. 836.\" ==== version-upgrade ==== 837.It Ar version-upgrade Ar filesystem Ar version Op Ar force 838This command upgrades the 839.Nm HAMMER 840filesystem to the specified version. 841Once upgraded a filesystem may not be downgraded. 842If you wish to upgrade a filesystem to a version greater or equal to the 843work-in-progress version number you must specify the 844.Ar force 845directive. 846Use of WIP versions should be relegated to testing and may require wiping 847the filesystem as development progresses, even though the WIP version might 848not change. 849.Pp 850NOTE! This command operates on the entire 851.Nm HAMMER 852filesystem and is not a per-PFS operation. 853All PFS's will be affected. 854.Bl -tag -width indent 855.It 1 856.Dx 2.0 857default version, first 858.Nm HAMMER 859release. 860.It 2 861Work-in-progress version. 862This version is developing a new directory hash key. 863.El 864.El 865.\".Sh EXAMPLES 866.Sh PSEUDO FILESYSTEM (PFS) NOTES 867The root of a PFS is not hooked into the primary 868.Nm HAMMER 869file system as a directory. 870Instead, 871.Nm HAMMER 872creates a special softlink called "@@PFS%05d" (exactly 10 characters long) 873in the primary 874.Nm HAMMER 875file system. 876.Nm HAMMER 877then modifies the contents of the softlink as read by 878.Xr readlink 2 , 879and thus what you see with an 880.Xr ls 1 881command or if you were to 882.Xr cd 1 883into the link. 884If the PFS is a master the link reflects the current state of the PFS. 885If the PFS is a slave the link reflects the last completed snapshot, and the 886contents of the link will change when the next snapshot is completed, and 887so forth. 888.Pp 889PFS support is currently very new and experimental. 890The 891.Nm 892utility employs numerous safeties to reduce user foot-shooting. 893The 894.Ar mirror-copy 895directive requires that the target be configured as a slave and that the 896.Ar shared-uuid 897field of the mirroring source and target match. 898.Sh FILES 899.Bl -tag -width ".It Pa <fs>/var/slaves/<name>" -compact 900.It Pa snapshots 901default per PFS snapshots directory 902.It Pa <snapshots>/config 903.Nm 904.Ar cleanup 905configuration file 906.It Pa <fs>/var/slaves/<name> 907recommended slave PFS snapshots directory 908.El 909.Sh EXIT STATUS 910.Ex -std 911.Sh SEE ALSO 912.Xr undo 1 , 913.Xr HAMMER 5 , 914.Xr periodic.conf 5 , 915.Xr mount_hammer 8 , 916.Xr mount_null 8 , 917.Xr newfs_hammer 8 918.Sh HISTORY 919The 920.Nm 921utility first appeared in 922.Dx 1.11 . 923.Sh AUTHORS 924.An Matthew Dillon Aq dillon@backplane.com 925