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