drm/ttm: Remove sf_buf usage
[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 .\"
32 .\"
33 .Dd December 2, 2017
34 .Dt HAMMER2 8
35 .Os
36 .Sh NAME
37 .Nm hammer2
38 .Nd hammer2 file system utility
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 ...
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.
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.  If not specified, a unique,
69 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.  This bypasses
105 all normal checks and will unconditionally destroy the directory entry.
106 The underlying inode is not checked and, if it does exist, its nlinks count
107 is not decremented.
108 This directive should only be used to destroy a corrupted directory entry
109 which no longer has a working inode.
110 .Pp
111 Note that this command may desynchronize the system namecache for the
112 specified entry.  If this happens, you may have to unmount and remount the
113 filesystem.
114 .\" ==== disconnect ====
115 .It Cm disconnect Ar target
116 Delete a cluster link entry from the volume header.
117 This feature is not currently used.
118 .\" ==== info ====
119 .It Cm info Op devpath
120 Access and print the status and super-root entries for all HAMMER2
121 partitions found in /dev/serno or the specified device path(s).
122 The partitions do not have to be mounted.
123 Note that only mounted partitions will be under active management.
124 This is accomplished by mounting at least one PFS within the partition.
125 Typically at least the @LOCAL PFS is mounted.
126 .\" ==== mountall ====
127 .It Cm mountall Op devpath
128 This directive mounts the @LOCAL PFS on all HAMMER2 partitions found
129 in /dev/serno, or the specified device path(s).
130 The partitions are mounted as /var/hammer2/LOCAL.<id>.
131 Mounts are executed in the background and this command will wait a
132 limited amount of time for the mounts to complete before returning.
133 .\" ==== status ====
134 .It Cm status Ar path...
135 Dump a list of all cluster link entries configured in the volume header.
136 .\" ==== hash ====
137 .It Cm hash Ar filename...
138 Compute and print the directory hash for any number of filenames.
139 .\" ==== pfs-list ====
140 .It Cm pfs-list Op path...
141 List all local PFSs available on a mounted HAMMER2 filesystem, their type,
142 and their current status.
143 You must mount at least one PFS in order to be able to access the whole list.
144 .\" ==== pfs-clid ====
145 .It Cm pfs-clid Ar label
146 Print the cluster id for a PFS specified by name.
147 .\" ==== pfs-fsid ====
148 .It Cm pfs-fsid Ar label
149 Print the unique filesystem id for a PFS specified by name.
150 .\" ==== pfs-create ====
151 .It Cm pfs-create Ar label
152 Create a local PFS on a mounted HAMMER2 filesystem.
153 If no uuid is specified the pfs-type defaults to MASTER.
154 If a uuid is specified via the
155 .Fl u
156 option the pfs-type defaults to SLAVE.
157 Other types can be specified with the
158 .Fl t
159 option.
160 .Pp
161 If you wish to add a MASTER to an existing cluster, you must first add it as
162 a SLAVE and then upgrade it to MASTER to properly synchronize it.
163 .Pp
164 The DUMMY pfs-type is used to tie network-accessible clusters into the local
165 machine when no local storage is desired.
166 This type should be used on minimal H2 partitions or entirely in ram for
167 netboot-centric systems to provide a tie-in point for the mount command,
168 or on more complex systems where you need to also access network-centric
169 clusters.
170 .Pp
171 The CACHE or SLAVE pfs-type is typically used when the main store is on
172 the network but local storage is desired to improve performance.
173 SLAVE is also used when a backup is desired.
174 .Pp
175 Generally speaking, you can mount any PFS element of a cluster in order to
176 access the cluster via the full cluster protocol.
177 There are two exceptions.
178 If you mount a SOFT_SLAVE or a SOFT_MASTER then soft quorum semantics are
179 employed... the soft slave or soft master's current state will always be used
180 and the quorum protocol will not be used.  The soft PFS will still be
181 synchronized to masters in the background when available.
182 Also, you can use
183 .Sq mount -o local
184 to mount ONLY a local HAMMER2 PFS and
185 not run any network or quorum protocols for the mount.
186 All such mounts except for a SOFT_MASTER mount will be read-only.
187 Other than that, you will be mounting the whole cluster when you mount any
188 PFS within the cluster.
189 .Pp
190 DUMMY - Create a PFS skeleton intended to be the mount point for a
191 more complex cluster, probably one that is entirely network based.
192 No data will be synchronized to this PFS so it is suitable for use
193 in a network boot image or memory filesystem.
194 This allows you to create placeholders for mount points on your local
195 disk, SSD, or memory disk.
196 .Pp
197 CACHE - Create a PFS for caching portions of the cluster piecemeal.
198 This is similar to a SLAVE but does not synchronize the entire contents of
199 the cluster to the PFS.
200 Elements found in the CACHE PFS which are validated against the cluster
201 will be read, presumably a faster access than having to go to the cluster.
202 Only local CACHEs will be updated.
203 Network-accessible CACHE PFSs might be read but will not be written to.
204 If you have a large hard-drive-based cluster you can set up localized
205 SSD CACHE PFSs to improve performance.
206 .Pp
207 SLAVE - Create a PFS which maintains synchronization with and provides a
208 read-only copy of the cluster.
209 HAMMER2 will prioritize local SLAVEs for data retrieval after validating
210 their transaction id against the cluster.
211 The difference between a CACHE and a SLAVE is that the SLAVE is synchronized
212 to a full copy of the cluster and thus can serve as a backup or be staged
213 for use as a MASTER later on.
214 .Pp
215 SOFT_SLAVE - Create a PFS which maintains synchronization with and provides
216 a read-only copy of the cluster.
217 This is one of the special mount cases.  A SOFT_SLAVE will synchronize with
218 the cluster when the cluster is available, but can still be accessed when
219 the cluster is not available.
220 .Pp
221 MASTER - Create a PFS which will hold a master copy of the cluster.
222 If you create several MASTER PFSs with the same cluster id you are
223 effectively creating a multi-master cluster and causing a quorum and
224 cache coherency protocol to be used to validate operations.
225 The total number of masters is stored in each PFSs making up the cluster.
226 Filesystem operations will stall for normal mounts if a quorum cannot be
227 obtained to validate the operation.
228 MASTER nodes which go offline and return later will synchronize in the
229 background.
230 Note that when adding a MASTER to an existing cluster you must add the
231 new PFS as a SLAVE and then upgrade it to a MASTER.
232 .Pp
233 SOFT_MASTER - Create a PFS which maintains synchronization with and provides
234 a read-write copy of the cluster.
235 This is one of the special mount cases.  A SOFT_MASTER will synchronize with
236 the cluster when the cluster is available, but can still be read AND written
237 to even when the cluster is not available.
238 Modifications made to a SOFT_MASTER will be automatically flushed to the
239 cluster when it becomes accessible again, and vise-versa.
240 Manual intervention may be required if a conflict occurs during
241 synchronization.
242 .\" ==== pfs-delete ====
243 .It Cm pfs-delete Ar label
244 Delete a local PFS on a mounted HAMMER2 filesystem.
245 Deleting a PFS of type MASTER requires first downgrading it to a SLAVE (XXX).
246 .\" ==== snapshot ====
247 .It Cm snapshot Ar path Op label
248 Create a snapshot of a directory.
249 This can only be used on a local PFS, and is only really useful if the PFS
250 contains a complete copy of what you desire to snapshot so that typically
251 means a local MASTER, SOFT_MASTER, SLAVE, or SOFT_SLAVE must be present.
252 Snapshots are created simply by flushing a PFS mount to disk and then copying
253 the directory inode to the PFS.
254 The topology is snapshotted without having to be copied or scanned.
255 Snapshots are effectively separate from the cluster they came from
256 and can be used as a starting point for a new cluster.
257 So unless you build a new cluster from the snapshot, it will stay local
258 to the machine it was made on.
259 .\" ==== service ====
260 .It Cm service
261 Start the
262 .Nm
263 service daemon.
264 This daemon is also automatically started when you run
265 .Xr mount_hammer2 8 .
266 The hammer2 service daemon handles incoming TCP connections and maintains
267 outgoing TCP connections.  It will interconnect available services on the
268 machine (e.g. hammer2 mounts and xdisks) to the network.
269 .\" ==== stat ====
270 .It Cm stat Op path...
271 Print the inode statistics, compression, and other meta-data associated
272 with a list of paths.
273 .\" ==== leaf ====
274 .It Cm leaf
275 XXX
276 .\" ==== shell ====
277 .It Cm shell
278 Start a debug shell to the local hammer2 service daemon via the DMSG protocol.
279 .\" ==== debugspan ====
280 .It Cm debugspan
281 (do not use)
282 .\" ==== rsainit ====
283 .It Cm rsainit
284 Create the
285 .Pa /etc/hammer2
286 directory and initialize a public/private keypair in that directory for
287 use by the network cluster protocols.
288 .\" ==== show ====
289 .It Cm show Ar devpath
290 Dump the radix tree for the HAMMER2 filesystem by scanning a
291 block device directly.  No mount is required.
292 .\" ==== freemap ====
293 Dump the freemap tree for the HAMMER2 filesystem by scanning a
294 block device directly.  No mount is required.
295 .It Cm freemap Ar devpath
296 .\" ==== setcomp ====
297 .It Cm setcomp Ar mode[:level] Op path...
298 Set the compression mode as specified for any newly created elements at or
299 under the path if not overridden by deeper elements.
300 Available modes are none, autozero, lz4, or zlib.
301 When zlib is used the compression level can be set.
302 The default will be 6 which is the best trade-off between performance and
303 time.
304 .Pp
305 newfs_hammer2 will set the default compression to lz4 which prioritizes
306 speed over performance.
307 Also note that HAMMER2 contains a heuristic and will not attempt to
308 compress every block if it detects a sufficient amount of uncompressable
309 data.
310 .Pp
311 Hammer2 compression is only effective when it can reduce the size of dataset
312 (typically a 64KB block) by one or more powers of 2.  A 64K block which
313 only compresses to 40K will not yield any storage improvement.
314 .Pp
315 Generally speaking you do not want to set the compression mode to
316 .Sq none ,
317 as this will cause blocks of all-zeros to be written as all-zero blocks,
318 instead of holes.  The
319 .Sq autozero
320 compression mode detects blocks of all-zeros
321 and writes them as holes.  However, HAMMER2 will rewrite data in-place if
322 the compression mode is set to
323 .Sq none
324 and the check code is set to
325 .Sq  disabled .
326 Formal snapshots will still snapshot such files.  However,
327 de-duplication will no longer function on the data blocks.
328 .\" ==== setcheck ====
329 .It Cm setcheck Ar check Op path...
330 Set the check code as specified for any newly created elements at or under
331 the path if not overridden by deeper elements.
332 Available codes are default, disabled, crc32, xxhash64, or sha192.
333 .\" ==== clrcheck ====
334 .It Cm clrcheck Op path...
335 Clear the check code override for the specified paths.
336 Overrides may still be present in deeper elements.
337 .\" ==== setcrc32 ====
338 .It Cm setcrc32 Op path...
339 Set the check code to the ISCSI 32-bit CRC for any newly created elements
340 at or under the path if not overridden by deeper elements.
341 .\" ==== setxxhash64 ====
342 .It Cm setxxhash64 Op path...
343 Set the check code to XXHASH64, a fast 64-bit hash
344 .\" ==== setsha192 ====
345 .It Cm setsha192 Op path...
346 Set the check code to SHA192 for any newly created elements at or under
347 the path if not overridden by deeper elements.
348 .\" ==== bulkfree ====
349 .It Cm bulkfree Op path...
350 Run a bulkfree pass on a HAMMER2 mount.
351 You can specify any PFS for the mount, the bulkfree pass is run on the
352 entire partition.
353 Note that it takes two passes to actually free space.
354 By default this directive will use up to 1/16 physical memory to track
355 the freemap.  The amount of memory used may be overridden with the
356 .Op Fl m Ar mem
357 option.
358 .El
360 .Bl -tag -width indent
361 .It Va vfs.hammer2.dedup_enable (default on)
362 Enables live de-duplication.  Any recently read data that is on-media
363 (already synchronized to media) is tested against pending writes for
364 compatibility.  If a match is found, the write will reference the
365 existing on-media data instead of writing new data.
366 .It Va vfs.hammer2.always_compress (default off)
367 This disables the H2 compression heuristic and forces H2 to always
368 try to compress data blocks, even if they look uncompressable.
369 Enabling this option reduces performance but has higher de-duplication
370 repeatability.
371 .It Va vfs.hammer2.cluster_data_read (default 4)
372 .It Va vfs.hammer2.cluster_meta_read (default 1)
373 Set the amount of read-ahead clustering to perform on data and meta-data
374 blocks.
375 .It Va vfs.hammer2.cluster_write (default 4)
376 Set the amount of write-behind clustering to perform in buffers.  Each
377 buffer represents 64KB.  The default is 4 and higher values typically do
378 not improve performance.  A value of 0 disables clustered writes.
379 This variable applies to the underlying media device, not to logical
380 file writes, so it should not interfere with temporary file optimization.
381 Generally speaking you want this enabled to generate smoothly pipelined
382 writes to the media.
383 .It Va vfs.hammer2.bulkfree_tps (default 5000)
384 Set bulkfree's maximum scan rate.  This is primarily intended to limit
385 I/O utilization on SSDs and cpu utilization when the meta-data is mostly
386 cached in memory.
387 .El
388 .Sh SETTING UP /etc/hammer2
389 The
390 .Sq rsainit
391 directive will create the
392 .Pa /etc/hammer2
393 directory with appropriate permissions and also generate a public key
394 pair in this directory for the machine.  These files will be
395 .Pa rsa.pub
396 and
397 .Pa rsa.prv
398 and needless to say, the private key shouldn't leave the host.
399 .Pp
400 The service daemon will also scan the
401 .Pa /etc/hammer2/autoconn
402 file which contains a list of hosts which it will automatically maintain
403 connections to to form your cluster.
404 The service daemon will automatically reconnect on any failure and will
405 also monitor the file for changes.
406 .Pp
407 When the service daemon receives a connection it expects to find a
408 public key for that connection in a file in
409 .Pa /etc/hammer2/remote/
410 called
411 .Pa <IPADDR>.pub .
412 You normally copy the
413 .Pa rsa.pub
414 key from the host in question to this file.
415 The IP address must match exactly or the connection will not be allowed.
416 .Pp
417 If you want to use an unencrypted connection you can create empty,
418 dummy files in the remote directory in the form
419 .Pa <IPADDR>.none .
420 We do not recommend using unencrypted connections.
422 Currently there are two services which use the cluster network infrastructure,
423 HAMMER2 mounts and XDISK.
424 Any HAMMER2 mount will make all PFSs for that filesystem available to the
425 cluster.
426 And if the XDISK kernel module is loaded, the hammer2 service daemon will make
427 your machine's block devices available to the cluster (you must load the
428 xdisk.ko kernel module before starting the hammer2 service).
429 They will show up as
430 .Pa /dev/xa*
431 and
432 .Pa /dev/serno/*
433 devices on the remote machines making up the cluster.
434 Remote block devices are just what they appear to be... direct access to a
435 block device on a remote machine.  If the link goes down remote accesses
436 will stall until it comes back up again, then automatically requeue any
437 pending I/O and resume as if nothing happened.
438 However, if the server hosting the physical disks crashes or is rebooted,
439 any remote opens to its devices will see a permanent I/O failure requiring a
440 close and open sequence to re-establish.
441 The latter is necessary because the server's drives might not have committed
442 the data before the crash, but had already acknowledged the transfer.
443 .Pp
444 Data commits work exactly the same as they do for real block devices.
445 The originater must issue a BUF_CMD_FLUSH.
447 When you
448 .Xr newfs_hammer2 8
449 a HAMMER2 filesystem or use the
450 .Sq pfs-create
451 directive on one already mounted
452 to create a new PFS, with no special options, you wind up with a PFS
453 typed as a MASTER and a unique cluster uuid, but because there is only one
454 PFS for that cluster (for each PFS you create via pfs-create), it will
455 act just like a normal filesystem would act and does not require any special
456 protocols to operate.
457 .Pp
458 If you use the
459 .Sq pfs-create
460 directive along with the
461 .Fl u
462 option to specify a cluster uuid that already exists in the cluster,
463 you are adding a PFS to an existing cluster and this can trigger a whole
464 series of events in the background.
465 When you specify the
466 .Fl u
467 option in a
468 .Sq pfs-create ,
469 .Nm
470 will by default create a SLAVE PFS.
471 In fact, this is what must be created first even if you want to add a new
472 MASTER to your cluster.
473 .Pp
474 The most common action a system admin will want to take is to upgrade or
475 downgrade a PFS.
476 A new MASTER can be added to the cluster by upgrading an existing SLAVE
477 to MASTER.
478 A MASTER can be removed from the cluster by downgrading it to a SLAVE.
479 Upgrades and downgrades will put nodes in the cluster in a transition state
480 until the operation is complete.
481 For downgrades the transition state is fleeting unless one or more other
482 masters has not acknowledged the change.
483 For upgrades a background synchronization process must complete before the
484 transition can be said to be complete, and the node remains (really) a SLAVE
485 until that transition is complete.
487 The SOFT_MASTER PFS type is a special type which must be specifically
488 mounted by a machine.
489 It is a R/W mount which does not use the quorum protocol and is not
490 cache coherent with the cluster, but which synchronizes from the cluster
491 and allows modifying operations which will synchronize to the cluster.
492 The most common case is to use a SOFT_MASTER PFS in a laptop allowing you
493 to work on your laptop when you are on the road and not connected to
494 your main servers, and for the laptop to synchronize when a connection is
495 available.
497 A SOFT_SLAVE PFS type is a special type which must be specifically mounted
498 by a machine.
499 It is a RO mount which does not use the quorum protocol and is not
500 cache coherent with the cluster.  It will receive synchronization from
501 the cluster when network connectivity is available but will not stall if
502 network connectivity is lost.
504 TODO.
506 TODO.
508 Because HAMMER2 implements compression, decompression, and dedup natively,
509 it always double-buffers file data.  This means that the file data is
510 cached via the device vnode (in compressed / dedupped-form) and the same
511 data is also cached by the file vnode (in decompressed / non-dedupped form).
512 .Pp
513 While HAMMER2 will try to age the logical file buffers on its, some
514 additional performance tuning may be necessary for optimal operation
515 whether swapcache is used or not.  Our recommendation is to reduce the
516 number of vnodes (and thus also the logical buffer cache behind the
517 vnodes) that the system caches via the
518 .Va kern.maxvnodes
519 sysctl.
520 .Pp
521 Too-large a value will result in excessive double-caching and can cause
522 unnecessary read disk I/O.
523 We recommend a number between 25000 and 250000 vnodes, depending on your
524 use case.
525 Keep in mind that even though the vnode cache is smaller, this will make
526 room for a great deal more device-level buffer caching which can encompasses
527 far more data and meta-data than the vnode-level caching.
529 TODO.
530 .Sh FILES
531 .Bl -tag -width ".It Pa <fs>/abc/defghi/<name>" -compact
532 .It Pa /etc/hammer2/
533 .It Pa /etc/hammer2/rsa.pub
534 .It Pa /etc/hammer2/rsa.prv
535 .It Pa /etc/hammer2/autoconn
536 .It Pa /etc/hammer2/remote/<IP>.pub
537 .It Pa /etc/hammer2/remote/<IP>.none
538 .El
540 .Ex -std
541 .Sh SEE ALSO
542 .Xr mount_hammer2 8 ,
543 .Xr mount_null 8 ,
544 .Xr newfs_hammer2 8 ,
545 .Xr swapcache 8 ,
546 .Xr sysctl 8
548 The
549 .Nm
550 utility first appeared in
551 .Dx 4.1 .
553 .An Matthew Dillon Aq Mt dillon@backplane.com