sbin/hammer: Minor fix for hammer(8) manpage
[dragonfly.git] / sbin / hammer / hammer.8
1 .\" Copyright (c) 2007 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 4, 2016
34 .Dt HAMMER 8
35 .Os
36 .Sh NAME
37 .Nm hammer
38 .Nd HAMMER file system utility
39 .Sh SYNOPSIS
40 .Nm
41 .Fl h
42 .Nm
43 .Op Fl 2ABFqrvXy
44 .Op Fl b Ar bandwidth
45 .Op Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead
46 .Op Fl R Ar restrictcmd
47 .Op Fl T Ar restrictpath
48 .Op Fl c Ar cyclefile
49 .Op Fl e Ar scoreboardfile
50 .Op Fl f Ar blkdevs
51 .\" .Op Fl s Ar linkpath
52 .Op Fl i Ar delay
53 .Op Fl p Ar ssh-port
54 .Op Fl S Ar splitsize
55 .Op Fl t Ar seconds
56 .Op Fl m Ar memlimit
57 .Ar command
58 .Op Ar argument ...
59 .Sh DESCRIPTION
60 This manual page documents the
61 .Nm
62 utility which provides miscellaneous functions related to managing a
63 .Nm HAMMER
64 file system.
65 For a general introduction to the
66 .Nm HAMMER
67 file system, its features, and
68 examples on how to set up and maintain one, see
69 .Xr HAMMER 5 .
70 .Pp
71 The options are as follows:
72 .Bl -tag -width indent
73 .It Fl 2
74 Tell the mirror commands to use a 2-way protocol, which allows
75 automatic negotiation of transaction id ranges.
76 This option is automatically enabled by the
77 .Cm mirror-copy
78 command.
79 .It Fl A
80 Make per PFS commands perform on all PFSs if possible.
81 If the command supports this option, it targets all PFSs of the
82 .Nm HAMMER
83 filesystem that the
84 .Ar filesystem
85 argument (of that command) belongs to.
86 Currently
87 .Cm rebalance ,
88 .Cm reblock ,
89 .Cm reblock-btree ,
90 .Cm reblock-inodes ,
91 .Cm reblock-dirs
92 and
93 .Cm reblock-data
94 commands support this option.
95 If the command does not support this option, it does nothing.
96 .It Fl B
97 Bulk transfer.
98 .Cm Mirror-stream
99 will not attempt to break-up large initial bulk transfers into smaller
100 pieces.
101 This can save time but if the link is lost in the middle of the
102 initial bulk transfer you will have to start over from scratch.
103 For more information see the
104 .Fl S
105 option.
106 .It Fl b Ar bandwidth
107 Specify a bandwidth limit in bytes per second for mirroring streams.
108 This option is typically used to prevent batch mirroring operations from
109 loading down the machine.
110 The bandwidth may be suffixed with
111 .Cm k , m ,
112 or
113 .Cm g
114 to specify values in kilobytes, megabytes, and gigabytes per second.
115 If no suffix is specified, bytes per second is assumed.
116 .Pp
117 Unfortunately this is only applicable to the pre-compression bandwidth
118 when compression is used, so a better solution would probably be to
119 use a
120 .Xr ipfw 8
121 pipe or a
122 .Xr pf 4
123 queue.
124 .It Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead
125 Set the memory cache size for any raw
126 .Tn I/O .
127 The default is 16MB.
128 A suffix of
129 .Cm k
130 for kilobytes and
131 .Cm m
132 for megabytes is allowed,
133 else the cache size is specified in bytes.
134 .Pp
135 The read-behind/read-ahead defaults to 4
136 .Nm HAMMER
137 blocks.
138 .Pp
139 This option is typically only used with diagnostic commands
140 as kernel-supported commands will use the kernel's buffer cache.
141 .It Fl R Ar restrictcmd
142 This option is used by hammer ssh-remote to restrict the command later
143 on in the argument list.  Multiple commands may be specified, separated
144 by a comma (all one argument).
145 .It Fl T Ar restrictpath
146 This option is used by hammer ssh-remote to restrict the filesystem path
147 specified later on in the argument list.
148 .It Fl c Ar cyclefile
149 When pruning, rebalancing or reblocking you can tell the utility
150 to start at the object id stored in the specified file.
151 If the file does not exist
152 .Nm
153 will start at the beginning.
154 If
155 .Nm
156 is told to run for a specific period of time
157 .Pq Fl t
158 and is unable to complete the operation it will write out
159 the current object id so the next run can pick up where it left off.
160 If
161 .Nm
162 runs to completion it will delete
163 .Ar cyclefile .
164 .It Fl e Ar scoreboardfile
165 Update scoreboard file with progress, primarily used by mirror-stream.
166 .It Fl F
167 Force operation.
168 E.g.\&
169 .Cm cleanup
170 will not check that time period has elapsed if this option is given.
171 .It Fl f Ar blkdevs
172 Specify the volumes making up a
173 .Nm HAMMER
174 file system.
175 .Ar Blkdevs
176 is a colon-separated list of devices, each specifying a
177 .Nm HAMMER
178 volume.
179 .It Fl h
180 Show usage.
181 .It Fl i Ar delay
182 Specify delay in seconds for
183 .Cm mirror-read-stream .
184 When maintaining a streaming mirroring this option specifies the
185 minimum delay after a batch ends before the next batch is allowed
186 to start.
187 The default is five seconds.
188 .It Fl m Ar memlimit
189 Specify the maximum amount of memory
190 .Nm
191 will allocate during a dedup pass.
192 Specify a suffix 'm', 'g', or 't' for megabytes, gigabytes, or terabytes.
193 By default
194 .Nm
195 will allocate up to 1G of ram to hold CRC/SHA tables while running dedup.
196 When the limit is reached the dedup code restricts the range of CRCs to
197 keep memory use within bounds and runs multiple passes as necessary until
198 the entire filesystem has been deduped.
199 .It Fl p Ar ssh-port
200 Pass the
201 .Fl p Ar ssh-port
202 option to
203 .Xr ssh 1
204 when using a remote
205 specification for the source and/or destination.
206 .It Fl q
207 Decrease verboseness.
208 May be specified multiple times.
209 .It Fl r
210 Specify recursion for those commands which support it.
211 .It Fl S Ar splitsize
212 Specify the bulk splitup size in bytes for mirroring streams.
213 When a
214 .Cm mirror-stream
215 is first started
216 .Nm
217 will do an initial run-through of the data to calculate good
218 transaction ids to cut up the bulk transfers, creating
219 restart points in case the stream is interrupted.
220 If we don't do this and the stream is interrupted it might
221 have to start all over again.
222 The default is a
223 .Ar splitsize
224 of 4GB.
225 .Pp
226 At the moment the run-through is disk-bandwidth-heavy but some
227 future version will limit the run-through to just the B-Tree
228 records and not the record data.
229 .Pp
230 The splitsize may be suffixed with
231 .Cm k , m ,
232 or
233 .Cm g
234 to specify values in kilobytes, megabytes, or gigabytes.
235 If no suffix is specified, bytes is assumed.
236 .Pp
237 When mirroring very large filesystems the minimum recommended
238 split size is 4GB.
239 A small split size may wind up generating a great deal of overhead
240 but very little actual incremental data and is not recommended.
241 .It Fl t Ar seconds
242 Specify timeout in seconds.
243 When pruning, rebalancing, reblocking or mirror-reading
244 you can tell the utility to stop after a certain period of time.
245 A value of 0 means unlimited.
246 This option is used along with the
247 .Fl c Ar cyclefile
248 option to prune, rebalance or reblock incrementally.
249 .It Fl v
250 Increase verboseness.
251 May be specified multiple times.
252 .It Fl X
253 Enable compression for any remote ssh specifications.
254 This option is typically used with the mirroring directives.
255 .It Fl y
256 Force
257 .Dq yes
258 for interactive questions.
259 .El
260 .Pp
261 The commands are as follows:
262 .Bl -tag -width indent
263 .\" ==== synctid ====
264 .It Cm synctid Ar filesystem Op Cm quick
265 Generate a guaranteed, formal 64-bit transaction id representing the
266 current state of the specified
267 .Nm HAMMER
268 file system.
269 The file system will be synced to the media.
270 .Pp
271 If the
272 .Cm quick
273 keyword is specified the file system will be soft-synced, meaning that a
274 crash might still undo the state of the file system as of the transaction
275 id returned but any new modifications will occur after the returned
276 transaction id as expected.
277 .Pp
278 This operation does not create a snapshot.
279 It is meant to be used
280 to track temporary fine-grained changes to a subset of files and
281 will only remain valid for
282 .Ql @@
283 access purposes for the
284 .Cm prune-min
285 period configured for the PFS.
286 If you desire a real snapshot then the
287 .Cm snapq
288 directive may be what you are looking for.
289 .\" ==== bstats ====
290 .It Cm bstats Op Ar interval
291 Output
292 .Nm HAMMER
293 B-Tree statistics until interrupted.
294 Pause
295 .Ar interval
296 seconds between each display.
297 The default interval is one second.
298 .\" ==== iostats ====
299 .It Cm iostats Op Ar interval
300 Output
301 .Nm HAMMER
302 .Tn I/O
303 statistics until interrupted.
304 Pause
305 .Ar interval
306 seconds between each display.
307 The default interval is one second.
308 .\" ==== stats ====
309 .It Cm stats Op Ar interval
310 Output
311 .Nm HAMMER
312 B-Tree and
313 .Tn I/O
314 statistics until interrupted.
315 Pause
316 .Ar interval
317 seconds between each display.
318 The default interval is one second.
319 .\" ==== history ====
320 .It Cm history Ns Oo Cm @ Ns Ar offset Ns Oo Cm \&, Ns Ar length Oc Oc Ar path Ns Oo Cm @ Ns Ar offset Ns Oo Cm \&, Ns Ar length Oc Oc Ar ...
321 Show the modification history for inode and data of
322 .Nm HAMMER
323 files.
324 If
325 .Ar offset
326 is given history is shown for data block at given offset,
327 otherwise history is shown for inode.
328 If
329 .Fl v
330 is specified
331 .Ar length
332 data bytes at given offset are dumped for each version,
333 default is 32.
334 .Pp
335 For each
336 .Ar path
337 this directive shows object id and sync status,
338 and for each object version it shows transaction id and time stamp.
339 Files has to exist for this directive to be applicable,
340 to track inodes which has been deleted or renamed see
341 .Xr undo 1 .
342 .Pp
343 Different
344 .Ar offset
345 and
346 .Ar length
347 can be used for each
348 .Ar path
349 by specifying
350 .Ar offset
351 and
352 .Ar length
353 for each
354 .Ar path .
355 .\" ==== blockmap ====
356 .It Cm blockmap
357 Dump the blockmap for the file system.
358 The
359 .Nm HAMMER
360 blockmap is two-layer
361 blockmap representing the maximum possible file system size of 1 Exabyte.
362 Needless to say the second layer is only present for blocks which exist.
363 .Nm HAMMER Ns 's
364 blockmap represents 8-Megabyte blocks, called big-blocks.
365 Each big-block has an append
366 point, a free byte count, and a typed zone id which allows content to be
367 reverse engineered to some degree.
368 .Pp
369 In
370 .Nm HAMMER
371 allocations are essentially appended to a selected big-block using
372 the append offset and deducted from the free byte count.
373 When space is freed the free byte count is adjusted but
374 .Nm HAMMER
375 does not track holes in big-blocks for reallocation.
376 A big-block must be completely freed, either
377 through normal file system operations or through reblocking, before
378 it can be reused.
379 .Pp
380 Data blocks can be shared by deducting the space used from the free byte
381 count for each shared references.
382 This means the free byte count can legally go negative.
383 .Pp
384 This command needs the
385 .Fl f Ar blkdevs
386 option.
387 .\" ==== checkmap ====
388 .It Cm checkmap
389 Check the blockmap allocation count.
390 .Nm
391 will scan the freemap, B-Tree, UNDO FIFO, then collect allocation information,
392 and construct a blockmap in-memory.
393 It will then check that blockmap against the on-disk blockmap.
394 .Pp
395 This command needs the
396 .Fl f Ar blkdevs
397 option.
398 .\" ==== show ====
399 .It Cm show Op Ar localization Ns Op Cm \&: Ns Ar object_id Ns Op Cm \&: Ns Ar rec_type Ns Op Cm \&: Ns Ar key Ns Op Cm \&: Ns Ar create_tid
400 Dump the B-Tree.
401 By default this command will validate all B-Tree
402 linkages and CRCs, including data CRCs, and will report the most verbose
403 information it can dig up.
404 Any errors will show up with a
405 .Ql B
406 in column 1 along with various
407 other error flags.
408 .Pp
409 If you specify
410 .Ar localization
411 or
412 .Ar localization Ns Cm \&: Ns Ar object_id
413 or
414 .Ar localization Ns Cm \&: Ns Ar object_id Ns Cm \&: Ns Ar rec_type
415 or
416 .Ar localization Ns Cm \&: Ns Ar object_id Ns Cm \&: Ns Ar rec_type Ns Cm \&: Ns Ar key
417 or
418 .Ar localization Ns Cm \&: Ns Ar object_id Ns Cm \&: Ns Ar rec_type Ns Cm \&: Ns Ar key Ns Cm \&: Ns Ar create_tid
419 the dump will
420 search for the key printing nodes as it recurses down, and then
421 will iterate forwards.
422 These fields are specified in HEX.
423 Note that the PFS id is the top 16 bits of the 32-bit localization
424 field so PFS #1 would be 00010000.
425 .Pp
426 If you use
427 .Fl q
428 the command will report less information about the inode contents.
429 .Pp
430 If you use
431 .Fl qq
432 the command will not report the content of the inode or other typed
433 data at all.
434 .Pp
435 If you use
436 .Fl qqq
437 the command will not report volume header information, big-block fill
438 ratios, mirror transaction ids, or report or check data CRCs.
439 B-Tree CRCs and linkages are still checked.
440 .Pp
441 This command needs the
442 .Fl f Ar blkdevs
443 option.
444 .\" ==== show-undo ====
445 .It Cm show-undo
446 .Nm ( HAMMER
447 VERSION 4+)
448 Dump the UNDO/REDO map.
449 .Pp
450 This command needs the
451 .Fl f Ar blkdevs
452 option.
453 .\" .It Ar blockmap
454 .\" Dump the B-Tree, record, large-data, and small-data blockmaps, showing
455 .\" physical block assignments and free space percentages.
456 .\" ==== ssh-remote ====
457 .It Cm ssh-remote Ar command Ar targetdir
458 Used in a ssh authorized_keys line such as
459 command="/sbin/hammer ssh-remote mirror-read /fubarmount" ... to allow
460 mirror-read or mirror-write access to a particular subdirectory tree.
461 This way you do not have to give shell access to the remote box.
462 .Nm
463 will obtain the original command line from the SSH_ORIGINAL_COMMAND
464 environment variable, validate it against the restriction, and then
465 re-exec hammer with the validated arguments.
466 .Pp
467 The remote hammer command does not allow the
468 .Fl c
469 or
470 .Fl f
471 options to be passed in.
472 .\" ==== recover ====
473 .It Cm recover Ar targetdir
474 Recover data from a corrupted
475 .Nm HAMMER
476 filesystem.
477 This is a low level command which operates on the filesystem image and
478 attempts to locate and recover files from a corrupted filesystem.
479 The entire image is scanned linearly looking for B-Tree nodes.
480 Any node
481 found which passes its CRC test is scanned for file, inode, and directory
482 fragments and the target directory is populated with the resulting data.
483 files and directories in the target directory are initially named after
484 the object id and are renamed as fragmentary information is processed.
485 .Pp
486 This command keeps track of filename/object_id translations and may eat a
487 considerably amount of memory while operating.
488 .Pp
489 This command is literally the last line of defense when it comes to
490 recovering data from a dead filesystem.
491 .Pp
492 This command needs the
493 .Fl f Ar blkdevs
494 option.
495 .\" ==== namekey1 ====
496 .It Cm namekey1 Ar filename
497 Generate a
498 .Nm HAMMER
499 64-bit directory hash for the specified file name, using
500 the original directory hash algorithm in version 1 of the file system.
501 The low 32 bits are used as an iterator for hash collisions and will be
502 output as 0.
503 .\" ==== namekey2 ====
504 .It Cm namekey2 Ar filename
505 Generate a
506 .Nm HAMMER
507 64-bit directory hash for the specified file name, using
508 the new directory hash algorithm in version 2 of the file system.
509 The low 32 bits are still used as an iterator but will start out containing
510 part of the hash key.
511 .\" ==== namekey32 ====
512 .It Cm namekey32 Ar filename
513 Generate the top 32 bits of a
514 .Nm HAMMER
515 64 bit directory hash for the specified file name.
516 .\" ==== info ====
517 .It Cm info Ar dirpath ...
518 Show extended information about all
519 .Nm HAMMER
520 file systems mounted in the system or the one mounted in
521 .Ar dirpath
522 when this argument is specified.
523 .Pp
524 The information is divided into sections:
525 .Bl -tag -width indent
526 .It Volume identification
527 General information, like the label of the
528 .Nm HAMMER
529 filesystem, the number of volumes it contains, the FSID, and the
530 .Nm HAMMER
531 version being used.
532 .It Big-block information
533 Big-block statistics, such as total, used, reserved and free big-blocks.
534 .It Space information
535 Information about space used on the filesystem.
536 Currently total size, used, reserved and free space are displayed.
537 .It PFS information
538 Basic information about the PFSs currently present on a
539 .Nm HAMMER
540 filesystem.
541 .Pp
542 .Dq PFS ID
543 is the ID of the PFS, with 0 being the root PFS.
544 .Dq Snaps
545 is the current snapshot count on the PFS.
546 .Dq Mounted on
547 displays the mount point of the PFS is currently mounted on (if any).
548 .El
549 .\" ==== cleanup ====
550 .It Cm cleanup Op Ar filesystem ...
551 This is a meta-command which executes snapshot, prune, rebalance, dedup
552 and reblock commands on the specified
553 .Nm HAMMER
554 file systems.
555 If no
556 .Ar filesystem
557 is specified this command will clean-up all
558 .Nm HAMMER
559 file systems in use, including PFS's.
560 To do this it will scan all
561 .Nm HAMMER
562 and
563 .Nm null
564 mounts, extract PFS id's, and clean-up each PFS found.
565 .Pp
566 This command will access a snapshots
567 directory and a configuration file for each
568 .Ar filesystem ,
569 creating them if necessary.
570 .Bl -tag -width indent
571 .It Nm HAMMER No version 2-
572 The configuration file is
573 .Pa config
574 in the snapshots directory which defaults to
575 .Pa <pfs>/snapshots .
576 .It Nm HAMMER No version 3+
577 The configuration file is saved in file system meta-data, see
578 .Nm
579 .Cm config .
580 The snapshots directory defaults to
581 .Pa /var/hammer/<pfs>
582 .Pa ( /var/hammer/root
583 for root mount).
584 .El
585 .Pp
586 The format of the configuration file is:
587 .Bd -literal -offset indent
588 snapshots  <period> <retention-time> [any]
589 prune      <period> <max-runtime>
590 rebalance  <period> <max-runtime>
591 dedup      <period> <max-runtime>
592 reblock    <period> <max-runtime>
593 recopy     <period> <max-runtime>
594 .Ed
595 .Pp
596 Defaults are:
597 .Bd -literal -offset indent
598 snapshots  1d 60d  # 0d 0d  for PFS /tmp, /var/tmp, /usr/obj
599 prune      1d 5m
600 rebalance  1d 5m
601 dedup      1d 5m
602 reblock    1d 5m
603 recopy     30d 10m
604 .Ed
605 .Pp
606 Time is given with a suffix of
607 .Cm d ,
608 .Cm h ,
609 .Cm m
610 or
611 .Cm s
612 meaning day, hour, minute and second.
613 .Pp
614 If the
615 .Cm snapshots
616 directive has a period of 0 and a retention time of 0
617 then snapshot generation is disabled, removal of old snapshots are
618 disabled, and prunes will use
619 .Cm prune-everything .
620 .Pp
621 If the
622 .Cm snapshots
623 directive has a period of 0 but a non-zero retention time
624 then this command will not create any new snapshots but will remove old
625 snapshots it finds based on the retention time.
626 This form should be
627 used on PFS masters where you are generating your own snapshot softlinks
628 manually and on PFS slaves when all you wish to do is prune away existing
629 snapshots inherited via the mirroring stream.
630 .Pp
631 By default only snapshots in the form
632 .Ql snap- Ns Ar yyyymmdd Ns Op - Ns Ar HHMM
633 are processed.
634 If the
635 .Cm any
636 directive is specified as a third argument on the
637 .Cm snapshots
638 config line then any softlink of the form
639 .Ql *- Ns Ar yyyymmdd Ns Op - Ns Ar HHMM
640 or
641 .Ql *. Ns Ar yyyymmdd Ns Op - Ns Ar HHMM
642 will be processed.
643 .Pp
644 A period of 0 for prune, rebalance, dedup, reblock or recopy disables the directive.
645 A max-runtime of 0 means unlimited.
646 .Pp
647 If period hasn't passed since the previous
648 .Cm cleanup
649 run nothing is done.
650 For example a day has passed when midnight is passed (localtime).
651 If the
652 .Fl F
653 flag is given the period is ignored.
654 By default,
655 .Dx
656 is set up to run
657 .Nm Cm cleanup
658 nightly via
659 .Xr periodic 8 .
660 .Pp
661 The default configuration file will create a daily snapshot, do a daily
662 pruning, rebalancing, deduping and reblocking run and a monthly recopy run.
663 Reblocking is defragmentation with a level of 95%,
664 and recopy is full defragmentation.
665 .Pp
666 By default prune, dedup and rebalance operations are time limited to 5 minutes,
667 and reblock operations to a bit over 5 minutes,
668 and recopy operations to a bit over 10 minutes.
669 Reblocking and recopy runs are each broken down into four separate functions:
670 B-Tree, inodes, dirs and data.
671 Each function is time limited to the time given in the configuration file,
672 but the B-Tree, inodes and dirs functions usually does not take very long time,
673 full defragmentation is always used for these three functions.
674 Also note that this directive will by default disable snapshots on
675 the following PFS's:
676 .Pa /tmp ,
677 .Pa /var/tmp
678 and
679 .Pa /usr/obj .
680 .Pp
681 The defaults may be adjusted by modifying the configuration file.
682 The pruning and reblocking commands automatically maintain a cyclefile
683 for incremental operation.
684 If you interrupt (^C) the program the cyclefile will be updated,
685 but a sub-command
686 may continue to run in the background for a few seconds until the
687 .Nm HAMMER
688 ioctl detects the interrupt.
689 The
690 .Cm snapshots
691 PFS option can be set to use another location for the snapshots directory.
692 .Pp
693 Work on this command is still in progress.
694 Expected additions:
695 An ability to remove snapshots dynamically as the
696 file system becomes full.
697 .\" ==== abort-cleanup ====
698 .It Cm abort-cleanup
699 This command will terminate all active
700 .Cm cleanup
701 processes.
702 .\" ==== config ====
703 .It Cm config Op Ar filesystem Op Ar configfile
704 .Nm ( HAMMER
705 VERSION 3+)
706 Show or change configuration for
707 .Ar filesystem .
708 If zero or one arguments are specified this function dumps the current
709 configuration file to stdout.
710 Zero arguments specifies the PFS containing the current directory.
711 This configuration file is stored in file system meta-data.
712 If two arguments are specified this function installs a new configuration file
713 .Ar configfile .
714 .Pp
715 In
716 .Nm HAMMER
717 versions less than 3 the configuration file is by default stored in
718 .Pa <pfs>/snapshots/config ,
719 but in all later versions the configuration file is stored in file system
720 meta-data.
721 .\" ==== viconfig ====
722 .It Cm viconfig Op Ar filesystem
723 .Nm ( HAMMER
724 VERSION 3+)
725 Edit the configuration file and reinstall into file system meta-data when done.
726 Zero arguments specifies the PFS containing the current directory.
727 .\" ==== volume-add ====
728 .It Cm volume-add Ar device Ar filesystem
729 Add volume
730 .Ar device
731 to
732 .Ar filesystem .
733 This will format
734 .Ar device
735 and add all of its space to
736 .Ar filesystem .
737 A
738 .Nm HAMMER
739 file system can use up to 256 volumes.
740 .Pp
741 .Em NOTE!
742 All existing data contained on
743 .Ar device
744 will be destroyed by this operation!
745 If
746 .Ar device
747 contains a valid
748 .Nm HAMMER
749 file system, formatting will be denied.
750 You can overcome this sanity check by using
751 .Xr dd 1
752 to erase the beginning sectors of the device.
753 .Pp
754 Remember that you have to specify
755 .Ar device ,
756 together with any other device that make up the file system,
757 colon-separated to
758 .Pa /etc/fstab
759 and
760 .Xr mount_hammer 8 .
761 If
762 .Ar filesystem
763 is root file system, also remember to add
764 .Ar device
765 to
766 .Va vfs.root.mountfrom
767 in
768 .Pa /boot/loader.conf ,
769 see
770 .Xr loader 8 .
771 .\" ==== volume-del ====
772 .It Cm volume-del Ar device Ar filesystem
773 Remove volume
774 .Ar device
775 from
776 .Ar filesystem .
777 .Pp
778 Remember that you have to remove
779 .Ar device
780 from the colon-separated list in
781 .Pa /etc/fstab
782 and
783 .Xr mount_hammer 8 .
784 If
785 .Ar filesystem
786 is root file system, also remember to remove
787 .Ar device
788 from
789 .Va vfs.root.mountfrom
790 in
791 .Pa /boot/loader.conf ,
792 see
793 .Xr loader 8 .
794 .Pp
795 It is not possible to remove the
796 .Ar root-volume
797 as it contains
798 .Ar filesystem
799 meta data such as
800 .Nm HAMMER Ns 's
801 layer1 blockmap and UNDO FIFO.
802 .Pp
803 This command may
804 .Cm reblock
805 filesystem before it attempts to remove the volume if the volume is not empty.
806 .\" ==== volume-list ====
807 .It Cm volume-list Ar filesystem
808 List the volumes that make up
809 .Ar filesystem .
810 .\" ==== volume-blkdevs ====
811 .It Cm volume-blkdevs Ar filesystem
812 List the volumes that make up
813 .Ar filesystem
814 in
815 .Ar blkdevs
816 format.
817 .\" ==== snapshot ====
818 .It Cm snapshot Oo Ar filesystem Oc Ar snapshot-dir
819 .It Cm snapshot Ar filesystem Ar snapshot-dir Op Ar note
820 Take a snapshot of the file system either explicitly given by
821 .Ar filesystem
822 or implicitly derived from the
823 .Ar snapshot-dir
824 argument and creates a symlink in the directory provided by
825 .Ar snapshot-dir
826 pointing to the snapshot.
827 If
828 .Ar snapshot-dir
829 is not a directory, it is assumed to be a format string passed to
830 .Xr strftime 3
831 with the current time as parameter.
832 If
833 .Ar snapshot-dir
834 refers to an existing directory, a default format string of
835 .Ql snap-%Y%m%d-%H%M
836 is assumed and used as name for the newly created symlink.
837 .Pp
838 Snapshot is a per PFS operation, so each PFS in a
839 .Nm HAMMER
840 file system have to be snapshot separately.
841 .Pp
842 Example, assuming that
843 .Pa /mysnapshots
844 is on file system
845 .Pa /
846 and that
847 .Pa /obj
848 and
849 .Pa /usr
850 are file systems on their own, the following invocations:
851 .Bd -literal -offset indent
852 hammer snapshot /mysnapshots
853
854 hammer snapshot /mysnapshots/%Y-%m-%d
855
856 hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d
857
858 hammer snapshot /usr /my/snaps/usr "note"
859 .Ed
860 .Pp
861 Would create symlinks similar to:
862 .Bd -literal -offset indent
863 /mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16
864
865 /mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16
866
867 /mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16
868
869 /my/snaps/usr/snap-20080627-1210 -> /usr@@0x10d2cd05b7270d16
870 .Ed
871 .Pp
872 When run on a
873 .Nm HAMMER
874 version 3+ file system the snapshot is also recorded in file system meta-data
875 along with the optional
876 .Ar note .
877 See the
878 .Cm snapls
879 directive.
880 .\" ==== snap* ====
881 .It Cm snap Ar path Op Ar note
882 .Nm ( HAMMER
883 VERSION 3+)
884 Create a snapshot for the PFS containing
885 .Ar path
886 and create a snapshot softlink.
887 If the path specified is a
888 directory a standard snapshot softlink will be created in the directory.
889 The snapshot softlink points to the base of the mounted PFS.
890 .It Cm snaplo Ar path Op Ar note
891 .Nm ( HAMMER
892 VERSION 3+)
893 Create a snapshot for the PFS containing
894 .Ar path
895 and create a snapshot softlink.
896 If the path specified is a
897 directory a standard snapshot softlink will be created in the directory.
898 The snapshot softlink points into the directory it is contained in.
899 .It Cm snapq Ar dir Op Ar note
900 .Nm ( HAMMER
901 VERSION 3+)
902 Create a snapshot for the PFS containing the specified directory but do
903 not create a softlink.
904 Instead output a path which can be used to access
905 the directory via the snapshot.
906 .Pp
907 An absolute or relative path may be specified.
908 The path will be used as-is as a prefix in the path output to stdout.
909 As with the other
910 snap and snapshot directives the snapshot transaction id will be registered
911 in the file system meta-data.
912 .It Cm snaprm Ar path Ar ...
913 .It Cm snaprm Ar transaction_id Ar ...
914 .It Cm snaprm Ar filesystem Ar transaction_id Ar ...
915 .Nm ( HAMMER
916 VERSION 3+)
917 Remove a snapshot given its softlink or transaction id.
918 If specifying a transaction id
919 the snapshot is removed from file system meta-data but you are responsible
920 for removing any related softlinks.
921 .Pp
922 If a softlink path is specified the filesystem and transaction id
923 is derived from the contents of the softlink.
924 If just a transaction id is specified it is assumed to be a snapshot in the
925 .Nm HAMMER
926 filesystem you are currently chdir'd into.
927 You can also specify the filesystem and transaction id explicitly.
928 .It Cm snapls Op Ar path ...
929 .Nm ( HAMMER
930 VERSION 3+)
931 Dump the snapshot meta-data for PFSs containing each
932 .Ar path
933 listing all available snapshots and their notes.
934 If no arguments are specified snapshots for the PFS containing the
935 current directory are listed.
936 This is the definitive list of snapshots for the file system.
937 .\" ==== prune ====
938 .It Cm prune Ar softlink-dir
939 Prune the file system based on previously created snapshot softlinks.
940 Pruning is the act of deleting file system history.
941 The
942 .Cm prune
943 command will delete file system history such that
944 the file system state is retained for the given snapshots,
945 and all history after the latest snapshot.
946 By setting the per PFS parameter
947 .Cm prune-min ,
948 history is guaranteed to be saved at least this time interval.
949 All other history is deleted.
950 .Pp
951 The target directory is expected to contain softlinks pointing to
952 snapshots of the file systems you wish to retain.
953 The directory is scanned non-recursively and the mount points and
954 transaction ids stored in the softlinks are extracted and sorted.
955 The file system is then explicitly pruned according to what is found.
956 Cleaning out portions of the file system is as simple as removing a
957 snapshot softlink and then running the
958 .Cm prune
959 command.
960 .Pp
961 As a safety measure pruning only occurs if one or more softlinks are found
962 containing the
963 .Ql @@
964 snapshot id extension.
965 Currently the scanned softlink directory must contain softlinks pointing
966 to a single
967 .Nm HAMMER
968 mount.
969 The softlinks may specify absolute or relative paths.
970 Softlinks must use 20-character
971 .Ql @@0x%016llx
972 transaction ids, as might be returned from
973 .Nm Cm synctid Ar filesystem .
974 .Pp
975 Pruning is a per PFS operation, so each PFS in a
976 .Nm HAMMER
977 file system have to be pruned separately.
978 .Pp
979 Note that pruning a file system may not immediately free-up space,
980 though typically some space will be freed if a large number of records are
981 pruned out.
982 The file system must be reblocked to completely recover all available space.
983 .Pp
984 Example, lets say your that you didn't set
985 .Cm prune-min ,
986 and snapshot directory contains the following links:
987 .Bd -literal -offset indent
988 lrwxr-xr-x  1 root  wheel  29 May 31 17:57 snap1 ->
989 /usr/obj/@@0x10d2cd05b7270d16
990
991 lrwxr-xr-x  1 root  wheel  29 May 31 17:58 snap2 ->
992 /usr/obj/@@0x10d2cd13f3fde98f
993
994 lrwxr-xr-x  1 root  wheel  29 May 31 17:59 snap3 ->
995 /usr/obj/@@0x10d2cd222adee364
996 .Ed
997 .Pp
998 If you were to run the
999 .Cm prune
1000 command on this directory, then the
1001 .Nm HAMMER
1002 .Pa /usr/obj
1003 mount will be pruned to retain the above three snapshots.
1004 In addition, history for modifications made to the file system older than
1005 the oldest snapshot will be destroyed and history for potentially fine-grained
1006 modifications made to the file system more recently than the most recent
1007 snapshot will be retained.
1008 .Pp
1009 If you then delete the
1010 .Pa snap2
1011 softlink and rerun the
1012 .Cm prune
1013 command,
1014 history for modifications pertaining to that snapshot would be destroyed.
1015 .Pp
1016 In
1017 .Nm HAMMER
1018 file system versions 3+ this command also scans the snapshots stored
1019 in the file system meta-data and includes them in the prune.
1020 .\" ==== prune-everything ====
1021 .It Cm prune-everything Ar filesystem
1022 Remove all historical records from
1023 .Ar filesystem .
1024 Use this directive with caution on PFSs where you intend to use history.
1025 .Pp
1026 This command does not remove snapshot softlinks but will delete all
1027 snapshots recorded in file system meta-data (for file system version 3+).
1028 The user is responsible for deleting any softlinks.
1029 .Pp
1030 Pruning is a per PFS operation, so each PFS in a
1031 .Nm HAMMER
1032 file system have to be pruned separately.
1033 .\" ==== rebalance ====
1034 .It Cm rebalance Ar filesystem Op Ar saturation_percentage
1035 Rebalance the B-Tree, nodes with small number of
1036 elements will be combined and element counts will be smoothed out
1037 between nodes.
1038 .Pp
1039 The saturation percentage is between 50% and 100%.
1040 The default is 85% (the
1041 .Sq %
1042 suffix is not needed).
1043 .Pp
1044 Rebalancing is a per PFS operation, so each PFS in a
1045 .Nm HAMMER
1046 file system have to be rebalanced separately.
1047 .\" ==== dedup ====
1048 .It Cm dedup Ar filesystem
1049 .Nm ( HAMMER
1050 VERSION 5+)
1051 Perform offline (post-process) deduplication.
1052 Deduplication occurs at
1053 the block level, currently only data blocks of the same size can be
1054 deduped, metadata blocks can not.
1055 The hash function used for comparing
1056 data blocks is CRC-32 (CRCs are computed anyways as part of
1057 .Nm HAMMER
1058 data integrity features, so there's no additional overhead).
1059 Since CRC is a weak hash function a byte-by-byte comparison is done
1060 before actual deduping.
1061 In case of a CRC collision (two data blocks have the same CRC
1062 but different contents) the checksum is upgraded to SHA-256.
1063 .Pp
1064 Currently
1065 .Nm HAMMER
1066 reblocker may partially blow up (re-expand) dedup (reblocker's normal
1067 operation is to reallocate every record, so it's possible for deduped
1068 blocks to be re-expanded back).
1069 .Pp
1070 Deduplication is a per PFS operation, so each PFS in a
1071 .Nm HAMMER
1072 file system have to be deduped separately.
1073 This also
1074 means that if you have duplicated data in two different PFSs that data
1075 won't be deduped, however the addition of such feature is planned.
1076 .Pp
1077 The
1078 .Fl m Ar memlimit
1079 option should be used to limit memory use during the dedup run if the
1080 default 1G limit is too much for the machine.
1081 .\" ==== dedup-simulate ====
1082 .It Cm dedup-simulate Ar filesystem
1083 Shows potential space savings (simulated dedup ratio) one can get after
1084 running
1085 .Cm dedup
1086 command.
1087 If the estimated dedup ratio is greater than 1.00 you will see
1088 dedup space savings.
1089 Remember that this is an estimated number, in
1090 practice real dedup ratio will be slightly smaller because of
1091 .Nm HAMMER
1092 big-block underflows, B-Tree locking issues and other factors.
1093 .Pp
1094 Note that deduplication currently works only on bulk data so if you
1095 try to run
1096 .Cm dedup-simulate
1097 or
1098 .Cm dedup
1099 commands on a PFS that contains metadata only (directory entries,
1100 softlinks) you will get a 0.00 dedup ratio.
1101 .Pp
1102 The
1103 .Fl m Ar memlimit
1104 option should be used to limit memory use during the dedup run if the
1105 default 1G limit is too much for the machine.
1106 .\" ==== reblock* ====
1107 .It Cm reblock Ar filesystem Op Ar fill_percentage
1108 .It Cm reblock-btree Ar filesystem Op Ar fill_percentage
1109 .It Cm reblock-inodes Ar filesystem Op Ar fill_percentage
1110 .It Cm reblock-dirs Ar filesystem Op Ar fill_percentage
1111 .It Cm reblock-data Ar filesystem Op Ar fill_percentage
1112 Attempt to defragment and free space for reuse by reblocking a live
1113 .Nm HAMMER
1114 file system.
1115 Big-blocks cannot be reused by
1116 .Nm HAMMER
1117 until they are completely free.
1118 This command also has the effect of reordering all elements, effectively
1119 defragmenting the file system.
1120 .Pp
1121 The default fill percentage is 100% and will cause the file system to be
1122 completely defragmented.
1123 All specified element types will be reallocated and rewritten.
1124 If you wish to quickly free up space instead try specifying
1125 a smaller fill percentage, such as 90% or 80% (the
1126 .Sq %
1127 suffix is not needed).
1128 .Pp
1129 Since this command may rewrite the entire contents of the disk it is
1130 best to do it incrementally from a
1131 .Xr cron 8
1132 job along with the
1133 .Fl c Ar cyclefile
1134 and
1135 .Fl t Ar seconds
1136 options to limit the run time.
1137 The file system would thus be defragmented over long period of time.
1138 .Pp
1139 It is recommended that separate invocations be used for each data type.
1140 B-Tree nodes, inodes, and directories are typically the most important
1141 elements needing defragmentation.
1142 Data can be defragmented over a longer period of time.
1143 .Pp
1144 Reblocking is a per PFS operation, so each PFS in a
1145 .Nm HAMMER
1146 file system have to be reblocked separately.
1147 .\" ==== pfs-status ====
1148 .It Cm pfs-status Ar dirpath ...
1149 Retrieve the mirroring configuration parameters for the specified
1150 .Nm HAMMER
1151 file systems or pseudo-filesystems (PFS's).
1152 .\" ==== pfs-master ====
1153 .It Cm pfs-master Ar dirpath Op Ar options
1154 Create a pseudo-filesystem (PFS) inside a
1155 .Nm HAMMER
1156 file system.
1157 Up to 65536 PFSs can be created.
1158 Each PFS uses an independent inode numbering space making it suitable
1159 for replication.
1160 .Pp
1161 The
1162 .Cm pfs-master
1163 directive creates a PFS that you can read, write, and use as a mirroring
1164 source.
1165 .Pp
1166 A PFS can only be truly destroyed with the
1167 .Cm pfs-destroy
1168 directive.
1169 Removing the softlink will not destroy the underlying PFS.
1170 .Pp
1171 A PFS can only be created in the root PFS (PFS# 0),
1172 not in a PFS created by
1173 .Cm pfs-master
1174 or
1175 .Cm pfs-slave
1176 (PFS# >0).
1177 .Pp
1178 It is recommended that
1179 .Ar dirpath
1180 is of the form
1181 .Pa <fs>/pfs/<name>
1182 (i.e.\& located in
1183 .Pa PFS
1184 directory at root of
1185 .Nm HAMMER
1186 file system).
1187 .Pp
1188 It is recommended to use a
1189 .Nm null
1190 mount to access a PFS, except for root PFS, for more information see
1191 .Xr HAMMER 5 .
1192 .\" ==== pfs-slave ====
1193 .It Cm pfs-slave Ar dirpath Op Ar options
1194 Create a pseudo-filesystem (PFS) inside a
1195 .Nm HAMMER
1196 file system.
1197 Up to 65536 PFSs can be created.
1198 Each PFS uses an independent inode numbering space making it suitable
1199 for replication.
1200 .Pp
1201 The
1202 .Cm pfs-slave
1203 directive creates a PFS that you can use as a mirroring source or target.
1204 You will not be able to access a slave PFS until you have completed the
1205 first mirroring operation with it as the target (its root directory will
1206 not exist until then).
1207 .Pp
1208 Access to the pfs-slave via the special softlink, as described in the
1209 .Sx PSEUDO-FILESYSTEM (PFS) NOTES
1210 below, allows
1211 .Nm HAMMER
1212 to
1213 dynamically modify the snapshot transaction id by returning a dynamic result
1214 from
1215 .Xr readlink 2
1216 calls.
1217 .Pp
1218 A PFS can only be truly destroyed with the
1219 .Cm pfs-destroy
1220 directive.
1221 Removing the softlink will not destroy the underlying PFS.
1222 .Pp
1223 A PFS can only be created in the root PFS (PFS# 0),
1224 not in a PFS created by
1225 .Cm pfs-master
1226 or
1227 .Cm pfs-slave
1228 (PFS# >0).
1229 .Pp
1230 It is recommended that
1231 .Ar dirpath
1232 is of the form
1233 .Pa <fs>/pfs/<name>
1234 (i.e.\& located in
1235 .Pa PFS
1236 directory at root of
1237 .Nm HAMMER
1238 file system).
1239 .Pp
1240 It is recommended to use a
1241 .Nm null
1242 mount to access a PFS, except for root PFS, for more information see
1243 .Xr HAMMER 5 .
1244 .\" ==== pfs-update ====
1245 .It Cm pfs-update Ar dirpath Op Ar options
1246 Update the configuration parameters for an existing
1247 .Nm HAMMER
1248 file system or pseudo-filesystem.
1249 Options that may be specified:
1250 .Bl -tag -width indent
1251 .It Cm sync-beg-tid= Ns Ar 0x16llx
1252 This is the automatic snapshot access starting transaction id for
1253 mirroring slaves.
1254 This parameter is normally updated automatically by the
1255 .Cm mirror-write
1256 directive.
1257 .Pp
1258 It is important to note that accessing a mirroring slave
1259 with a transaction id greater than the last fully synchronized transaction
1260 id can result in an unreliable snapshot since you will be accessing
1261 data that is still undergoing synchronization.
1262 .Pp
1263 Manually modifying this field is dangerous and can result in a broken mirror.
1264 .It Cm sync-end-tid= Ns Ar 0x16llx
1265 This is the current synchronization point for mirroring slaves.
1266 This parameter is normally updated automatically by the
1267 .Cm mirror-write
1268 directive.
1269 .Pp
1270 Manually modifying this field is dangerous and can result in a broken mirror.
1271 .It Cm shared-uuid= Ns Ar uuid
1272 Set the shared UUID for this file system.
1273 All mirrors must have the same shared UUID.
1274 For safety purposes the
1275 .Cm mirror-write
1276 directives will refuse to operate on a target with a different shared UUID.
1277 .Pp
1278 Changing the shared UUID on an existing, non-empty mirroring target,
1279 including an empty but not completely pruned target,
1280 can lead to corruption of the mirroring target.
1281 .It Cm unique-uuid= Ns Ar uuid
1282 Set the unique UUID for this file system.
1283 This UUID should not be used anywhere else,
1284 even on exact copies of the file system.
1285 .It Cm label= Ns Ar string
1286 Set a descriptive label for this file system.
1287 .It Cm snapshots= Ns Ar string
1288 Specify the snapshots directory which
1289 .Nm
1290 .Cm cleanup
1291 will use to manage this PFS.
1292 .Bl -tag -width indent
1293 .It Nm HAMMER No version 2-
1294 The snapshots directory does not need to be configured for
1295 PFS masters and will default to
1296 .Pa <pfs>/snapshots .
1297 .Pp
1298 PFS slaves are mirroring slaves so you cannot configure a snapshots
1299 directory on the slave itself to be managed by the slave's machine.
1300 In fact, the slave will likely have a
1301 .Pa snapshots
1302 sub-directory mirrored
1303 from the master, but that directory contains the configuration the master
1304 is using for its copy of the file system, not the configuration that we
1305 want to use for our slave.
1306 .Pp
1307 It is recommended that
1308 .Pa <fs>/var/slaves/<name>
1309 be configured for a PFS slave, where
1310 .Pa <fs>
1311 is the base
1312 .Nm HAMMER
1313 file system, and
1314 .Pa <name>
1315 is an appropriate label.
1316 .It Nm HAMMER No version 3+
1317 The snapshots directory does not need to be configured for PFS masters or
1318 slaves.
1319 The snapshots directory defaults to
1320 .Pa /var/hammer/<pfs>
1321 .Pa ( /var/hammer/root
1322 for root mount).
1323 .El
1324 .Pp
1325 You can control snapshot retention on your slave independent of the master.
1326 .It Cm snapshots-clear
1327 Zero out the
1328 .Cm snapshots
1329 directory path for this PFS.
1330 .It Cm prune-min= Ns Ar N Ns Cm d
1331 .It Cm prune-min= Ns Oo Ar N Ns Cm d/ Oc Ns \
1332 Ar hh Ns Op Cm \&: Ns Ar mm Ns Op Cm \&: Ns Ar ss
1333 Set the minimum fine-grained data retention period.
1334 .Nm HAMMER
1335 always retains fine-grained history up to the most recent snapshot.
1336 You can extend the retention period further by specifying a non-zero
1337 pruning minimum.
1338 Any snapshot softlinks within the retention period are ignored
1339 for the purposes of pruning (i.e.\& the fine grained history is retained).
1340 Number of days, hours, minutes and seconds are given as
1341 .Ar N , hh , mm
1342 and
1343 .Ar ss .
1344 .Pp
1345 Because the transaction id in the snapshot softlink cannot be used
1346 to calculate a timestamp,
1347 .Nm HAMMER
1348 uses the earlier of the
1349 .Fa st_ctime
1350 or
1351 .Fa st_mtime
1352 field of the softlink to
1353 determine which snapshots fall within the retention period.
1354 Users must be sure to retain one of these two fields when manipulating
1355 the softlink.
1356 .El
1357 .\" ==== pfs-upgrade ====
1358 .It Cm pfs-upgrade Ar dirpath
1359 Upgrade a PFS from slave to master operation.
1360 The PFS will be rolled back to the current end synchronization transaction id
1361 (removing any partial synchronizations), and will then become writable.
1362 .Pp
1363 .Em WARNING!
1364 .Nm HAMMER
1365 currently supports only single masters and using
1366 this command can easily result in file system corruption
1367 if you don't know what you are doing.
1368 .Pp
1369 This directive will refuse to run if any programs have open descriptors
1370 in the PFS, including programs chdir'd into the PFS.
1371 .\" ==== pfs-downgrade ====
1372 .It Cm pfs-downgrade Ar dirpath
1373 Downgrade a master PFS from master to slave operation.
1374 The PFS becomes read-only and access will be locked to its
1375 .Cm sync-end-tid .
1376 .Pp
1377 This directive will refuse to run if any programs have open descriptors
1378 in the PFS, including programs chdir'd into the PFS.
1379 .\" ==== pfs-destroy ====
1380 .It Cm pfs-destroy Ar dirpath
1381 This permanently destroys a PFS.
1382 .Pp
1383 This directive will refuse to run if any programs have open descriptors
1384 in the PFS, including programs chdir'd into the PFS.
1385 As safety measure the
1386 .Fl y
1387 flag have no effect on this directive.
1388 .\" ==== mirror-read ====
1389 .It Cm mirror-read Ar filesystem Op Ar begin-tid
1390 Generate a mirroring stream to stdout.
1391 The stream ends when the transaction id space has been exhausted.
1392 .Ar filesystem
1393 may be a master or slave PFS.
1394 .\" ==== mirror-read-stream ====
1395 .It Cm mirror-read-stream Ar filesystem Op Ar begin-tid
1396 Generate a mirroring stream to stdout.
1397 Upon completion the stream is paused until new data is synced to the
1398 .Ar filesystem ,
1399 then resumed.
1400 Operation continues until the pipe is broken.
1401 See the
1402 .Cm mirror-stream
1403 command for more details.
1404 .\" ==== mirror-write ====
1405 .It Cm mirror-write Ar filesystem
1406 Take a mirroring stream on stdin.
1407 .Ar filesystem
1408 must be a slave PFS.
1409 .Pp
1410 This command will fail if the
1411 .Cm shared-uuid
1412 configuration field for the two file systems do not match.
1413 See the
1414 .Cm mirror-copy
1415 command for more details.
1416 .Pp
1417 If the target PFS does not exist this command will ask you whether
1418 you want to create a compatible PFS slave for the target or not.
1419 .\" ==== mirror-dump ====
1420 .It Ar mirror-dump Ar [header]
1421 A
1422 .Cm mirror-read
1423 can be piped into a
1424 .Cm mirror-dump
1425 to dump an ASCII representation of the mirroring stream.
1426 If the keyword
1427 .Ar header
1428 is specified, only the header information is shown.
1429 .\" ==== mirror-copy ====
1430 .\".It Cm mirror-copy Ar [[user@]host:]filesystem [[user@]host:]filesystem
1431 .It Cm mirror-copy \
1432 Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem \
1433 Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem
1434 This is a shortcut which pipes a
1435 .Cm mirror-read
1436 command to a
1437 .Cm mirror-write
1438 command.
1439 If a remote host specification is made the program forks a
1440 .Xr ssh 1
1441 (or other program as specified by the
1442 .Ev HAMMER_RSH
1443 environment variable) and execs the
1444 .Cm mirror-read
1445 and/or
1446 .Cm mirror-write
1447 on the appropriate host.
1448 The source may be a master or slave PFS, and the target must be a slave PFS.
1449 .Pp
1450 This command also establishes full duplex communication and turns on
1451 the 2-way protocol feature
1452 .Fl ( 2 )
1453 which automatically negotiates transaction id
1454 ranges without having to use a cyclefile.
1455 If the operation completes successfully the target PFS's
1456 .Cm sync-end-tid
1457 will be updated.
1458 Note that you must re-chdir into the target PFS to see the updated information.
1459 If you do not you will still be in the previous snapshot.
1460 .Pp
1461 If the target PFS does not exist this command will ask you whether
1462 you want to create a compatible PFS slave for the target or not.
1463 .\" ==== mirror-stream ====
1464 .\".It Cm mirror-stream Ar [[user@]host:]filesystem [[user@]host:]filesystem
1465 .It Cm mirror-stream \
1466 Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem \
1467 Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem
1468 This is a shortcut which pipes a
1469 .Cm mirror-read-stream
1470 command to a
1471 .Cm mirror-write
1472 command.
1473 This command works similarly to
1474 .Cm mirror-copy
1475 but does not exit after the initial mirroring completes.
1476 The mirroring operation will resume as changes continue to be made to the
1477 source.
1478 The command is commonly used with
1479 .Fl i Ar delay
1480 and
1481 .Fl b Ar bandwidth
1482 options to keep the mirroring target in sync with the source on a continuing
1483 basis.
1484 .Pp
1485 If the pipe is broken the command will automatically retry after sleeping
1486 for a short while.
1487 The time slept will be 15 seconds plus the time given in the
1488 .Fl i
1489 option.
1490 .Pp
1491 This command also detects the initial-mirroring case and spends some
1492 time scanning the B-Tree to find good break points, allowing the initial
1493 bulk mirroring operation to be broken down into 4GB pieces.
1494 This means that the user can kill and restart the operation and it will
1495 not have to start from scratch once it has gotten past the first chunk.
1496 The
1497 .Fl S
1498 option may be used to change the size of pieces and the
1499 .Fl B
1500 option may be used to disable this feature and perform an initial bulk
1501 transfer instead.
1502 .\" ==== version ====
1503 .It Cm version Ar filesystem
1504 This command returns the
1505 .Nm HAMMER
1506 file system version for the specified
1507 .Ar filesystem
1508 as well as the range of versions supported in the kernel.
1509 The
1510 .Fl q
1511 option may be used to remove the summary at the end.
1512 .\" ==== version-upgrade ====
1513 .It Cm version-upgrade Ar filesystem Ar version Op Cm force
1514 Upgrade the
1515 .Nm HAMMER
1516 .Ar filesystem
1517 to the specified
1518 .Ar version .
1519 Once upgraded a file system may not be downgraded.
1520 If you wish to upgrade a file system to a version greater or equal to the
1521 work-in-progress (WIP) version number you must specify the
1522 .Cm force
1523 directive.
1524 Use of WIP versions should be relegated to testing and may require wiping
1525 the file system as development progresses, even though the WIP version might
1526 not change.
1527 .Pp
1528 .Em NOTE!
1529 This command operates on the entire
1530 .Nm HAMMER
1531 file system and is not a per PFS operation.
1532 All PFS's will be affected.
1533 .Bl -tag -width indent
1534 .It 1
1535 .Dx 2.0
1536 default version, first
1537 .Nm HAMMER
1538 release.
1539 .It 2
1540 .Dx 2.3 .
1541 New directory entry layout.
1542 This version is using a new directory hash key.
1543 .It 3
1544 .Dx 2.5 .
1545 New snapshot management, using file system meta-data for saving
1546 configuration file and snapshots (transaction ids etc.).
1547 Also default snapshots directory has changed.
1548 .It 4
1549 .Dx 2.6
1550 default version.
1551 New undo/redo/flush, giving
1552 .Nm HAMMER
1553 a much faster sync and fsync.
1554 .It 5
1555 .Dx 2.9 .
1556 Deduplication support.
1557 .It 6
1558 .Dx 2.9 .
1559 Directory hash ALG1.
1560 Tends to maintain inode number / directory name entry ordering better
1561 for files after minor renaming.
1562 .El
1563 .El
1564 .Sh PSEUDO-FILESYSTEM (PFS) NOTES
1565 The root of a PFS is not hooked into the primary
1566 .Nm HAMMER
1567 file system as a directory.
1568 Instead,
1569 .Nm HAMMER
1570 creates a special softlink called
1571 .Ql @@PFS%05d
1572 (exactly 10 characters long) in the primary
1573 .Nm HAMMER
1574 file system.
1575 .Nm HAMMER
1576 then modifies the contents of the softlink as read by
1577 .Xr readlink 2 ,
1578 and thus what you see with an
1579 .Nm ls
1580 command or if you were to
1581 .Nm cd
1582 into the link.
1583 If the PFS is a master the link reflects the current state of the PFS.
1584 If the PFS is a slave the link reflects the last completed snapshot, and the
1585 contents of the link will change when the next snapshot is completed, and
1586 so forth.
1587 .Pp
1588 The
1589 .Nm
1590 utility employs numerous safeties to reduce user foot-shooting.
1591 The
1592 .Cm mirror-copy
1593 directive requires that the target be configured as a slave and that the
1594 .Cm shared-uuid
1595 field of the mirroring source and target match.
1596 The
1597 .Cm pfs-master
1598 and
1599 .Cm pfs-slave
1600 directives require that the PFS softlink be created under the main
1601 .Nm
1602 filesystem mount. You may only access PFS softlinks via the main
1603 .Nm
1604 filesystem mount.
1605 .Sh DOUBLE_BUFFER MODE
1606 There is a limit to the number of vnodes the kernel can cache, and because
1607 file buffers are associated with a vnode the related data cache can get
1608 blown away when operating on large numbers of files even if the system has
1609 sufficient memory to hold the file data.
1610 .Pp
1611 If you turn on
1612 .Nm HAMMER Ns 's
1613 double buffer mode by setting the
1614 .Xr sysctl 8
1615 node
1616 .Va vfs.hammer.double_buffer
1617 to 1
1618 .Nm HAMMER
1619 will cache file data via the block device and copy it into the per-file
1620 buffers as needed.  The data will be double-cached at least until the
1621 buffer cache throws away the file buffer.
1622 This mode is typically used in conjunction with
1623 .Xr swapcache 8
1624 when
1625 .Va vm.swapcache.data_enable
1626 is turned on in order to prevent unnecessary re-caching of file data
1627 due to vnode recycling.
1628 The swapcache will save the cached VM pages related to
1629 .Nm HAMMER Ns 's
1630 block
1631 device (which doesn't recycle unless you umount the filesystem) instead
1632 of the cached VM pages backing the file vnodes.
1633 .Pp
1634 Double buffering is normally desirable when working with large filesystems,
1635 particularly when swapcache is used.
1636 The swapcache can only back active VM objects, including the block device,
1637 and large filesystems often have far more inodes than the kernel can support.
1638 In addition, when using this mode, you may wish to reduce the
1639 .Va kern.maxvnodes
1640 setting for the system to force the system to do less caching of logical
1641 file buffers and more caching of device buffers, since the device buffers
1642 are backing the logical file buffers.
1643 .Sh UPGRADE INSTRUCTIONS HAMMER V1 TO V2
1644 This upgrade changes the way directory entries are stored.
1645 It is possible to upgrade a V1 file system to V2 in place, but
1646 directories created prior to the upgrade will continue to use
1647 the old layout.
1648 .Pp
1649 Note that the slave mirroring code in the target kernel had bugs in
1650 V1 which can create an incompatible root directory on the slave.
1651 Do not mix a
1652 .Nm HAMMER
1653 master created after the upgrade with a
1654 .Nm HAMMER
1655 slave created prior to the upgrade.
1656 .Pp
1657 Any directories created after upgrading will use a new layout.
1658 .Sh UPGRADE INSTRUCTIONS HAMMER V2 TO V3
1659 This upgrade adds meta-data elements to the B-Tree.
1660 It is possible to upgrade a V2 file system to V3 in place.
1661 After issuing the upgrade be sure to run a
1662 .Nm
1663 .Cm cleanup
1664 to perform post-upgrade tasks.
1665 .Pp
1666 After making this upgrade running a
1667 .Nm
1668 .Cm cleanup
1669 will move the
1670 .Pa <pfs>/snapshots
1671 directory for each PFS mount into
1672 .Pa /var/hammer/<pfs> .
1673 A
1674 .Nm HAMMER
1675 root mount will migrate
1676 .Pa /snapshots
1677 into
1678 .Pa /var/hammer/root .
1679 Migration occurs only once and only if you have not specified
1680 a snapshots directory in the PFS configuration.
1681 If you have specified a snapshots directory in the PFS configuration no
1682 automatic migration will occur.
1683 .Pp
1684 For slaves, if you desire, you can migrate your snapshots
1685 config to the new location manually and then clear the
1686 snapshot directory configuration in the slave PFS.
1687 The new snapshots hierarchy is designed to work with
1688 both master and slave PFSs equally well.
1689 .Pp
1690 In addition, the old config file will be moved to file system meta-data,
1691 editable via the new
1692 .Nm
1693 .Cm viconfig
1694 directive.
1695 The old config file will be deleted.
1696 Migration occurs only once.
1697 .Pp
1698 The V3 file system has new
1699 .Cm snap*
1700 directives for creating snapshots.
1701 All snapshot directives, including the original, will create
1702 meta-data entries for the snapshots and the pruning code will
1703 automatically incorporate these entries into its list and
1704 expire them the same way it expires softlinks.
1705 If you by accident blow away your snapshot softlinks you can use the
1706 .Cm snapls
1707 directive to get a definitive list from the file system meta-data and
1708 regenerate them from that list.
1709 .Pp
1710 .Em WARNING!
1711 If you are using
1712 .Nm
1713 to backup file systems your scripts may be using the
1714 .Cm synctid
1715 directive to generate transaction ids.
1716 This directive does not create a snapshot.
1717 You will have to modify your scripts to use the
1718 .Cm snapq
1719 directive to generate the linkbuf for the softlink you create, or
1720 use one of the other
1721 .Cm snap*
1722 directives.
1723 The older
1724 .Cm snapshot
1725 directive will continue to work as expected and in V3 it will also
1726 record the snapshot transaction id in file system meta-data.
1727 You may also want to make use of the new
1728 .Ar note
1729 tag for the meta-data.
1730 .Pp
1731 .Em WARNING!
1732 If you used to remove snapshot softlinks with
1733 .Nm rm
1734 you should probably start using the
1735 .Cm snaprm
1736 directive instead to also remove the related meta-data.
1737 The pruning code scans the meta-data so just removing the
1738 softlink is not sufficient.
1739 .Sh UPGRADE INSTRUCTIONS HAMMER V3 TO V4
1740 This upgrade changes undo/flush, giving faster sync.
1741 It is possible to upgrade a V3 file system to V4 in place.
1742 This upgrade reformats the UNDO/REDO FIFO (typically 1GB),
1743 so upgrade might take a minute or two depending.
1744 .Pp
1745 Version 4 allows the UNDO/REDO FIFO to be flushed without also having
1746 to flush the volume header, removing 2 of the 4 disk syncs typically
1747 required for an
1748 .Fn fsync
1749 and removing 1 of the 2 disk syncs typically
1750 required for a flush sequence.
1751 Version 4 also implements the REDO log (see
1752 .Sx FSYNC FLUSH MODES
1753 below) which is capable
1754 of fsync()ing with either one disk flush or zero disk flushes.
1755 .Sh UPGRADE INSTRUCTIONS HAMMER V4 TO V5
1756 This upgrade brings in deduplication support.
1757 It is possible to upgrade a V4 file system to V5 in place.
1758 Technically it makes the layer2
1759 .Va bytes_free
1760 field a signed value instead of unsigned, allowing it to go negative.
1761 A version 5 filesystem is required for dedup operation.
1762 .Sh UPGRADE INSTRUCTIONS HAMMER V5 TO V6
1763 It is possible to upgrade a V5 file system to V6 in place.
1764 .Sh FSYNC FLUSH MODES
1765 .Nm HAMMER
1766 implements five different fsync flush modes via the
1767 .Va vfs.hammer.fsync_mode
1768 sysctl, for
1769 .Nm HAMMER
1770 version 4+ file systems.
1771 .Pp
1772 As of
1773 .Dx 2.6
1774 fsync mode 3 is set by default.
1775 REDO operation and recovery is enabled by default.
1776 .Bl -tag -width indent
1777 .It mode 0
1778 Full synchronous fsync semantics without REDO.
1779 .Pp
1780 .Nm HAMMER
1781 will not generate REDOs.
1782 A
1783 .Fn fsync
1784 will completely sync
1785 the data and meta-data and double-flush the FIFO, including
1786 issuing two disk synchronization commands.
1787 The data is guaranteed
1788 to be on the media as of when
1789 .Fn fsync
1790 returns.
1791 Needless to say, this is slow.
1792 .It mode 1
1793 Relaxed asynchronous fsync semantics without REDO.
1794 .Pp
1795 This mode works the same as mode 0 except the last disk synchronization
1796 command is not issued.
1797 It is faster than mode 0 but not even remotely
1798 close to the speed you get with mode 2 or mode 3.
1799 .Pp
1800 Note that there is no chance of meta-data corruption when using this
1801 mode, it simply means that the data you wrote and then
1802 .Fn fsync Ns 'd
1803 might not have made it to the media if the storage system crashes at a bad
1804 time.
1805 .It mode 2
1806 Full synchronous fsync semantics using REDO.
1807 NOTE: If not running a
1808 .Nm HAMMER
1809 version 4 filesystem or later mode 0 is silently used.
1810 .Pp
1811 .Nm HAMMER
1812 will generate REDOs in the UNDO/REDO FIFO based on a heuristic.
1813 If this is sufficient to satisfy the
1814 .Fn fsync
1815 operation the blocks will be written out and
1816 .Nm HAMMER
1817 will wait for the I/Os to complete,
1818 and then followup with a disk sync command to guarantee the data
1819 is on the media before returning.
1820 This is slower than mode 3 and can result in significant disk or
1821 SSDs overheads, though not as bad as mode 0 or mode 1.
1822 .It mode 3
1823 Relaxed asynchronous fsync semantics using REDO.
1824 NOTE: If not running a
1825 .Nm HAMMER
1826 version 4 filesystem or later mode 1 is silently used.
1827 .Pp
1828 .Nm HAMMER
1829 will generate REDOs in the UNDO/REDO FIFO based on a heuristic.
1830 If this is sufficient to satisfy the
1831 .Fn fsync
1832 operation the blocks
1833 will be written out and
1834 .Nm HAMMER
1835 will wait for the I/Os to complete,
1836 but will
1837 .Em NOT
1838 issue a disk synchronization command.
1839 .Pp
1840 Note that there is no chance of meta-data corruption when using this
1841 mode, it simply means that the data you wrote and then
1842 .Fn fsync Ns 'd
1843 might
1844 not have made it to the media if the storage system crashes at a bad
1845 time.
1846 .Pp
1847 This mode is the fastest production fsyncing mode available.
1848 This mode is equivalent to how the UFS fsync in the
1849 .Bx Ns s
1850 operates.
1851 .It mode 4
1852 fsync is ignored.
1853 .Pp
1854 Calls to
1855 .Fn fsync
1856 will be ignored.
1857 This mode is primarily designed
1858 for testing and should not be used on a production system.
1859 .El
1860 .Sh RESTORING FROM A SNAPSHOT BACKUP
1861 You restore a snapshot by copying it over to live, but there is a caveat.
1862 The mtime and atime fields for files accessed via a snapshot is locked
1863 to the ctime in order to keep the snapshot consistent, because neither
1864 mtime nor atime changes roll any history.
1865 .Pp
1866 In order to avoid unnecessary copying it is recommended that you use
1867 .Nm cpdup
1868 .Fl VV
1869 .Fl v
1870 when doing the copyback.
1871 Also make sure you traverse the snapshot softlink by appending a ".",
1872 as in "<snapshotpath>/.", and you match up the directory properly.
1873 .Sh RESTORING A PFS FROM A MIRROR
1874 A PFS can be restored from a mirror with
1875 .Cm mirror-copy .
1876 .Cm config
1877 data must be copied separately.
1878 At last the PFS can be upgraded to master using
1879 .Cm pfs-upgrade .
1880 .Pp
1881 It is not possible to restore the root PFS (PFS# 0) by using mirroring,
1882 as the root PFS is always a master PFS.
1883 A normal copy (e.g.\& using
1884 .Xr cpdup 1 )
1885 must be done, ignoring history.
1886 If history is important, old root PFS can me restored to a new PFS, and
1887 important directories/files can be
1888 .Nm null
1889 mounted to the new PFS.
1890 .Sh ENVIRONMENT
1891 The following environment variables affect the execution of
1892 .Nm :
1893 .Bl -tag -width ".Ev EDITOR"
1894 .It Ev EDITOR
1895 The editor program specified in the variable
1896 .Ev EDITOR
1897 will be invoked instead of the default editor, which is
1898 .Xr vi 1 .
1899 .It Ev HAMMER_RSH
1900 The command specified in the variable
1901 .Ev HAMMER_RSH
1902 will be used to initiate remote operations for the mirror-copy and
1903 mirror-stream commands instead of the default command, which is
1904 .Xr ssh 1 .
1905 The program will be invoked via
1906 .Xr execvp 3
1907 using a typical
1908 .Xr rsh 1
1909 style
1910 .Cm -l user host <remote-command>
1911 command line.
1912 .It Ev VISUAL
1913 Same effect as
1914 .Ev EDITOR
1915 variable.
1916 .El
1917 .Sh FILES
1918 .Bl -tag -width ".It Pa <fs>/var/slaves/<name>" -compact
1919 .It Pa <pfs>/snapshots
1920 default per PFS snapshots directory
1921 .Nm ( HAMMER
1922 VERSION 2-)
1923 .It Pa /var/hammer/<pfs>
1924 default per PFS snapshots directory (not root)
1925 .Nm ( HAMMER
1926 VERSION 3+)
1927 .It Pa /var/hammer/root
1928 default snapshots directory for root directory
1929 .Nm ( HAMMER
1930 VERSION 3+)
1931 .It Pa <snapshots>/config
1932 per PFS
1933 .Nm
1934 .Cm cleanup
1935 configuration file
1936 .Nm ( HAMMER
1937 VERSION 2-)
1938 .It Pa <fs>/var/slaves/<name>
1939 recommended slave PFS snapshots directory
1940 .Nm ( HAMMER
1941 VERSION 2-)
1942 .It Pa <fs>/pfs
1943 recommended PFS directory
1944 .El
1945 .Sh EXIT STATUS
1946 .Ex -std
1947 .Sh SEE ALSO
1948 .Xr ssh 1 ,
1949 .Xr undo 1 ,
1950 .Xr HAMMER 5 ,
1951 .Xr periodic.conf 5 ,
1952 .Xr loader 8 ,
1953 .Xr mount_hammer 8 ,
1954 .Xr mount_null 8 ,
1955 .Xr newfs_hammer 8 ,
1956 .Xr swapcache 8 ,
1957 .Xr sysctl 8
1958 .Sh HISTORY
1959 The
1960 .Nm
1961 utility first appeared in
1962 .Dx 1.11 .
1963 .Sh AUTHORS
1964 .An Matthew Dillon Aq Mt dillon@backplane.com