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