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