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.46 2008/08/21 23:28:43 thomas Exp $ 34.Dd July 27, 2008 35.Dt HAMMER 8 36.Os 37.Sh NAME 38.Nm hammer 39.Nd HAMMER file system utility 40.Sh SYNOPSIS 41.Nm 42.Op Fl h2rv 43.Op Fl b Ar bandwidth 44.Op Fl c Ar cyclefile 45.Op Fl f Ar blkdev[:blkdev]* 46.\" .Op Fl s Ar linkpath 47.Op Fl i Ar delay 48.Op Fl t Ar seconds 49.Ar command 50.Op Ar argument ... 51.Sh DESCRIPTION 52This manual page documents the 53.Nm 54utility which provides miscellaneous functions related to managing a 55.Nm HAMMER 56file system. 57For a general introduction to the 58.Nm HAMMER 59file system, its features, and 60examples on how to set up and maintain one, see 61.Xr HAMMER 5 . 62.Pp 63The options are as follows: 64.Bl -tag -width indent 65.It Fl h 66Get help. 67.It Fl 2 68Tell the mirror commands to use a 2-way protocol, which allows 69automatic negotiation of transaction id ranges. This option is 70automatically enabled by the 71.Ar mirror-copy 72command. 73.It Fl r 74Specify recursion for those commands which support it. 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 85values in kilobytes, megabytes, and gigabytes per second. 86.It Fl c Ar cyclefile 87When pruning and reblocking you can instruction 88.Nm 89to start at the 90object id stored in the specified file. 91If the file does not exist 92.Nm 93will start at the beginning. 94If 95.Nm 96is told to run for a 97specific period of time and is unable to complete the operation it will 98write out the current object id so the next run can pick up where it left 99off. 100If 101.Nm 102runs to completion it will delete the cyclefile. 103.It Fl f Ar blkdev[:blkdev]* 104Specify the volumes making up a 105.Nm HAMMER 106file system. 107.\" .It Fl s Ar linkpath 108.\" When pruning a filesystem you can instruct 109.\" .Nm to create softlinks 110.\" to available snapshots. 111.It Fl i Ar delay 112When maintaining a streaming mirroring this option specifies the 113minimum delay after a batch ends before the next batch is allowed 114to start. 115The default is five seconds. 116.It Fl t Ar seconds 117When pruning and reblocking you can tell the utility to stop after a 118certain period of time. This option is used along with the cycle file 119option to prune or reblock a portion of the file system incrementally. 120.It Fl v 121Increase verboseness. May be specified multiple times. 122.El 123.Pp 124The commands are as follows: 125.Bl -tag -width indent 126.\" ==== synctid ==== 127.It Ar synctid Ar filesystem Op quick 128Generates a guaranteed, formal 64 bit transaction id representing the 129current state of the specified 130.Nm HAMMER 131file system. The file system will 132be synced to the media. 133.Pp 134If the 135.Ar quick 136keyword is specified the file system will be soft-synced, meaning that a 137crash might still undo the state of the file system as of the transaction 138id returned but any new modifications will occur after the returned 139transaction id as expected. 140.\" ==== bstats ==== 141.It Ar bstats Op interval 142Output 143.Nm HAMMER 144B-tree statistics until interrupted. 145Pause 146.Ar interval 147seconds between each display. 148The default interval is one second. 149.\" ==== iostats ==== 150.It Ar iostats Op interval 151Output 152.Nm HAMMER 153I/O statistics until interrupted. 154Pause 155.Ar interval 156seconds between each display. 157The default interval is one second. 158.\" ==== history ==== 159.It Ar history Ar path ... 160Show the modification history for 161.Nm HAMMER 162file's inode and data. 163.\" ==== show ==== 164.It Ar show 165Dump the B-tree. This command needs the 166.Fl f 167flag. 168.\" .It Ar blockmap 169.\" Dump the B-tree, record, large-data, and small-data blockmaps, showing 170.\" physical block assignments and free space percentages. 171.\" ==== namekey ==== 172.It Ar namekey Ar filename 173Generate a 174.Nm HAMMER 17564 bit directory hash for the specified file name. 176The low 32 bits are used as an iterator for hash collisions and will be 177output as 0. 178.\" ==== namekey32 ==== 179.It Ar namekey32 Ar filename 180Generate the top 32 bits of a 181.Nm HAMMER 18264 bit directory hash for the specified 183file name. 184.\" ==== prune ==== 185.It Ar prune Ar softlink-dir 186Prune the file system based on previously created snapshot softlinks. 187Pruning is the act of deleting file system history. 188The 189.Ar prune 190command 191will delete file system history such that 192the file system state is retained for the given snapshots, 193and all history after the latest snapshot, 194but all other history is deleted. 195.Pp 196The target directory is expected to contain softlinks pointing to 197snapshots of the file systems you wish to retain. The directory is scanned 198non-recursively and the mount points and transaction ids stored in the 199softlinks are extracted and sorted. 200The file system is then explicitly pruned according to what is found. 201Cleaning out portions of the file system is as simple as removing a softlink 202and then running the 203.Ar prune 204command. 205.Pp 206As a safety measure pruning only occurs if one or more softlinks are found 207containing the @@ snapshot id extension. 208Currently the scanned softlink directory must contain softlinks pointing 209to a single 210.Nm HAMMER 211mount. The softlinks may specify absolute or relative 212paths. Softlinks must use 20-character (@@0x%016llx) transaction ids, 213as might be returned from 214.Dq Nm Ar synctid filesystem . 215.Pp 216Pruning is a per-PFS operation, so a 217.Nm HAMMER 218file system and each PFS in it have to be pruned separately. 219.Pp 220Note that pruning a file system may not immediately free-up space, 221though typically some space will be freed if a large number of records are 222pruned out. The file system must be reblocked to completely recover all 223available space. 224.Pp 225Example, lets say your snapshot directory contains the following links: 226.Bd -literal 227lrwxr-xr-x 1 root wheel 29 May 31 17:57 snap1 -> 228/usr/obj/@@0x10d2cd05b7270d16 229 230lrwxr-xr-x 1 root wheel 29 May 31 17:58 snap2 -> 231/usr/obj/@@0x10d2cd13f3fde98f 232 233lrwxr-xr-x 1 root wheel 29 May 31 17:59 snap3 -> 234/usr/obj/@@0x10d2cd222adee364 235.Ed 236.Pp 237If you were to run the 238.Ar prune 239command on this directory, then the 240.Nm HAMMER 241.Pa /usr/obj 242mount will be pruned to retain the above three snapshots. 243In addition, history for modifications made to the file system older than the oldest 244snapshot will be destroyed and history for potentially fine-grained modifications made 245to the file system more recently than the most recent snapshot will be 246retained. 247.Pp 248If you then delete the snap2 softlink and rerun the 249.Ar prune 250command, 251history for modifications pertaining to that snapshot would be destroyed. 252.\" ==== prune-everything ==== 253.It Ar prune-everything Ar filesystem 254This command will remove all historical records from the file system. 255This directive is not normally used on a production system. 256.\" ==== snapshot ==== 257.It Ar snapshot Ar snapshot-dir 258.It Ar snapshot Ar filesystem snapshot-dir 259Takes a snapshot of the file system either explicitly given by 260.Ar filesystem 261or implicitly derived from the 262.Ar snapshot-dir 263argument and creates a symlink in the directory provided by 264.Ar snapshot-dir 265pointing to the snapshot. 266If 267.Ar snapshot-dir 268is not a directory, it is assumed to be a format string 269passed to 270.Xr strftime 3 271with the current time as parameter. 272If 273.Ar snapshot-dir 274refers to an existing directory, a default format string of "snap-%Y%d%m-%H%M" 275is assumed and used as name for the newly created symlink. 276.Pp 277Example, assuming that 278.Pa /mysnapshots 279is on file system 280.Pa / 281and that 282.Pa /obj 283is a file system on its own, the following invocations: 284.Bd -literal 285hammer snapshot /mysnapshots 286 287hammer snapshot /mysnapshots/%Y-%m-%d 288 289hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d 290.Ed 291.Pp 292would create symlinks similar to: 293.Bd -literal 294/mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16 295 296/mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16 297 298/mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16 299.Ed 300.\" ==== reblock ==== 301.It Ar reblock Ar filesystem Op Ar fill_percentage 302.It Ar reblock-btree Ar filesystem Op Ar fill_percentage 303.It Ar reblock-inodes Ar filesystem Op Ar fill_percentage 304.It Ar reblock-dirs Ar filesystem Op Ar fill_percentage 305.It Ar reblock-data Ar filesystem Op Ar fill_percentage 306Attempt to defragment and free space for reuse by reblocking a live 307.Nm HAMMER 308file system. 309Big blocks cannot be reused by 310.Nm HAMMER 311until they are completely free. 312This command also has the effect of reordering all elements, effectively 313defragmenting the file system. 314.Pp 315The default fill percentage is 100% and will cause the file system to be 316completely defragmented. All specified element types will be reallocated 317and rewritten. If you wish to quickly free up space instead try specifying 318a smaller fill percentage, such as 90% or 80% (the 319.Sq % 320suffix is not needed). 321.Pp 322Since this command may rewrite the entire contents of the disk it is 323best to do it incrementally from a 324.Xr cron 8 325job along with the 326.Fl c Ar cyclefile 327and 328.Fl t Ar seconds 329options to limit the run time. 330The file system would thus be defragmented over long period of time. 331.Pp 332It is recommended that separate invocations be used for each data type. 333B-tree nodes, inodes, and directories are typically the most important 334elements needing defragmentation. Data can be defragmented over a longer 335period of time. 336.Pp 337Reblocking is a per-PFS operation, so a 338.Nm HAMMER 339file system and each PFS in it have to be reblocked separately. 340.\" ==== pfs-status ==== 341.It Ar pfs-status Ar dirpath ... 342Retrieve the mirroring configuration parameters for the specified 343.Nm HAMMER 344file systems or pseudo-filesystems. 345.\" ==== pfs-master ==== 346.It Ar pfs-master Ar dirpath Op options 347Create a pseudo-filesystem (PFS) inside a 348.Nm HAMMER 349file system. 350Up to 65535 such file systems can be created. 351Each PFS uses an independent inode numbering space making it suitable 352for use as a replication source or target. 353.Pp 354The 355.Ar pfs-master 356directive creates a PFS that you can read, write, and use as a mirroring 357source. 358.\" ==== pfs-slave ==== 359.It Ar pfs-slave Ar dirpath Op options 360Create a pseudo-filesystem (PFS) inside a 361.Nm HAMMER 362file system. 363Up to 65535 such file systems can be created. 364Each PFS uses an independent inode numbering space making it suitable 365for use as a replication source or target. 366.Pp 367The 368.Ar pfs-slave 369directive creates a PFS that you can use as a mirroring target. 370You will not be able to access a slave PFS until you have completed the 371first mirroring operation with it as the target (its root directory will 372not exist until then). 373.Pp 374Access to the pfs-slave via the special softlink, 375as described in the PFS NOTES below, allows 376.Nm HAMMER 377to 378dynamically modify the snapshot transaction id by returning a dynamic result 379from 380.Xr readlink 2 381calls. 382.Pp 383A PFS can only be truly destroyed with the 384.Ar pfs-destroy 385directive. 386Removing the softlink will not destroy the underlying PFS. 387.\" ==== pfs-update ==== 388.It Ar pfs-update Ar dirpath Op options 389Update the configuration parameters for an existing 390.Nm HAMMER 391file system 392or pseudo-filesystem. Options that may be specified: 393.Bl -tag -width indent 394.It sync-beg-tid=0x16llx 395This is the automatic snapshot access starting transaction id for mirroring slaves. 396This parameter is normally updated automatically by the 397.Ar mirror-write 398directive. 399.Pp 400It is important to note that accessing a mirroring slave 401with a transaction id greater than the last fully synchronized transaction 402id can result in an unreliable snapshot since you will be accessing 403data that is still undergoing synchronization. 404.Pp 405Manually modifying this field is dangerous and can result in a broken 406mirror. 407.It sync-end-tid=0x16llx 408This is the current synchronization point for mirroring slaves. 409This parameter is normally updated automatically by the 410.Ar mirror-write 411directive. 412.Pp 413Manually modifying this field is dangerous and can result in a broken 414mirror. 415.It shared-uuid=<uuid> 416Set the shared UUID for this file system. All mirrors must have the same 417shared UUID. For safety purposes the 418.Ar mirror-write 419directives will refuse 420to operate on a target with a different shared UUID. 421.Pp 422Changing the shared UUID on an existing, non-empty mirroring target, 423including an empty but not completely pruned target, can lead 424to corruption of the mirroring target. 425.It unique-uuid=<uuid> 426Set the unique UUID for this file system. This UUID should not be used 427anywhere else, even on exact copies of the file system. 428.It label=<string> 429Set a descriptive label for this file system. 430.El 431.\" ==== pfs-upgrade ==== 432.It Ar pfs-upgrade Ar dirpath 433Upgrade a PFS from slave to master operation. The PFS will be rolled back 434to the current end synchronization tid (removing any partial synchronizations), 435and will then becomes writable. 436.Pp 437.Em WARNING! 438.Nm HAMMER 439currently supports only single masters and using 440this command can easily result in file system corruption if you don't 441know what you are doing. 442.Pp 443This directive will refuse to run if any programs have open descriptors 444in the PFS, including programs chdir'd into the PFS. 445.\" ==== pfs-downgrade ==== 446.It Ar pfs-downgrade Ar dirpath 447Downgrade a master PFS from master to slave operation. The PFS becomes 448read-only and access will be locked to its 449.Ar sync-end-tid . 450.Pp 451This directive will refuse to run if any programs have open descriptors 452in the PFS, including programs chdir'd into the PFS. 453.\" ==== pfs-destroy ==== 454.It Ar pfs-destroy Ar dirpath 455This permanently destroys a PFS. 456.Pp 457This directive will refuse to run if any programs have open descriptors 458in the PFS, including programs chdir'd into the PFS. 459.\" ==== mirror-read ==== 460.It Ar mirror-read Ar filesystem Op Ar <begin-tid> 461Generate a mirroring stream to stdout. 462The stream ends when the transaction id space has been exhausted. 463.\" ==== mirror-read-stream ==== 464.It Ar mirror-read-stream Ar filesystem Op Ar <begin-tid> 465Generate a mirroring stream to stdout. 466Upon completion the stream is paused until new data is synced to the 467master, then resumed. 468Operation continues until the pipe is broken. 469.\" ==== mirror-write ==== 470.It Ar mirror-write Ar filesystem 471Take a mirroring stream on stdin. 472.Pp 473This command will fail if the 474.Ar shared-uuid 475configuration field for the two file systems do not match. 476.\" ==== mirror-dump ==== 477.It Ar mirror-dump 478A 479.Ar mirror-read 480can be piped into a 481.Ar mirror-dump 482to dump an ascii 483representation of the mirroring stream. 484.\" ==== mirror-copy ==== 485.It Ar mirror-copy Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem 486This is a shortcut which pipes a 487.Ar mirror-read 488command to a 489.Ar mirror-write 490command. If a remote host specification is made the program forks a 491.Xr ssh 1 492and execs the 493.Ar mirror-read 494and/or 495.Ar mirror-write 496on the appropriate host. 497The source may be a master or slave PFS, and the target must be a slave PFS. 498.Pp 499This command also established full duplex communication and turns on 500the two-way protocol feature which automatically negotiates transaction id ranges 501without having to use a cycle file. 502If the operation completes successfully the target PFS's 503.Ar sync-end-tid 504will 505be updated. Note that you must re-chdir into the target PFS to see the 506updated information. If you do not you will still be in the previous snapshot. 507.\" ==== mirror-stream ==== 508.It Ar mirror-stream Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem 509This command works similarly to 510.Ar mirror-copy 511but does not exit unless the pipe is broken. 512This command will resume the mirroring operation whenever the master is 513synced. The command is commonly used with 514.Fl i Ar delay 515and 516.Fl b Ar bandwidth 517options to keep the mirroring target in sync with the source on a continuing 518basis. 519.El 520.\".Sh EXAMPLES 521.Sh PSEUDO FILESYSTEM (PFS) NOTES 522The root of a PFS is not hooked into the primary 523.Nm HAMMER 524file system as a 525directory. 526Instead, 527.Nm HAMMER 528creates a special softlink called "@@PFS%05d" (exactly 10 529characters long) in the primary 530.Nm HAMMER 531file system. 532.Nm HAMMER 533then modifies the contents of the softlink as read by 534.Xr readlink 2 , 535and thus what you see with an 536.Xr ls 1 537command or if you were to 538.Xr cd 1 539into the link. 540If the PFS is a master the link reflects the current state of the PFS. 541If the PFS is a slave the link reflects the last completed snapshot, and the 542contents of the link will change when the next snapshot is completed, and 543so forth. 544.Pp 545PFS support is currently very new and experimental. The 546.Nm 547utility 548employs numerous safeties to reduce user foot-shooting. 549The 550.Ar mirror-copy 551directive requires that the target be configured as a slave and that the 552.Ar shared-uuid 553field of the mirroring source and target match. 554.Sh DIAGNOSTICS 555.Ex -std 556.Sh SEE ALSO 557.Xr undo 1 , 558.Xr HAMMER 5 , 559.Xr mount_hammer 8 , 560.Xr newfs_hammer 8 561.Sh HISTORY 562The 563.Nm 564utility first appeared in 565.Dx 1.11 . 566.Sh AUTHORS 567.An Matthew Dillon Aq dillon@backplane.com 568