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