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