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 November 2, 2008
  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 and
  81 .Xr undo 1
  82 utilities.
  83 .Pp
  84 For a more detailed introduction refer to the paper and slides listed in the
  85 .Sx SEE ALSO
  86 section.
  87 For some common usages of
  88 .Nm
  89 see the
  90 .Sx EXAMPLES
  91 section below.
  92 .Ss Instant Crash Recovery
  93 After a non-graceful system shutdown,
  94 .Nm
  95 file systems will be brought back into a fully coherent state
  96 when mounting the file system, usually within a few seconds.
  97 .Ss Large File Systems & Multi Volume
  98 A
  99 .Nm
 100 file system 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 For volumes over 2 TB in size
 106 .Xr gpt 8
 107 and
 108 .Xr disklabel64 8
 109 normally need to be used.
 110 .Ss Data Integrity Checking
 111 .Nm
 112 has high focus on data integrity,
 113 CRC checks are made for all major structures and data.
 114 .Nm
 115 snapshots implements features to make data integrity checking easier:
 116 The atime and mtime fields are locked to the ctime for files accessed via a snapshot.
 117 The
 118 .Fa st_dev
 119 field is based on the PFS
 120 .Ar shared-uuid
 121 and not on any real device.
 122 This means that archiving the contents of a snaphot with e.g.\&
 123 .Xr tar 1
 124 and piping it to something like
 125 .Xr md5 1
 126 will yield a consistent result.
 127 The consistency is also retained on mirroring targets.
 128 .Ss Transaction IDs
 129 The
 130 .Nm
 131 file system uses 64 bit, hexadecimal transaction IDs to refer to historical
 132 file or directory data.
 133 An ID has the
 134 .Xr printf 3
 135 format
 136 .Li %#016llx ,
 137 such as
 138 .Li 0x00000001061a8ba6 .
 139 .Pp
 140 Related
 141 .Xr hammer 8
 142 commands:
 143 .Ar synctid
 144 .Ss History & Snapshots
 145 History metadata on the media is written with every sync operation, so that
 146 by default the resolution of a file's history is 30-60 seconds until the next
 147 prune operation.
 148 Prior versions of files or directories are generally accessible by appending
 149 .Li @@
 150 and a transaction ID to the name.
 151 The common way of accessing history, however, is by taking snapshots.
 152 .Pp
 153 Snapshots are softlinks to prior versions of directories and their files.
 154 Their data will be retained across prune operations for as long as the
 155 softlink exists.
 156 Removing the softlink enables the file system to reclaim the space
 157 again upon the next prune & reblock operations.
 158 .Pp
 159 Related
 160 .Xr hammer 8
 161 commands:
 162 .Ar cleanup ,
 163 .Ar history ,
 164 .Ar snapshot ;
 165 see also
 166 .Xr undo 1
 167 .Ss Pruning & Reblocking
 168 Pruning is the act of deleting file system history.
 169 Only history used by the given snapshots and history from after the latest
 170 snapshot will be retained.
 171 All other history is deleted.
 172 Reblocking will reorder all elements and thus defragment the file system and
 173 free space for reuse.
 174 After pruning a file system must be reblocked to recover all available space.
 175 Reblocking is needed even when using the
 176 .Ar nohistory
 177 .Xr mount_hammer 8
 178 option.
 179 .Pp
 180 Related
 181 .Xr hammer 8
 182 commands:
 183 .Ar cleanup ,
 184 .Ar prune ,
 185 .Ar prune-everything ,
 186 .Ar reblock ,
 187 .Ar reblock-btree ,
 188 .Ar reblock-inodes ,
 189 .Ar reblock-dirs ,
 190 .Ar reblock-data
 191 .Ss Mirroring & Pseudo File Systems
 192 In order to allow inode numbers to be duplicated on the slaves
 193 .Nm Ap s
 194 mirroring feature uses
 195 .Dq Pseudo File Systems
 196 (PFSs).
 197 A
 198 .Nm
 199 file system supports up to 65535 PFSs.
 200 Multiple slaves per master are supported, but multiple masters per slave
 201 are not.
 202 Slaves are always read-only.
 203 Upgrading slaves to masters and downgrading masters to slaves are supported.
 204 .Pp
 205 It is recommended to use a
 206 .Nm null
 207 mount to access a PFS;
 208 this way no tools are confused by the PFS root being a symlink
 209 and inodes not being unique across a
 210 .Nm
 211 file system.
 212 .Pp
 213 Related
 214 .Xr hammer 8
 215 commands:
 216 .Ar pfs-master ,
 217 .Ar pfs-slave ,
 218 .Ar pfs-cleanup ,
 219 .Ar pfs-status ,
 220 .Ar pfs-update ,
 221 .Ar pfs-destroy ,
 222 .Ar pfs-upgrade ,
 223 .Ar pfs-downgrade ,
 224 .Ar mirror-copy ,
 225 .Ar mirror-stream ,
 226 .Ar mirror-read ,
 227 .Ar mirror-read-stream ,
 228 .Ar mirror-write ,
 229 .Ar mirror-dump
 230 .Ss NFS Export
 231 .Nm
 232 file systems support NFS export.
 233 NFS export of PFSs is done using
 234 .Nm null
 235 mounts.
 236 For example, to export the PFS
 237 .Pa /hammer/pfs/data ,
 238 create a
 239 .Nm null
 240 mount, e.g.\& to
 241 .Pa /hammer/data
 242 and export the latter path.
 243 .Pp
 244 Don't export a directory containing a PFS (e.g.\&
 245 .Pa /hammer/pfs
 246 above).
 247 Only
 248 .Nm null
 249 mount for PFS root
 250 (e.g.\&
 251 .Pa /hammer/data
 252 above)
 253 should be exported
 254 (subdirectory may be escaped if exported).
 255 .Sh EXAMPLES
 256 .Ss Preparing the File System
 257 To create and mount a
 258 .Nm
 259 file system use the
 260 .Xr newfs_hammer 8
 261 and
 262 .Xr mount_hammer 8
 263 commands.
 264 Note that all
 265 .Nm
 266 file systems must have a unique name on a per-machine basis.
 267 .Bd -literal -offset indent
 268 newfs_hammer -L HOME /dev/ad0s1d
 269 mount_hammer /dev/ad0s1d /home
 270 .Ed
 271 .Pp
 272 Similarly, multi volume file systems can be created and mounted by
 273 specifying additional arguments.
 274 .Bd -literal -offset indent
 275 newfs_hammer -L MULTIHOME /dev/ad0s1d /dev/ad1s1d
 276 mount_hammer /dev/ad0s1d /dev/ad1s1d /home
 277 .Ed
 278 .Pp
 279 Once created and mounted,
 280 .Nm
 281 file systems need periodic clean up making snapshots, pruning and reblocking,
 282 in order to have access to history and file system not to fill up.
 283 For this it is recommended to use the
 284 .Xr hammer 8
 285 .Ar cleanup
 286 metacommand.
 287 .Pp
 288 By default,
 289 .Dx
 290 is set up to run
 291 .Nm hammer Ar cleanup
 292 nightly via
 293 .Xr periodic 8 .
 294 .Pp
 295 It is also possible to perform these operations individually via
 296 .Xr crontab 5 .
 297 For example, to reblock the
 298 .Pa /home
 299 file system every night at 2:15 for up to 5 minutes:
 300 .Bd -literal -offset indent
 301 15 2 * * * hammer -c /var/run/HOME.reblock -t 300 reblock /home \e
 302         >/dev/null 2>&1
 303 .Ed
 304 .Ss Snapshots
 305 The
 306 .Xr hammer 8
 307 utility's
 308 .Ar snapshot
 309 command provides several ways of taking snapshots.
 310 They all assume a directory where snapshots are kept.
 311 .Bd -literal -offset indent
 312 mkdir /snaps
 313 hammer snapshot /home /snaps/snap1
 314 (...after some changes in /home...)
 315 hammer snapshot /home /snaps/snap2
 316 .Ed
 317 .Pp
 318 The softlinks in
 319 .Pa /snaps
 320 point to the state of the
 321 .Pa /home
 322 directory at the time each snapshot was taken, and could now be used to copy
 323 the data somewhere else for backup purposes.
 324 .Pp
 325 By default,
 326 .Dx
 327 is set up to create nightly snapshots of all
 328 .Nm
 329 file systems via
 330 .Xr periodic 8
 331 and to keep them for 60 days.
 332 .Ss Pruning
 333 A snapshot directory is also the argument to the
 334 .Xr hammer 8 Ap s
 335 .Ar prune
 336 command which frees historical data from the file system that is not
 337 pointed to by any snapshot link and is not from after the latest snapshot.
 338 .Bd -literal -offset indent
 339 rm /snaps/snap1
 340 hammer prune /snaps
 341 .Ed
 342 .Ss Mirroring
 343 Mirroring can be set up using
 344 .Nm Ap s
 345 pseudo file systems.
 346 To associate the slave with the master its shared UUID should be set to
 347 the master's shared UUID as output by the
 348 .Nm hammer Ar pfs-master
 349 command.
 350 .Bd -literal -offset indent
 351 hammer pfs-master /home/pfs/master
 352 hammer pfs-slave /home/pfs/slave shared-uuid=<master's shared uuid>
 353 .Ed
 354 .Pp
 355 The
 356 .Pa /home/pfs/slave
 357 link is unusable for as long as no mirroring operation has taken place.
 358 .Pp
 359 To mirror the master's data, either pipe a
 360 .Fa mirror-read
 361 command into a
 362 .Fa mirror-write
 363 or, as a short-cut, use the
 364 .Fa mirror-copy
 365 command (which works across a
 366 .Xr ssh 1
 367 connection as well).
 368 Initial mirroring operation has to be done to the PFS path (as
 369 .Xr mount_null 8
 370 can't access it yet).
 371 .Bd -literal -offset indent
 372 hammer mirror-copy /home/pfs/master /home/pfs/slave
 373 .Ed
 374 .Pp
 375 After this initial step
 376 .Nm null
 377 mount can be setup for
 378 .Pa /home/pfs/slave .
 379 Further operations can use
 380 .Nm null
 381 mounts.
 382 .Bd -literal -offset indent
 383 mount_null /home/pfs/master /home/master
 384 mount_null /home/pfs/slave /home/slave
 385
 386 hammer mirror-copy /home/master /home/slave
 387 .Ed
 388 .Ss NFS Export
 389 To NFS export from the
 390 .Nm
 391 file system
 392 .Pa /hammer
 393 the directory
 394 .Pa /hammer/non-pfs
 395 without PFSs, and the PFS
 396 .Pa /hammer/pfs/data ,
 397 the latter is null mounted to
 398 .Pa /hammer/data .
 399 .Pp
 400 Add to
 401 .Pa /etc/fstab
 402 (see
 403 .Xr fstab 5 ) :
 404 .Bd -literal -offset indent
 405 /hammer/pfs/data /hammer/data null rw
 406 .Ed
 407 .Pp
 408 Add to
 409 .Pa /etc/exports
 410 (see
 411 .Xr exports 5 ) :
 412 .Bd -literal -offset indent
 413 /hammer/non-pfs
 414 /hammer/data
 415 .Ed
 416 .Sh SEE ALSO
 417 .Xr md5 1 ,
 418 .Xr tar 1 ,
 419 .Xr undo 1 ,
 420 .Xr ffs 5 ,
 421 .Xr disklabel64 8 ,
 422 .Xr gpt 8 ,
 423 .Xr hammer 8 ,
 424 .Xr mount_hammer 8 ,
 425 .Xr mount_null 8 ,
 426 .Xr newfs_hammer 8
 427 .Rs
 428 .%A Matthew Dillon
 429 .%D June 2008
 430 .%O http://www.dragonflybsd.org/hammer/hammer.pdf
 431 .%T "The HAMMER Filesystem"
 432 .Re
 433 .Rs
 434 .%A Matthew Dillon
 435 .%D October 2008
 436 .%O http://www.dragonflybsd.org/hammer/nycbsdcon/
 437 .%T "Slideshow from NYCBSDCon 2008"
 438 .Re
 439 .Sh HISTORY
 440 The
 441 .Nm
 442 file system first appeared in
 443 .Dx 1.11 .
 444 .Sh AUTHORS
 445 .An -nosplit
 446 The
 447 .Nm
 448 file system was designed and implemented by
 449 .An Matthew Dillon Aq dillon@backplane.com .
 450 This manual page was written by
 451 .An Sascha Wildner .