00bf94ef5475ec02c7cdf9bea97eb132ed9eea16
[dragonfly.git] / sbin / hammer2 / hammer2.8
1 .\" Copyright (c) 2015-2019 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 September 29, 2019
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 .Op Fl m Ar mem
47 .Ar command
48 .Op Ar argument ...
49 .Sh DESCRIPTION
50 The
51 .Nm
52 utility provides miscellaneous support functions for a
53 HAMMER2 file system.
54 .Pp
55 The options are as follows:
56 .Bl -tag -width indent
57 .It Fl s Ar path
58 Specify the path to a mounted HAMMER2 filesystem.
59 At least one PFS on a HAMMER2 filesystem must be mounted for the system
60 to act on all PFSs managed by it.
61 Every HAMMER2 filesystem typically has a PFS called "LOCAL" for this purpose.
62 .It Fl t Ar type
63 Specify the type when creating, upgrading, or downgrading a PFS.
64 Supported types are MASTER, SLAVE, SOFT_MASTER, SOFT_SLAVE, CACHE, and DUMMY.
65 If not specified the pfs-create directive will default to MASTER if no
66 UUID is specified, and SLAVE if a UUID is specified.
67 .It Fl u Ar uuid
68 Specify the cluster UUID when creating a PFS.
69 If not specified, a unique, random UUID will be generated.
70 Note that every PFS also has a unique pfs_id which is always generated
71 and cannot be overridden with an option.
72 The { pfs_clid, pfs_fsid } tuple uniquely identifies a component of a cluster.
73 .It Fl m Ar mem
74 Specify how much tracking memory to use for certain directives.
75 At the moment, this option is only applicable to the
76 .Cm bulkfree
77 directive, allowing it to operate in fewer passes when given more memory.
78 A nominal value for a 4TB drive with a ton of stuff on it would be around
79 a gigabyte '-m 1g'.
80 .El
81 .Pp
82 .Nm
83 directives are as shown below.
84 Note that most directives require you to either be CD'd into a hammer2
85 filesystem, specify a path to a mounted hammer2 filesystem via the
86 .Fl s
87 option, or specify a path after the directive.
88 It depends on the directive.
89 All hammer2 filesystem have a PFS called "LOCAL" which is typically mounted
90 locally on the host in order to be able to issue commands for other PFSs
91 on the filesystem.
92 The mount also enables PFS configuration scanning for that filesystem.
93 .Bl -tag -width indent
94 .\" ==== cleanup ====
95 .It Cm cleanup Op path
96 Perform manual cleanup passes on paths or all mounted partitions.
97 .\" ==== connect ====
98 .It Cm connect Ar target
99 Add a cluster link entry to the volume header.
100 The volume header can support up to 255 link entries.
101 This feature is not currently used.
102 .\" ==== destroy ====
103 .It Cm destroy Ar path...
104 Destroy the specified directory entry in a hammer2 filesystem.
105 This bypasses
106 all normal checks and will unconditionally destroy the directory entry.
107 The underlying inode is not checked and, if it does exist, its nlinks count
108 is not decremented.
109 This directive should only be used to destroy a corrupted directory entry
110 which no longer has a working inode.
111 .Pp
112 Note that this command may desynchronize the system namecache for the
113 specified entry.
114 If this happens, you may have to unmount and remount the filesystem.
115 .\" ==== destroy-inum ====
116 .It Cm destroy-inum Ar path...
117 Destroy the specified inode in a hammer2 filesystem.
118 .\" ==== disconnect ====
119 .It Cm disconnect Ar target
120 Delete a cluster link entry from the volume header.
121 This feature is not currently used.
122 .\" ==== emergency-mode-enable ===
123 .It Cm emergency-mode-enable Ar target
124 Flag emergency operations mode in the filesystem.
125 This mode may be used
126 as a last resort to delete files and directories from a full filesystem.
127 Inode creation, file writes, and certain meta-data cleanups are disallowed
128 while emergency mode is active.
129 File and directory removal and mode/attr setting is still allowed.
130 This mode is extremely dangerous and should only be used as a last resort.
131 .Pp
132 This mode allows the filesystem to modify blocks in-place when it is unable
133 to allocate a copy.
134 Thus it is possible to chflags and remove files and
135 directories even when the filesystem is completely full.
136 However, there is a price.
137 This mode of operation WILL LIKELY CORRUPT ANY SNAPSHOTS related
138 to this filesystem.
139 The filesystem will report this condition if it encounters
140 it but if you are forced to use this mode to fix a filesystem full condition
141 your snapshots can get a bit dicey.
142 It is usually safest to delete any related snapshots when using this mode.
143 .Pp
144 You can detect whether related snapshots have been corrupted by running
145 a bulkfree pass and checking the console output for reported CRC errors.
146 If no errors are reported, your snapshots are fine.
147 If errors are reported
148 you should delete related snapshots until bulkfree reports no further errors.
149 .Pp
150 The emergency mode will also make meta-data updates unsafe due to the lack of
151 copy-on-write, causing potential harm if the system unexpectedly panics or
152 loses power.
153 GREAT CARE MUST BE TAKEN WHILE THIS MODE IS ACTIVE.
154 .Bl -enum
155 .It
156 Determine that you are unable to recover space with normal file and directory
157 removal commands due to
158 .Er ENOSPC
159 errors being returned by 'rm', or through the
160 removal of snapshots (if any).  The 'bulkfree' directive must be issued to
161 scan the filesystem and free up the actual space, then check with 'df'.
162 Continue if you still have insufficient space and are unable to remove items
163 normally.
164 .It
165 If you need any related snapshots, this is a good time to copy them elsewhere.
166 .It
167 Idle or kill any processes trying to use the filesystem.
168 .It
169 Issue the emergency-mode-enable directive on the filesystem.
170 Once enabled, run 'sync' to update any dirty inodes which may still
171 be dirty due to not being able to flush.
172 Please remember that this
173 directive is a LAST RESORT, is dangerous, and will likely corrupt any
174 other snapshots you have based on the filesystem you are removing files
175 from.
176 .It
177 Remove file trees as necessary with 'rm -rf' to free space, being cognizant
178 of any warnings issued by the kernel on the console (via 'dmesg') while
179 doing so.
180 .It
181 Issue the 'bulkfree' directive to actually free the space and check that
182 sufficient space has been freed with 'df'.
183 .It
184 If bulkfree reports CHECK errors, or if you have snapshots and insufficient
185 space has been freed, you will need to delete snapshots.
186 Re-run bulkfree and delete snapshots until no errors are reported.
187 .It
188 Issue the emergency-mode-disable directive when done.
189 It might also be a
190 good idea to reboot after using this mode, but theoretically you should not
191 have to.
192 .It
193 Restore services using the filesystem.
194 .El
195 .\" ==== emergency-mode-disable ===
196 .It Cm emergency-mode-disable Ar target
197 Turn off the emergency operations mode on a filesystem, restoring normal
198 operation.
199 .\" ==== info ====
200 .It Cm info Op devpath...
201 Access and print the status and super-root entries for all HAMMER2
202 partitions found in /dev/serno or the specified device path(s).
203 The partitions do not have to be mounted.
204 Note that only mounted partitions will be under active management.
205 This is accomplished by mounting at least one PFS within the partition.
206 Typically at least the @LOCAL PFS is mounted.
207 .\" ==== mountall ====
208 .It Cm mountall Op devpath...
209 This directive mounts the @LOCAL PFS on all HAMMER2 partitions found
210 in /dev/serno, or the specified device path(s).
211 The partitions are mounted as /var/hammer2/LOCAL.<id>.
212 Mounts are executed in the background and this command will wait a
213 limited amount of time for the mounts to complete before returning.
214 .\" ==== status ====
215 .It Cm status Op path...
216 Dump a list of all cluster link entries configured in the volume header.
217 .\" ==== hash ====
218 .It Cm hash Op filename...
219 Compute and print the directory hash for any number of filenames.
220 .\" ==== dhash ====
221 .It Cm dhash Op filename...
222 Compute and print the data hash for long directory entry for any number of filenames.
223 .\" ==== pfs-list ====
224 .It Cm pfs-list Op path...
225 List all PFSs associated with all mounted hammer2 storage devices.
226 The list may be restricted to a particular filesystem using
227 .Fl s Ar mount .
228 .Pp
229 Note that hammer2 PFSs associated with storage devices which have not been
230 mounted in any fashion will not be listed.  At least one hammer2 label must
231 be mounted for the PFSs on that device to be visible.
232 .\" ==== pfs-clid ====
233 .It Cm pfs-clid Ar label
234 Print the cluster id for a PFS specified by name.
235 .\" ==== pfs-fsid ====
236 .It Cm pfs-fsid Ar label
237 Print the unique filesystem id for a PFS specified by name.
238 .\" ==== pfs-create ====
239 .It Cm pfs-create Ar label
240 Create a local PFS on the mounted HAMMER2 filesystem represented
241 by the current directory, or specified via
242 .Fl s Ar mount .
243 If no UUID is specified the pfs-type defaults to MASTER.
244 If a UUID is specified via the
245 .Fl u
246 option the pfs-type defaults to SLAVE.
247 Other types can be specified with the
248 .Fl t
249 option.
250 .Pp
251 If you wish to add a MASTER to an existing cluster, you must first add it as
252 a SLAVE and then upgrade it to MASTER to properly synchronize it.
253 .Pp
254 The DUMMY pfs-type is used to tie network-accessible clusters into the local
255 machine when no local storage is desired.
256 This type should be used on minimal H2 partitions or entirely in ram for
257 netboot-centric systems to provide a tie-in point for the mount command,
258 or on more complex systems where you need to also access network-centric
259 clusters.
260 .Pp
261 The CACHE or SLAVE pfs-type is typically used when the main store is on
262 the network but local storage is desired to improve performance.
263 SLAVE is also used when a backup is desired.
264 .Pp
265 Generally speaking, you can mount any PFS element of a cluster in order to
266 access the cluster via the full cluster protocol.
267 There are two exceptions.
268 If you mount a SOFT_SLAVE or a SOFT_MASTER then soft quorum semantics are
269 employed... the soft slave or soft master's current state will always be used
270 and the quorum protocol will not be used.
271 The soft PFS will still be
272 synchronized to masters in the background when available.
273 Also, you can use
274 .Sq mount -o local
275 to mount ONLY a local HAMMER2 PFS and
276 not run any network or quorum protocols for the mount.
277 All such mounts except for a SOFT_MASTER mount will be read-only.
278 Other than that, you will be mounting the whole cluster when you mount any
279 PFS within the cluster.
280 .Pp
281 DUMMY - Create a PFS skeleton intended to be the mount point for a
282 more complex cluster, probably one that is entirely network based.
283 No data will be synchronized to this PFS so it is suitable for use
284 in a network boot image or memory filesystem.
285 This allows you to create placeholders for mount points on your local
286 disk, SSD, or memory disk.
287 .Pp
288 CACHE - Create a PFS for caching portions of the cluster piecemeal.
289 This is similar to a SLAVE but does not synchronize the entire contents of
290 the cluster to the PFS.
291 Elements found in the CACHE PFS which are validated against the cluster
292 will be read, presumably a faster access than having to go to the cluster.
293 Only local CACHEs will be updated.
294 Network-accessible CACHE PFSs might be read but will not be written to.
295 If you have a large hard-drive-based cluster you can set up localized
296 SSD CACHE PFSs to improve performance.
297 .Pp
298 SLAVE - Create a PFS which maintains synchronization with and provides a
299 read-only copy of the cluster.
300 HAMMER2 will prioritize local SLAVEs for data retrieval after validating
301 their transaction id against the cluster.
302 The difference between a CACHE and a SLAVE is that the SLAVE is synchronized
303 to a full copy of the cluster and thus can serve as a backup or be staged
304 for use as a MASTER later on.
305 .Pp
306 SOFT_SLAVE - Create a PFS which maintains synchronization with and provides
307 a read-only copy of the cluster.
308 This is one of the special mount cases.
309 A SOFT_SLAVE will synchronize with
310 the cluster when the cluster is available, but can still be accessed when
311 the cluster is not available.
312 .Pp
313 MASTER - Create a PFS which will hold a master copy of the cluster.
314 If you create several MASTER PFSs with the same cluster id you are
315 effectively creating a multi-master cluster and causing a quorum and
316 cache coherency protocol to be used to validate operations.
317 The total number of masters is stored in each PFSs making up the cluster.
318 Filesystem operations will stall for normal mounts if a quorum cannot be
319 obtained to validate the operation.
320 MASTER nodes which go offline and return later will synchronize in the
321 background.
322 Note that when adding a MASTER to an existing cluster you must add the
323 new PFS as a SLAVE and then upgrade it to a MASTER.
324 .Pp
325 SOFT_MASTER - Create a PFS which maintains synchronization with and provides
326 a read-write copy of the cluster.
327 This is one of the special mount cases.
328 A SOFT_MASTER will synchronize with
329 the cluster when the cluster is available, but can still be read AND written
330 to even when the cluster is not available.
331 Modifications made to a SOFT_MASTER will be automatically flushed to the
332 cluster when it becomes accessible again, and vise-versa.
333 Manual intervention may be required if a conflict occurs during
334 synchronization.
335 .\" ==== pfs-delete ====
336 .It Cm pfs-delete Op label...
337 Destroy a PFS by name.  All hammer2 mount points will be checked, however
338 this directive will refuse to delete a PFS whos name is duplicated on
339 multiple mount points.  A specific mount point may be specified to restrict
340 the deletion via the
341 .Fl s Ar mount
342 option.
343 .\" ==== snapshot ====
344 .It Cm snapshot Ar path Op label
345 Create a snapshot of a directory.
346 The snapshot will be created on the same hammer2 storage device as the
347 directory.
348 This can only be used on a local PFS, and is only really useful if the PFS
349 contains a complete copy of what you desire to snapshot so that typically
350 means a local MASTER, SOFT_MASTER, SLAVE, or SOFT_SLAVE must be present.
351 Snapshots are created simply by flushing a PFS mount to disk and then copying
352 the directory inode to the PFS.
353 The topology is snapshotted without having to be copied or scanned and
354 take no additional space.
355 However, bulkfree scans may take longer.
356 Snapshots are effectively separate from the cluster they came from
357 and can be used as a starting point for a new cluster.
358 So unless you build a new cluster from the snapshot, it will stay local
359 to the machine it was made on.
360 .\" ==== snapshot-debug ====
361 .It Cm snapshot-debug Ar path Op label
362 Snapshot without filesystem sync.
363 .\" ==== service ====
364 .It Cm service
365 Start the
366 .Nm
367 service daemon.
368 This daemon is also automatically started when you run
369 .Xr mount_hammer2 8 .
370 The hammer2 service daemon handles incoming TCP connections and maintains
371 outgoing TCP connections.
372 It will interconnect available services on the
373 machine (e.g. hammer2 mounts and xdisks) to the network.
374 .\" ==== stat ====
375 .It Cm stat Op path...
376 Print the inode statistics, compression, and other meta-data associated
377 with a list of paths.
378 .\" ==== leaf ====
379 .It Cm leaf
380 XXX
381 .\" ==== shell ====
382 .It Cm shell Op host
383 Start a debug shell to the local hammer2 service daemon via the DMSG protocol.
384 .\" ==== debugspan ====
385 .It Cm debugspan Ar target
386 (do not use)
387 .\" ==== rsainit ====
388 .It Cm rsainit Op path
389 Create the
390 .Pa /etc/hammer2
391 directory and initialize a public/private keypair in that directory for
392 use by the network cluster protocols.
393 .\" ==== show ====
394 .It Cm show Ar devpath
395 Dump the radix tree for the HAMMER2 filesystem by scanning a
396 block device directly.
397 No mount is required.
398 .\" ==== freemap ====
399 .It Cm freemap Ar devpath
400 Dump the freemap tree for the HAMMER2 filesystem by scanning a
401 block device directly.
402 No mount is required.
403 .\" ==== volhdr ====
404 .It Cm volhdr Ar devpath
405 Dump the volume header for the HAMMER2 filesystem by scanning a
406 block device directly.
407 No mount is required.
408 .\" ==== setcomp ====
409 .It Cm setcomp Ar mode[:level] Ar path...
410 Set the compression mode as specified for any newly created elements at or
411 under the path if not overridden by deeper elements.
412 Available modes are none, autozero, lz4, or zlib.
413 When zlib is used the compression level can be set.
414 The default will be 6 which is the best trade-off between performance and
415 time.
416 .Pp
417 newfs_hammer2 will set the default compression to lz4 which prioritizes
418 speed over performance.
419 Also note that HAMMER2 contains a heuristic and will not attempt to
420 compress every block if it detects a sufficient amount of uncompressable
421 data.
422 .Pp
423 Hammer2 compression is only effective when it can reduce the size of dataset
424 (typically a 64KB block) by one or more powers of 2.  A 64K block which
425 only compresses to 40K will not yield any storage improvement.
426 .Pp
427 Generally speaking you do not want to set the compression mode to
428 .Sq none ,
429 as this will cause blocks of all-zeros to be written as all-zero blocks,
430 instead of holes.
431 The
432 .Sq autozero
433 compression mode detects blocks of all-zeros
434 and writes them as holes.
435 .\" ==== setcheck ====
436 .It Cm setcheck Ar check Ar path...
437 Set the check code as specified for any newly created elements at or under
438 the path if not overridden by deeper elements.
439 Available codes are default, disabled, crc32, xxhash64, or sha192.
440 .Pp
441 Normally HAMMER2 does not overwrite data blocks on the media in order
442 to ensure snapshot integrity.  Replacement data blocks will be reallocated.
443 However, if the compression mode is set to
444 .Sq none
445 and the check code is set to
446 .Sq disabled
447 HAMMER2 will overwrite data on the media in-place.
448 In this mode of operation,
449 snapshots will not be able to snapshot the data against later changes
450 made to the file, and de-duplication will no longer function on any
451 data related to the file.
452 However, you can still recover the most recent data from previously
453 taken snapshots if you accidentally remove the file.
454 .\" ==== clrcheck ====
455 .It Cm clrcheck Op path...
456 Clear the check code override for the specified paths.
457 Overrides may still be present in deeper elements.
458 .\" ==== setcrc32 ====
459 .It Cm setcrc32 Op path...
460 Set the check code to the ISCSI 32-bit CRC for any newly created elements
461 at or under the path if not overridden by deeper elements.
462 .\" ==== setxxhash64 ====
463 .It Cm setxxhash64 Op path...
464 Set the check code to XXHASH64, a fast 64-bit hash
465 .\" ==== setsha192 ====
466 .It Cm setsha192 Op path...
467 Set the check code to SHA192 for any newly created elements at or under
468 the path if not overridden by deeper elements.
469 .\" ==== bulkfree ====
470 .It Cm bulkfree Ar path
471 Run a bulkfree pass on a HAMMER2 mount.
472 You can specify any PFS for the mount, the bulkfree pass is run on the
473 entire partition.
474 Note that it takes two passes to actually free space.
475 By default this directive will use up to 1/16 physical memory to track
476 the freemap.
477 The amount of memory used may be overridden with the
478 .Op Fl m Ar mem
479 option.
480 .\" ==== printinode ====
481 .It Cm printinode Ar path
482 Dump inode.
483 .\" ==== dumpchain ====
484 .It Cm dumpchain Op path Op chnflags
485 Dump in-memory chain topology.
486 .El
487 .Sh SYSCTLS
488 .Bl -tag -width indent
489 .It Va vfs.hammer2.dedup_enable (default on)
490 Enables live de-duplication.
491 Any recently read data that is on-media
492 (already synchronized to media) is tested against pending writes for
493 compatibility.
494 If a match is found, the write will reference the
495 existing on-media data instead of writing new data.
496 .It Va vfs.hammer2.always_compress (default off)
497 This disables the H2 compression heuristic and forces H2 to always
498 try to compress data blocks, even if they look uncompressable.
499 Enabling this option reduces performance but has higher de-duplication
500 repeatability.
501 .It Va vfs.hammer2.cluster_data_read (default 4)
502 .It Va vfs.hammer2.cluster_meta_read (default 1)
503 Set the amount of read-ahead clustering to perform on data and meta-data
504 blocks.
505 .It Va vfs.hammer2.cluster_write (default 4)
506 Set the amount of write-behind clustering to perform in buffers.
507 Each buffer represents 64KB.
508 The default is 4 and higher values typically do not improve performance.
509 A value of 0 disables clustered writes.
510 This variable applies to the underlying media device, not to logical
511 file writes, so it should not interfere with temporary file optimization.
512 Generally speaking you want this enabled to generate smoothly pipelined
513 writes to the media.
514 .It Va vfs.hammer2.bulkfree_tps (default 5000)
515 Set bulkfree's maximum scan rate.
516 This is primarily intended to limit
517 I/O utilization on SSDs and CPU utilization when the meta-data is mostly
518 cached in memory.
519 .El
520 .Sh SETTING UP /etc/hammer2
521 The
522 .Sq rsainit
523 directive will create the
524 .Pa /etc/hammer2
525 directory with appropriate permissions and also generate a public key
526 pair in this directory for the machine.
527 These files will be
528 .Pa rsa.pub
529 and
530 .Pa rsa.prv
531 and needless to say, the private key shouldn't leave the host.
532 .Pp
533 The service daemon will also scan the
534 .Pa /etc/hammer2/autoconn
535 file which contains a list of hosts which it will automatically maintain
536 connections to to form your cluster.
537 The service daemon will automatically reconnect on any failure and will
538 also monitor the file for changes.
539 .Pp
540 When the service daemon receives a connection it expects to find a
541 public key for that connection in a file in
542 .Pa /etc/hammer2/remote/
543 called
544 .Pa <IPADDR>.pub .
545 You normally copy the
546 .Pa rsa.pub
547 key from the host in question to this file.
548 The IP address must match exactly or the connection will not be allowed.
549 .Pp
550 If you want to use an unencrypted connection you can create empty,
551 dummy files in the remote directory in the form
552 .Pa <IPADDR>.none .
553 We do not recommend using unencrypted connections.
554 .Sh CLUSTER SERVICES
555 Currently there are two services which use the cluster network infrastructure,
556 HAMMER2 mounts and XDISK.
557 Any HAMMER2 mount will make all PFSs for that filesystem available to the
558 cluster.
559 And if the XDISK kernel module is loaded, the hammer2 service daemon will make
560 your machine's block devices available to the cluster (you must load the
561 xdisk.ko kernel module before starting the hammer2 service).
562 They will show up as
563 .Pa /dev/xa*
564 and
565 .Pa /dev/serno/*
566 devices on the remote machines making up the cluster.
567 Remote block devices are just what they appear to be... direct access to a
568 block device on a remote machine.
569 If the link goes down remote accesses
570 will stall until it comes back up again, then automatically requeue any
571 pending I/O and resume as if nothing happened.
572 However, if the server hosting the physical disks crashes or is rebooted,
573 any remote opens to its devices will see a permanent I/O failure requiring a
574 close and open sequence to re-establish.
575 The latter is necessary because the server's drives might not have committed
576 the data before the crash, but had already acknowledged the transfer.
577 .Pp
578 Data commits work exactly the same as they do for real block devices.
579 The originater must issue a BUF_CMD_FLUSH.
580 .Sh ADDING A NEW MASTER TO A CLUSTER
581 When you
582 .Xr newfs_hammer2 8
583 a HAMMER2 filesystem or use the
584 .Sq pfs-create
585 directive on one already mounted
586 to create a new PFS, with no special options, you wind up with a PFS
587 typed as a MASTER and a unique cluster UUID, but because there is only one
588 PFS for that cluster (for each PFS you create via pfs-create), it will
589 act just like a normal filesystem would act and does not require any special
590 protocols to operate.
591 .Pp
592 If you use the
593 .Sq pfs-create
594 directive along with the
595 .Fl u
596 option to specify a cluster UUID that already exists in the cluster,
597 you are adding a PFS to an existing cluster and this can trigger a whole
598 series of events in the background.
599 When you specify the
600 .Fl u
601 option in a
602 .Sq pfs-create ,
603 .Nm
604 will by default create a SLAVE PFS.
605 In fact, this is what must be created first even if you want to add a new
606 MASTER to your cluster.
607 .Pp
608 The most common action a system admin will want to take is to upgrade or
609 downgrade a PFS.
610 A new MASTER can be added to the cluster by upgrading an existing SLAVE
611 to MASTER.
612 A MASTER can be removed from the cluster by downgrading it to a SLAVE.
613 Upgrades and downgrades will put nodes in the cluster in a transition state
614 until the operation is complete.
615 For downgrades the transition state is fleeting unless one or more other
616 masters has not acknowledged the change.
617 For upgrades a background synchronization process must complete before the
618 transition can be said to be complete, and the node remains (really) a SLAVE
619 until that transition is complete.
620 .Sh USE CASES FOR A SOFT_MASTER
621 The SOFT_MASTER PFS type is a special type which must be specifically
622 mounted by a machine.
623 It is a R/W mount which does not use the quorum protocol and is not
624 cache coherent with the cluster, but which synchronizes from the cluster
625 and allows modifying operations which will synchronize to the cluster.
626 The most common case is to use a SOFT_MASTER PFS in a laptop allowing you
627 to work on your laptop when you are on the road and not connected to
628 your main servers, and for the laptop to synchronize when a connection is
629 available.
630 .Sh USE CASES FOR A SOFT_SLAVE
631 A SOFT_SLAVE PFS type is a special type which must be specifically mounted
632 by a machine.
633 It is a RO mount which does not use the quorum protocol and is not
634 cache coherent with the cluster.
635 It will receive synchronization from
636 the cluster when network connectivity is available but will not stall if
637 network connectivity is lost.
638 .Sh FSYNC FLUSH MODES
639 TODO.
640 .Sh RESTORING FROM A SNAPSHOT BACKUP
641 TODO.
642 .Sh PERFORMANCE TUNING
643 Because HAMMER2 implements compression, decompression, and dedup natively,
644 it always double-buffers file data.
645 This means that the file data is
646 cached via the device vnode (in compressed / dedupped-form) and the same
647 data is also cached by the file vnode (in decompressed / non-dedupped form).
648 .Pp
649 While HAMMER2 will try to age the logical file buffers on its, some
650 additional performance tuning may be necessary for optimal operation
651 whether swapcache is used or not.
652 Our recommendation is to reduce the
653 number of vnodes (and thus also the logical buffer cache behind the
654 vnodes) that the system caches via the
655 .Va kern.maxvnodes
656 sysctl.
657 .Pp
658 Too-large a value will result in excessive double-caching and can cause
659 unnecessary read disk I/O.
660 We recommend a number between 25000 and 250000 vnodes, depending on your
661 use case.
662 Keep in mind that even though the vnode cache is smaller, this will make
663 room for a great deal more device-level buffer caching which can encompasses
664 far more data and meta-data than the vnode-level caching.
665 .Sh ENVIRONMENT
666 TODO.
667 .Sh FILES
668 .Bl -tag -width ".It Pa <fs>/abc/defghi/<name>" -compact
669 .It Pa /etc/hammer2/
670 .It Pa /etc/hammer2/rsa.pub
671 .It Pa /etc/hammer2/rsa.prv
672 .It Pa /etc/hammer2/autoconn
673 .It Pa /etc/hammer2/remote/<IP>.pub
674 .It Pa /etc/hammer2/remote/<IP>.none
675 .El
676 .Sh EXIT STATUS
677 .Ex -std
678 .Sh SEE ALSO
679 .Xr mount_hammer2 8 ,
680 .Xr mount_null 8 ,
681 .Xr newfs_hammer2 8 ,
682 .Xr swapcache 8 ,
683 .Xr sysctl 8
684 .Sh HISTORY
685 The
686 .Nm
687 utility first appeared in
688 .Dx 4.1 .
689 .Sh AUTHORS
690 .An Matthew Dillon Aq Mt dillon@backplane.com