sbin/hammer/hammer.8

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