* Add some lines about HAMMER mirroring which are based on a nice explanation
[dragonfly.git] / 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.6 2008/07/18 22:54:52 swildner Exp $
33 .\"
34 .Dd July 18, 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 a disk device
64 and is intended to replace UFS as the default file system for
65 .Dx .
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
69 .Sx SEE ALSO
70 section.
71 .Pp
72 All functions related to managing
73 .Nm
74 file systems are provided by the
75 .Xr newfs_hammer 8 ,
76 .Xr mount_hammer 8 ,
77 .Xr hammer 8 ,
78 and
79 .Xr undo 1
80 utilities.
81 .Ss Transaction IDs
82 The
83 .Nm
84 file system uses 64 bit, hexadecimal transaction IDs to refer to historical
85 file or directory data.
86 An ID has the format
87 .Li 0x%016llx ,
88 such as
89 .Li 0x00000001061a8ba6 .
90 .Pp
91 Related
92 .Xr hammer 8
93 commands:
94 .Ar synctid
95 .Ss History
96 History metadata on the media is written with every sync operation.
97 Prior versions of files or directories are accessible by appending
98 .Li @@
99 and a transaction ID to the name.
100 .Ss Snapshots
101 Snapshots are symbolic links to specific versions of directories or files,
102 prior or current.
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.
107 .Pp
108 Related
109 .Xr hammer 8
110 commands:
111 .Ar snapshot
112 .Ss Reblocking & Pruning
113 Reblocking will reorder all elements and thus defragment the file system and
114 free space for reuse.
115 Pruning a
116 .Nm
117 file system free all historical records no longer used by any snapshots.
118 .Pp
119 Related
120 .Xr hammer 8
121 commands:
122 .Ar reblock ,
123 .Ar reblock-btree ,
124 .Ar reblock-inodes ,
125 .Ar reblock-dirs ,
126 .Ar reblock-data ,
127 .Ar prune ,
128 .Ar prune-everything
129 .Ss Mirroring & Pseudo File Systems
130 In order to allow inode numbers to be duplicated on the slaves
131 .Nm Ap s
132 mirroring feature uses
133 .Dq Pseudo File Systems
134 (PFSs).
135 A
136 .Nm
137 file system supports up to 65536 PFSs.
138 Multiple slaves per master are supported, but multiple masters per slave
139 are not.
140 Slaves are always read-only.
141 Upgrading slaves to masters and downgrading masters to slaves are supported.
142 .Pp
143 Related
144 .Xr hammer 8
145 commands:
146 .Ar pfs-master ,
147 .Ar pfs-slave ,
148 .Ar pfs-status ,
149 .Ar pfs-update ,
150 .Ar pfs-destroy ,
151 .Ar pfs-upgrade ,
152 .Ar pfs-downgrade ,
153 .Ar mirror-copy ,
154 .Ar mirror-read ,
155 .Ar mirror-write ,
156 .Ar mirror-dump
157 .Sh EXAMPLES
158 .Ss Preparing the file system
159 To create and mount a
160 .Nm
161 file system use the
162 .Xr newfs_hammer 8
163 and
164 .Xr mount_hammer 8
165 commands.
166 Note that all
167 .Nm
168 file systems must have a unique name on a per-machine basis.
169 .Bd -literal
170 newfs_hammer -L Home /dev/ad0s1d
171 mount_hammer /dev/ad0s1d /home
172 .Ed
173 .Pp
174 Similarly, multi volume file systems can be created and mounted by
175 specifying additional arguments.
176 .Bd -literal
177 newfs_hammer -L MultiHome /dev/ad0s1d /dev/ad1s1d
178 mount_hammer /dev/ad0s1d /dev/ad1s1d /home
179 .Ed
180 .Pp
181 Once created and mounted,
182 .Nm
183 file systems need to be reblocked periodically in order not to fill up
184 over time, either manually or with a
185 .Xr cron 8
186 job.
187 It is recommended that the
188 .Xr hammer 8
189 utility's
190 .Fl c
191 and
192 .Fl t
193 options be used for this job (for example, every night at 2:15 up to 5
194 minutes).
195 .Bd -literal
196 15 2 * * * hammer -c /var/run/Home -t 300 reblock /home >/dev/null 2>&1
197 .Ed
198 .Ss Snapshots
199 The
200 .Xr hammer 8
201 utility's
202 .Ar snapshot
203 command provides several ways of taking snapshots.
204 They all assume a directory where snapshots are kept.
205 .Bd -literal
206 mkdir /snaps
207 hammer snapshot /home /snaps/snap1
208 (...after some changes in /home...)
209 hammer snapshot /home /snaps/snap2
210 .Ed
211 .Ss Pruning
212 A snapshot directory is also the argument to the
213 .Xr hammer 8 Ap s
214 .Ar prune
215 command which frees historical data from the file system that is no longer
216 pointed to by any snapshot link.
217 .Bd -literal
218 rm /snaps/snap1
219 hammer prune /snaps
220 .Ed
221 .Pp
222 Unless the file system is mounted with the
223 .Ar nohistory
224 option, it might be advisable to also set up
225 .Xr cron 8
226 jobs for pruning no longer used historical data regularly.
227 .Ss Mirroring
228 Mirroring can be set up using
229 .Nm Ap s
230 pseudo file systems.
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
234 command.
235 .Bd -literal
236 hammer pfs-master /home/master
237 hammer pfs-slave /home/slave shared-uuid=<master's shared uuid>
238 .Ed
239 .Pp
240 The
241 .Pa /home/slave
242 link is unusable for as long as no mirroring operation has taken place.
243 .Pp
244 To mirror the master's data, either pipe a
245 .Fa mirror-read
246 command into a
247 .Fa mirror-write
248 or, as a short-cut, use the
249 .Fa mirror-copy
250 command (which works across a
251 .Xr ssh 1
252 connection as well).
253 .Bd -literal
254 hammer mirror-copy /home/master /home/slave
255 .Ed
256 .Sh SEE ALSO
257 .Xr undo 1 ,
258 .Xr hammer 8 ,
259 .Xr mount_hammer 8 ,
260 .Xr newfs_hammer 8
261 .Rs
262 .%A Matthew Dillon
263 .%D June 2008
264 .%T "The HAMMER Filesystem"
265 .Re
266 .Sh HISTORY
267 The
268 .Nm
269 file system first appeared in
270 .Dx 1.11 .
271 .Sh AUTHORS
272 .An -nosplit
273 The
274 .Nm
275 file system was designed and implemented by
276 .An Matthew Dillon Aq dillon@backplane.com .
277 This manual page was written by
278 .An Sascha Wildner .