HAMMER - Add additional warnings for v2/v3 upgrades, fix bug in snaprm
[dragonfly.git] / sbin / hammer / hammer.8
CommitLineData
0dfeb6c8
MD
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.\"
de1c0b31 33.\" $DragonFly: src/sbin/hammer/hammer.8,v 1.58 2008/11/13 02:04:27 dillon Exp $
e0331f4f 34.\"
4567021b 35.Dd September 28, 2009
0dfeb6c8
MD
36.Dt HAMMER 8
37.Os
38.Sh NAME
39.Nm hammer
40.Nd HAMMER file system utility
41.Sh SYNOPSIS
42.Nm
4567021b
TN
43.Fl h
44.Nm
45.Op Fl 2Bqrvy
48eadef9 46.Op Fl b Ar bandwidth
4567021b 47.Op Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead
d7ae405c 48.Op Fl c Ar cyclefile
4567021b 49.Op Fl f Ar blkdev Ns Oo Ns Cm \&: Ns Ar blkdev Oc Ns *
6d9ab5c5 50.\" .Op Fl s Ar linkpath
48eadef9 51.Op Fl i Ar delay
99d6191f 52.Op Fl t Ar seconds
0dfeb6c8 53.Ar command
34bb69d8 54.Op Ar argument ...
0dfeb6c8 55.Sh DESCRIPTION
6d9ab5c5 56This manual page documents the
0dfeb6c8 57.Nm
6d9ab5c5 58utility which provides miscellaneous functions related to managing a
b4448f1a
TN
59.Nm HAMMER
60file system.
61For a general introduction to the
62.Nm HAMMER
63file system, its features, and
6d9ab5c5 64examples on how to set up and maintain one, see
b4448f1a 65.Xr HAMMER 5 .
0dfeb6c8
MD
66.Pp
67The options are as follows:
68.Bl -tag -width indent
69.It Fl h
84082922 70Get help.
d4e5b69b
MD
71.It Fl 2
72Tell the mirror commands to use a 2-way protocol, which allows
2010519f
TN
73automatic negotiation of transaction id ranges.
74This option is automatically enabled by the
4567021b 75.Cm mirror-copy
d4e5b69b 76command.
4567021b
TN
77.It Fl B
78Bulk Transfer.
79.Cm Mirror-stream
80will not attempt to break-up large initial bulk transfers into smaller pieces.
81This can save time but if the link is lost in the middle of the
82initial bulk transfer you will have to start over from scratch.
48eadef9
MD
83.It Fl b Ar bandwidth
84Specify a bandwidth limit in bytes per second for mirroring streams.
85This option is typically used to prevent batch mirroring operations from
86loading down the machine.
15fa4caf 87The bandwidth may be suffixed with
4567021b 88.Cm k , m ,
15fa4caf 89or
4567021b 90.Cm g
2010519f 91to specify values in kilobytes, megabytes, and gigabytes per second.
224ac2f2 92If no suffix is specified, bytes per second is assumed.
4567021b
TN
93.It Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead
94Set the memory cache size for any raw
95.Tn I/O .
96The default is 16m.
97A suffix of
98.Cm k
99for kilobytes and
100.Cm m
101for megabytes is allowed,
102else the cache size is specified in bytes.
103.Pp
104The read-behind/read-ahead defaults to 4 hammer blocks.
105.Pp
106This option is typically only used with diagnostic commands
107as kernel-supported commands will use the kernel's buffer cache.
d7ae405c 108.It Fl c Ar cyclefile
84082922
TN
109When pruning and reblocking you can instruction
110.Nm
2010519f 111to start at the object id stored in the specified file.
84082922 112If the file does not exist
15fa4caf 113.Nm
84082922
TN
114will start at the beginning.
115If
15fa4caf 116.Nm
84082922 117is told to run for a
d7ae405c 118specific period of time and is unable to complete the operation it will
2010519f 119write out the current object id so the next run can pick up where it left off.
84082922
TN
120If
121.Nm
483bb69b
TN
122runs to completion it will delete
123.Ar cyclefile .
4567021b 124.It Fl f Ar blkdev Ns Oo Ns Cm \&: Ns Ar blkdev Oc Ns *
b4448f1a
TN
125Specify the volumes making up a
126.Nm HAMMER
127file system.
48eadef9
MD
128.It Fl i Ar delay
129When maintaining a streaming mirroring this option specifies the
130minimum delay after a batch ends before the next batch is allowed
131to start.
132The default is five seconds.
e95314de 133.It Fl q
bb92c669 134Decrease verboseness.
2010519f 135May be specified multiple times.
bb8e52c0
TN
136.It Fl r
137Specify recursion for those commands which support it.
99d6191f 138.It Fl t Ar seconds
0006adae 139When pruning and reblocking you can tell the utility to stop after a
2010519f
TN
140certain period of time.
141This option is used along with the
483bb69b 142.Fl c Ar cyclefile
b4448f1a 143option to prune or reblock a portion of the file system incrementally.
563b4845 144.It Fl v
2010519f
TN
145Increase verboseness.
146May be specified multiple times.
07485271
MN
147.It Fl y
148Force "yes" for any interactive question.
0dfeb6c8
MD
149.El
150.Pp
151The commands are as follows:
152.Bl -tag -width indent
15fa4caf 153.\" ==== synctid ====
4567021b 154.It Cm synctid Ar filesystem Op Cm quick
367431cf 155Generates a guaranteed, formal 64 bit transaction id representing the
b4448f1a
TN
156current state of the specified
157.Nm HAMMER
2010519f
TN
158file system.
159The file system will be synced to the media.
367431cf
MD
160.Pp
161If the
4567021b 162.Cm quick
b4448f1a
TN
163keyword is specified the file system will be soft-synced, meaning that a
164crash might still undo the state of the file system as of the transaction
367431cf
MD
165id returned but any new modifications will occur after the returned
166transaction id as expected.
bf2c6489
MD
167.Pp
168This operation does not create a snapshot. It is meant to be used
169to track temporary fine-grained changes to a subset of files and
170will only remain valid for @@ snapshot access purposes for the
171.Cm prune-min
172period configured for the PFS. If you desire a real snapshot then
173the
174.Cm snapq
175directive may be what you are looking for.
15fa4caf 176.\" ==== bstats ====
4567021b 177.It Cm bstats Op Ar interval
b4448f1a
TN
178Output
179.Nm HAMMER
180B-tree statistics until interrupted.
84082922
TN
181Pause
182.Ar interval
b4448f1a 183seconds between each display.
84082922 184The default interval is one second.
15fa4caf 185.\" ==== iostats ====
4567021b 186.It Cm iostats Op Ar interval
b4448f1a
TN
187Output
188.Nm HAMMER
4567021b
TN
189.Tn I/O
190statistics until interrupted.
84082922
TN
191Pause
192.Ar interval
b4448f1a 193seconds between each display.
84082922 194The default interval is one second.
15fa4caf 195.\" ==== history ====
4567021b 196.It Cm history Ar path ...
b4448f1a
TN
197Show the modification history for
198.Nm HAMMER
199file's inode and data.
b46b99bf 200.\" ==== blockmap ====
4567021b
TN
201.It Cm blockmap
202Dump the blockmap for the file system.
203The
204.Nm HAMMER
205blockmap is two-layer
206blockmap representing the maximum possible file system size of 1 Exabyte.
b46b99bf 207Needless to say the second layer is only present for blocks which exist.
4567021b
TN
208.Nm HAMMER Ns 's
209blockmap represents 8-Megabyte blocks, called big-blocks.
210Each big-block has an append
b46b99bf
MD
211point, a free byte count, and a typed zone id which allows content to be
212reverse engineered to some degree.
213.Pp
4567021b
TN
214In
215.Nm HAMMER
216allocations essentially appended to a selected big-block using
217the append offset and deducted from the free byte count.
218When space is freed the free byte count is adjusted but
219.Nm HAMMER
220does not track holes in big-blocks for reallocation.
221A big-block must be completely freed, either
222through normal file system operations or through reblocking, before
b46b99bf
MD
223it can be reused.
224.Pp
225Data blocks can be shared by deducting the space used from the free byte
4567021b
TN
226count for each shared references, though
227.Nm HAMMER
228does not yet make use of this feature.
229This means the free byte count can legally go negative.
b46b99bf
MD
230.Pp
231This command needs the
232.Fl f
233flag.
15fa4caf 234.\" ==== show ====
4567021b
TN
235.It Cm show Op Ar lo Ns Cm \&: Ns Ar objid
236Dump the B-tree.
237By default this command will validate all B-Tree
b46b99bf
MD
238linkages and CRCs, including data CRCs, and will report the most verbose
239information it can dig up.
240Any errors will show up with a 'B' in column 1 along with various
241other error flags.
242.Pp
e7f926a5
MD
243If you specify a localization and object id field the dump will
244search for the key printing nodes as it recurses down, and then
245will iterate forwards.
246.Pp
b46b99bf
MD
247If you use
248.Fl q
249the command will report less information about the inode contents.
250.Pp
251If you use
252.Fl qq
253the command will not report the content of the inode or other typed
254data at all.
255.Pp
256If you use
257.Fl qqq
258the command will not report volume header information, big-block fill
4567021b
TN
259ratios, mirror transaction ids, or report or check data CRCs.
260B-tree CRCs and linkages are still checked.
b46b99bf 261.Pp
2010519f 262This command needs the
b4448f1a 263.Fl f
84082922
TN
264flag.
265.\" .It Ar blockmap
266.\" Dump the B-tree, record, large-data, and small-data blockmaps, showing
267.\" physical block assignments and free space percentages.
5e435c92 268.\" ==== namekey1 ====
4567021b 269.It Cm namekey1 Ar filename
b4448f1a
TN
270Generate a
271.Nm HAMMER
5e435c92 27264 bit directory hash for the specified file name, using
4567021b 273the original directory hash algorithm in version 1 of the file system.
cbd800c2
MD
274The low 32 bits are used as an iterator for hash collisions and will be
275output as 0.
5e435c92 276.\" ==== namekey2 ====
4567021b 277.It Cm namekey2 Ar filename
5e435c92
MD
278Generate a
279.Nm HAMMER
28064 bit directory hash for the specified file name, using
4567021b 281the new directory hash algorithm in version 2 of the file system.
5e435c92
MD
282The low 32 bits are still used as an iterator but will start out containing
283part of the hash key.
15fa4caf 284.\" ==== namekey32 ====
4567021b 285.It Cm namekey32 Ar filename
b4448f1a
TN
286Generate the top 32 bits of a
287.Nm HAMMER
2010519f 28864 bit directory hash for the specified file name.
b66b9421 289.\" ==== info ====
4567021b
TN
290.It Cm info
291Shows extended information about all the mounted
292.Nm HAMMER
293file systems.
294At the moment volume identification, big-blocks information and space details
295are shown.
6a6e350f 296.\" ==== cleanup ====
4567021b
TN
297.It Cm cleanup Op Ar filesystem ...
298This is a meta-command which executes snapshot, prune, rebalance and reblock
226f3799
TN
299commands on the specified
300.Nm HAMMER
4567021b 301file system(s).
226f3799
TN
302If no
303.Ar filesystem
304is specified this command will clean-up all
305.Nm HAMMER
306file systems in use, including PFS's.
307To do this it will scan all
308.Nm HAMMER
309and
310.Nm null
6a6e350f
MD
311mounts, extract PFS id's, and clean-up each PFS found.
312.Pp
226f3799
TN
313This command will by default access a
314.Pa snapshots
6a6e350f 315subdirectory and a
226f3799
TN
316.Pa snapshots/config
317file for each
318.Ar filesystem ,
319creating them if necessary.
320The format of the configuration file is:
321.Bd -literal -offset indent
5e435c92 322snapshots <period> <retention-time> [any]
226f3799 323prune <period> <max-runtime>
f13fea8b 324rebalance <period> <max-runtime>
4567021b
TN
325reblock <period> <max-runtime>
326recopy <period> <max-runtime>
327.Ed
328.Pp
226f3799 329Defaults are:
4567021b
TN
330.Bd -literal -offset indent
331snapshots 1d 60d # 0d 0d for PFS /tmp, /var/tmp, /usr/obj
226f3799 332prune 1d 5m
f13fea8b 333rebalance 1d 5m
226f3799
TN
334reblock 1d 5m
335recopy 30d 10m
336.Ed
6a6e350f 337.Pp
483bb69b 338Time is given with a suffix of
226f3799
TN
339.Cm d ,
340.Cm h ,
341.Cm m
483bb69b 342or
226f3799
TN
343.Cm s
344meaning day, hour, minute and second.
5e435c92 345.Pp
4567021b
TN
346If the
347.Cm snapshots
348directive has a period of 0 and a retention time of 0
5e435c92
MD
349then snapshot generation is disabled, removal of old snapshots are
350disabled, and prunes will use
4567021b
TN
351.Cm prune-everything .
352If the
353.Cm snapshots
354directive has a period of 0 but a non-zero retention time
5e435c92
MD
355then this command will not create any new snapshots but will remove old
356snapshots it finds based on the retention time.
357.Pp
4567021b
TN
358By default only snapshots in the form
359.Ql snap- Ns Ar yyyymmdd Ns Op - Ns Ar HHMM
360are processed.
5e435c92 361If the
4567021b
TN
362.Cm any
363directive is specified as a third argument on the
364.Cm snapshots
365config line then any softlink of the form
366.Ql *- Ns Ar yyyymmdd Ns Op - Ns Ar HHMM
367or
368.Ql *. Ns Ar yyyymmdd Ns Op - Ns Ar HHMM
369will be processed.
5e435c92 370.Pp
226f3799
TN
371A prune max-runtime of 0 means unlimited.
372.Pp
e0331f4f 373If period hasn't passed since the previous
4567021b 374.Cm cleanup
483bb69b
TN
375run nothing is done.
376For example a day has passed when midnight is passed (localtime).
e0331f4f
SW
377By default,
378.Dx
379is set up to run
380.Nm Ar cleanup
381nightly via
382.Xr periodic 8 .
226f3799
TN
383.Pp
384The default configuration file will create a daily snapshot, do a daily
f13fea8b 385pruning, rebalancing and reblocking run and a monthly recopy run.
226f3799
TN
386Reblocking is defragmentation with a level of 95%,
387and recopy is full defragmentation.
388.Pp
4567021b
TN
389By default prune and rebalance operations are time limited to 5 minutes,
390reblock operations to a bit over 5 minutes,
391and recopy operations to a bit over 10 minutes.
392Reblocking and recopy runs are each broken down into four separate functions:
393btree, inodes, dirs and data.
394Each function is time limited to the time given in the configuration file,
395but the btree, inodes and dirs functions usually does not take very long time,
396full defragmentation is always used for these three functions.
226f3799 397Also note that this directive will by default disable snapshots on
2010519f 398the following PFS's:
6a6e350f 399.Pa /tmp ,
226f3799 400.Pa /var/tmp
6a6e350f 401and
226f3799 402.Pa /usr/obj .
6a6e350f 403.Pp
226f3799
TN
404The defaults may be adjusted by modifying the
405.Pa config
406file.
6a6e350f
MD
407The pruning and reblocking commands automatically maintain a cyclefile
408for incremental operation.
4567021b
TN
409If you interrupt (^C) the program the cyclefile will be updated,
410but a sub-command
226f3799
TN
411may continue to run in the background for a few seconds until the
412.Nm HAMMER
6a6e350f 413ioctl detects the interrupt.
226f3799 414The
4567021b 415.Cm snapshots
226f3799 416PFS option can be set to use another location for the snapshots directory.
6a6e350f
MD
417.Pp
418Work on this command is still in progress.
4567021b
TN
419Expected additions:
420An ability to remove snapshots dynamically as the
226f3799 421file system becomes full.
83f2a3aa
MD
422.\" ==== config ====
423.It Cm config Ar filesystem Op configfile
424(HAMMER VERSION 3+)
425If one argument is specified this function dumps the current configuration
426file to stdout. This configuration file is stored in filesystem meta-data.
427If two arguments are specified this function installs a new config file.
428.Pp
429In
430.Nm HAMMER
431versions less then 3 the configuration file is stored in
432.Pa <fs>/snapshots/config ,
433but in all later versions the configuration file is stored in filesystem
434meta-data.
435.It Cm viconfig Ar filesystem
436(HAMMER VERSION 3+)
437Edit the configuration file and reinstall into filesystem meta-data when
438done.
ceed7673 439.\" ==== expand ====
4567021b 440.It Cm expand Ar filesystem Ar device
ceed7673
MN
441This command will format
442.Ar device
443and add all of its space to
444.Ar filesystem .
445.Pp
4567021b
TN
446.Em NOTE!
447All existing data contained on
ceed7673 448.Ar device
4567021b
TN
449will be destroyed by this operation!
450If
ceed7673
MN
451.Ar device
452contains a valid
453.Nm HAMMER
454filesystem, formatting will be denied. You can overcome this sanity check
455by using
456.Xr dd 1
457to erase the beginning sectors of the device.
458Also remember that you have to specify
459.Ar device ,
460together with any other device that make the filesystem, colon-separated to
461.Xr mount_hammer 8 .
0e999592 462.\" ==== snapshot ====
4567021b 463.It Cm snapshot Oo Ar filesystem Oc Ar snapshot-dir
b5ec5ad4 464.It Cm snapshot Ar filesystem Ar snapshot-dir Ar note
0e999592
TN
465Takes a snapshot of the file system either explicitly given by
466.Ar filesystem
467or implicitly derived from the
468.Ar snapshot-dir
469argument and creates a symlink in the directory provided by
470.Ar snapshot-dir
471pointing to the snapshot.
472If
473.Ar snapshot-dir
474is not a directory, it is assumed to be a format string passed to
475.Xr strftime 3
476with the current time as parameter.
477If
478.Ar snapshot-dir
4567021b
TN
479refers to an existing directory, a default format string of
480.Ql snap-%Y%d%m-%H%M
0e999592
TN
481is assumed and used as name for the newly created symlink.
482.Pp
483Snapshot is a per PFS operation, so a
484.Nm HAMMER
485file system and each PFS in it have to be snapshot separately.
486.Pp
487Example, assuming that
488.Pa /mysnapshots
489is on file system
490.Pa /
491and that
492.Pa /obj
493is a file system on its own, the following invocations:
494.Bd -literal -offset indent
495hammer snapshot /mysnapshots
496
497hammer snapshot /mysnapshots/%Y-%m-%d
498
499hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d
b5ec5ad4
MD
500
501hammer snapshot /usr /my/snaps/for/usr "note"
0e999592
TN
502.Ed
503.Pp
b5ec5ad4 504Would create symlinks similar to:
0e999592
TN
505.Bd -literal -offset indent
506/mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16
507
508/mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16
509
510/mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16
511.Ed
b5ec5ad4
MD
512.Pp
513When run on a
514.Nm HAMMER
515version 3+ filesystem the snapshot is also recorded in meta-data
516along with the optional note. See the
517.Cm snapls
518directive.
83f2a3aa
MD
519.\" ==== snap* ====
520.It Cm snap Ar path Op "note"
521(HAMMER VERSION 3+)
522Create the named snapshot softlink. If the path specified is a
523directory a standard snapshot softlink will be created in the directory.
524The snapshot softlink points to the base of the mounted PFS.
525.It Cm snaplo Ar path Op "note"
526(HAMMER VERSION 3+)
527Create the named snapshot softlink. If the path specified is a
528directory a standard snapshot softlink will be created in the directory.
529The snapshot softlink points into the directory it is contained in.
530.It Cm snapq Ar dir Op "note"
531(HAMMER VERSION 3+)
532Create a snapshot for the PFS containing the specified directory but do
533not create a softlink. Instead output a path which can be used to access
534the directory via the snapshot.
bf2c6489
MD
535.Pp
536An absolute or relative path may be specified. The path will be used
537as-is as a prefix in the path output to stdout. As with the other
538snap and snapshot directives the snapshot transaction id will be registered
539in the filesystem meta-data.
83f2a3aa
MD
540.It Cm snaprm Op fs Ar path/transid
541(HAMMER VERSION 3+)
542Remove a snapshot given its softlink. If specifying a transaction id
543the snapshot is removed from filesystem meta-data but you are responsible
544for removing any related softlinks.
545.It Cm snapls
546(HAMMER VERSION 3+)
547Dump the snapshot meta-data in the filesystem, listing all available
548snapshots and their notes. This is the definitive list of snapshots
549for the filesystem.
15fa4caf 550.\" ==== prune ====
4567021b 551.It Cm prune Ar softlink-dir
b4448f1a
TN
552Prune the file system based on previously created snapshot softlinks.
553Pruning is the act of deleting file system history.
84082922 554The
4567021b
TN
555.Cm prune
556command will delete file system history such that
b4448f1a 557the file system state is retained for the given snapshots,
4567021b
TN
558and all history after the latest snapshot.
559By setting the per PFS parameter
560.Cm prune-min ,
561history is guaranteed to be saved at least this time interval.
562All other history is deleted.
84082922 563.Pp
e8969ef0 564The target directory is expected to contain softlinks pointing to
2010519f
TN
565snapshots of the file systems you wish to retain.
566The directory is scanned non-recursively and the mount points and
567transaction ids stored in the softlinks are extracted and sorted.
b4448f1a 568The file system is then explicitly pruned according to what is found.
4567021b
TN
569Cleaning out portions of the file system is as simple as removing a
570snapshot softlink and then running the
571.Cm prune
e8969ef0
MD
572command.
573.Pp
574As a safety measure pruning only occurs if one or more softlinks are found
4567021b
TN
575containing the
576.Ql @@
577snapshot id extension.
e8969ef0 578Currently the scanned softlink directory must contain softlinks pointing
b4448f1a
TN
579to a single
580.Nm HAMMER
2010519f
TN
581mount.
582The softlinks may specify absolute or relative paths.
4567021b
TN
583Softlinks must use 20-character
584.Ql @@0x%016llx
585transaction ids, as might be returned from
586.Nm Cm synctid Ar filesystem .
e8969ef0 587.Pp
226f3799 588Pruning is a per PFS operation, so a
15fa4caf
TN
589.Nm HAMMER
590file system and each PFS in it have to be pruned separately.
591.Pp
592Note that pruning a file system may not immediately free-up space,
593though typically some space will be freed if a large number of records are
2010519f
TN
594pruned out.
595The file system must be reblocked to completely recover all available space.
15fa4caf 596.Pp
4567021b
TN
597Example, lets say your that you didn't set
598.Cm prune-min ,
599and snapshot directory contains the following links:
226f3799 600.Bd -literal -offset indent
f51a18e7
SW
601lrwxr-xr-x 1 root wheel 29 May 31 17:57 snap1 ->
602/usr/obj/@@0x10d2cd05b7270d16
603
604lrwxr-xr-x 1 root wheel 29 May 31 17:58 snap2 ->
605/usr/obj/@@0x10d2cd13f3fde98f
606
607lrwxr-xr-x 1 root wheel 29 May 31 17:59 snap3 ->
608/usr/obj/@@0x10d2cd222adee364
609.Ed
e8969ef0 610.Pp
84082922 611If you were to run the
4567021b 612.Cm prune
b4448f1a
TN
613command on this directory, then the
614.Nm HAMMER
f51a18e7
SW
615.Pa /usr/obj
616mount will be pruned to retain the above three snapshots.
2010519f
TN
617In addition, history for modifications made to the file system older than
618the oldest snapshot will be destroyed and history for potentially fine-grained
619modifications made to the file system more recently than the most recent
620snapshot will be retained.
621.Pp
622If you then delete the
623.Pa snap2
624softlink and rerun the
4567021b 625.Cm prune
84082922
TN
626command,
627history for modifications pertaining to that snapshot would be destroyed.
83f2a3aa
MD
628.Pp
629In
630.Nm HAMMER
631filesystem versions 3+ this command also scans the snapshots stored
632in the filesystem meta-data and includes them in the prune.
15fa4caf 633.\" ==== prune-everything ====
4567021b 634.It Cm prune-everything Ar filesystem
b4448f1a 635This command will remove all historical records from the file system.
b5aaba7f 636This directive is not normally used on a production system.
83f2a3aa
MD
637.Pp
638This command does not remove snapshot softlinks but will delete all
639snapshots recorded in filesystem meta-data (for filesystem version 3+).
640The user is responsible for deleting any softlinks.
797a0b63 641.\" ==== rebalance ====
4567021b
TN
642.It Cm rebalance Ar filesystem Op Ar saturation_level
643This command will rebalance the B-tree, nodes with small number of
797a0b63
MD
644elements will be combined and element counts will be smoothed out
645between nodes.
646.Pp
4567021b
TN
647The saturation level is a percentage between 50 and 100.
648The default is 75 percent.
15fa4caf 649.\" ==== reblock ====
4567021b
TN
650.It Cm reblock Ar filesystem Op Ar fill_percentage
651.It Cm reblock-btree Ar filesystem Op Ar fill_percentage
652.It Cm reblock-inodes Ar filesystem Op Ar fill_percentage
653.It Cm reblock-dirs Ar filesystem Op Ar fill_percentage
654.It Cm reblock-data Ar filesystem Op Ar fill_percentage
9e29c876 655Attempt to defragment and free space for reuse by reblocking a live
b4448f1a
TN
656.Nm HAMMER
657file system.
4567021b 658Big-blocks cannot be reused by
b4448f1a
TN
659.Nm HAMMER
660until they are completely free.
9e29c876 661This command also has the effect of reordering all elements, effectively
b4448f1a 662defragmenting the file system.
ba7b52c9 663.Pp
b4448f1a 664The default fill percentage is 100% and will cause the file system to be
2010519f
TN
665completely defragmented.
666All specified element types will be reallocated and rewritten.
667If you wish to quickly free up space instead try specifying
15fa4caf
TN
668a smaller fill percentage, such as 90% or 80% (the
669.Sq %
670suffix is not needed).
ba7b52c9 671.Pp
9e29c876 672Since this command may rewrite the entire contents of the disk it is
84082922
TN
673best to do it incrementally from a
674.Xr cron 8
675job along with the
9e29c876
MD
676.Fl c Ar cyclefile
677and
99d6191f 678.Fl t Ar seconds
9e29c876 679options to limit the run time.
b4448f1a 680The file system would thus be defragmented over long period of time.
9e29c876
MD
681.Pp
682It is recommended that separate invocations be used for each data type.
d2ee8e9f 683B-tree nodes, inodes, and directories are typically the most important
2010519f
TN
684elements needing defragmentation.
685Data can be defragmented over a longer period of time.
15fa4caf 686.Pp
226f3799 687Reblocking is a per PFS operation, so a
15fa4caf
TN
688.Nm HAMMER
689file system and each PFS in it have to be reblocked separately.
690.\" ==== pfs-status ====
4567021b 691.It Cm pfs-status Ar dirpath ...
34ebae70 692Retrieve the mirroring configuration parameters for the specified
b4448f1a 693.Nm HAMMER
2010519f 694file systems or pseudo-filesystems (PFS's).
15fa4caf 695.\" ==== pfs-master ====
4567021b 696.It Cm pfs-master Ar dirpath Op Ar options
b4448f1a
TN
697Create a pseudo-filesystem (PFS) inside a
698.Nm HAMMER
699file system.
700Up to 65535 such file systems can be created.
765c85a8 701Each PFS uses an independent inode numbering space making it suitable
d4e5b69b
MD
702for use as a replication source or target.
703.Pp
704The
4567021b 705.Cm pfs-master
d4e5b69b
MD
706directive creates a PFS that you can read, write, and use as a mirroring
707source.
bb8e52c0
TN
708.Pp
709It is recommended to use a
710.Nm null
711mount to access a PFS, for more information see
712.Xr HAMMER 5 .
15fa4caf 713.\" ==== pfs-slave ====
4567021b 714.It Cm pfs-slave Ar dirpath Op Ar options
b4448f1a
TN
715Create a pseudo-filesystem (PFS) inside a
716.Nm HAMMER
717file system.
718Up to 65535 such file systems can be created.
765c85a8 719Each PFS uses an independent inode numbering space making it suitable
d4e5b69b
MD
720for use as a replication source or target.
721.Pp
722The
4567021b 723.Cm pfs-slave
765c85a8 724directive creates a PFS that you can use as a mirroring target.
d4e5b69b
MD
725You will not be able to access a slave PFS until you have completed the
726first mirroring operation with it as the target (its root directory will
727not exist until then).
34ebae70 728.Pp
4567021b 729Access to the pfs-slave via the special softlink, as described in the
2010519f
TN
730.Sx PFS NOTES
731below, allows
b4448f1a
TN
732.Nm HAMMER
733to
84082922
TN
734dynamically modify the snapshot transaction id by returning a dynamic result
735from
736.Xr readlink 2
737calls.
d4e5b69b 738.Pp
765c85a8 739A PFS can only be truly destroyed with the
4567021b 740.Cm pfs-destroy
d4e5b69b
MD
741directive.
742Removing the softlink will not destroy the underlying PFS.
bb8e52c0
TN
743.Pp
744It is recommended to use a
745.Nm null
746mount to access a PFS, for more information see
747.Xr HAMMER 5 .
15fa4caf 748.\" ==== pfs-update ====
4567021b 749.It Cm pfs-update Ar dirpath Op Ar options
b4448f1a
TN
750Update the configuration parameters for an existing
751.Nm HAMMER
4567021b 752file system or pseudo-filesystem.
2010519f 753Options that may be specified:
34ebae70 754.Bl -tag -width indent
4567021b 755.It Cm sync-beg-tid= Ns Ar 0x16llx
2010519f
TN
756This is the automatic snapshot access starting transaction id for
757mirroring slaves.
34ebae70 758This parameter is normally updated automatically by the
4567021b 759.Cm mirror-write
34ebae70
MD
760directive.
761.Pp
762It is important to note that accessing a mirroring slave
765c85a8 763with a transaction id greater than the last fully synchronized transaction
34ebae70
MD
764id can result in an unreliable snapshot since you will be accessing
765data that is still undergoing synchronization.
766.Pp
4567021b
TN
767Manually modifying this field is dangerous and can result in a broken mirror.
768.It Cm sync-end-tid= Ns Ar 0x16llx
ddc8e722 769This is the current synchronization point for mirroring slaves.
34ebae70 770This parameter is normally updated automatically by the
4567021b 771.Cm mirror-write
34ebae70
MD
772directive.
773.Pp
2010519f 774Manually modifying this field is dangerous and can result in a broken mirror.
4567021b 775.It Cm shared-uuid= Ns Ar uuid
2010519f
TN
776Set the shared UUID for this file system.
777All mirrors must have the same shared UUID.
778For safety purposes the
4567021b 779.Cm mirror-write
2010519f 780directives will refuse to operate on a target with a different shared UUID.
34ebae70 781.Pp
84082922 782Changing the shared UUID on an existing, non-empty mirroring target,
2010519f
TN
783including an empty but not completely pruned target,
784can lead to corruption of the mirroring target.
4567021b 785.It Cm unique-uuid= Ns Ar uuid
2010519f
TN
786Set the unique UUID for this file system.
787This UUID should not be used anywhere else,
788even on exact copies of the file system.
4567021b 789.It Cm label= Ns Ar string
b4448f1a 790Set a descriptive label for this file system.
4567021b 791.It Cm snapshots= Ns Ar string
226f3799
TN
792Specify the snapshots directory which
793.Nm
4567021b 794.Cm cleanup
2010519f
TN
795will use to manage this PFS.
796The snapshots directory does not need to be configured for
226f3799
TN
797PFS masters and will default to
798.Pa <pfs>/snapshots .
ff1c9800
MD
799.Pp
800PFS slaves are mirroring slaves so you cannot configure a snapshots
801directory on the slave itself to be managed by the slave's machine.
226f3799
TN
802In fact, the slave will likely have a
803.Pa snapshots
804sub-directory mirrored
ff1c9800 805from the master, but that directory contains the configuration the master
226f3799 806is using for its copy of the file system, not the configuration that we
ff1c9800
MD
807want to use for our slave.
808.Pp
226f3799
TN
809It is recommended that
810.Pa <fs>/var/slaves/<name>
811be configured for a PFS slave, where
812.Pa <fs>
813is the base
814.Nm HAMMER
815file system, and
816.Pa <name>
817is an appropriate label.
2010519f 818You can control snapshot retention on your slave independent of the master.
4567021b
TN
819.It Cm snapshots-clear
820Zero out the
821.Cm snapshots
822directory path for this PFS.
823.It Cm prune-min= Ns Ar N Ns Cm d
824.It Cm prune-min= Ns Xo
825.Op Ar N Ns Cm d/ Ns
826.Ar hh Ns Op Cm \&: Ns Ar mm Ns Op Cm \&: Ns Ar ss
827.Xc
e7f926a5
MD
828Set the minimum fine-grained data retention period.
829.Nm HAMMER
0bd7a37c
MD
830always retains fine-grained history up to the most recent snapshot.
831You can extend the retention period further by specifying a non-zero
4567021b
TN
832pruning minimum.
833Any snapshot softlinks within the retention period are ignored
834for the purposes of pruning (the fine grained history is retained).
835Number of days, hours, minutes and seconds are given as
836.Ar N , hh , mm
837and
838.Ar ss .
0bd7a37c
MD
839.Pp
840Because the transaction id in the snapshot softlink cannot be used
841to calculate a timestamp,
842.Nm HAMMER
4567021b
TN
843uses the earlier of the
844.Fa st_ctime
845or
846.Fa st_mtime
847field of the softlink to
0bd7a37c
MD
848determine which snapshots fall within the retention period.
849Users must be sure to retain one of these two fields when manipulating
850the softlink.
34ebae70 851.El
34bb69d8 852.\" ==== pfs-upgrade ====
4567021b 853.It Cm pfs-upgrade Ar dirpath
2010519f 854Upgrade a PFS from slave to master operation.
4567021b 855The PFS will be rolled back to the current end synchronization transaction id
2010519f 856(removing any partial synchronizations), and will then become writable.
34bb69d8
TN
857.Pp
858.Em WARNING!
859.Nm HAMMER
860currently supports only single masters and using
2010519f
TN
861this command can easily result in file system corruption
862if you don't know what you are doing.
34bb69d8
TN
863.Pp
864This directive will refuse to run if any programs have open descriptors
865in the PFS, including programs chdir'd into the PFS.
866.\" ==== pfs-downgrade ====
4567021b 867.It Cm pfs-downgrade Ar dirpath
2010519f
TN
868Downgrade a master PFS from master to slave operation
869The PFS becomes read-only and access will be locked to its
4567021b 870.Cm sync-end-tid .
34bb69d8
TN
871.Pp
872This directive will refuse to run if any programs have open descriptors
873in the PFS, including programs chdir'd into the PFS.
874.\" ==== pfs-destroy ====
4567021b 875.It Cm pfs-destroy Ar dirpath
34bb69d8
TN
876This permanently destroys a PFS.
877.Pp
878This directive will refuse to run if any programs have open descriptors
879in the PFS, including programs chdir'd into the PFS.
15fa4caf 880.\" ==== mirror-read ====
4567021b 881.It Cm mirror-read Ar filesystem Op Ar begin-tid
34ebae70 882Generate a mirroring stream to stdout.
48eadef9 883The stream ends when the transaction id space has been exhausted.
15fa4caf 884.\" ==== mirror-read-stream ====
4567021b 885.It Cm mirror-read-stream Ar filesystem Op Ar begin-tid
48eadef9
MD
886Generate a mirroring stream to stdout.
887Upon completion the stream is paused until new data is synced to the
888master, then resumed.
889Operation continues until the pipe is broken.
15fa4caf 890.\" ==== mirror-write ====
4567021b 891.It Cm mirror-write Ar filesystem
34bb69d8 892Take a mirroring stream on stdin.
34ebae70
MD
893.Pp
894This command will fail if the
4567021b 895.Cm shared-uuid
b4448f1a 896configuration field for the two file systems do not match.
01a72c9f
MD
897.Pp
898If the target PFS does not exist this command will ask you whether
899you want to create a compatible PFS slave for the target or not.
15fa4caf 900.\" ==== mirror-dump ====
4567021b 901.It Cm mirror-dump
15fa4caf 902A
4567021b 903.Cm mirror-read
15fa4caf 904can be piped into a
4567021b 905.Cm mirror-dump
2010519f 906to dump an ASCII representation of the mirroring stream.
15fa4caf 907.\" ==== mirror-copy ====
4567021b
TN
908.\".It Cm mirror-copy Ar [[user@]host:]filesystem [[user@]host:]filesystem
909.It Cm mirror-copy Xo
910.Oo Oo Ar user Oc Ns Cm @ Ns Ar host Ns Cm \&: Oc Ns Ar filesystem
911.Oo Oo Ar user Oc Ns Cm @ Ns Ar host Ns Cm \&: Oc Ns Ar filesystem
912.Xc
84082922 913This is a shortcut which pipes a
4567021b 914.Cm mirror-read
84082922 915command to a
4567021b 916.Cm mirror-write
2010519f
TN
917command.
918If a remote host specification is made the program forks a
6d9ab5c5 919.Xr ssh 1
84082922 920and execs the
4567021b 921.Cm mirror-read
84082922 922and/or
4567021b 923.Cm mirror-write
84082922 924on the appropriate host.
9c67b4d2 925The source may be a master or slave PFS, and the target must be a slave PFS.
d4e5b69b 926.Pp
9c67b4d2 927This command also established full duplex communication and turns on
2010519f
TN
928the two-way protocol feature which automatically negotiates transaction id
929ranges without having to use a cyclefile.
84082922 930If the operation completes successfully the target PFS's
4567021b 931.Cm sync-end-tid
2010519f
TN
932will be updated.
933Note that you must re-chdir into the target PFS to see the updated information.
934If you do not you will still be in the previous snapshot.
01a72c9f
MD
935.Pp
936If the target PFS does not exist this command will ask you whether
937you want to create a compatible PFS slave for the target or not.
15fa4caf 938.\" ==== mirror-stream ====
4567021b
TN
939.\".It Cm mirror-stream Ar [[user@]host:]filesystem [[user@]host:]filesystem
940.It Cm mirror-stream Xo
941.Oo Oo Ar user Oc Ns Cm @ Ns Ar host Ns Cm \&: Oc Ns Ar filesystem
942.Oo Oo Ar user Oc Ns Cm @ Ns Ar host Ns Cm \&: Oc Ns Ar filesystem
943.Xc
48eadef9 944This command works similarly to
4567021b 945.Cm mirror-copy
e7f926a5
MD
946but does not exit after the initial mirroring completes.
947The mirroring operation will resume as changes continue to be made to the
948master.
2010519f 949The command is commonly used with
48eadef9
MD
950.Fl i Ar delay
951and
952.Fl b Ar bandwidth
953options to keep the mirroring target in sync with the source on a continuing
954basis.
e7f926a5
MD
955.Pp
956If the pipe is broken the command will automatically retry after sleeping
4567021b
TN
957for a short while.
958The time slept will be 15 seconds plus the time given in the
0bd7a37c
MD
959.Fl i
960option.
e7f926a5
MD
961.Pp
962This command also detects the initial-mirroring case and spends some
963time scanning the B-Tree to find good break points, allowing the initial
964bulk mirroring operation to be broken down into about 20 separate pieces.
965This means that the user can kill and restart the operation and it will
966not have to start from scratch once it has gotten past the first chunk.
0bd7a37c
MD
967The
968.Fl B
969option may be used to disable this feature and perform an initial bulk
970transfer instead.
de1c0b31 971.\" ==== version ====
4567021b 972.It Cm version Ar filesystem
3f2565b9
SW
973This command returns the
974.Nm HAMMER
4567021b
TN
975file system version for the specified
976.Ar filesystem
977as well as the range of versions supported in the kernel.
de1c0b31
MD
978The
979.Fl q
980option may be used to remove the summary at the end.
981.\" ==== version-upgrade ====
4567021b 982.It Cm version-upgrade Ar filesystem Ar version Op Cm force
3f2565b9
SW
983This command upgrades the
984.Nm HAMMER
4567021b
TN
985.Ar filesystem
986to the specified
987.Ar version .
988Once upgraded a file system may not be downgraded.
989If you wish to upgrade a file system to a version greater or equal to the
de1c0b31 990work-in-progress version number you must specify the
4567021b 991.Cm force
de1c0b31
MD
992directive.
993Use of WIP versions should be relegated to testing and may require wiping
994the filesystem as development progresses, even though the WIP version might
995not change.
996.Pp
4567021b
TN
997.Em NOTE!
998This command operates on the entire
3f2565b9 999.Nm HAMMER
4567021b 1000file system and is not a per PFS operation.
3f2565b9 1001All PFS's will be affected.
de1c0b31
MD
1002.Bl -tag -width indent
1003.It 1
3f2565b9
SW
1004.Dx 2.0
1005default version, first
1006.Nm HAMMER
1007release.
de1c0b31 1008.It 2
4567021b
TN
1009.Dx 2.3
1010default version, new directory entry layout.
1011This version is using a new directory hash key.
de1c0b31 1012.El
0dfeb6c8 1013.El
f51a18e7 1014.\".Sh EXAMPLES
4567021b 1015.Sh PSEUDO-FILESYSTEM (PFS) NOTES
b4448f1a
TN
1016The root of a PFS is not hooked into the primary
1017.Nm HAMMER
2010519f 1018file system as a directory.
b4448f1a
TN
1019Instead,
1020.Nm HAMMER
4567021b
TN
1021creates a special softlink called
1022.Ql @@PFS%05d
1023(exactly 10 characters long) in the primary
b4448f1a
TN
1024.Nm HAMMER
1025file system.
1026.Nm HAMMER
1027then modifies the contents of the softlink as read by
9c67b4d2 1028.Xr readlink 2 ,
84082922
TN
1029and thus what you see with an
1030.Xr ls 1
1031command or if you were to
1032.Xr cd 1
1033into the link.
9c67b4d2
MD
1034If the PFS is a master the link reflects the current state of the PFS.
1035If the PFS is a slave the link reflects the last completed snapshot, and the
1036contents of the link will change when the next snapshot is completed, and
1037so forth.
1038.Pp
2010519f 1039The
9c67b4d2 1040.Nm
2010519f 1041utility employs numerous safeties to reduce user foot-shooting.
9c67b4d2 1042The
4567021b 1043.Cm mirror-copy
9c67b4d2 1044directive requires that the target be configured as a slave and that the
4567021b 1045.Cm shared-uuid
9c67b4d2 1046field of the mirroring source and target match.
bf2c6489
MD
1047.Sh UPGRADE INSTRUCTIONS HAMMER V1 TO V2
1048This upgrade changes the way directory entries are stored. It
1049is possible to upgrade a V1 filesystem to V2 in place, but
1050directories created prior to the upgrade will continue to use
1051the old layout.
1052.Pp
1053Note that the slave mirroring code in the target kernel had bugs in
1054V1 which can create an incompatible root directory on the slave.
1055Do not mix a HAMMER master created after the upgrade with a HAMMER
1056slave created prior to the upgrade.
1057.Pp
1058Any directories created after upgrading will use a new layout.
1059.Sh UPGRADE INSTRUCTIONS HAMMER V2 TO V3
1060This upgrade adds meta-data elements to the B-Tree. It is
1061possible to upgrade a V2 filesystem to V3 in place. After
1062issuing the upgrade be sure to run a 'hammer cleanup' to
1063perform post-upgrade tasks.
1064.Pp
1065After making this upgrade running a hammer cleanup will move the
1066.Pa <fs>/snapshots
1067directory for each PFS mount into
1068.Pa /var/hammer/<path-from-root> .
1069A HAMMER root mount will migrated
1070.Pa /snapshots
1071into
1072.Pa /var/hammer/root .
1073Migration occurs only once and only if you have not specified
1074a snapshots directory in the PFS configuration. If you have
1075specified a snapshots directory in the PFS configuration no
1076automatic migration will occur.
1077.Pp
1078For slaves, if you desire, you can migrate your snapshots
1079config to the new location manually and then clear the
1080snapshot directory configuration in the slave PFS.
1081The new snapshots hierarchy is designed to work with
1082both master and slave PFSs equally well.
1083.Pp
1084In addition, the old config file will be moved to meta-data,
1085editable via the new hammer
1086.Cm viconfig
1087directive. The old config file will be deleted.
1088Migration occurs only once.
1089.Pp
1090The V3 filesystem has new
1091.Cm snap*
1092directives for creating snapshots.
1093All snapshot directives, including the original, will create
1094meta-data entries for the snapshots and the pruning code will
1095automatically incorporate these entries into its list and
1096expire them the same way it expires softlinks.
1097If you accidently blow away your snapshot softlinks you can use
1098the
1099.Cm snapls
1100directive to get a definitive list from the meta-data and
1101regenerate them from that list.
92ed14a3
MD
1102.Pp
1103WARNING! If you are using hammer to backup filesystems your scripts
1104may be using the
1105.Cm synctid
1106directive to generate transaction ids. This directive does not create
1107a snapshot. You will have to modify your scripts to use the
1108.Cm snapq
1109directive to generate the linkbuf for the softlink you create, or
1110use one of the other
1111.Cm snap*
1112directives.
1113The older
1114.Cm snapshot
1115directive will continue to work as expected and in V3 it will also
1116record the snapshot transaction id in meta-data. You may also want
1117to make use of the new 'note' tag for the meta-data.
1118.Pp
1119WARNING! If you used to remove snapshot softlinks with
1120.Nm rm
1121you should probably start using the
1122.Cm snaprm
1123directive instead to also remove the related meta-data.
1124The pruning code scans the meta-data so just removing the
1125softlink is not sufficient.
226f3799
TN
1126.Sh FILES
1127.Bl -tag -width ".It Pa <fs>/var/slaves/<name>" -compact
4567021b 1128.It Pa <pfs>/snapshots
226f3799
TN
1129default per PFS snapshots directory
1130.It Pa <snapshots>/config
4567021b 1131per PFS
226f3799 1132.Nm
4567021b 1133.Cm cleanup
226f3799
TN
1134configuration file
1135.It Pa <fs>/var/slaves/<name>
1136recommended slave PFS snapshots directory
1137.El
19fe1c42
SW
1138.Sh EXIT STATUS
1139.Ex -std
0dfeb6c8 1140.Sh SEE ALSO
4567021b 1141.Xr ssh 1 ,
84082922 1142.Xr undo 1 ,
b4448f1a 1143.Xr HAMMER 5 ,
e0331f4f 1144.Xr periodic.conf 5 ,
84082922 1145.Xr mount_hammer 8 ,
bb8e52c0 1146.Xr mount_null 8 ,
0dfeb6c8
MD
1147.Xr newfs_hammer 8
1148.Sh HISTORY
1149The
1150.Nm
1151utility first appeared in
1152.Dx 1.11 .
1153.Sh AUTHORS
1154.An Matthew Dillon Aq dillon@backplane.com