share/man/man5/hammer.5

   1 .\"
   2 .\" Copyright (c) 2008
   3 .\"     The DragonFly Project.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\" 3. Neither the name of The DragonFly Project nor the names of its
  16 .\"    contributors may be used to endorse or promote products derived
  17 .\"    from this software without specific, prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .Dd April 8, 2010
  33 .Os
  34 .Dt HAMMER 5
  35 .Sh NAME
  36 .Nm HAMMER
  37 .Nd HAMMER file system
  38 .Sh SYNOPSIS
  39 To compile this driver into the kernel,
  40 place the following line in your
  41 kernel configuration file:
  42 .Bd -ragged -offset indent
  43 .Cd options HAMMER
  44 .Ed
  45 .Pp
  46 Alternatively, to load the driver as a
  47 module at boot time, place the following line in
  48 .Xr loader.conf 5 :
  49 .Bd -literal -offset indent
  50 hammer_load="YES"
  51 .Ed
  52 .Pp
  53 To mount via
  54 .Xr fstab 5 :
  55 .Bd -literal -offset indent
  56 /dev/ad0s1d[:/dev/ad1s1d:...]   /mnt hammer rw 2 0
  57 .Ed
  58 .Sh DESCRIPTION
  59 The
  60 .Nm
  61 file system provides facilities to store file system data onto disk devices
  62 and is intended to replace
  63 .Xr ffs 5
  64 as the default file system for
  65 .Dx .
  66 Among its features are instant crash recovery,
  67 large file systems spanning multiple volumes,
  68 data integrity checking,
  69 fine grained history retention,
  70 mirroring capability, and pseudo file systems.
  71 .Pp
  72 All functions related to managing
  73 .Nm
  74 file systems are provided by the
  75 .Xr newfs_hammer 8 ,
  76 .Xr mount_hammer 8 ,
  77 .Xr hammer 8 ,
  78 .Xr chflags 1 ,
  79 and
  80 .Xr undo 1
  81 utilities.
  82 .Pp
  83 For a more detailed introduction refer to the paper and slides listed in the
  84 .Sx SEE ALSO
  85 section.
  86 For some common usages of
  87 .Nm
  88 see the
  89 .Sx EXAMPLES
  90 section below.
  91 .Ss Instant Crash Recovery
  92 After a non-graceful system shutdown,
  93 .Nm
  94 file systems will be brought back into a fully coherent state
  95 when mounting the file system, usually within a few seconds.
  96 .Ss Large File Systems & Multi Volume
  97 A
  98 .Nm
  99 file system can be up to 1 Exabyte in size.
 100 It can span up to 256 volumes,
 101 each volume occupies a
 102 .Dx
 103 disk slice or partition, or another special file,
 104 and can be up to 4096 TB in size.
 105 Minimum recommended
 106 .Nm
 107 file system size is 50 GB.
 108 For volumes over 2 TB in size
 109 .Xr gpt 8
 110 and
 111 .Xr disklabel64 8
 112 normally need to be used.
 113 .Ss Data Integrity Checking
 114 .Nm
 115 has high focus on data integrity,
 116 CRC checks are made for all major structures and data.
 117 .Nm
 118 snapshots implements features to make data integrity checking easier:
 119 The atime and mtime fields are locked to the ctime
 120 for files accessed via a snapshot.
 121 The
 122 .Fa st_dev
 123 field is based on the PFS
 124 .Ar shared-uuid
 125 and not on any real device.
 126 This means that archiving the contents of a snapshot with e.g.\&
 127 .Xr tar 1
 128 and piping it to something like
 129 .Xr md5 1
 130 will yield a consistent result.
 131 The consistency is also retained on mirroring targets.
 132 .Ss Transaction IDs
 133 The
 134 .Nm
 135 file system uses 64 bit, hexadecimal transaction IDs to refer to historical
 136 file or directory data.
 137 An ID has the
 138 .Xr printf 3
 139 format
 140 .Li %#016llx ,
 141 such as
 142 .Li 0x00000001061a8ba6 .
 143 .Pp
 144 Related
 145 .Xr hammer 8
 146 commands:
 147 .Ar snapshot ,
 148 .Ar synctid
 149 .Ss History & Snapshots
 150 History metadata on the media is written with every sync operation, so that
 151 by default the resolution of a file's history is 30-60 seconds until the next
 152 prune operation.
 153 Prior versions of files or directories are generally accessible by appending
 154 .Li @@
 155 and a transaction ID to the name.
 156 The common way of accessing history, however, is by taking snapshots.
 157 .Pp
 158 Snapshots are softlinks to prior versions of directories and their files.
 159 Their data will be retained across prune operations for as long as the
 160 softlink exists.
 161 Removing the softlink enables the file system to reclaim the space
 162 again upon the next prune & reblock operations.
 163 .Pp
 164 Related
 165 .Xr hammer 8
 166 commands:
 167 .Ar cleanup ,
 168 .Ar history ,
 169 .Ar snapshot ;
 170 see also
 171 .Xr undo 1
 172 .Ss Pruning & Reblocking
 173 Pruning is the act of deleting file system history.
 174 By default only history used by the given snapshots
 175 and history from after the latest snapshot will be retained.
 176 By setting the per PFS parameter
 177 .Cm prune-min ,
 178 history is guaranteed to be saved at least this time interval.
 179 All other history is deleted.
 180 Reblocking will reorder all elements and thus defragment the file system and
 181 free space for reuse.
 182 After pruning a file system must be reblocked to recover all available space.
 183 Reblocking is needed even when using the
 184 .Ar nohistory
 185 .Xr mount_hammer 8
 186 option or
 187 .Xr chflags 1
 188 flag.
 189 .Pp
 190 Related
 191 .Xr hammer 8
 192 commands:
 193 .Ar cleanup ,
 194 .Ar snapshot ,
 195 .Ar prune ,
 196 .Ar prune-everything ,
 197 .Ar rebalance ,
 198 .Ar reblock ,
 199 .Ar reblock-btree ,
 200 .Ar reblock-inodes ,
 201 .Ar reblock-dirs ,
 202 .Ar reblock-data
 203 .Ss Mirroring & Pseudo File Systems
 204 In order to allow inode numbers to be duplicated on the slaves
 205 .Nm Ap s
 206 mirroring feature uses
 207 .Dq Pseudo File Systems
 208 (PFSs).
 209 A
 210 .Nm
 211 file system supports up to 65535 PFSs.
 212 Multiple slaves per master are supported, but multiple masters per slave
 213 are not.
 214 Slaves are always read-only.
 215 Upgrading slaves to masters and downgrading masters to slaves are supported.
 216 .Pp
 217 It is recommended to use a
 218 .Nm null
 219 mount to access a PFS;
 220 this way no tools are confused by the PFS root being a symlink
 221 and inodes not being unique across a
 222 .Nm
 223 file system.
 224 .Pp
 225 Related
 226 .Xr hammer 8
 227 commands:
 228 .Ar pfs-master ,
 229 .Ar pfs-slave ,
 230 .Ar pfs-cleanup ,
 231 .Ar pfs-status ,
 232 .Ar pfs-update ,
 233 .Ar pfs-destroy ,
 234 .Ar pfs-upgrade ,
 235 .Ar pfs-downgrade ,
 236 .Ar mirror-copy ,
 237 .Ar mirror-stream ,
 238 .Ar mirror-read ,
 239 .Ar mirror-read-stream ,
 240 .Ar mirror-write ,
 241 .Ar mirror-dump
 242 .Ss NFS Export
 243 .Nm
 244 file systems support NFS export.
 245 NFS export of PFSs is done using
 246 .Nm null
 247 mounts.
 248 For example, to export the PFS
 249 .Pa /hammer/pfs/data ,
 250 create a
 251 .Nm null
 252 mount, e.g.\& to
 253 .Pa /hammer/data
 254 and export the latter path.
 255 .Pp
 256 Don't export a directory containing a PFS (e.g.\&
 257 .Pa /hammer/pfs
 258 above).
 259 Only
 260 .Nm null
 261 mount for PFS root
 262 (e.g.\&
 263 .Pa /hammer/data
 264 above)
 265 should be exported
 266 (subdirectory may be escaped if exported).
 267 .Sh EXAMPLES
 268 .Ss Preparing the File System
 269 To create and mount a
 270 .Nm
 271 file system use the
 272 .Xr newfs_hammer 8
 273 and
 274 .Xr mount_hammer 8
 275 commands.
 276 Note that all
 277 .Nm
 278 file systems must have a unique name on a per-machine basis.
 279 .Bd -literal -offset indent
 280 newfs_hammer -L HOME /dev/ad0s1d
 281 mount_hammer /dev/ad0s1d /home
 282 .Ed
 283 .Pp
 284 Similarly, multi volume file systems can be created and mounted by
 285 specifying additional arguments.
 286 .Bd -literal -offset indent
 287 newfs_hammer -L MULTIHOME /dev/ad0s1d /dev/ad1s1d
 288 mount_hammer /dev/ad0s1d /dev/ad1s1d /home
 289 .Ed
 290 .Pp
 291 Once created and mounted,
 292 .Nm
 293 file systems need periodic clean up making snapshots, pruning and reblocking,
 294 in order to have access to history and file system not to fill up.
 295 For this it is recommended to use the
 296 .Xr hammer 8
 297 .Ar cleanup
 298 metacommand.
 299 .Pp
 300 By default,
 301 .Dx
 302 is set up to run
 303 .Nm hammer Ar cleanup
 304 nightly via
 305 .Xr periodic 8 .
 306 .Pp
 307 It is also possible to perform these operations individually via
 308 .Xr crontab 5 .
 309 For example, to reblock the
 310 .Pa /home
 311 file system every night at 2:15 for up to 5 minutes:
 312 .Bd -literal -offset indent
 313 15 2 * * * hammer -c /var/run/HOME.reblock -t 300 reblock /home \e
 314         >/dev/null 2>&1
 315 .Ed
 316 .Ss Snapshots
 317 The
 318 .Xr hammer 8
 319 utility's
 320 .Ar snapshot
 321 command provides several ways of taking snapshots.
 322 They all assume a directory where snapshots are kept.
 323 .Bd -literal -offset indent
 324 mkdir /snaps
 325 hammer snapshot /home /snaps/snap1
 326 (...after some changes in /home...)
 327 hammer snapshot /home /snaps/snap2
 328 .Ed
 329 .Pp
 330 The softlinks in
 331 .Pa /snaps
 332 point to the state of the
 333 .Pa /home
 334 directory at the time each snapshot was taken, and could now be used to copy
 335 the data somewhere else for backup purposes.
 336 .Pp
 337 By default,
 338 .Dx
 339 is set up to create nightly snapshots of all
 340 .Nm
 341 file systems via
 342 .Xr periodic 8
 343 and to keep them for 60 days.
 344 .Ss Pruning
 345 A snapshot directory is also the argument to the
 346 .Xr hammer 8 Ap s
 347 .Ar prune
 348 command which frees historical data from the file system that is not
 349 pointed to by any snapshot link and is not from after the latest snapshot.
 350 .Bd -literal -offset indent
 351 rm /snaps/snap1
 352 hammer prune /snaps
 353 .Ed
 354 .Ss Mirroring
 355 Mirroring can be set up using
 356 .Nm Ap s
 357 pseudo file systems.
 358 To associate the slave with the master its shared UUID should be set to
 359 the master's shared UUID as output by the
 360 .Nm hammer Ar pfs-master
 361 command.
 362 .Bd -literal -offset indent
 363 hammer pfs-master /home/pfs/master
 364 hammer pfs-slave /home/pfs/slave shared-uuid=<master's shared uuid>
 365 .Ed
 366 .Pp
 367 The
 368 .Pa /home/pfs/slave
 369 link is unusable for as long as no mirroring operation has taken place.
 370 .Pp
 371 To mirror the master's data, either pipe a
 372 .Fa mirror-read
 373 command into a
 374 .Fa mirror-write
 375 or, as a short-cut, use the
 376 .Fa mirror-copy
 377 command (which works across a
 378 .Xr ssh 1
 379 connection as well).
 380 Initial mirroring operation has to be done to the PFS path (as
 381 .Xr mount_null 8
 382 can't access it yet).
 383 .Bd -literal -offset indent
 384 hammer mirror-copy /home/pfs/master /home/pfs/slave
 385 .Ed
 386 .Pp
 387 After this initial step
 388 .Nm null
 389 mount can be setup for
 390 .Pa /home/pfs/slave .
 391 Further operations can use
 392 .Nm null
 393 mounts.
 394 .Bd -literal -offset indent
 395 mount_null /home/pfs/master /home/master
 396 mount_null /home/pfs/slave /home/slave
 397
 398 hammer mirror-copy /home/master /home/slave
 399 .Ed
 400 .Ss NFS Export
 401 To NFS export from the
 402 .Nm
 403 file system
 404 .Pa /hammer
 405 the directory
 406 .Pa /hammer/non-pfs
 407 without PFSs, and the PFS
 408 .Pa /hammer/pfs/data ,
 409 the latter is null mounted to
 410 .Pa /hammer/data .
 411 .Pp
 412 Add to
 413 .Pa /etc/fstab
 414 (see
 415 .Xr fstab 5 ) :
 416 .Bd -literal -offset indent
 417 /hammer/pfs/data /hammer/data null rw
 418 .Ed
 419 .Pp
 420 Add to
 421 .Pa /etc/exports
 422 (see
 423 .Xr exports 5 ) :
 424 .Bd -literal -offset indent
 425 /hammer/non-pfs
 426 /hammer/data
 427 .Ed
 428 .Sh SEE ALSO
 429 .Xr chflags 1 ,
 430 .Xr md5 1 ,
 431 .Xr tar 1 ,
 432 .Xr undo 1 ,
 433 .Xr exports 5 ,
 434 .Xr ffs 5 ,
 435 .Xr fstab 5 ,
 436 .Xr disklabel64 8 ,
 437 .Xr gpt 8 ,
 438 .Xr hammer 8 ,
 439 .Xr mount_hammer 8 ,
 440 .Xr mount_null 8 ,
 441 .Xr newfs_hammer 8
 442 .Rs
 443 .%A Matthew Dillon
 444 .%D June 2008
 445 .%O http://www.dragonflybsd.org/hammer/hammer.pdf
 446 .%T "The HAMMER Filesystem"
 447 .Re
 448 .Rs
 449 .%A Matthew Dillon
 450 .%D October 2008
 451 .%O http://www.dragonflybsd.org/hammer/nycbsdcon/
 452 .%T "Slideshow from NYCBSDCon 2008"
 453 .Re
 454 .Rs
 455 .%A Michael Neumann
 456 .%D January 2010
 457 .%O http://www.ntecs.de/sysarch09/HAMMER.pdf
 458 .%T "Slideshow for a presentation held at KIT (http://www.kit.edu)."
 459 .Re
 460 .Sh FILESYSTEM PERFORMANCE
 461 The
 462 .Nm
 463 file system has a front-end which processes VNOPS and issues necessary
 464 block reads from disk, and a back-end which handles meta-data updates
 465 on-media and performs all meta-data write operations.
 466 Bulk file write operations are handled by the front-end.
 467 Because
 468 .Nm
 469 defers meta-data updates virtually no meta-data read operations will be
 470 issued by the frontend while writing large amounts of data to the file system
 471 or even when creating new files or directories, and even though the
 472 kernel prioritizes reads over writes the fact that writes are cached by
 473 the drive itself tends to lead to excessive priority given to writes.
 474 .Pp
 475 There are four bioq sysctls, shown below with default values,
 476 which can be adjusted to give reads a higher priority:
 477 .Bd -literal -offset indent
 478 kern.bioq_reorder_minor_bytes: 262144
 479 kern.bioq_reorder_burst_bytes: 3000000
 480 kern.bioq_reorder_minor_interval: 5
 481 kern.bioq_reorder_burst_interval: 60
 482 .Ed
 483 .Pp
 484 If a higher read priority is desired it is recommended that the
 485 .Fa kern.bioq_reorder_minor_interval
 486 be increased to 15, 30, or even 60, and the
 487 .Fa kern.bioq_reorder_burst_bytes
 488 be decreased to 262144 or 524288.
 489 .Sh HISTORY
 490 The
 491 .Nm
 492 file system first appeared in
 493 .Dx 1.11 .
 494 .Sh AUTHORS
 495 .An -nosplit
 496 The
 497 .Nm
 498 file system was designed and implemented by
 499 .An Matthew Dillon Aq dillon@backplane.com .
 500 This manual page was written by
 501 .An Sascha Wildner .