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.34 2008/07/09 18:32:19 swildner Exp $ 34.Dd June 26, 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 hrv2 43.Op Fl c Ar cyclefile 44.Op Fl f Ar blkdev[:blkdev]* 45.Op Fl s Ar linkpath 46.Op Fl t Ar seconds 47.Ar command 48.Ar ... 49.Sh DESCRIPTION 50The 51.Nm 52utility provides miscellaneous functions related to managing a HAMMER 53filesystem. 54.Pp 55The options are as follows: 56.Bl -tag -width indent 57.It Fl h 58Get help 59.It Fl 2 60Tell the mirror commands to use a 2-way protocol, which allows 61automatic negotiation of transaction id ranges. This option is 62automatically enabled by the 63.Ar mirror-copy 64command. 65.It Fl r 66Specify recursion for those commands which support it. 67.It Fl c Ar cyclefile 68When pruning and reblocking you can instruction HAMMER to start at the 69object id stored in the specified file. If the file does not exist 70HAMMER will start at the beginning. If HAMMER is told to run for a 71specific period of time and is unable to complete the operation it will 72write out the current obj_id so the next run can pick up where it left 73off. If HAMMER runs to completion it will delete the cyclefile. 74.It Fl f Ar blkdev[:blkdev]* 75Specify the volumes making up a HAMMER filesystem. 76.It Fl s Ar linkpath 77When pruning a filesystem you can instruct HAMMER to create softlinks 78to available snapshots. 79.It Fl t Ar seconds 80When pruning and reblocking you can tell the utility to stop after a 81certain period of time. This option is used along with the cycle file 82option to prune or reblock a portion of the filesystem incrementally. 83.It Fl v 84Increase verboseness. May be specified multiple times. 85.El 86.Pp 87The commands are as follows: 88.Bl -tag -width indent 89.It Ar synctid Ar filesystem Op quick 90Generates a guaranteed, formal 64 bit transaction id representing the 91current state of the specified HAMMER filesystem. The filesystem will 92be synced to the media. 93.Pp 94If the 95.Ar quick 96keyword is specified the filesystem will be soft-synced, meaning that a 97crash might still undo the state of the filesystem as of the transaction 98id returned but any new modifications will occur after the returned 99transaction id as expected. 100.It Ar bstats Op interval 101Output HAMMER B-Tree statistics until interrupted. The default interval 102is one second. 103.It Ar iostats Op interval 104Output HAMMER I/O statistics until interrupted. The default interval 105is one second. 106.It Ar history Ar path 107Show the modification history for a HAMMER file's inode and data. 108.It Ar show Op vol_no[:clu_no] 109Dump the B-Tree starting at the specified volume and cluster, or 110at the root volume if not specified. 111The B-Tree is dumped recursively if the 112.Fl r 113option is specified. 114.It Ar blockmap 115Dump the btree, record, large-data, and small-data blockmaps, showing 116physical block assignments and free space percentages. 117.It Ar namekey Ar filename 118Generate a HAMMER 64 bit directory hash for the specified file name. 119The low 32 bits are used as an iterator for hash collisions and will be 120output as 0. 121.It Ar namekey32 Ar filename 122Generate the top 32 bits of a HAMMER 64 bit directory hash for the specified 123file name. 124.It Ar prune Ar softlink-dir 125Prune the filesystem based on previously created snapshot softlinks. 126The target directory is expected to contain softlinks pointing to 127snapshots of the filesystems you wish to retain. The directory is scanned 128non-recursively and the mount points and transaction ids stored in the 129softlinks are extracted and sorted. 130The filesystem is then explicitly pruned according to what is found. 131Cleaning out portions of the filesystem is as simple as removing a softlink 132and then running the 133.Ar prune 134command. 135.Pp 136As a safety measure pruning only occurs if one or more softlinks are found 137containing the @@ snapshot id extension. 138.Pp 139Currently the scanned softlink directory must contain softlinks pointing 140to a single HAMMER mount. The softlinks may specify absolute or relative 141paths. Softlinks must use 20-character (@@0x%016llx) transaction ids, 142as might be returned from 'hammer synctid <filesystem>'. 143.Pp 144Example, lets say your snapshot directory contains the following links: 145.Bd -literal 146lrwxr-xr-x 1 root wheel 29 May 31 17:57 snap1 -> 147/usr/obj/@@0x10d2cd05b7270d16 148 149lrwxr-xr-x 1 root wheel 29 May 31 17:58 snap2 -> 150/usr/obj/@@0x10d2cd13f3fde98f 151 152lrwxr-xr-x 1 root wheel 29 May 31 17:59 snap3 -> 153/usr/obj/@@0x10d2cd222adee364 154.Ed 155.Pp 156If you were to run the prune command on this directory, then the HAMMER 157.Pa /usr/obj 158mount will be pruned to retain the above three snapshots. 159In addition, modifications made to the filesystem older than the oldest 160snapshot will be destroyed and potentially fine-grained modifications made 161to the filesystem more recently than the most recent snapshot will be 162retained. 163.Pp 164If you then delete the snap2 softlink and rerun the prune command, 165modifications pertaining to that snapshot would be destroyed. 166.It Ar prune-everything Ar filesystem 167This command will remove all historical records from the filesystem. 168This directive is not normally used on a production system. 169.Pp 170Note that pruning a filesystem may not immediately free-up space, 171though typically some space will be freed if a large number of records are 172pruned out. The filesystem must be reblocked to completely recover all 173available space. 174.It Ar snapshot Ar snapshot-dir 175.It Ar snapshot Ar filesystem snapshot-dir 176Takes a snapshot of the filesystem either explicitly given by 177.Ar filesystem 178or implicitly derived from the 179.Ar snapshot-dir 180argument and creates a symlink in the directory provided by 181.Ar snapshot-dir 182pointing to the snapshot. 183If 184.Ar snapshot-dir 185is no directory, it is assumed to be a format string 186passed to 187.Xr strftime 3 188with the current time as parameter. 189If 190.Ar snapshot-dir 191refers to an existing directory, a default format string of "snap-%Y%d%m-%H%M" 192is assumed and used as name for the newly created symlink. 193Assuming that 194.Pa /mysnapshots 195is on filesystem 196.Pa / 197and that 198.Pa /obj 199is a filesystem on its own, the following invocations: 200.Bd -literal 201hammer snapshot /mysnapshots 202 203hammer snapshot /mysnapshots/%Y-%m-%d 204 205hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d 206.Ed 207.Pp 208would create symlinks similar to: 209.Bd -literal 210/mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16 211 212/mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16 213 214/mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16 215.Ed 216.It Ar reblock Ar filesystem Op Ar fill_percentage 217.It Ar reblock-btree Ar filesystem Op Ar fill_percentage 218.It Ar reblock-inodes Ar filesystem Op Ar fill_percentage 219.It Ar reblock-dirs Ar filesystem Op Ar fill_percentage 220.It Ar reblock-data Ar filesystem Op Ar fill_percentage 221Attempt to defragment and free space for reuse by reblocking a live 222HAMMER filesystem. 223Big blocks cannot be reused by HAMMER until they are completely free. 224This command also has the effect of reordering all elements, effectively 225defragmenting the filesystem. 226.Pp 227The default fill percentage is 100% and will cause the filesystem to be 228completely defragmented. All specified element types will be reallocated 229and rewritten. If you wish to quickly free up space instead try specifying 230a smaller fill percentage, such as 90% or 80% (the '%' suffix is not needed). 231.Pp 232Since this command may rewrite the entire contents of the disk it is 233best to do it incrementally from a cron job along with the 234.Fl c Ar cyclefile 235and 236.Fl t Ar seconds 237options to limit the run time. 238The filesystem would thus be defragmented over long period of time. 239.Pp 240It is recommended that separate invocations be used for each data type. 241Btree nodes, inodes, and directories are typically the most important 242elements needing defragmentation. Data can be defragmented over a longer 243period of time. 244.It Ar pfs-status Ar dirpath 245Retrieve the mirroring configuration parameters for the specified 246HAMMER filesystem or pseudo-filesystem. 247.It Ar pfs-master Ar dirpath Op options 248Create a pseudo-filesystem (PFS) inside a HAMMER filesystem. 249Up to 65535 such filesystems can be created. 250Each PFS uses an independant inode numbering space making it suitable 251for use as a replication source or target. 252.Pp 253The 254.Ar pfs-master 255directive creates a PFS that you can read, write, and use as a mirroring 256source. 257.It Ar pfs-slave Ar dirpath Op options 258Create a pseudo-filesystem (PFS) inside a HAMMER filesystem. 259Up to 65535 such filesystems can be created. 260Each PFS uses an independant inode numbering space making it suitable 261for use as a replication source or target. 262.Pp 263The 264.Ar pfs-slave 265directive creates a PFS that you can use as a mirroring target. 266You will not be able to access a slave PFS until you have completed the 267first mirroring operation with it as the target (its root directory will 268not exist until then). 269.Pp 270Access to the pfs-slave via the special softlink allows Hammer to 271dynamically modify the snapshot TID by returning a dynamic result 272from readlink() calls. 273.Pp 274A PFS can only be truely destroyed with the 275.AR pfs-destroy 276directive. 277Removing the softlink will not destroy the underlying PFS. 278.It Ar pfs-destroy Ar dirpath 279This permanently destroys a PFS. 280.It Ar pfs-update Ar dirpath Op options 281Update the configuration parameters for an existing HAMMER filesystem 282or pseudo-filesystem. Options that may be specified: 283.Pp 284.Bl -tag -width indent 285.It sync-beg-tid=0x16llx 286This is the automatic snapshot access starting TID for mirroring slaves. 287This parameter is normally updated automatically by the 288.Ar mirror-write 289directive. 290.Pp 291It is important to note that accessing a mirroring slave 292with a transaction id greater then the last fully synchronized transaction 293id can result in an unreliable snapshot since you will be accessing 294data that is still undergoing synchronization. 295.Pp 296Manually modifying this field is dangerous and can result in a broken 297mirror. 298.It sync-end-tid=0x16llx 299This is the current synchronization point for mirroring slaves. 300This parameter is normally updated automatically by the 301.Ar mirror-write 302directive. 303.Pp 304Manually modifying this field is dangerous and can result in a broken 305mirror. 306.It shared-uuid=<uuid> 307Set the shared uuid for this filesystem. All mirrors must have the same 308shared uuid. For safety purposes the mirror-write directives will refuse 309to operate on a target with a different shared uuid. 310.Pp 311Changing the shared uuid on an existing, non-empty mirroring target, 312including an empty but not completely pruned target, can lead 313to corruption of the mirroring target. 314.It unique-uuid=<uuid> 315Set the unique uuid for this filesystem. This uuid should not be used 316anywhere else, even on exact copies of the filesystem. 317.It master=<num> 318Set the master id for multi-master mirroring. Only values between 0 and 15 319inclusive may be specified. All masters sharing the same 320.Ar shared-uuid 321must have different ids. 322Up to 16 masters will eventually be supported. 323.Pp 324Multi-master mirroring is not supported yet and the master id should be 325set to 0 on the single master when mirroring to one or more slaves. 326.Pp 327The master id may only be changed if the PFS is in master mode. A PFS 328slave cannot be upgraded to a master at this time. 329.It no-mirror 330This disables the ability to use this filesystem as a mirroring source 331or target. You can still do full scans with mirror-read but incremental 332scans will not work. This option may only be set on masters. 333.It slave 334Sets slave mode, allowing the mirror to be used as a slave. Except for 335the mirror-write directive all accesses to the mirror will be made read-only 336and will be as-of the 337.Ar sync_beg_tid . 338This option is currently not supported, slave mode must be specified 339when creating the PFS and cannot be changed on the fly. 340.It label=<string> 341Set a descriptive label for this filesystem. 342.El 343.It Ar mirror-read Ar filesystem Op Ar <begin-tid> 344Generate a mirroring stream to stdout. 345.It Ar mirror-write Ar filesystem Op Ar 346Take a mirroring stream on stdin and output it to stdout. 347.Pp 348This command will fail if the 349.Ar shared_uuid 350configuration field for the two filesystems do not match. 351.It Ar mirror-dump 352A mirror-read can be piped into a mirror-dump to dump an ascii 353representation of the mirroring stream. 354.It Ar mirror-copy Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem 355This is a shortcut which pipes a mirror-read command to a mirror-write 356command. If a remote host specification is made the program forks a 357ssh and execs the mirror-read and/or mirror-write on the appropriate host. 358.Pp 359This command also turns on the two-way protocol feature which automatically 360negotiates TID ranges without having to use a cycle file. 361.El 362.\".Sh EXAMPLES 363.Sh DIAGNOSTICS 364.Ex -std 365.Sh SEE ALSO 366.Xr newfs_hammer 8 367.Sh HISTORY 368The 369.Nm 370utility first appeared in 371.Dx 1.11 . 372.Sh AUTHORS 373.An Matthew Dillon Aq dillon@backplane.com 374