Make HAMMER build and work as a module and extend hammer(5)'s SYNOPSIS
[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.3 2008/07/17 00:16:14 swildner Exp $
33 .\"
34 .Dd July 16, 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 In
56 .Xr fstab 5 :
57 .Bd -literal
58 # single volume
59 #
60 /dev/disk0a     /mnt hammer rw 2 0
61
62 # multi volume
63 #
64 /dev/disk0a:/dev/disk1a:/dev/disk2a     /mnt hammer rw 2 0
65 .Ed
66 .Sh DESCRIPTION
67 The
68 .Nm
69 file system provides facilities to store file system data onto a disk device
70 and is intended to replace UFS as the default file system for
71 .Dx .
72 Among its features are fine grained history retention, file systems spanning
73 multiple volumes, mirroring capability, and pseudo file systems.
74 .Pp
75 All functions related to managing
76 .Nm
77 file systems are provided by the
78 .Xr newfs_hammer 8 ,
79 .Xr mount_hammer 8 ,
80 .Xr hammer 8 ,
81 and
82 .Xr undo 1
83 utilities.
84 .Ss Transaction IDs
85 The
86 .Nm
87 file system uses 64 bit, hexadecimal transaction IDs to refer to historical
88 file or directory data.
89 An ID has the format
90 .Li 0x%016llx ,
91 such as
92 .Li 0x00000001061a8ba6 .
93 .Ss History & Pruning
94 History metadata on the media is updated with every sync operation.
95 Prior versions of files or directories are accessible by appending
96 .Li @@
97 and a transaction ID to the name.
98 Pruning a
99 .Nm
100 file system will free all unused historical records.
101 .Ss Snapshots
102 A snapshot can be taken by creating a symbolic link to a specific
103 version of a file or directory.
104 Snapshots created this way will be retained across subsequent prune
105 operations.
106 Removing the symbolic link enables the file system to reclaim the space
107 again.
108 .\".Ss Mirroring
109 .\".Ss Pseudo File Systems
110 .Sh EXAMPLES
111 .Ss Preparing the file system
112 To create and mount a
113 .Nm
114 file system use the
115 .Xr newfs_hammer 8
116 and
117 .Xr mount_hammer 8
118 commands.
119 Note that all
120 .Nm
121 file systems must have a unique name on a per-machine basis.
122 .Bd -literal
123 newfs_hammer -L Home /dev/ad0s1d
124 mount_hammer /dev/ad0s1d /home
125 .Ed
126 .Pp
127 Similarly, multi volume file systems can be created and mounted by just
128 specifying more arguments.
129 .Bd -literal
130 newfs_hammer -L MultiHome /dev/ad0s1d /dev/ad1s1d
131 mount_hammer /dev/ad0s1d /dev/ad1s1d /home
132 .Ed
133 .Pp
134 Once created and mounted,
135 .Nm
136 file systems need to be reblocked periodically in order not to fill up
137 over time, either manually or with a
138 .Xr cron 8
139 job.
140 It is recommended that the
141 .Xr hammer 8
142 utility's
143 .Fl c
144 and
145 .Fl t
146 options be used for this job (for example, every night up to 5 minutes).
147 .Bd -literal
148 2 15 * * * hammer -c /var/run/Home -t 300 reblock /home >/dev/null 2>&1
149 .Ed
150 .Sh SEE ALSO
151 .Xr undo 1 ,
152 .Xr hammer 8 ,
153 .Xr mount_hammer 8 ,
154 .Xr newfs_hammer 8
155 .Rs
156 .%A Matthew Dillon
157 .%D June 2008
158 .%T "The HAMMER Filesystem"
159 .Re
160 .Sh HISTORY
161 The
162 .Nm
163 file system first appeared in
164 .Dx 1.11 .
165 .Sh AUTHORS
166 .An -nosplit
167 The
168 .Nm
169 file system was designed and implemented by
170 .An Matthew Dillon Aq dillon@backplane.com .
171 This manual page was written by
172 .An Sascha Wildner .