| blob | 87769ab4b8f36c1b1f671097935dc744619a1503 |
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.2.2.5 2008/09/28 22:06:39 thomas Exp $
33 .\"
34 .Dd September 28, 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 UFS as the default file system for
65 .Dx .
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
72 .Sx SEE ALSO
73 section.
74 For some common usages of
75 .Nm
76 see the
77 .Sx EXAMPLES
78 section below.
79 .Pp
80 All functions related to managing
81 .Nm
82 file systems are provided by the
83 .Xr newfs_hammer 8 ,
84 .Xr mount_hammer 8 ,
85 .Xr hammer 8 ,
86 and
87 .Xr undo 1
88 utilities.
89 .Ss Instant Crash Recovery
90 After a non-graceful system shutdown,
91 .Nm
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
95 A
96 .Nm
97 file system can span up to 256 volumes.
98 Each volume occupies a
99 .Dx
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
103 .Xr gpt 8
104 and
105 .Xr disklabel64 8
106 normally need to be used.
107 .Ss Data Integrity Checking
108 .Nm
109 has high focus on data integrity,
110 CRC checks are made for all major structures and data.
111 .Nm
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.
114 The
115 .Fa st_dev
116 field is based on the PFS
117 .Ar shared-uuid
118 and not on any real device.
119 This means that archiving the contents of a snaphot with e.g.\&
120 .Xr tar 1
121 and piping it to something like
122 .Xr md5 1
123 will yield a consistent result.
124 The consistency is also retained on mirroring targets.
125 .Ss Transaction IDs
126 The
127 .Nm
128 file system uses 64 bit, hexadecimal transaction IDs to refer to historical
129 file or directory data.
130 An ID has the format
131 .Li 0x%016llx ,
132 such as
133 .Li 0x00000001061a8ba6 .
134 .Pp
135 Related
136 .Xr hammer 8
137 commands:
138 .Ar synctid
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
142 prune operation.
143 Prior versions of files or directories are generally accessible by appending
144 .Li @@
145 and a transaction ID to the name.
146 The common way of accessing history, however, is by taking snapshots.
147 .Pp
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
150 softlink exists.
151 Removing the softlink enables the file system to reclaim the space
152 again upon the next prune & reblock operations.
153 .Pp
154 Related
155 .Xr hammer 8
156 commands:
157 .Ar history ,
158 .Ar snapshot ;
159 see also
160 .Xr undo 1
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
170 .Ar nohistory
171 .Xr mount_hammer 8
172 option.
173 .Pp
174 Related
175 .Xr hammer 8
176 commands:
177 .Ar reblock ,
178 .Ar reblock-btree ,
179 .Ar reblock-inodes ,
180 .Ar reblock-dirs ,
181 .Ar reblock-data ,
182 .Ar prune ,
183 .Ar prune-everything
184 .Ss Mirroring & Pseudo File Systems
185 In order to allow inode numbers to be duplicated on the slaves
186 .Nm Ap s
187 mirroring feature uses
188 .Dq Pseudo File Systems
189 (PFSs).
190 A
191 .Nm
192 file system supports up to 65535 PFSs.
193 Multiple slaves per master are supported, but multiple masters per slave
194 are not.
195 Slaves are always read-only.
196 Upgrading slaves to masters and downgrading masters to slaves are supported.
197 .Pp
198 It is recommended to use a
199 .Nm null
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
203 .Nm
204 file system.
205 .Pp
206 Related
207 .Xr hammer 8
208 commands:
209 .Ar pfs-master ,
210 .Ar pfs-slave ,
211 .Ar pfs-cleanup ,
212 .Ar pfs-status ,
213 .Ar pfs-update ,
214 .Ar pfs-destroy ,
215 .Ar pfs-upgrade ,
216 .Ar pfs-downgrade ,
217 .Ar mirror-copy ,
218 .Ar mirror-stream ,
219 .Ar mirror-read ,
220 .Ar mirror-read-stream ,
221 .Ar mirror-write ,
222 .Ar mirror-dump
223 .Ss NFS Export
224 .Nm
225 file systems support NFS export.
226 NFS export of PFSs is done using null mounts, e.g.\&
227 to export the PFS
228 .Pa /hammer/pfs/data ,
229 make a null mount, e.g.\& to
230 .Pa /hammer/data
231 and export the latter path.
232 .Pp
233 Don't export a directory containing a PFS (e.g.\&
234 .Pa /hammer/pfs
235 above).
236 Only
237 .Nm null
238 mount for PFS root
239 (e.g.\&
240 .Pa /hammer/data
241 above)
242 should be exported
243 (subdirectory may be escaped if exported).
244 .Sh EXAMPLES
245 .Ss Preparing the File System
246 To create and mount a
247 .Nm
248 file system use the
249 .Xr newfs_hammer 8
250 and
251 .Xr mount_hammer 8
252 commands.
253 Note that all
254 .Nm
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
259 .Ed
260 .Pp
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
266 .Ed
267 .Pp
268 Once created and mounted,
269 .Nm
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
273 .Xr hammer 8
274 .Ar cleanup
275 utility either manually or with a
276 .Xr cron 8
277 job.
278 For example, to clean-up all
279 .Nm
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
283 .Ed
284 .Pp
285 It is also possible to make these operations individually.
286 For example, to reblock the
287 .Pa /home
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
291 >/dev/null 2>&1
292 .Ed
293 .Ss Snapshots
294 The
295 .Xr hammer 8
296 utility's
297 .Ar snapshot
298 command provides several ways of taking snapshots.
299 They all assume a directory where snapshots are kept.
300 .Bd -literal -offset indent
301 mkdir /snaps
302 hammer snapshot /home /snaps/snap1
303 (...after some changes in /home...)
304 hammer snapshot /home /snaps/snap2
305 .Ed
306 .Pp
307 The softlinks in
308 .Pa /snaps
309 point to the state of the
310 .Pa /home
311 directory at the time each snapshot was taken, and could now be used to copy
312 the data somewhere else for backup purposes.
313 .Ss Pruning
314 A snapshot directory is also the argument to the
315 .Xr hammer 8 Ap s
316 .Ar prune
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
320 rm /snaps/snap1
321 hammer prune /snaps
322 .Ed
323 .Pp
324 Unless the file system is mounted with the
325 .Ar nohistory
326 option, it might be advisable to also set up
327 .Xr cron 8
328 jobs for pruning no longer used historical data regularly.
329 For example, to prune the
330 .Pa /snaps
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
334 >/dev/null 2>&1
335 .Ed
336 .Ss Mirroring
337 Mirroring can be set up using
338 .Nm Ap s
339 pseudo file systems.
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
343 command.
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
350 .Ed
351 .Pp
352 The
353 .Pa /home/slave
354 link is unusable for as long as no mirroring operation has taken place.
355 .Pp
356 To mirror the master's data, either pipe a
357 .Fa mirror-read
358 command into a
359 .Fa mirror-write
360 or, as a short-cut, use the
361 .Fa mirror-copy
362 command (which works across a
363 .Xr ssh 1
364 connection as well).
365 .Bd -literal -offset indent
366 hammer mirror-copy /home/master /home/slave
367 .Ed
368 .Ss NFS Export
369 To NFS export from the
370 .Nm
371 file system
372 .Pa /hammer
373 the directory
374 .Pa /hammer/non-pfs
375 without PFSs, and the PFS
376 .Pa /hammer/pfs/data ,
377 the latter is null mounted to
378 .Pa /hammer/data .
379 .Pp
380 Add to
381 .Pa /etc/fstab
382 (see
383 .Xr fstab 5 ) :
384 .Bd -literal -offset indent
385 /hammer/pfs/data /hammer/data null rw
386 .Ed
387 .Pp
388 Add to
389 .Pa /etc/exports
390 (see
391 .Xr exports 5 ) :
392 .Bd -literal -offset indent
393 /hammer/non-pfs
394 /hammer/data
395 .Ed
396 .Sh SEE ALSO
397 .Xr md5 1 ,
398 .Xr tar 1 ,
399 .Xr undo 1 ,
400 .Xr disklabel64 8 ,
401 .Xr gpt 8 ,
402 .Xr hammer 8 ,
403 .Xr mount_hammer 8 ,
404 .Xr mount_null 8 ,
405 .Xr newfs_hammer 8
406 .Rs
407 .%A Matthew Dillon
408 .%D June 2008
409 .%T "The HAMMER Filesystem"
410 .Re
411 .Sh HISTORY
412 The
413 .Nm
414 file system first appeared in
415 .Dx 1.11 .
416 .Sh AUTHORS
417 .An -nosplit
418 The
419 .Nm
420 file system was designed and implemented by
421 .An Matthew Dillon Aq dillon@backplane.com .
422 This manual page was written by
423 .An Sascha Wildner .