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