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