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