| blob | 5cd001fbe3851f662ce9cfe182d65c79aabaa5e0 |
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.6 2008/10/10 18:18:12 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
227 .Nm null
228 mounts, e.g.\&
229 to export the PFS
230 .Pa /hammer/pfs/data ,
231 make a
232 .Nm null
233 mount, e.g.\& to
234 .Pa /hammer/data
235 and export the latter path.
236 .Pp
237 Don't export a directory containing a PFS (e.g.\&
238 .Pa /hammer/pfs
239 above).
240 Only
241 .Nm null
242 mount for PFS root
243 (e.g.\&
244 .Pa /hammer/data
245 above)
246 should be exported
247 (subdirectory may be escaped if exported).
248 .Sh EXAMPLES
249 .Ss Preparing the File System
250 To create and mount a
251 .Nm
252 file system use the
253 .Xr newfs_hammer 8
254 and
255 .Xr mount_hammer 8
256 commands.
257 Note that all
258 .Nm
259 file systems must have a unique name on a per-machine basis.
260 .Bd -literal -offset indent
261 newfs_hammer -L Home /dev/ad0s1d
262 mount_hammer /dev/ad0s1d /home
263 .Ed
264 .Pp
265 Similarly, multi volume file systems can be created and mounted by
266 specifying additional arguments.
267 .Bd -literal -offset indent
268 newfs_hammer -L MultiHome /dev/ad0s1d /dev/ad1s1d
269 mount_hammer /dev/ad0s1d /dev/ad1s1d /home
270 .Ed
271 .Pp
272 Once created and mounted,
273 .Nm
274 file systems need periodic clean-up making snapshots, pruning and reblocking,
275 in order to have access to history and file system not to fill up.
276 For this it is recommended to use the
277 .Xr hammer 8
278 .Ar cleanup
279 utility either manually or with a
280 .Xr cron 8
281 job.
282 For example, to clean-up all
283 .Nm
284 file systems in use, including PFSs, every night at 2:15:
285 .Bd -literal -offset indent
286 15 2 * * * hammer cleanup >>/var/log/hammer.log 2>&1
287 .Ed
288 .Pp
289 It is also possible to make these operations individually.
290 For example, to reblock the
291 .Pa /home
292 file system every night at 2:15 for up to 5 minutes:
293 .Bd -literal -offset indent
294 15 2 * * * hammer -c /var/run/Home.reblock -t 300 reblock /home \e
295 >/dev/null 2>&1
296 .Ed
297 .Ss Snapshots
298 The
299 .Xr hammer 8
300 utility's
301 .Ar snapshot
302 command provides several ways of taking snapshots.
303 They all assume a directory where snapshots are kept.
304 .Bd -literal -offset indent
305 mkdir /snaps
306 hammer snapshot /home /snaps/snap1
307 (...after some changes in /home...)
308 hammer snapshot /home /snaps/snap2
309 .Ed
310 .Pp
311 The softlinks in
312 .Pa /snaps
313 point to the state of the
314 .Pa /home
315 directory at the time each snapshot was taken, and could now be used to copy
316 the data somewhere else for backup purposes.
317 .Ss Pruning
318 A snapshot directory is also the argument to the
319 .Xr hammer 8 Ap s
320 .Ar prune
321 command which frees historical data from the file system that is not
322 pointed to by any snapshot link and is not from after the latest snapshot.
323 .Bd -literal -offset indent
324 rm /snaps/snap1
325 hammer prune /snaps
326 .Ed
327 .Pp
328 Unless the file system is mounted with the
329 .Ar nohistory
330 option, it might be advisable to also set up
331 .Xr cron 8
332 jobs for pruning no longer used historical data regularly.
333 For example, to prune the
334 .Pa /snaps
335 directory every night at 3:15 for up to 5 minutes:
336 .Bd -literal -offset indent
337 15 3 * * * hammer -c /var/run/snaps.prune -t 300 prune /snaps \e
338 >/dev/null 2>&1
339 .Ed
340 .Ss Mirroring
341 Mirroring can be set up using
342 .Nm Ap s
343 pseudo file systems.
344 To associate the slave with the master its shared UUID should be set to
345 the master's shared UUID as output by the
346 .Nm hammer Ar pfs-master
347 command.
348 .Bd -literal -offset indent
349 hammer pfs-master /home/pfs/master
350 hammer pfs-slave /home/pfs/slave shared-uuid=<master's shared uuid>
351 .Ed
352 .Pp
353 The
354 .Pa /home/pfs/slave
355 link is unusable for as long as no mirroring operation has taken place.
356 .Pp
357 To mirror the master's data, either pipe a
358 .Fa mirror-read
359 command into a
360 .Fa mirror-write
361 or, as a short-cut, use the
362 .Fa mirror-copy
363 command (which works across a
364 .Xr ssh 1
365 connection as well).
366 Initial mirroring operation has to be done to the PFS path (as
367 .Xr mount_null 8
368 can't access it yet).
369 .Bd -literal -offset indent
370 hammer mirror-copy /home/pfs/master /home/pfs/slave
371 .Ed
372 .Pp
373 After this initial step
374 .Nm null
375 mount can be setup for
376 .Pa /home/pfs/slave .
377 Further operations can use
378 .Nm null
379 mounts.
380 .Bd -literal -offset indent
381 mount_null /home/pfs/master /home/master
382 mount_null /home/pfs/slave /home/slave
384 hammer mirror-copy /home/master /home/slave
385 .Ed
386 .Ss NFS Export
387 To NFS export from the
388 .Nm
389 file system
390 .Pa /hammer
391 the directory
392 .Pa /hammer/non-pfs
393 without PFSs, and the PFS
394 .Pa /hammer/pfs/data ,
395 the latter is null mounted to
396 .Pa /hammer/data .
397 .Pp
398 Add to
399 .Pa /etc/fstab
400 (see
401 .Xr fstab 5 ) :
402 .Bd -literal -offset indent
403 /hammer/pfs/data /hammer/data null rw
404 .Ed
405 .Pp
406 Add to
407 .Pa /etc/exports
408 (see
409 .Xr exports 5 ) :
410 .Bd -literal -offset indent
411 /hammer/non-pfs
412 /hammer/data
413 .Ed
414 .Sh SEE ALSO
415 .Xr md5 1 ,
416 .Xr tar 1 ,
417 .Xr undo 1 ,
418 .Xr disklabel64 8 ,
419 .Xr gpt 8 ,
420 .Xr hammer 8 ,
421 .Xr mount_hammer 8 ,
422 .Xr mount_null 8 ,
423 .Xr newfs_hammer 8
424 .Rs
425 .%A Matthew Dillon
426 .%D June 2008
427 .%T "The HAMMER Filesystem"
428 .Re
429 .Sh HISTORY
430 The
431 .Nm
432 file system first appeared in
433 .Dx 1.11 .
434 .Sh AUTHORS
435 .An -nosplit
436 The
437 .Nm
438 file system was designed and implemented by
439 .An Matthew Dillon Aq dillon@backplane.com .
440 This manual page was written by
441 .An Sascha Wildner .