HAMMER utility - Handle pruning when only snapshot meta-data present
[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 .
0e999592 633.\" ==== snapshot ====
4567021b 634.It Cm snapshot Oo Ar filesystem Oc Ar snapshot-dir
16265794 635.It Cm snapshot Ar filesystem Ar snapshot-dir Op Ar note
0e999592
TN
636Takes a snapshot of the file system either explicitly given by
637.Ar filesystem
638or implicitly derived from the
639.Ar snapshot-dir
640argument and creates a symlink in the directory provided by
641.Ar snapshot-dir
642pointing to the snapshot.
643If
644.Ar snapshot-dir
645is not a directory, it is assumed to be a format string passed to
646.Xr strftime 3
647with the current time as parameter.
648If
649.Ar snapshot-dir
4567021b
TN
650refers to an existing directory, a default format string of
651.Ql snap-%Y%d%m-%H%M
0e999592
TN
652is assumed and used as name for the newly created symlink.
653.Pp
654Snapshot is a per PFS operation, so a
655.Nm HAMMER
656file system and each PFS in it have to be snapshot separately.
657.Pp
658Example, assuming that
659.Pa /mysnapshots
660is on file system
661.Pa /
662and that
663.Pa /obj
16265794
TN
664and
665.Pa /usr
666are file systems on their own, the following invocations:
0e999592
TN
667.Bd -literal -offset indent
668hammer snapshot /mysnapshots
669
670hammer snapshot /mysnapshots/%Y-%m-%d
671
672hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d
b5ec5ad4 673
16265794 674hammer snapshot /usr /my/snaps/usr "note"
0e999592
TN
675.Ed
676.Pp
b5ec5ad4 677Would create symlinks similar to:
0e999592
TN
678.Bd -literal -offset indent
679/mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16
680
681/mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16
682
683/mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16
16265794
TN
684
685/my/snaps/usr/snap-20080627-1210 -> /usr@@0x10d2cd05b7270d16
0e999592 686.Ed
b5ec5ad4
MD
687.Pp
688When run on a
689.Nm HAMMER
f6532f03 690version 3+ file system the snapshot is also recorded in file system meta-data
16265794
TN
691along with the optional
692.Ar note .
693See the
b5ec5ad4
MD
694.Cm snapls
695directive.
83f2a3aa 696.\" ==== snap* ====
16265794
TN
697.It Cm snap Ar path Op Ar note
698.Nm ( HAMMER
699VERSION 3+)
700Create a snapshot for the PFS containing
701.Ar path
702and create a snapshot softlink.
703If the path specified is a
83f2a3aa
MD
704directory a standard snapshot softlink will be created in the directory.
705The snapshot softlink points to the base of the mounted PFS.
16265794
TN
706.It Cm snaplo Ar path Op Ar note
707.Nm ( HAMMER
708VERSION 3+)
709Create a snapshot for the PFS containing
710.Ar path
711and create a snapshot softlink.
712If the path specified is a
83f2a3aa
MD
713directory a standard snapshot softlink will be created in the directory.
714The snapshot softlink points into the directory it is contained in.
16265794
TN
715.It Cm snapq Ar dir Op Ar note
716.Nm ( HAMMER
717VERSION 3+)
83f2a3aa 718Create a snapshot for the PFS containing the specified directory but do
16265794
TN
719not create a softlink.
720Instead output a path which can be used to access
83f2a3aa 721the directory via the snapshot.
bf2c6489 722.Pp
16265794
TN
723An absolute or relative path may be specified.
724The path will be used as-is as a prefix in the path output to stdout.
725As with the other
bf2c6489 726snap and snapshot directives the snapshot transaction id will be registered
f6532f03 727in the file system meta-data.
ef872b8d
MD
728.It Cm snaprm Ar path Ar ...
729.It Cm snaprm Ar transid Ar ...
730.It Cm snaprm Ar filesystem Ar transid Ar ...
16265794
TN
731.Nm ( HAMMER
732VERSION 3+)
733Remove a snapshot given its softlink or transaction id.
734If specifying a transaction id
f6532f03 735the snapshot is removed from file system meta-data but you are responsible
83f2a3aa 736for removing any related softlinks.
ef872b8d
MD
737.Pp
738If a softlink path is specified the filesystem and transaction id
739is derived from the contents of the softlink.
740If just a transaction id is specified it is assumed to be a snapshot
741in the HAMMER filesystem you are currently chdir'd into.
742You can also specify the filesystem and transaction id explicitly.
16265794
TN
743.It Cm snapls Op Ar path ...
744.Nm ( HAMMER
745VERSION 3+)
746Dump the snapshot meta-data for PFSs containing each
747.Ar path
748listing all available snapshots and their notes.
749If no arguments are specified snapshots for the PFS containing the
750current directory are listed.
f6532f03 751This is the definitive list of snapshots for the file system.
15fa4caf 752.\" ==== prune ====
4567021b 753.It Cm prune Ar softlink-dir
b4448f1a
TN
754Prune the file system based on previously created snapshot softlinks.
755Pruning is the act of deleting file system history.
84082922 756The
4567021b
TN
757.Cm prune
758command will delete file system history such that
b4448f1a 759the file system state is retained for the given snapshots,
4567021b
TN
760and all history after the latest snapshot.
761By setting the per PFS parameter
762.Cm prune-min ,
763history is guaranteed to be saved at least this time interval.
764All other history is deleted.
84082922 765.Pp
e8969ef0 766The target directory is expected to contain softlinks pointing to
2010519f
TN
767snapshots of the file systems you wish to retain.
768The directory is scanned non-recursively and the mount points and
769transaction ids stored in the softlinks are extracted and sorted.
b4448f1a 770The file system is then explicitly pruned according to what is found.
4567021b
TN
771Cleaning out portions of the file system is as simple as removing a
772snapshot softlink and then running the
773.Cm prune
e8969ef0
MD
774command.
775.Pp
776As a safety measure pruning only occurs if one or more softlinks are found
4567021b
TN
777containing the
778.Ql @@
779snapshot id extension.
e8969ef0 780Currently the scanned softlink directory must contain softlinks pointing
b4448f1a
TN
781to a single
782.Nm HAMMER
2010519f
TN
783mount.
784The softlinks may specify absolute or relative paths.
4567021b
TN
785Softlinks must use 20-character
786.Ql @@0x%016llx
787transaction ids, as might be returned from
788.Nm Cm synctid Ar filesystem .
e8969ef0 789.Pp
226f3799 790Pruning is a per PFS operation, so a
15fa4caf
TN
791.Nm HAMMER
792file system and each PFS in it have to be pruned separately.
793.Pp
794Note that pruning a file system may not immediately free-up space,
795though typically some space will be freed if a large number of records are
2010519f
TN
796pruned out.
797The file system must be reblocked to completely recover all available space.
15fa4caf 798.Pp
4567021b
TN
799Example, lets say your that you didn't set
800.Cm prune-min ,
801and snapshot directory contains the following links:
226f3799 802.Bd -literal -offset indent
f51a18e7
SW
803lrwxr-xr-x 1 root wheel 29 May 31 17:57 snap1 ->
804/usr/obj/@@0x10d2cd05b7270d16
805
806lrwxr-xr-x 1 root wheel 29 May 31 17:58 snap2 ->
807/usr/obj/@@0x10d2cd13f3fde98f
808
809lrwxr-xr-x 1 root wheel 29 May 31 17:59 snap3 ->
810/usr/obj/@@0x10d2cd222adee364
811.Ed
e8969ef0 812.Pp
84082922 813If you were to run the
4567021b 814.Cm prune
b4448f1a
TN
815command on this directory, then the
816.Nm HAMMER
f51a18e7
SW
817.Pa /usr/obj
818mount will be pruned to retain the above three snapshots.
2010519f
TN
819In addition, history for modifications made to the file system older than
820the oldest snapshot will be destroyed and history for potentially fine-grained
821modifications made to the file system more recently than the most recent
822snapshot will be retained.
823.Pp
824If you then delete the
825.Pa snap2
826softlink and rerun the
4567021b 827.Cm prune
84082922
TN
828command,
829history for modifications pertaining to that snapshot would be destroyed.
83f2a3aa
MD
830.Pp
831In
832.Nm HAMMER
f6532f03
TN
833file system versions 3+ this command also scans the snapshots stored
834in the file system meta-data and includes them in the prune.
15fa4caf 835.\" ==== prune-everything ====
4567021b 836.It Cm prune-everything Ar filesystem
b4448f1a 837This command will remove all historical records from the file system.
b5aaba7f 838This directive is not normally used on a production system.
83f2a3aa
MD
839.Pp
840This command does not remove snapshot softlinks but will delete all
f6532f03 841snapshots recorded in file system meta-data (for file system version 3+).
83f2a3aa 842The user is responsible for deleting any softlinks.
aaf93065
TN
843.Pp
844Pruning is a per PFS operation, so a
845.Nm HAMMER
846file system and each PFS in it have to be pruned separately.
797a0b63 847.\" ==== rebalance ====
f6532f03 848.It Cm rebalance Ar filesystem Op Ar saturation_percentage
aaf93065 849This command will rebalance the B-Tree, nodes with small number of
797a0b63
MD
850elements will be combined and element counts will be smoothed out
851between nodes.
852.Pp
f6532f03
TN
853The saturation percentage is between 50% and 100%.
854The default is 75% (the
855.Sq %
856suffix is not needed).
aaf93065
TN
857.Pp
858Rebalancing is a per PFS operation, so a
859.Nm HAMMER
860file system and each PFS in it have to be rebalanced separately.
bb29b5d8
MD
861.\" ==== dedup ====
862.It Cm dedup Ar filesystem
863.Nm ( HAMMER
864VERSION 5+)
865Perform offline (post-process) deduplication. Deduplication occurs at
866the block level, currently only data blocks of the same size can be
867deduped, metadata blocks can not. The hash function used for comparing
868data blocks is CRC-32 (CRCs are computed anyways as part of
869.Nm HAMMER
870data integrity features, so there's no additional overhead). Since CRC
871is a weak hash function a byte-by-byte comparison is done before actual
872deduping. In case of a CRC collision (two data blocks have the same CRC
873but different contents) the checksum is upgraded to SHA-256.
874.Pp
875Currently
876.Nm HAMMER
877reblocker may partially blow up (re-expand) dedup (reblocker's normal
878operation is to reallocate every record, so it's possible for deduped
879blocks to be re-expanded back).
880.Pp
881Deduplication is a per PFS operation, so a
882.Nm HAMMER
883file system and each PFS in it have to be deduped separately. This also
884means that if you have duplicated data in two different PFSs that data
885won't be deduped, however the addition of such feature is planned.
886.\" ==== dedup-simulate ====
887.It Cm dedup-simulate Ar filesystem
888.Nm ( HAMMER
889VERSION 5+)
890Shows potential space savings (simulated dedup ratio) one can get after
891running
892.Cm dedup
893command. If the estimated dedup ratio is greater than 1.00 you will see
894dedup space savings. Remember that this is an estimated number, in
895practice real dedup ratio will be slightly smaller because of
896.Nm HAMMER
897bigblock underflows, B-Tree locking issues and other factors.
16265794 898.\" ==== reblock* ====
4567021b
TN
899.It Cm reblock Ar filesystem Op Ar fill_percentage
900.It Cm reblock-btree Ar filesystem Op Ar fill_percentage
901.It Cm reblock-inodes Ar filesystem Op Ar fill_percentage
902.It Cm reblock-dirs Ar filesystem Op Ar fill_percentage
903.It Cm reblock-data Ar filesystem Op Ar fill_percentage
9e29c876 904Attempt to defragment and free space for reuse by reblocking a live
b4448f1a
TN
905.Nm HAMMER
906file system.
4567021b 907Big-blocks cannot be reused by
b4448f1a
TN
908.Nm HAMMER
909until they are completely free.
9e29c876 910This command also has the effect of reordering all elements, effectively
b4448f1a 911defragmenting the file system.
ba7b52c9 912.Pp
b4448f1a 913The default fill percentage is 100% and will cause the file system to be
2010519f
TN
914completely defragmented.
915All specified element types will be reallocated and rewritten.
916If you wish to quickly free up space instead try specifying
15fa4caf
TN
917a smaller fill percentage, such as 90% or 80% (the
918.Sq %
919suffix is not needed).
ba7b52c9 920.Pp
9e29c876 921Since this command may rewrite the entire contents of the disk it is
84082922
TN
922best to do it incrementally from a
923.Xr cron 8
924job along with the
9e29c876
MD
925.Fl c Ar cyclefile
926and
99d6191f 927.Fl t Ar seconds
9e29c876 928options to limit the run time.
b4448f1a 929The file system would thus be defragmented over long period of time.
9e29c876
MD
930.Pp
931It is recommended that separate invocations be used for each data type.
aaf93065 932B-Tree nodes, inodes, and directories are typically the most important
2010519f
TN
933elements needing defragmentation.
934Data can be defragmented over a longer period of time.
15fa4caf 935.Pp
226f3799 936Reblocking is a per PFS operation, so a
15fa4caf
TN
937.Nm HAMMER
938file system and each PFS in it have to be reblocked separately.
939.\" ==== pfs-status ====
4567021b 940.It Cm pfs-status Ar dirpath ...
34ebae70 941Retrieve the mirroring configuration parameters for the specified
b4448f1a 942.Nm HAMMER
2010519f 943file systems or pseudo-filesystems (PFS's).
15fa4caf 944.\" ==== pfs-master ====
4567021b 945.It Cm pfs-master Ar dirpath Op Ar options
b4448f1a
TN
946Create a pseudo-filesystem (PFS) inside a
947.Nm HAMMER
948file system.
949Up to 65535 such file systems can be created.
765c85a8 950Each PFS uses an independent inode numbering space making it suitable
d4e5b69b
MD
951for use as a replication source or target.
952.Pp
953The
4567021b 954.Cm pfs-master
d4e5b69b
MD
955directive creates a PFS that you can read, write, and use as a mirroring
956source.
bb8e52c0
TN
957.Pp
958It is recommended to use a
959.Nm null
960mount to access a PFS, for more information see
961.Xr HAMMER 5 .
15fa4caf 962.\" ==== pfs-slave ====
4567021b 963.It Cm pfs-slave Ar dirpath Op Ar options
b4448f1a
TN
964Create a pseudo-filesystem (PFS) inside a
965.Nm HAMMER
966file system.
967Up to 65535 such file systems can be created.
765c85a8 968Each PFS uses an independent inode numbering space making it suitable
d4e5b69b
MD
969for use as a replication source or target.
970.Pp
971The
4567021b 972.Cm pfs-slave
765c85a8 973directive creates a PFS that you can use as a mirroring target.
d4e5b69b
MD
974You will not be able to access a slave PFS until you have completed the
975first mirroring operation with it as the target (its root directory will
976not exist until then).
34ebae70 977.Pp
4567021b 978Access to the pfs-slave via the special softlink, as described in the
2010519f
TN
979.Sx PFS NOTES
980below, allows
b4448f1a
TN
981.Nm HAMMER
982to
84082922
TN
983dynamically modify the snapshot transaction id by returning a dynamic result
984from
985.Xr readlink 2
986calls.
d4e5b69b 987.Pp
765c85a8 988A PFS can only be truly destroyed with the
4567021b 989.Cm pfs-destroy
d4e5b69b
MD
990directive.
991Removing the softlink will not destroy the underlying PFS.
bb8e52c0
TN
992.Pp
993It is recommended to use a
994.Nm null
995mount to access a PFS, for more information see
996.Xr HAMMER 5 .
15fa4caf 997.\" ==== pfs-update ====
4567021b 998.It Cm pfs-update Ar dirpath Op Ar options
b4448f1a
TN
999Update the configuration parameters for an existing
1000.Nm HAMMER
4567021b 1001file system or pseudo-filesystem.
2010519f 1002Options that may be specified:
34ebae70 1003.Bl -tag -width indent
4567021b 1004.It Cm sync-beg-tid= Ns Ar 0x16llx
2010519f
TN
1005This is the automatic snapshot access starting transaction id for
1006mirroring slaves.
34ebae70 1007This parameter is normally updated automatically by the
4567021b 1008.Cm mirror-write
34ebae70
MD
1009directive.
1010.Pp
1011It is important to note that accessing a mirroring slave
765c85a8 1012with a transaction id greater than the last fully synchronized transaction
34ebae70
MD
1013id can result in an unreliable snapshot since you will be accessing
1014data that is still undergoing synchronization.
1015.Pp
4567021b
TN
1016Manually modifying this field is dangerous and can result in a broken mirror.
1017.It Cm sync-end-tid= Ns Ar 0x16llx
ddc8e722 1018This is the current synchronization point for mirroring slaves.
34ebae70 1019This parameter is normally updated automatically by the
4567021b 1020.Cm mirror-write
34ebae70
MD
1021directive.
1022.Pp
2010519f 1023Manually modifying this field is dangerous and can result in a broken mirror.
4567021b 1024.It Cm shared-uuid= Ns Ar uuid
2010519f
TN
1025Set the shared UUID for this file system.
1026All mirrors must have the same shared UUID.
1027For safety purposes the
4567021b 1028.Cm mirror-write
2010519f 1029directives will refuse to operate on a target with a different shared UUID.
34ebae70 1030.Pp
84082922 1031Changing the shared UUID on an existing, non-empty mirroring target,
2010519f
TN
1032including an empty but not completely pruned target,
1033can lead to corruption of the mirroring target.
4567021b 1034.It Cm unique-uuid= Ns Ar uuid
2010519f
TN
1035Set the unique UUID for this file system.
1036This UUID should not be used anywhere else,
1037even on exact copies of the file system.
4567021b 1038.It Cm label= Ns Ar string
b4448f1a 1039Set a descriptive label for this file system.
4567021b 1040.It Cm snapshots= Ns Ar string
226f3799
TN
1041Specify the snapshots directory which
1042.Nm
4567021b 1043.Cm cleanup
2010519f 1044will use to manage this PFS.
f85afb25
TN
1045.Bl -tag -width indent
1046.It Nm HAMMER No version 2-
2010519f 1047The snapshots directory does not need to be configured for
226f3799
TN
1048PFS masters and will default to
1049.Pa <pfs>/snapshots .
ff1c9800
MD
1050.Pp
1051PFS slaves are mirroring slaves so you cannot configure a snapshots
1052directory on the slave itself to be managed by the slave's machine.
226f3799
TN
1053In fact, the slave will likely have a
1054.Pa snapshots
1055sub-directory mirrored
ff1c9800 1056from the master, but that directory contains the configuration the master
226f3799 1057is using for its copy of the file system, not the configuration that we
ff1c9800
MD
1058want to use for our slave.
1059.Pp
226f3799
TN
1060It is recommended that
1061.Pa <fs>/var/slaves/<name>
1062be configured for a PFS slave, where
1063.Pa <fs>
1064is the base
1065.Nm HAMMER
1066file system, and
1067.Pa <name>
1068is an appropriate label.
f85afb25
TN
1069.It Nm HAMMER No version 3+
1070The snapshots directory does not need to be configured for PFS masters or
1071slaves.
1072The snapshots directory defaults to
1073.Pa /var/hammer/<pfs>
1074.Pa ( /var/hammer/root
1075for root mount).
1076.El
1077.Pp
2010519f 1078You can control snapshot retention on your slave independent of the master.
4567021b
TN
1079.It Cm snapshots-clear
1080Zero out the
1081.Cm snapshots
1082directory path for this PFS.
1083.It Cm prune-min= Ns Ar N Ns Cm d
f85afb25
TN
1084.It Cm prune-min= Ns Oo Ar N Ns Cm d/ Oc Ns \
1085Ar hh Ns Op Cm \&: Ns Ar mm Ns Op Cm \&: Ns Ar ss
e7f926a5
MD
1086Set the minimum fine-grained data retention period.
1087.Nm HAMMER
0bd7a37c
MD
1088always retains fine-grained history up to the most recent snapshot.
1089You can extend the retention period further by specifying a non-zero
4567021b
TN
1090pruning minimum.
1091Any snapshot softlinks within the retention period are ignored
1092for the purposes of pruning (the fine grained history is retained).
1093Number of days, hours, minutes and seconds are given as
1094.Ar N , hh , mm
1095and
1096.Ar ss .
0bd7a37c
MD
1097.Pp
1098Because the transaction id in the snapshot softlink cannot be used
1099to calculate a timestamp,
1100.Nm HAMMER
4567021b
TN
1101uses the earlier of the
1102.Fa st_ctime
1103or
1104.Fa st_mtime
1105field of the softlink to
0bd7a37c
MD
1106determine which snapshots fall within the retention period.
1107Users must be sure to retain one of these two fields when manipulating
1108the softlink.
34ebae70 1109.El
34bb69d8 1110.\" ==== pfs-upgrade ====
4567021b 1111.It Cm pfs-upgrade Ar dirpath
2010519f 1112Upgrade a PFS from slave to master operation.
4567021b 1113The PFS will be rolled back to the current end synchronization transaction id
2010519f 1114(removing any partial synchronizations), and will then become writable.
34bb69d8
TN
1115.Pp
1116.Em WARNING!
1117.Nm HAMMER
1118currently supports only single masters and using
2010519f
TN
1119this command can easily result in file system corruption
1120if you don't know what you are doing.
34bb69d8
TN
1121.Pp
1122This directive will refuse to run if any programs have open descriptors
1123in the PFS, including programs chdir'd into the PFS.
1124.\" ==== pfs-downgrade ====
4567021b 1125.It Cm pfs-downgrade Ar dirpath
aaf93065 1126Downgrade a master PFS from master to slave operation.
2010519f 1127The PFS becomes read-only and access will be locked to its
4567021b 1128.Cm sync-end-tid .
34bb69d8
TN
1129.Pp
1130This directive will refuse to run if any programs have open descriptors
1131in the PFS, including programs chdir'd into the PFS.
1132.\" ==== pfs-destroy ====
4567021b 1133.It Cm pfs-destroy Ar dirpath
34bb69d8
TN
1134This permanently destroys a PFS.
1135.Pp
1136This directive will refuse to run if any programs have open descriptors
1137in the PFS, including programs chdir'd into the PFS.
15fa4caf 1138.\" ==== mirror-read ====
4567021b 1139.It Cm mirror-read Ar filesystem Op Ar begin-tid
34ebae70 1140Generate a mirroring stream to stdout.
48eadef9 1141The stream ends when the transaction id space has been exhausted.
15fa4caf 1142.\" ==== mirror-read-stream ====
4567021b 1143.It Cm mirror-read-stream Ar filesystem Op Ar begin-tid
48eadef9
MD
1144Generate a mirroring stream to stdout.
1145Upon completion the stream is paused until new data is synced to the
aaf93065
TN
1146.Ar filesystem ,
1147then resumed.
48eadef9 1148Operation continues until the pipe is broken.
aaf93065
TN
1149See the
1150.Cm mirror-stream
1151command for more details.
15fa4caf 1152.\" ==== mirror-write ====
4567021b 1153.It Cm mirror-write Ar filesystem
34bb69d8 1154Take a mirroring stream on stdin.
34ebae70
MD
1155.Pp
1156This command will fail if the
4567021b 1157.Cm shared-uuid
b4448f1a 1158configuration field for the two file systems do not match.
aaf93065
TN
1159See the
1160.Cm mirror-copy
1161command for more details.
01a72c9f
MD
1162.Pp
1163If the target PFS does not exist this command will ask you whether
1164you want to create a compatible PFS slave for the target or not.
15fa4caf 1165.\" ==== mirror-dump ====
4567021b 1166.It Cm mirror-dump
15fa4caf 1167A
4567021b 1168.Cm mirror-read
15fa4caf 1169can be piped into a
4567021b 1170.Cm mirror-dump
2010519f 1171to dump an ASCII representation of the mirroring stream.
15fa4caf 1172.\" ==== mirror-copy ====
4567021b 1173.\".It Cm mirror-copy Ar [[user@]host:]filesystem [[user@]host:]filesystem
f85afb25 1174.It Cm mirror-copy \
f6532f03
TN
1175Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem \
1176Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem
84082922 1177This is a shortcut which pipes a
4567021b 1178.Cm mirror-read
84082922 1179command to a
4567021b 1180.Cm mirror-write
2010519f
TN
1181command.
1182If a remote host specification is made the program forks a
6d9ab5c5 1183.Xr ssh 1
84082922 1184and execs the
4567021b 1185.Cm mirror-read
84082922 1186and/or
4567021b 1187.Cm mirror-write
84082922 1188on the appropriate host.
9c67b4d2 1189The source may be a master or slave PFS, and the target must be a slave PFS.
d4e5b69b 1190.Pp
aaf93065
TN
1191This command also establishes full duplex communication and turns on
1192the 2-way protocol feature
1193.Fl ( 2 )
1194which automatically negotiates transaction id
2010519f 1195ranges without having to use a cyclefile.
84082922 1196If the operation completes successfully the target PFS's
4567021b 1197.Cm sync-end-tid
2010519f
TN
1198will be updated.
1199Note that you must re-chdir into the target PFS to see the updated information.
1200If you do not you will still be in the previous snapshot.
01a72c9f
MD
1201.Pp
1202If the target PFS does not exist this command will ask you whether
1203you want to create a compatible PFS slave for the target or not.
15fa4caf 1204.\" ==== mirror-stream ====
4567021b 1205.\".It Cm mirror-stream Ar [[user@]host:]filesystem [[user@]host:]filesystem
f85afb25 1206.It Cm mirror-stream \
f6532f03
TN
1207Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem \
1208Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem
aaf93065
TN
1209This is a shortcut which pipes a
1210.Cm mirror-read-stream
1211command to a
1212.Cm mirror-write
1213command.
48eadef9 1214This command works similarly to
4567021b 1215.Cm mirror-copy
e7f926a5
MD
1216but does not exit after the initial mirroring completes.
1217The mirroring operation will resume as changes continue to be made to the
aaf93065 1218source.
2010519f 1219The command is commonly used with
48eadef9
MD
1220.Fl i Ar delay
1221and
1222.Fl b Ar bandwidth
1223options to keep the mirroring target in sync with the source on a continuing
1224basis.
e7f926a5
MD
1225.Pp
1226If the pipe is broken the command will automatically retry after sleeping
4567021b
TN
1227for a short while.
1228The time slept will be 15 seconds plus the time given in the
0bd7a37c
MD
1229.Fl i
1230option.
e7f926a5
MD
1231.Pp
1232This command also detects the initial-mirroring case and spends some
1233time scanning the B-Tree to find good break points, allowing the initial
aaf93065 1234bulk mirroring operation to be broken down into 100MB pieces.
e7f926a5
MD
1235This means that the user can kill and restart the operation and it will
1236not have to start from scratch once it has gotten past the first chunk.
0bd7a37c 1237The
aaf93065
TN
1238.Fl S
1239option may be used to change the size of pieces and the
0bd7a37c
MD
1240.Fl B
1241option may be used to disable this feature and perform an initial bulk
1242transfer instead.
de1c0b31 1243.\" ==== version ====
4567021b 1244.It Cm version Ar filesystem
3f2565b9
SW
1245This command returns the
1246.Nm HAMMER
4567021b
TN
1247file system version for the specified
1248.Ar filesystem
1249as well as the range of versions supported in the kernel.
de1c0b31
MD
1250The
1251.Fl q
1252option may be used to remove the summary at the end.
1253.\" ==== version-upgrade ====
4567021b 1254.It Cm version-upgrade Ar filesystem Ar version Op Cm force
3f2565b9
SW
1255This command upgrades the
1256.Nm HAMMER
4567021b
TN
1257.Ar filesystem
1258to the specified
1259.Ar version .
1260Once upgraded a file system may not be downgraded.
1261If you wish to upgrade a file system to a version greater or equal to the
de1c0b31 1262work-in-progress version number you must specify the
4567021b 1263.Cm force
de1c0b31
MD
1264directive.
1265Use of WIP versions should be relegated to testing and may require wiping
f6532f03 1266the file system as development progresses, even though the WIP version might
de1c0b31
MD
1267not change.
1268.Pp
4567021b
TN
1269.Em NOTE!
1270This command operates on the entire
3f2565b9 1271.Nm HAMMER
4567021b 1272file system and is not a per PFS operation.
3f2565b9 1273All PFS's will be affected.
de1c0b31
MD
1274.Bl -tag -width indent
1275.It 1
3f2565b9
SW
1276.Dx 2.0
1277default version, first
1278.Nm HAMMER
1279release.
de1c0b31 1280.It 2
f6532f03
TN
1281.Dx 2.3 .
1282New directory entry layout.
4567021b 1283This version is using a new directory hash key.
16265794 1284.It 3
856bc468 1285.Dx 2.5 .
f6532f03 1286New snapshot management, using file system meta-data for saving
16265794
TN
1287configuration file and snapshots (transaction ids etc.).
1288Also default snapshots directory has changed.
1289.It 4
9d0a6205 1290.Dx 2.6
856bc468 1291default version.
9d0a6205 1292New undo/redo/flush, giving HAMMER a much faster sync and fsync.
de1c0b31 1293.El
0dfeb6c8 1294.El
4567021b 1295.Sh PSEUDO-FILESYSTEM (PFS) NOTES
b4448f1a
TN
1296The root of a PFS is not hooked into the primary
1297.Nm HAMMER
2010519f 1298file system as a directory.
b4448f1a
TN
1299Instead,
1300.Nm HAMMER
4567021b
TN
1301creates a special softlink called
1302.Ql @@PFS%05d
1303(exactly 10 characters long) in the primary
b4448f1a
TN
1304.Nm HAMMER
1305file system.
1306.Nm HAMMER
1307then modifies the contents of the softlink as read by
9c67b4d2 1308.Xr readlink 2 ,
84082922 1309and thus what you see with an
16265794 1310.Nm ls
84082922 1311command or if you were to
16265794 1312.Nm cd
84082922 1313into the link.
9c67b4d2
MD
1314If the PFS is a master the link reflects the current state of the PFS.
1315If the PFS is a slave the link reflects the last completed snapshot, and the
1316contents of the link will change when the next snapshot is completed, and
1317so forth.
1318.Pp
2010519f 1319The
9c67b4d2 1320.Nm
2010519f 1321utility employs numerous safeties to reduce user foot-shooting.
9c67b4d2 1322The
4567021b 1323.Cm mirror-copy
9c67b4d2 1324directive requires that the target be configured as a slave and that the
4567021b 1325.Cm shared-uuid
9c67b4d2 1326field of the mirroring source and target match.
bf2c6489 1327.Sh UPGRADE INSTRUCTIONS HAMMER V1 TO V2
16265794 1328This upgrade changes the way directory entries are stored.
f6532f03 1329It is possible to upgrade a V1 file system to V2 in place, but
bf2c6489
MD
1330directories created prior to the upgrade will continue to use
1331the old layout.
1332.Pp
1333Note that the slave mirroring code in the target kernel had bugs in
1334V1 which can create an incompatible root directory on the slave.
16265794
TN
1335Do not mix a
1336.Nm HAMMER
1337master created after the upgrade with a
1338.Nm HAMMER
bf2c6489
MD
1339slave created prior to the upgrade.
1340.Pp
1341Any directories created after upgrading will use a new layout.
1342.Sh UPGRADE INSTRUCTIONS HAMMER V2 TO V3
16265794 1343This upgrade adds meta-data elements to the B-Tree.
f6532f03 1344It is possible to upgrade a V2 file system to V3 in place.
16265794
TN
1345After issuing the upgrade be sure to run a
1346.Nm
1347.Cm cleanup
1348to perform post-upgrade tasks.
bf2c6489 1349.Pp
16265794
TN
1350After making this upgrade running a
1351.Nm
1352.Cm cleanup
1353will move the
1354.Pa <pfs>/snapshots
bf2c6489 1355directory for each PFS mount into
16265794
TN
1356.Pa /var/hammer/<pfs> .
1357A
1358.Nm HAMMER
1359root mount will migrate
bf2c6489
MD
1360.Pa /snapshots
1361into
1362.Pa /var/hammer/root .
1363Migration occurs only once and only if you have not specified
16265794
TN
1364a snapshots directory in the PFS configuration.
1365If you have specified a snapshots directory in the PFS configuration no
bf2c6489
MD
1366automatic migration will occur.
1367.Pp
1368For slaves, if you desire, you can migrate your snapshots
1369config to the new location manually and then clear the
1370snapshot directory configuration in the slave PFS.
1371The new snapshots hierarchy is designed to work with
1372both master and slave PFSs equally well.
1373.Pp
f6532f03 1374In addition, the old config file will be moved to file system meta-data,
16265794
TN
1375editable via the new
1376.Nm
bf2c6489 1377.Cm viconfig
16265794
TN
1378directive.
1379The old config file will be deleted.
bf2c6489
MD
1380Migration occurs only once.
1381.Pp
f6532f03 1382The V3 file system has new
bf2c6489
MD
1383.Cm snap*
1384directives for creating snapshots.
1385All snapshot directives, including the original, will create
1386meta-data entries for the snapshots and the pruning code will
1387automatically incorporate these entries into its list and
1388expire them the same way it expires softlinks.
16265794 1389If you by accident blow away your snapshot softlinks you can use the
bf2c6489 1390.Cm snapls
f6532f03 1391directive to get a definitive list from the file system meta-data and
bf2c6489 1392regenerate them from that list.
92ed14a3 1393.Pp
16265794
TN
1394.Em WARNING!
1395If you are using
1396.Nm
f6532f03 1397to backup file systems your scripts may be using the
92ed14a3 1398.Cm synctid
16265794
TN
1399directive to generate transaction ids.
1400This directive does not create a snapshot.
1401You will have to modify your scripts to use the
92ed14a3
MD
1402.Cm snapq
1403directive to generate the linkbuf for the softlink you create, or
1404use one of the other
1405.Cm snap*
1406directives.
1407The older
1408.Cm snapshot
1409directive will continue to work as expected and in V3 it will also
f6532f03 1410record the snapshot transaction id in file system meta-data.
16265794
TN
1411You may also want to make use of the new
1412.Ar note
1413tag for the meta-data.
92ed14a3 1414.Pp
16265794
TN
1415.Em WARNING!
1416If you used to remove snapshot softlinks with
92ed14a3
MD
1417.Nm rm
1418you should probably start using the
1419.Cm snaprm
1420directive instead to also remove the related meta-data.
1421The pruning code scans the meta-data so just removing the
1422softlink is not sufficient.
856bc468
TN
1423.Sh UPGRADE INSTRUCTIONS HAMMER V3 TO V4
1424This upgrade changes undo/flush, giving faster sync.
1425It is possible to upgrade a V3 file system to V4 in place.
1426This upgrade reformats the UNDO FIFO (typically 1GB), so upgrade might take
1427a minute or two depending.
1428.Pp
1429Version 4 allows the UNDO FIFO to be flushed without also having
1430to flush the volume header, removing 2 of the 4 disk syncs typically
aaf93065
TN
1431required for an
1432.Fn fsync
1433and removing 1 of the 2 disk syncs typically
856bc468 1434required for a flush sequence.
9d0a6205
MD
1435Version 4 also implements the REDO log (see below) which is capable
1436of fsync()ing with either one disk flush or zero disk flushes.
152385a8 1437.Sh FSYNC FLUSH MODES
aaf93065
TN
1438.Nm HAMMER
1439implements five different fsync flush modes via the
1440.Va vfs.hammer.fsync_mode
1441sysctl, for
1442.Nm HAMMER
1443version 4+ file systems.
152385a8 1444.Pp
9d0a6205 1445As of
aaf93065 1446.Dx 2.6
9d0a6205
MD
1447fsync mode 3 is set by default.
1448REDO operation and recovery is enabled by default.
152385a8
MD
1449.Bl -tag -width indent
1450.It mode 0
1451Full synchronous fsync semantics without REDO.
1452.Pp
aaf93065
TN
1453.Nm HAMMER
1454will not generate REDOs.
1455A
1456.Fn fsync
1457will completely sync
152385a8 1458the data and meta-data and double-flush the FIFO, including
aaf93065
TN
1459issuing two disk synchronization commands.
1460The data is guaranteed
1461to be on the media as of when
1462.Fn fsync
1463returns.
152385a8 1464Needless to say, this is slow.
152385a8
MD
1465.It mode 1
1466Relaxed asynchronous fsync semantics without REDO.
1467.Pp
1468This mode works the same as mode 0 except the last disk synchronization
aaf93065
TN
1469command is not issued.
1470It is faster than mode 0 but not even remotely
152385a8
MD
1471close to the speed you get with mode 2 or mode 3.
1472.Pp
1473Note that there is no chance of meta-data corruption when using this
aaf93065
TN
1474mode, it simply means that the data you wrote and then
1475.Fn fsync Ns 'd
1476might not have made it to the media if the storage system crashes at a bad
152385a8
MD
1477time.
1478.Pp
1479.It mode 2
1480Full synchronous fsync semantics using REDO.
9d0a6205
MD
1481NOTE: If not running
1482a HAMMER version 4 filesystem or later mode 0 is silently used.
152385a8 1483.Pp
aaf93065
TN
1484.Nm HAMMER
1485will generate REDOs in the UNDO/REDO FIFO based on a heuristic.
1486If this is sufficient to satisfy the
1487.Fn fsync
1488operation the blocks
1489will be written out and
1490.Nm HAMMER
1491will wait for the I/Os to complete,
152385a8
MD
1492and then followup with a disk sync command to guarantee the data
1493is on the media before returning.
1494This is slower than mode 3 and can result in significant disk or
1495SSDs overheads, though not as bad as mode 0 or mode 1.
1496.Pp
1497.It mode 3
1498Relaxed asynchronous fsync semantics using REDO.
9d0a6205
MD
1499NOTE: If not running
1500a HAMMER version 4 filesystem or later mode 1 is silently used.
152385a8 1501.Pp
aaf93065
TN
1502.Nm HAMMER
1503will generate REDOs in the UNDO/REDO FIFO based on a heuristic.
1504If this is sufficient to satisfy the
1505.Fn fsync
1506operation the blocks
1507will be written out and
1508.Nm HAMMER
1509will wait for the I/Os to complete,
152385a8
MD
1510but will
1511.Em NOT
1512issue a disk synchronization command.
1513.Pp
1514Note that there is no chance of meta-data corruption when using this
aaf93065
TN
1515mode, it simply means that the data you wrote and then
1516.Fn fsync Ns 'd
1517might
152385a8
MD
1518not have made it to the media if the storage system crashes at a bad
1519time.
1520.Pp
1521This mode is the fastest production fsyncing mode available.
aaf93065
TN
1522This mode is equivalent to how the UFS fsync in the
1523.Bx Ns s
1524operates.
152385a8
MD
1525.Pp
1526.It mode 4
1527fsync is ignored.
1528.Pp
aaf93065
TN
1529Calls to
1530.Fn fsync
1531will be ignored.
1532This mode is primarily designed
152385a8
MD
1533for testing and should not be used on a production system.
1534.El
3120b3e8
MD
1535.Sh RESTORING FROM A SNAPSHOT BACKUP
1536You restore a snapshot by copying it over to live, but there is a caveat.
1537The mtime and atime fields for files accessed via a snapshot is locked
1538to the ctime in order to keep the snapshot consistent, because neither
1539mtime nor atime changes roll any history.
1540.Pp
1541In order to avoid unnecessary copying it is recommended that you use
1542.Nm cpdup
1543.Fl VV
1544.Fl v
1545when doing the copyback. Also make sure you traverse the snapshot softlink
1546by appending a ".", as in "<snapshotpath>/.", and you match up the directory
1547properly.
aaf93065
TN
1548.Sh EXIT STATUS
1549.Ex -std
1550.Sh ENVIRONMENT
1551If the following environment variables exist, they will be used by:
1552.Bl -tag -width ".Ev EDITOR"
1553.It Ev EDITOR
1554The editor program specified in the variable
1555.Ev EDITOR
1556will be invoked instead of the default editor, which is
1557.Xr vi 1 .
1558.It Ev VISUAL
1559Same effect as
1560.Ev EDITOR
1561variable.
1562.El
226f3799
TN
1563.Sh FILES
1564.Bl -tag -width ".It Pa <fs>/var/slaves/<name>" -compact
4567021b 1565.It Pa <pfs>/snapshots
226f3799 1566default per PFS snapshots directory
16265794
TN
1567.Nm ( HAMMER
1568VERSION 2-)
1569.It Pa /var/hammer/<pfs>
1570default per PFS snapshots directory (not root)
1571.Nm ( HAMMER
1572VERSION 3+)
1573.It Pa /var/hammer/root
1574default snapshots directory for root directory
1575.Nm ( HAMMER
1576VERSION 3+)
226f3799 1577.It Pa <snapshots>/config
4567021b 1578per PFS
226f3799 1579.Nm
4567021b 1580.Cm cleanup
226f3799 1581configuration file
16265794
TN
1582.Nm ( HAMMER
1583VERSION 2-)
226f3799
TN
1584.It Pa <fs>/var/slaves/<name>
1585recommended slave PFS snapshots directory
16265794
TN
1586.Nm ( HAMMER
1587VERSION 2-)
226f3799 1588.El
aaf93065 1589.\".Sh EXAMPLES
0dfeb6c8 1590.Sh SEE ALSO
4567021b 1591.Xr ssh 1 ,
84082922 1592.Xr undo 1 ,
b4448f1a 1593.Xr HAMMER 5 ,
e0331f4f 1594.Xr periodic.conf 5 ,
84082922 1595.Xr mount_hammer 8 ,
bb8e52c0 1596.Xr mount_null 8 ,
0dfeb6c8
MD
1597.Xr newfs_hammer 8
1598.Sh HISTORY
1599The
1600.Nm
1601utility first appeared in
1602.Dx 1.11 .
1603.Sh AUTHORS
1604.An Matthew Dillon Aq dillon@backplane.com