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.2.2.5 2008/09/28 22:06:39 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 null mounts, e.g.\&
228 .Pa /hammer/pfs/data ,
229 make a null mount, e.g.\& to
231 and export the latter path.
233 Don't export a directory containing a PFS (e.g.\&
243 (subdirectory may be escaped if exported).
245 .Ss Preparing the File System
246 To create and mount a
255 file systems must have a unique name on a per-machine basis.
256 .Bd -literal -offset indent
257 newfs_hammer -L Home /dev/ad0s1d
258 mount_hammer /dev/ad0s1d /home
261 Similarly, multi volume file systems can be created and mounted by
262 specifying additional arguments.
263 .Bd -literal -offset indent
264 newfs_hammer -L MultiHome /dev/ad0s1d /dev/ad1s1d
265 mount_hammer /dev/ad0s1d /dev/ad1s1d /home
268 Once created and mounted,
270 file systems need periodic clean-up making snapshots, pruning and reblocking,
271 in order to have access to history and file system not to fill up.
272 For this it is recommended to use the
275 utility either manually or with a
278 For example, to clean-up all
280 file systems in use, including PFSs, every night at 2:15:
281 .Bd -literal -offset indent
282 15 2 * * * hammer cleanup >>/var/log/hammer.log 2>&1
285 It is also possible to make these operations individually.
286 For example, to reblock the
288 file system every night at 2:15 for up to 5 minutes:
289 .Bd -literal -offset indent
290 15 2 * * * hammer -c /var/run/Home.reblock -t 300 reblock /home \e
298 command provides several ways of taking snapshots.
299 They all assume a directory where snapshots are kept.
300 .Bd -literal -offset indent
302 hammer snapshot /home /snaps/snap1
303 (...after some changes in /home...)
304 hammer snapshot /home /snaps/snap2
309 point to the state of the
311 directory at the time each snapshot was taken, and could now be used to copy
312 the data somewhere else for backup purposes.
314 A snapshot directory is also the argument to the
317 command which frees historical data from the file system that is not
318 pointed to by any snapshot link and is not from after the latest snapshot.
319 .Bd -literal -offset indent
324 Unless the file system is mounted with the
326 option, it might be advisable to also set up
328 jobs for pruning no longer used historical data regularly.
329 For example, to prune the
331 directory every night at 3:15 for up to 5 minutes:
332 .Bd -literal -offset indent
333 15 3 * * * hammer -c /var/run/snaps.prune -t 300 prune /snaps \e
337 Mirroring can be set up using
340 To associate the slave with the master its shared UUID should be set to
341 the master's shared UUID as output by the
342 .Nm hammer Ar pfs-master
344 .Bd -literal -offset indent
345 hammer pfs-master /home/pfs/master
346 hammer pfs-slave /home/pfs/slave shared-uuid=<master's shared uuid>
348 mount_null /home/pfs/master /home/master
349 mount_null /home/pfs/slave /home/slave
354 link is unusable for as long as no mirroring operation has taken place.
356 To mirror the master's data, either pipe a
360 or, as a short-cut, use the
362 command (which works across a
365 .Bd -literal -offset indent
366 hammer mirror-copy /home/master /home/slave
369 To NFS export from the
375 without PFSs, and the PFS
376 .Pa /hammer/pfs/data ,
377 the latter is null mounted to
384 .Bd -literal -offset indent
385 /hammer/pfs/data /hammer/data null rw
392 .Bd -literal -offset indent
409 .%T "The HAMMER Filesystem"
414 file system first appeared in
420 file system was designed and implemented by
421 .An Matthew Dillon Aq dillon@backplane.com .
422 This manual page was written by