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