3 .\" The DragonFly Project. All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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
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.
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
32 .\" $DragonFly: src/share/man/man5/hammer.5,v 1.13 2008/10/07 22:23:12 thomas Exp $
34 .Dd September 28, 2008
39 .Nd HAMMER file system
41 To compile this driver into the kernel,
42 place the following line in your
43 kernel configuration file:
44 .Bd -ragged -offset indent
48 Alternatively, to load the driver as a
49 module at boot time, place the following line in
51 .Bd -literal -offset indent
57 .Bd -literal -offset indent
58 /dev/ad0s1d[:/dev/ad1s1d:...] /mnt hammer rw 2 0
63 file system provides facilities to store file system data onto disk devices
64 and is intended to replace UFS as the default file system for
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 For a more detailed introduction refer to the paper listed in the
74 For some common usages of
80 All functions related to managing
82 file systems are provided by the
89 .Ss Instant Crash Recovery
90 After a non-graceful system shutdown,
92 file systems will be brought back into a fully coherent state
93 when mounting the file system, usually within a few seconds.
94 .Ss Large File Systems & Multi Volume
97 file system can span up to 256 volumes.
98 Each volume occupies a
100 disk slice or partition, or another special file,
101 and can be up to 4096 TB in size.
102 For volumes over 2 TB in size
106 normally need to be used.
107 .Ss Data Integrity Checking
109 has high focus on data integrity,
110 CRC checks are made for all major structures and data.
112 snapshots implements features to make data integrity checking easier:
113 The atime and mtime fields are locked to the ctime for files accessed via a snapshot.
116 field is based on the PFS
118 and not on any real device.
119 This means that archiving the contents of a snaphot with e.g.\&
121 and piping it to something like
123 will yield a consistent result.
124 The consistency is also retained on mirroring targets.
128 file system uses 64 bit, hexadecimal transaction IDs to refer to historical
129 file or directory data.
133 .Li 0x00000001061a8ba6 .
139 .Ss History & Snapshots
140 History metadata on the media is written with every sync operation, so that
141 by default the resolution of a file's history is 30-60 seconds until the next
143 Prior versions of files or directories are generally accessible by appending
145 and a transaction ID to the name.
146 The common way of accessing history, however, is by taking snapshots.
148 Snapshots are softlinks to prior versions of directories and their files.
149 Their data will be retained across prune operations for as long as the
151 Removing the softlink enables the file system to reclaim the space
152 again upon the next prune & reblock operations.
161 .Ss Pruning & Reblocking
162 Pruning is the act of deleting file system history.
163 Only history used by the given snapshots and history from after the latest
164 snapshot will be retained.
165 All other history is deleted.
166 Reblocking will reorder all elements and thus defragment the file system and
167 free space for reuse.
168 After pruning a file system must be reblocked to recover all available space.
169 Reblocking is needed even when using the
184 .Ss Mirroring & Pseudo File Systems
185 In order to allow inode numbers to be duplicated on the slaves
187 mirroring feature uses
188 .Dq Pseudo File Systems
192 file system supports up to 65535 PFSs.
193 Multiple slaves per master are supported, but multiple masters per slave
195 Slaves are always read-only.
196 Upgrading slaves to masters and downgrading masters to slaves are supported.
198 It is recommended to use a
200 mount to access a PFS;
201 this way no tools are confused by the PFS root being a symlink
202 and inodes not being unique across a
220 .Ar mirror-read-stream ,
225 file systems support NFS export.
226 NFS export of PFSs is done using
230 .Pa /hammer/pfs/data ,
235 and export the latter path.
237 Don't export a directory containing a PFS (e.g.\&
247 (subdirectory may be escaped if exported).
249 .Ss Preparing the File System
250 To create and mount a
259 file systems must have a unique name on a per-machine basis.
260 .Bd -literal -offset indent
261 newfs_hammer -L Home /dev/ad0s1d
262 mount_hammer /dev/ad0s1d /home
265 Similarly, multi volume file systems can be created and mounted by
266 specifying additional arguments.
267 .Bd -literal -offset indent
268 newfs_hammer -L MultiHome /dev/ad0s1d /dev/ad1s1d
269 mount_hammer /dev/ad0s1d /dev/ad1s1d /home
272 Once created and mounted,
274 file systems need periodic clean-up making snapshots, pruning and reblocking,
275 in order to have access to history and file system not to fill up.
276 For this it is recommended to use the
279 utility either manually or with a
282 For example, to clean-up all
284 file systems in use, including PFSs, every night at 2:15:
285 .Bd -literal -offset indent
286 15 2 * * * hammer cleanup >>/var/log/hammer.log 2>&1
289 It is also possible to make these operations individually.
290 For example, to reblock the
292 file system every night at 2:15 for up to 5 minutes:
293 .Bd -literal -offset indent
294 15 2 * * * hammer -c /var/run/Home.reblock -t 300 reblock /home \e
302 command provides several ways of taking snapshots.
303 They all assume a directory where snapshots are kept.
304 .Bd -literal -offset indent
306 hammer snapshot /home /snaps/snap1
307 (...after some changes in /home...)
308 hammer snapshot /home /snaps/snap2
313 point to the state of the
315 directory at the time each snapshot was taken, and could now be used to copy
316 the data somewhere else for backup purposes.
318 A snapshot directory is also the argument to the
321 command which frees historical data from the file system that is not
322 pointed to by any snapshot link and is not from after the latest snapshot.
323 .Bd -literal -offset indent
328 Unless the file system is mounted with the
330 option, it might be advisable to also set up
332 jobs for pruning no longer used historical data regularly.
333 For example, to prune the
335 directory every night at 3:15 for up to 5 minutes:
336 .Bd -literal -offset indent
337 15 3 * * * hammer -c /var/run/snaps.prune -t 300 prune /snaps \e
341 Mirroring can be set up using
344 To associate the slave with the master its shared UUID should be set to
345 the master's shared UUID as output by the
346 .Nm hammer Ar pfs-master
348 .Bd -literal -offset indent
349 hammer pfs-master /home/pfs/master
350 hammer pfs-slave /home/pfs/slave shared-uuid=<master's shared uuid>
355 link is unusable for as long as no mirroring operation has taken place.
357 To mirror the master's data, either pipe a
361 or, as a short-cut, use the
363 command (which works across a
366 Initial mirroring operation has to be done to the PFS path (as
368 can't access it yet).
369 .Bd -literal -offset indent
370 hammer mirror-copy /home/pfs/master /home/pfs/slave
373 After this initial step
375 mount can be setup for
376 .Pa /home/pfs/slave .
377 Further operations can use
380 .Bd -literal -offset indent
381 mount_null /home/pfs/master /home/master
382 mount_null /home/pfs/slave /home/slave
384 hammer mirror-copy /home/master /home/slave
387 To NFS export from the
393 without PFSs, and the PFS
394 .Pa /hammer/pfs/data ,
395 the latter is null mounted to
402 .Bd -literal -offset indent
403 /hammer/pfs/data /hammer/data null rw
410 .Bd -literal -offset indent
427 .%T "The HAMMER Filesystem"
432 file system first appeared in
438 file system was designed and implemented by
439 .An Matthew Dillon Aq dillon@backplane.com .
440 This manual page was written by