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