hammer2 - cleanup, add manual page
[dragonfly.git] / sbin / hammer2 / hammer2.8
1 .\" Copyright (c) 2015 The DragonFly Project.  All rights reserved.
2 .\"
3 .\" This code is derived from software contributed to The DragonFly Project
4 .\" by Matthew Dillon <dillon@backplane.com>
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\"
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\"    notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\"    notice, this list of conditions and the following disclaimer in
14 .\"    the documentation and/or other materials provided with the
15 .\"    distribution.
16 .\" 3. Neither the name of The DragonFly Project nor the names of its
17 .\"    contributors may be used to endorse or promote products derived
18 .\"    from this software without specific, prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
23 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
24 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
25 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
26 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
27 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
28 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
29 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
30 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" SUCH DAMAGE.
32 .\"
33 .Dd March 26, 2015
34 .Dt HAMMER2 8
35 .Os
36 .Sh NAME
37 .Nm hammer2
38 .Nd hammer2 file system utility
39 .Sh SYNOPSIS
40 .Nm
41 .Fl h
42 .Nm
43 .Op Fl s Ar path
44 .Op Fl t Ar type
45 .Op Fl u Ar uuid
46 .Ar command
47 .Op Ar argument ...
48 .Sh DESCRIPTION
49 The
50 .Nm
51 utility provides miscellaneous support functions for a
52 HAMMER2 file system.
53 .Pp
54 The options are as follows:
55 .Bl -tag -width indent
56 .It Fl s Ar path
57 Specify the path to a mounted HAMMER2 filesystem.
58 At least one PFS on a HAMMER2 filesystem must be mounted for the system
59 to act on all PFSs managed by it.
60 Every HAMMER2 filesystem typically has a PFS called "LOCAL" for this purpose.
61 .It Fl t Ar type
62 Specify the type when creating, upgrading, or downgrading a PFS.
63 Supported types are CACHE, COPY, SLAVE, SOFT_SLAVE, MASTER, and SOFT_MASTER.
64 If not specified the pfs-create directive will default to MASTER if no
65 uuid is specified, and SLAVE if a uuid is specified.
66 .It Fl u Ar uuid
67 Specify the cluster uuid when creating a PFS.  If not specified, a unique,
68 random uuid will be generated.
69 Note that every PFS also has a unique pfs_id which is always generated
70 and cannot be overridden with an option.
71 The { pfs_clid, pfs_fsid } tuple uniquely identifies a component of a cluster.
72 .El
73 .Pp
74 .Nm
75 directives are as shown below.
76 Note that most directives require you to either be CD'd into a hammer2
77 filesystem, specify a path to a mounted hammer2 filesystem via the
78 .Fl s
79 option, or specify a path after the directive.
80 It depends on the directive.
81 All hammer2 filesystem have a PFS called "LOCAL" which is typically mounted
82 locally on the host in order to be able to issue commands for other PFSs
83 on the filesystem.
84 The mount also enables PFS configuration scanning for that filesystem.
85 .Bl -tag -width indent
86 .\" ==== connect ====
87 .It Cm connect Ar target
88 Add a cluster link entry to the volume header.
89 The volume header can support up to 255 link entries.
90 This feature is not currently used.
91 .\" ==== disconnect ====
92 .It Cm disconnect Ar target
93 Delete a cluster link entry from the volume header.
94 This feature is not currently used.
95 .\" ==== status ====
96 .It Cm status Ar path...
97 Dump a list of all cluster link entries configured in the volume header.
98 .\" ==== hash ====
99 .It Cm hash Ar filename...
100 Compute and print the directory hash for any number of filenames.
101 .\" ==== pfs-list ====
102 .It Cm pfs-list Op path...
103 List all local PFSs available on a mounted HAMMER2 filesystem, their type,
104 and their current status.
105 You must mount at least one PFS in order to be able to access the whole list.
106 .\" ==== pfs-clid ====
107 .It Cm pfs-clid Ar label
108 Print the cluster id for a PFS specified by name.
109 .\" ==== pfs-fsid ====
110 .It Cm pfs-fsid Ar label
111 Print the unique filesystem id for a PFS specified by name.
112 .\" ==== pfs-create ====
113 .It Cm pfs-create Ar label
114 Create a local PFS on a mounted HAMMER2 filesystem.
115 If no uuid is specified the pfs-type defaults to MASTER.
116 If a uuid is specified via the
117 .Fl u
118 option the pfs-type defaults to SLAVE.
119 If you wish to add a MASTER to an existing cluster, you must first add it as
120 a SLAVE and then upgrade it to MASTER to properly synchronize it.
121 Other types can be specified with the
122 .Fl t
123 option.
124 Generally speaking, you can mount any element of the cluster in order to
125 access the cluster via the full cluster protocol.
126 There are two exceptions.
127 If you mount a SOFT_SLAVE or a SOFT_MASTER then soft quorum semantics are
128 employed... the soft slave or soft master's current state will always be used
129 and the quorum protocol will not be used.  The soft PFS will still be
130 synchronized to masters in the background when available. 
131 Also, you can use 'mount -o local' to mount ONLY a local HAMMER2 PFS and
132 not run any network or quorum protocols for the mount.
133 All such mounts except for a SOFT_MASTER mount will be read-only.
134 Other than that, you will be mounting the whole cluster when you mount any
135 PFS within the cluster.
136 .Pp
137 DUMMY - Create a PFS skeleton intended to be the mount point for a
138 more complex cluster, probably one that is entirely network based.
139 No data will be synchronized to this PFS so it is suitable for use
140 in a network boot image or memory filesystem.
141 This allows you to create placeholders for mount points on your local
142 disk, SSD, or memory disk.
143 .Pp
144 CACHE - Create a PFS for caching portions of the cluster piecemeal.
145 This is similar to a SLAVE but does not synchronize the entire contents of
146 the cluster to the PFS.
147 Elements found in the CACHE PFS which are validated against the cluster
148 will be read, presumably a faster access than having to go to the cluster.
149 Only local CACHEs will be updated.
150 Network-accessable CACHE PFSs might be read but will not be written to.
151 If you have a large hard-drive-based cluster you can set up localized
152 SSD CACHE PFSs to improve performance.
153 .Pp
154 COPY - Create a PFS to store redundant copies of elements of the cluster.
155 (This has not been fleshed out yet).
156 .Pp
157 SLAVE - Create a PFS which maintains synchronization with and provides a
158 read-only copy of the cluster.
159 HAMMER2 will prioritize local SLAVEs for data retrieval after validating
160 their transaction id against the cluster.
161 The difference between a CACHE and a SLAVE is that the SLAVE is synchronized
162 to a full copy of the cluster and thus can serve as a backup or be staged
163 for use as a MASTER later on.
164 .Pp
165 SOFT_SLAVE - Create a PFS which maintains synchronization with and provides
166 a read-only copy of the cluster.
167 This is one of the special mount cases.  A SOFT_SLAVE will synchronize with
168 the cluster when the cluster is available, but can still be accessed when
169 the cluster is not available.
170 .Pp
171 MASTER - Create a PFS which will hold a master copy of the cluster.
172 If you create several MASTER PFSs with the same cluster id you are
173 effectively creating a multi-master cluster and causing a quorum and
174 cache coherency protocol to be used to validate operations.
175 The total number of masters is stored in each PFSs making up the cluster.
176 Filesystem operations will stall for normal mounts if a quorum cannot be
177 obtained to validate the operation.
178 MASTER nodes which go offline and return later will synchronize in the
179 background.
180 Note that when adding a MASTER to an existing cluster you must add the
181 new PFS as a SLAVE and then upgrade it to a MASTER.
182 .Pp
183 SOFT_MASTER - Create a PFS which maintains synchronization with and provides
184 a read-write copy of the cluster.
185 This is one of the special mount cases.  A SOFT_MASTER will synchronize with
186 the cluster when the cluster is available, but can still be read AND written
187 to even when the cluster is not available.
188 Modifications made to a SOFT_MASTER will be automatically flushed to the
189 cluster when it becomes accessible again, and vise-versa.
190 Manual intervention may be required if a conflict occurs during
191 synchronization.
192 .\" ==== pfs-delete ====
193 .It Cm pfs-delete Ar label
194 Delete a local PFS on a mounted HAMMER2 filesystem.
195 Deleting a PFS of type MASTER requires first downgrading it to a SLAVE (XXX).
196 .\" ==== snapshot ====
197 .It Cm snapshot Ar path Op label
198 Create a snapshot of a directory.
199 This can only be used on a local PFS, and is only really useful if the PFS
200 contains a complete copy of what you desire to snapshot so that typically
201 means a local MASTER, SOFT_MASTER, SLAVE, or SOFT_SLAVE must be present.
202 Snapshots are created simply by flushing a PFS mount to disk and then copying
203 the directory inode to the PFS.
204 The topology is snapshotted without having to be copied or scanned.
205 Snapshots are effectively separate from the cluster they came from
206 and can be used as a starting point for a new cluster.
207 So unless you build a new cluster from the snapshot, it will stay local
208 to the machine it was made on.
209 .\" ==== service ====
210 .It Cm service
211 Start the
212 .Nm
213 service daemon.
214 This daemon is also automatically started when you run
215 .Xr mount_hammer2 8 .
216 The hammer2 service daemon handles incoming TCP connections and maintains
217 outgoing TCP connections.  It will interconnect available services on the
218 machine (e.g. hammer2 mounts and xdisks) to the network.
219 .\" ==== stat ====
220 .It Cm stat Op path...
221 Print the inode statistics, compression, and other meta-data associated
222 with a list of paths.
223 .\" ==== leaf ====
224 .It Cm leaf
225 XXX
226 .\" ==== shell ====
227 .It Cm shell
228 Start a debug shell to the local hammer2 service daemon via the DMSG protocol.
229 .\" ==== debugspan ====
230 .It Cm debugspan
231 (do not use)
232 .\" ==== rsainit ====
233 .It Cm rsainit
234 Create the
235 .Pa /etc/hammer2
236 directory and initialize a public/private keypair in that directory for
237 use by the network cluster protocols.
238 .\" ==== show ====
239 .It Cm show Ar devpath
240 Dump the radix tree for the HAMMER2 filesystem by scanning a
241 block device directly.  No mount is required.
242 .\" ==== freemap ====
243 Dump the freemap tree for the HAMMER2 filesystem by scanning a
244 block device directly.  No mount is required.
245 .It Cm freemap Ar devpath
246 .\" ==== setcomp ====
247 .It Cm setcomp Ar mode[:level] Op path...
248 Set the compression mode as specified for any newly created elements at or
249 under the path if not overridden by deeper elements.
250 Available modes are none, autozero, lz4, or zlib.
251 When zlib is used the compression level can be set.
252 The default will be 6 which is the best trade-off between performance and
253 time.
254 .Pp
255 newfs_hammer2 will set the default compression to lz4 which prioritizes
256 speed over performance.
257 Also note that HAMMER2 contains a heuristic and will not attempt to
258 compress every block if it detects a sufficient amount of uncompressable
259 data.
260 .Pp
261 Hammer2 compression is only effective when it can reduce the size of dataset
262 (typically a 64KB block) by one or more powers of 2.  A 64K block which
263 only compresses to 40K will not yield any storage improvement.
264 .\" ==== setcheck ====
265 .It Cm setcheck Ar check Op path...
266 Set the check code as specified for any newly created elements at or under
267 the path if not overridden by deeper elements.
268 Available codes are default, disabled, crc32, crc64, or sha192.
269 .\" ==== clrcheck ====
270 .It Cm clrcheck Op path...
271 Clear the check code override for the specified paths.
272 Overrides may still be present in deeper elements.
273 .\" ==== setcrc32 ====
274 .It Cm setcrc32 Op path...
275 Set the check code to the ISCSI 32-bit CRC for any newly created elements
276 at or under the path if not overridden by deeper elements.
277 .\" ==== setcrc64 ====
278 .It Cm setcrc64 Op path...
279 Set the check code to CRC64 (not yet specified).
280 .\" ==== setsha192 ====
281 .It Cm setsha192 Op path...
282 Set the check code to SHA192 for any newly created elements at or under
283 the path if not overridden by deeper elements.
284 .\" ==== bulkfree ====
285 .It Cm bulkfree Op path...
286 Run a bulkfree pass on a HAMMER2 mount.
287 You can specify any PFS for the mount, the bulkfree pass is run on the
288 entire partition.
289 .El
290 .Sh SETTING UP /etc/hammer2
291 The 'rsainit' directive will create the
292 .Pa /etc/hammer2
293 directory with appropriate permissions and also generate a public key
294 pair in this directory for the machine.  These files will be
295 .Pa rsa.pub
296 and
297 .Pa rsa.prv
298 and needless to say, the private key shouldn't leave the host.
299 .Pp
300 The service daemon will also scan the
301 .Pa /etc/hammer2/autoconn
302 file which contains a list of hosts which it will automatically maintain
303 connections to to form your cluster.
304 The service daemon will automatically reconnect on any failure and will
305 also monitor the file for changes.
306 .Pp
307 When the service daemon receives a connection it expects to find a
308 public key for that connection in a file in
309 .Pa /etc/hammer2/remote/
310 called
311 .Pa <IPADDR>.pub .
312 You normally copy the
313 .Pa rsa.pub
314 key from the host in question to this file.
315 The IP address must match exactly or the connection will not be allowed.
316 .Pp
317 If you want to use an unencrypted connection you can create empty,
318 dummy files in the remote directory in the form
319 .Pa <IPADDR>.none .
320 We do not recommend using unencrypted connections.
321 .Sh CLUSTER SERVICES
322 Currently there are two services which use the cluster network infrastructure,
323 HAMMER2 mounts and XDISK.
324 Any HAMMER2 mount will make all PFSs for that filesystem available to the
325 cluster.
326 And if the XDISK kernel module is loaded, the hammer2 service daemon will make
327 your machine's block devices available to the cluster (you must load the
328 xdisk.ko kernel module before starting the hammer2 service).
329 They will show up as
330 .Pa /dev/xa*
331 and
332 .Pa /dev/serno/*
333 devices on the remote machines making up the cluster.
334 Remote block devices are just what they appear to be... direct access to a
335 block device on a remote machine.  If the link goes down remote accesses
336 will stall until it comes back up again, then automatically requeue any
337 pending I/O and resume as if nothing happened.
338 However, if the server hosting the physical disks crashes or is rebooted,
339 any remote opens to its devices will see a permanent I/O failure requiring a
340 close and open sequence to re-establish.
341 The latter is necessary because the server's drives might not have committed
342 the data before the crash, but had already acknowledged the transfer.
343 .Pp
344 Data commits work exactly the same as they do for real block devices.
345 The originater must issue a BUF_CMD_FLUSH.
346 .Sh ADDING A NEW MASTER TO A CLUSTER
347 When you
348 .Xr newfs_hammer2 8
349 a HAMMER2 filesystem or use the 'pfs-create' directive on one already mounted
350 to create a new PFS, with no special options, you wind up with a PFS
351 typed as a MASTER and a unique cluster uuid, but because there is only one 
352 PFS for that cluster (for each PFS you create via pfs-create), it will
353 act just like a normal filesystem would act and does not require any special
354 protocols to operate.
355 .Pp
356 If you use the 'pfs-create' directive along with the
357 .Fl u
358 option to specify a cluster uuid that already exists in the cluster,
359 you are adding a PFS to an existing cluster and this can trigger a whole
360 series of events in the background.
361 When you specify the
362 .Fl u
363 option in a 'pfs-create',
364 .Nm
365 will by default create a SLAVE PFS.
366 In fact, this is what must be created first even if you want to add a new
367 MASTER to your cluster.
368 .Pp
369 The most common action a system admin will want to take is to upgrade or
370 downgrade a PFS.
371 A new MASTER can be added to the cluster by upgrading an existing SLAVE
372 to MASTER.
373 A MASTER can be removed from the cluster by downgrading it to a SLAVE.
374 Upgrades and downgrades will put nodes in the cluster in a transition state
375 until the operation is complete.
376 For downgrades the transition state is fleeting unless one or more other
377 masters has not acknowledged the change.
378 For upgrades a background synchronization process must complete before the
379 transition can be said to be complete, and the node remains (really) a SLAVE
380 until that transition is complete.
381 .Sh USE CASES FOR A SOFT_MASTER
382 The SOFT_MASTER PFS type is a special type which must be specifically
383 mounted by a machine.
384 It is a R/W mount which does not use the quorum protocol and is not
385 cache coherent with the cluster, but which synchronizes from the cluster
386 and allows modifying operations which will synchronize to the cluster.
387 The most common case is to use a SOFT_MASTER PFS in a laptop allowing you
388 to work on your laptop when you are on the road and not connected to
389 your main servers, and for the laptop to synchronize when a connection is
390 available.
391 .Sh USE CASES FOR A SOFT_SLAVE
392 A SOFT_SLAVE PFS type is a special type which must be specifically mounted
393 by a machine.
394 It is a RO mount which does not use the quorum protocol and is not
395 cache coherent with the cluster.  It will receive synchronization from
396 the cluster when network connectivity is available but will not stall if
397 network connectivity is lost.
398 .Sh FSYNC FLUSH MODES
399 TODO.
400 .Sh RESTORING FROM A SNAPSHOT BACKUP
401 TODO.
402 .Sh ENVIRONMENT
403 TODO.
404 .Sh FILES
405 .Bl -tag -width ".It Pa <fs>/abc/defghi/<name>" -compact
406 .It Pa /etc/hammer2/
407 .It Pa /etc/hammer2/rsa.pub
408 .It Pa /etc/hammer2/rsa.prv
409 .It Pa /etc/hammer2/autoconn
410 .It Pa /etc/hammer2/remote/<IP>.pub
411 .It Pa /etc/hammer2/remote/<IP>.none
412 .El
413 .Sh EXIT STATUS
414 .Ex -std
415 .Sh SEE ALSO
416 .Xr mount_hammer2 8 ,
417 .Xr mount_null 8 ,
418 .Xr newfs_hammer2 8 ,
419 .Xr swapcache 8 ,
420 .Xr sysctl 8
421 .Sh HISTORY
422 The
423 .Nm
424 utility first appeared in
425 .Dx 4.1 .
426 .Sh AUTHORS
427 .An Matthew Dillon Aq Mt dillon@backplane.com