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.2 2008/07/18 23:28:02 swildner Exp $
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 a disk device
64 and is intended to replace UFS as the default file system for
66 Among its features are fine grained history retention, file systems spanning
67 multiple volumes, mirroring capability, and pseudo file systems.
68 For a more detailed introduction, see the paper listed in the
72 All functions related to managing
74 file systems are provided by the
84 file system uses 64 bit, hexadecimal transaction IDs to refer to historical
85 file or directory data.
89 .Li 0x00000001061a8ba6 .
96 History metadata on the media is written with every sync operation.
97 Prior versions of files or directories are accessible by appending
99 and a transaction ID to the name.
101 Snapshots are symbolic links to specific versions of directories or files,
103 Their data will be retained across prune operations for as long as the
104 symbolic link exists.
105 Removing the symbolic link enables the file system to reclaim the space
106 again upon the next reblock operation.
112 .Ss Reblocking & Pruning
113 Reblocking will reorder all elements and thus defragment the file system and
114 free space for reuse.
117 file system free all historical records no longer used by any snapshots.
129 .Ss Mirroring & Pseudo File Systems
130 In order to allow inode numbers to be duplicated on the slaves
132 mirroring feature uses
133 .Dq Pseudo File Systems
137 file system supports up to 65536 PFSs.
138 Multiple slaves per master are supported, but multiple masters per slave
140 Slaves are always read-only.
141 Upgrading slaves to masters and downgrading masters to slaves are supported.
158 .Ss Preparing the file system
159 To create and mount a
168 file systems must have a unique name on a per-machine basis.
170 newfs_hammer -L Home /dev/ad0s1d
171 mount_hammer /dev/ad0s1d /home
174 Similarly, multi volume file systems can be created and mounted by
175 specifying additional arguments.
177 newfs_hammer -L MultiHome /dev/ad0s1d /dev/ad1s1d
178 mount_hammer /dev/ad0s1d /dev/ad1s1d /home
181 Once created and mounted,
183 file systems need to be reblocked periodically in order not to fill up
184 over time, either manually or with a
187 It is recommended that the
193 options be used for this job (for example, every night at 2:15 up to 5
196 15 2 * * * hammer -c /var/run/Home -t 300 reblock /home >/dev/null 2>&1
203 command provides several ways of taking snapshots.
204 They all assume a directory where snapshots are kept.
207 hammer snapshot /home /snaps/snap1
208 (...after some changes in /home...)
209 hammer snapshot /home /snaps/snap2
212 A snapshot directory is also the argument to the
215 command which frees historical data from the file system that is no longer
216 pointed to by any snapshot link.
222 Unless the file system is mounted with the
224 option, it might be advisable to also set up
226 jobs for pruning no longer used historical data regularly.
228 Mirroring can be set up using
231 To associate the slave with the master its shared UUID should be set to
232 the master's shared UUID as output by the
233 .Nm hammer Ar pfs-master
236 hammer pfs-master /home/master
237 hammer pfs-slave /home/slave shared-uuid=<master's shared uuid>
242 link is unusable for as long as no mirroring operation has taken place.
244 To mirror the master's data, either pipe a
248 or, as a short-cut, use the
250 command (which works across a
254 hammer mirror-copy /home/master /home/slave
264 .%T "The HAMMER Filesystem"
269 file system first appeared in
275 file system was designed and implemented by
276 .An Matthew Dillon Aq dillon@backplane.com .
277 This manual page was written by