hammer.5: Add a reference to mneumann's KIT presentation slides.
[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 .Dd April 8, 2010
33 .Os
34 .Dt HAMMER 5
35 .Sh NAME
36 .Nm HAMMER
37 .Nd HAMMER file system
38 .Sh SYNOPSIS
39 To compile this driver into the kernel,
40 place the following line in your
41 kernel configuration file:
42 .Bd -ragged -offset indent
43 .Cd options HAMMER
44 .Ed
45 .Pp
46 Alternatively, to load the driver as a
47 module at boot time, place the following line in
48 .Xr loader.conf 5 :
49 .Bd -literal -offset indent
50 hammer_load="YES"
51 .Ed
52 .Pp
53 To mount via
54 .Xr fstab 5 :
55 .Bd -literal -offset indent
56 /dev/ad0s1d[:/dev/ad1s1d:...]   /mnt hammer rw 2 0
57 .Ed
58 .Sh DESCRIPTION
59 The
60 .Nm
61 file system provides facilities to store file system data onto disk devices
62 and is intended to replace
63 .Xr ffs 5
64 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 .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 .Xr chflags 1 ,
79 and
80 .Xr undo 1
81 utilities.
82 .Pp
83 For a more detailed introduction refer to the paper and slides listed in the
84 .Sx SEE ALSO
85 section.
86 For some common usages of
87 .Nm
88 see the
89 .Sx EXAMPLES
90 section below.
91 .Ss Instant Crash Recovery
92 After a non-graceful system shutdown,
93 .Nm
94 file systems will be brought back into a fully coherent state
95 when mounting the file system, usually within a few seconds.
96 .Ss Large File Systems & Multi Volume
97 A
98 .Nm
99 file system can be up to 1 Exabyte in size.
100 It can span up to 256 volumes,
101 each volume occupies a
102 .Dx
103 disk slice or partition, or another special file,
104 and can be up to 4096 TB in size.
105 Minimum recommended
106 .Nm
107 file system size is 50 GB.
108 For volumes over 2 TB in size
109 .Xr gpt 8
110 and
111 .Xr disklabel64 8
112 normally need to be used.
113 .Ss Data Integrity Checking
114 .Nm
115 has high focus on data integrity,
116 CRC checks are made for all major structures and data.
117 .Nm
118 snapshots implements features to make data integrity checking easier:
119 The atime and mtime fields are locked to the ctime
120 for files accessed via a snapshot.
121 The
122 .Fa st_dev
123 field is based on the PFS
124 .Ar shared-uuid
125 and not on any real device.
126 This means that archiving the contents of a snapshot with e.g.\&
127 .Xr tar 1
128 and piping it to something like
129 .Xr md5 1
130 will yield a consistent result.
131 The consistency is also retained on mirroring targets.
132 .Ss Transaction IDs
133 The
134 .Nm
135 file system uses 64 bit, hexadecimal transaction IDs to refer to historical
136 file or directory data.
137 An ID has the
138 .Xr printf 3
139 format
140 .Li %#016llx ,
141 such as
142 .Li 0x00000001061a8ba6 .
143 .Pp
144 Related
145 .Xr hammer 8
146 commands:
147 .Ar snapshot ,
148 .Ar synctid
149 .Ss History & Snapshots
150 History metadata on the media is written with every sync operation, so that
151 by default the resolution of a file's history is 30-60 seconds until the next
152 prune operation.
153 Prior versions of files or directories are generally accessible by appending
154 .Li @@
155 and a transaction ID to the name.
156 The common way of accessing history, however, is by taking snapshots.
157 .Pp
158 Snapshots are softlinks to prior versions of directories and their files.
159 Their data will be retained across prune operations for as long as the
160 softlink exists.
161 Removing the softlink enables the file system to reclaim the space
162 again upon the next prune & reblock operations.
163 .Pp
164 Related
165 .Xr hammer 8
166 commands:
167 .Ar cleanup ,
168 .Ar history ,
169 .Ar snapshot ;
170 see also
171 .Xr undo 1
172 .Ss Pruning & Reblocking
173 Pruning is the act of deleting file system history.
174 By default only history used by the given snapshots
175 and history from after the latest snapshot will be retained.
176 By setting the per PFS parameter
177 .Cm prune-min ,
178 history is guaranteed to be saved at least this time interval.
179 All other history is deleted.
180 Reblocking will reorder all elements and thus defragment the file system and
181 free space for reuse.
182 After pruning a file system must be reblocked to recover all available space.
183 Reblocking is needed even when using the
184 .Ar nohistory
185 .Xr mount_hammer 8
186 option or
187 .Xr chflags 1
188 flag.
189 .Pp
190 Related
191 .Xr hammer 8
192 commands:
193 .Ar cleanup ,
194 .Ar snapshot ,
195 .Ar prune ,
196 .Ar prune-everything ,
197 .Ar rebalance ,
198 .Ar reblock ,
199 .Ar reblock-btree ,
200 .Ar reblock-inodes ,
201 .Ar reblock-dirs ,
202 .Ar reblock-data
203 .Ss Mirroring & Pseudo File Systems
204 In order to allow inode numbers to be duplicated on the slaves
205 .Nm Ap s
206 mirroring feature uses
207 .Dq Pseudo File Systems
208 (PFSs).
209 A
210 .Nm
211 file system supports up to 65535 PFSs.
212 Multiple slaves per master are supported, but multiple masters per slave
213 are not.
214 Slaves are always read-only.
215 Upgrading slaves to masters and downgrading masters to slaves are supported.
216 .Pp
217 It is recommended to use a
218 .Nm null
219 mount to access a PFS;
220 this way no tools are confused by the PFS root being a symlink
221 and inodes not being unique across a
222 .Nm
223 file system.
224 .Pp
225 Related
226 .Xr hammer 8
227 commands:
228 .Ar pfs-master ,
229 .Ar pfs-slave ,
230 .Ar pfs-cleanup ,
231 .Ar pfs-status ,
232 .Ar pfs-update ,
233 .Ar pfs-destroy ,
234 .Ar pfs-upgrade ,
235 .Ar pfs-downgrade ,
236 .Ar mirror-copy ,
237 .Ar mirror-stream ,
238 .Ar mirror-read ,
239 .Ar mirror-read-stream ,
240 .Ar mirror-write ,
241 .Ar mirror-dump
242 .Ss NFS Export
243 .Nm
244 file systems support NFS export.
245 NFS export of PFSs is done using
246 .Nm null
247 mounts.
248 For example, to export the PFS
249 .Pa /hammer/pfs/data ,
250 create a
251 .Nm null
252 mount, e.g.\& to
253 .Pa /hammer/data
254 and export the latter path.
255 .Pp
256 Don't export a directory containing a PFS (e.g.\&
257 .Pa /hammer/pfs
258 above).
259 Only
260 .Nm null
261 mount for PFS root
262 (e.g.\&
263 .Pa /hammer/data
264 above)
265 should be exported
266 (subdirectory may be escaped if exported).
267 .Sh EXAMPLES
268 .Ss Preparing the File System
269 To create and mount a
270 .Nm
271 file system use the
272 .Xr newfs_hammer 8
273 and
274 .Xr mount_hammer 8
275 commands.
276 Note that all
277 .Nm
278 file systems must have a unique name on a per-machine basis.
279 .Bd -literal -offset indent
280 newfs_hammer -L HOME /dev/ad0s1d
281 mount_hammer /dev/ad0s1d /home
282 .Ed
283 .Pp
284 Similarly, multi volume file systems can be created and mounted by
285 specifying additional arguments.
286 .Bd -literal -offset indent
287 newfs_hammer -L MULTIHOME /dev/ad0s1d /dev/ad1s1d
288 mount_hammer /dev/ad0s1d /dev/ad1s1d /home
289 .Ed
290 .Pp
291 Once created and mounted,
292 .Nm
293 file systems need periodic clean up making snapshots, pruning and reblocking,
294 in order to have access to history and file system not to fill up.
295 For this it is recommended to use the
296 .Xr hammer 8
297 .Ar cleanup
298 metacommand.
299 .Pp
300 By default,
301 .Dx
302 is set up to run
303 .Nm hammer Ar cleanup
304 nightly via
305 .Xr periodic 8 .
306 .Pp
307 It is also possible to perform these operations individually via
308 .Xr crontab 5 .
309 For example, to reblock the
310 .Pa /home
311 file system every night at 2:15 for up to 5 minutes:
312 .Bd -literal -offset indent
313 15 2 * * * hammer -c /var/run/HOME.reblock -t 300 reblock /home \e
314         >/dev/null 2>&1
315 .Ed
316 .Ss Snapshots
317 The
318 .Xr hammer 8
319 utility's
320 .Ar snapshot
321 command provides several ways of taking snapshots.
322 They all assume a directory where snapshots are kept.
323 .Bd -literal -offset indent
324 mkdir /snaps
325 hammer snapshot /home /snaps/snap1
326 (...after some changes in /home...)
327 hammer snapshot /home /snaps/snap2
328 .Ed
329 .Pp
330 The softlinks in
331 .Pa /snaps
332 point to the state of the
333 .Pa /home
334 directory at the time each snapshot was taken, and could now be used to copy
335 the data somewhere else for backup purposes.
336 .Pp
337 By default,
338 .Dx
339 is set up to create nightly snapshots of all
340 .Nm
341 file systems via
342 .Xr periodic 8
343 and to keep them for 60 days.
344 .Ss Pruning
345 A snapshot directory is also the argument to the
346 .Xr hammer 8 Ap s
347 .Ar prune
348 command which frees historical data from the file system that is not
349 pointed to by any snapshot link and is not from after the latest snapshot.
350 .Bd -literal -offset indent
351 rm /snaps/snap1
352 hammer prune /snaps
353 .Ed
354 .Ss Mirroring
355 Mirroring can be set up using
356 .Nm Ap s
357 pseudo file systems.
358 To associate the slave with the master its shared UUID should be set to
359 the master's shared UUID as output by the
360 .Nm hammer Ar pfs-master
361 command.
362 .Bd -literal -offset indent
363 hammer pfs-master /home/pfs/master
364 hammer pfs-slave /home/pfs/slave shared-uuid=<master's shared uuid>
365 .Ed
366 .Pp
367 The
368 .Pa /home/pfs/slave
369 link is unusable for as long as no mirroring operation has taken place.
370 .Pp
371 To mirror the master's data, either pipe a
372 .Fa mirror-read
373 command into a
374 .Fa mirror-write
375 or, as a short-cut, use the
376 .Fa mirror-copy
377 command (which works across a
378 .Xr ssh 1
379 connection as well).
380 Initial mirroring operation has to be done to the PFS path (as
381 .Xr mount_null 8
382 can't access it yet).
383 .Bd -literal -offset indent
384 hammer mirror-copy /home/pfs/master /home/pfs/slave
385 .Ed
386 .Pp
387 After this initial step
388 .Nm null
389 mount can be setup for
390 .Pa /home/pfs/slave .
391 Further operations can use
392 .Nm null
393 mounts.
394 .Bd -literal -offset indent
395 mount_null /home/pfs/master /home/master
396 mount_null /home/pfs/slave /home/slave
397
398 hammer mirror-copy /home/master /home/slave
399 .Ed
400 .Ss NFS Export
401 To NFS export from the
402 .Nm
403 file system
404 .Pa /hammer
405 the directory
406 .Pa /hammer/non-pfs
407 without PFSs, and the PFS
408 .Pa /hammer/pfs/data ,
409 the latter is null mounted to
410 .Pa /hammer/data .
411 .Pp
412 Add to
413 .Pa /etc/fstab
414 (see
415 .Xr fstab 5 ) :
416 .Bd -literal -offset indent
417 /hammer/pfs/data /hammer/data null rw
418 .Ed
419 .Pp
420 Add to
421 .Pa /etc/exports
422 (see
423 .Xr exports 5 ) :
424 .Bd -literal -offset indent
425 /hammer/non-pfs
426 /hammer/data
427 .Ed
428 .Sh SEE ALSO
429 .Xr chflags 1 ,
430 .Xr md5 1 ,
431 .Xr tar 1 ,
432 .Xr undo 1 ,
433 .Xr exports 5 ,
434 .Xr ffs 5 ,
435 .Xr fstab 5 ,
436 .Xr disklabel64 8 ,
437 .Xr gpt 8 ,
438 .Xr hammer 8 ,
439 .Xr mount_hammer 8 ,
440 .Xr mount_null 8 ,
441 .Xr newfs_hammer 8
442 .Rs
443 .%A Matthew Dillon
444 .%D June 2008
445 .%O http://www.dragonflybsd.org/hammer/hammer.pdf
446 .%T "The HAMMER Filesystem"
447 .Re
448 .Rs
449 .%A Matthew Dillon
450 .%D October 2008
451 .%O http://www.dragonflybsd.org/hammer/nycbsdcon/
452 .%T "Slideshow from NYCBSDCon 2008"
453 .Re
454 .Rs
455 .%A Michael Neumann
456 .%D January 2010
457 .%O http://www.ntecs.de/sysarch09/HAMMER.pdf
458 .%T "Slideshow for a presentation held at KIT (http://www.kit.edu)."
459 .Re
460 .Sh FILESYSTEM PERFORMANCE
461 The
462 .Nm
463 file system has a front-end which processes VNOPS and issues necessary
464 block reads from disk, and a back-end which handles meta-data updates
465 on-media and performs all meta-data write operations.
466 Bulk file write operations are handled by the front-end.
467 Because
468 .Nm
469 defers meta-data updates virtually no meta-data read operations will be
470 issued by the frontend while writing large amounts of data to the file system
471 or even when creating new files or directories, and even though the
472 kernel prioritizes reads over writes the fact that writes are cached by
473 the drive itself tends to lead to excessive priority given to writes.
474 .Pp
475 There are four bioq sysctls, shown below with default values,
476 which can be adjusted to give reads a higher priority:
477 .Bd -literal -offset indent
478 kern.bioq_reorder_minor_bytes: 262144
479 kern.bioq_reorder_burst_bytes: 3000000
480 kern.bioq_reorder_minor_interval: 5
481 kern.bioq_reorder_burst_interval: 60
482 .Ed
483 .Pp
484 If a higher read priority is desired it is recommended that the
485 .Fa kern.bioq_reorder_minor_interval
486 be increased to 15, 30, or even 60, and the
487 .Fa kern.bioq_reorder_burst_bytes
488 be decreased to 262144 or 524288.
489 .Sh HISTORY
490 The
491 .Nm
492 file system first appeared in
493 .Dx 1.11 .
494 .Sh AUTHORS
495 .An -nosplit
496 The
497 .Nm
498 file system was designed and implemented by
499 .An Matthew Dillon Aq dillon@backplane.com .
500 This manual page was written by
501 .An Sascha Wildner .