hammer.8: Comment out rebalance which is not part of cleanup yet.
[dragonfly.git] / sbin / hammer / hammer.8
CommitLineData
0dfeb6c8
MD
1.\" Copyright (c) 2007 The DragonFly Project. All rights reserved.
2.\"
3.\" This code is derived from software contributed to The DragonFly Project
4.\" by Matthew Dillon <dillon@backplane.com>
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\"
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in
14.\" the documentation and/or other materials provided with the
15.\" distribution.
16.\" 3. Neither the name of The DragonFly Project nor the names of its
17.\" contributors may be used to endorse or promote products derived
18.\" from this software without specific, prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
23.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
24.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
25.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
26.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
27.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
28.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
30.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31.\" SUCH DAMAGE.
32.\"
de1c0b31 33.\" $DragonFly: src/sbin/hammer/hammer.8,v 1.58 2008/11/13 02:04:27 dillon Exp $
e0331f4f
SW
34.\"
35.Dd October 22, 2008
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
bb8e52c0 43.Op Fl h2qrv
48eadef9 44.Op Fl b Ar bandwidth
d7ae405c 45.Op Fl c Ar cyclefile
d38ab092 46.Op Fl f Ar blkdev[:blkdev]*
6d9ab5c5 47.\" .Op Fl s Ar linkpath
48eadef9 48.Op Fl i Ar delay
99d6191f 49.Op Fl t Ar seconds
b46b99bf 50.Op Fl C Ar cachesize[:readahead]
0dfeb6c8 51.Ar command
34bb69d8 52.Op Ar argument ...
0dfeb6c8 53.Sh DESCRIPTION
6d9ab5c5 54This manual page documents the
0dfeb6c8 55.Nm
6d9ab5c5 56utility which provides miscellaneous functions related to managing a
b4448f1a
TN
57.Nm HAMMER
58file system.
59For a general introduction to the
60.Nm HAMMER
61file system, its features, and
6d9ab5c5 62examples on how to set up and maintain one, see
b4448f1a 63.Xr HAMMER 5 .
0dfeb6c8
MD
64.Pp
65The options are as follows:
66.Bl -tag -width indent
67.It Fl h
84082922 68Get help.
d4e5b69b
MD
69.It Fl 2
70Tell the mirror commands to use a 2-way protocol, which allows
2010519f
TN
71automatic negotiation of transaction id ranges.
72This option is automatically enabled by the
d4e5b69b
MD
73.Ar mirror-copy
74command.
48eadef9
MD
75.It Fl b Ar bandwidth
76Specify a bandwidth limit in bytes per second for mirroring streams.
77This option is typically used to prevent batch mirroring operations from
78loading down the machine.
15fa4caf
TN
79The bandwidth may be suffixed with
80.Sq k ,
81.Sq m ,
82or
83.Sq g
2010519f 84to specify values in kilobytes, megabytes, and gigabytes per second.
224ac2f2 85If no suffix is specified, bytes per second is assumed.
d7ae405c 86.It Fl c Ar cyclefile
84082922
TN
87When pruning and reblocking you can instruction
88.Nm
2010519f 89to start at the object id stored in the specified file.
84082922 90If the file does not exist
15fa4caf 91.Nm
84082922
TN
92will start at the beginning.
93If
15fa4caf 94.Nm
84082922 95is told to run for a
d7ae405c 96specific period of time and is unable to complete the operation it will
2010519f 97write out the current object id so the next run can pick up where it left off.
84082922
TN
98If
99.Nm
483bb69b
TN
100runs to completion it will delete
101.Ar cyclefile .
d38ab092 102.It Fl f Ar blkdev[:blkdev]*
b4448f1a
TN
103Specify the volumes making up a
104.Nm HAMMER
105file system.
48eadef9
MD
106.It Fl i Ar delay
107When maintaining a streaming mirroring this option specifies the
108minimum delay after a batch ends before the next batch is allowed
109to start.
110The default is five seconds.
e95314de 111.It Fl q
bb92c669 112Decrease verboseness.
2010519f 113May be specified multiple times.
bb8e52c0
TN
114.It Fl r
115Specify recursion for those commands which support it.
99d6191f 116.It Fl t Ar seconds
0006adae 117When pruning and reblocking you can tell the utility to stop after a
2010519f
TN
118certain period of time.
119This option is used along with the
483bb69b 120.Fl c Ar cyclefile
b4448f1a 121option to prune or reblock a portion of the file system incrementally.
563b4845 122.It Fl v
2010519f
TN
123Increase verboseness.
124May be specified multiple times.
07485271
MN
125.It Fl y
126Force "yes" for any interactive question.
b46b99bf 127.It Fl C Ar cachesize[:readahead]
0faa08a1
MD
128Set the memory cache size for any raw I/O. The default is 16m.
129A suffix of 'k' for kilobytes and 'm' for megabytes is allowed,
130else the cache size is specified in bytes.
131.Pp
b46b99bf
MD
132The read-behind/read-ahead defaults to 4 hammer blocks.
133.Pp
0faa08a1
MD
134This option is typically only used with diagnostic commands
135as kernel-supported commands will use the kernel's buffer cache.
0dfeb6c8
MD
136.El
137.Pp
138The commands are as follows:
139.Bl -tag -width indent
15fa4caf 140.\" ==== synctid ====
367431cf
MD
141.It Ar synctid Ar filesystem Op quick
142Generates a guaranteed, formal 64 bit transaction id representing the
b4448f1a
TN
143current state of the specified
144.Nm HAMMER
2010519f
TN
145file system.
146The file system will be synced to the media.
367431cf
MD
147.Pp
148If the
149.Ar quick
b4448f1a
TN
150keyword is specified the file system will be soft-synced, meaning that a
151crash might still undo the state of the file system as of the transaction
367431cf
MD
152id returned but any new modifications will occur after the returned
153transaction id as expected.
15fa4caf 154.\" ==== bstats ====
68e079b8 155.It Ar bstats Op interval
b4448f1a
TN
156Output
157.Nm HAMMER
158B-tree statistics until interrupted.
84082922
TN
159Pause
160.Ar interval
b4448f1a 161seconds between each display.
84082922 162The default interval is one second.
15fa4caf 163.\" ==== iostats ====
68e079b8 164.It Ar iostats Op interval
b4448f1a
TN
165Output
166.Nm HAMMER
167I/O statistics until interrupted.
84082922
TN
168Pause
169.Ar interval
b4448f1a 170seconds between each display.
84082922 171The default interval is one second.
15fa4caf 172.\" ==== history ====
84082922 173.It Ar history Ar path ...
b4448f1a
TN
174Show the modification history for
175.Nm HAMMER
176file's inode and data.
b46b99bf
MD
177.\" ==== blockmap ====
178.It Ar blockmap
179Dump the blockmap for the filesystem. The HAMMER blockmap is two-layer
180blockmap representing the maximum possible filesystem size of 1 Exabyte.
181Needless to say the second layer is only present for blocks which exist.
182HAMMER's blockmap represents 8-Megabyte blocks. Each block has an append
183point, a free byte count, and a typed zone id which allows content to be
184reverse engineered to some degree.
185.Pp
186In HAMMER allocations essentially appended to a selected big-block using
187the append offset and deducted from the free byte count. When space is
188freed the free byte count is adjusted but HAMMER does not track holes in
189big-blocks for reallocation. A big-block must be completely freed, either
190through normal filesystem operations or through reblocking, before
191it can be reused.
192.Pp
193Data blocks can be shared by deducting the space used from the free byte
194count for each shared references, though HAMMER does not yet make use of
195this feature. This means the free byte count can legally go negative.
196.Pp
197This command needs the
198.Fl f
199flag.
15fa4caf 200.\" ==== show ====
c028469c 201.It Ar show
b46b99bf
MD
202Dump the B-tree. By default this command will validate all B-Tree
203linkages and CRCs, including data CRCs, and will report the most verbose
204information it can dig up.
205Any errors will show up with a 'B' in column 1 along with various
206other error flags.
207.Pp
208If you use
209.Fl q
210the command will report less information about the inode contents.
211.Pp
212If you use
213.Fl qq
214the command will not report the content of the inode or other typed
215data at all.
216.Pp
217If you use
218.Fl qqq
219the command will not report volume header information, big-block fill
220ratios, mirror TIDs, or report or check data CRCs. B-Tree CRCs and
221linkages are still checked.
222.Pp
2010519f 223This command needs the
b4448f1a 224.Fl f
84082922
TN
225flag.
226.\" .It Ar blockmap
227.\" Dump the B-tree, record, large-data, and small-data blockmaps, showing
228.\" physical block assignments and free space percentages.
5e435c92
MD
229.\" ==== namekey1 ====
230.It Ar namekey1 Ar filename
b4448f1a
TN
231Generate a
232.Nm HAMMER
5e435c92
MD
23364 bit directory hash for the specified file name, using
234the original directory hash algorithm in version 1 of the filesystem.
cbd800c2
MD
235The low 32 bits are used as an iterator for hash collisions and will be
236output as 0.
5e435c92
MD
237.\" ==== namekey2 ====
238.It Ar namekey2 Ar filename
239Generate a
240.Nm HAMMER
24164 bit directory hash for the specified file name, using
242the new directory hash algorithm in version 2 of the filesystem.
243The low 32 bits are still used as an iterator but will start out containing
244part of the hash key.
15fa4caf 245.\" ==== namekey32 ====
cbd800c2 246.It Ar namekey32 Ar filename
b4448f1a
TN
247Generate the top 32 bits of a
248.Nm HAMMER
2010519f 24964 bit directory hash for the specified file name.
b66b9421
AH
250.\" ==== info ====
251.It Ar info
252Shows extended information about all the mounted HAMMER filesystems.
253At the moment volume identification, big blocks information and space details are shown.
6a6e350f 254.\" ==== cleanup ====
226f3799 255.It Ar cleanup Op Ar filesystem ...
6a6e350f 256This is a meta-command which executes snapshot, pruning, and reblocking
226f3799
TN
257commands on the specified
258.Nm HAMMER
259file system.
260If no
261.Ar filesystem
262is specified this command will clean-up all
263.Nm HAMMER
264file systems in use, including PFS's.
265To do this it will scan all
266.Nm HAMMER
267and
268.Nm null
6a6e350f
MD
269mounts, extract PFS id's, and clean-up each PFS found.
270.Pp
226f3799
TN
271This command will by default access a
272.Pa snapshots
6a6e350f 273subdirectory and a
226f3799
TN
274.Pa snapshots/config
275file for each
276.Ar filesystem ,
277creating them if necessary.
278The format of the configuration file is:
279.Bd -literal -offset indent
5e435c92 280snapshots <period> <retention-time> [any]
226f3799 281prune <period> <max-runtime>
bb4c57c6 282.\"rebalance <period> <max-runtime>
226f3799
TN
283reblock <period> <1/3 max-runtime>
284recopy <period> <1/3 max-runtime>
285
286Defaults are:
483bb69b 287snapshots 1d 60d # 0d 60d for PFS /tmp, /var/tmp, /usr/obj
226f3799 288prune 1d 5m
bb4c57c6 289.\"rebalance 1d 5m
226f3799
TN
290reblock 1d 5m
291recopy 30d 10m
292.Ed
6a6e350f 293.Pp
483bb69b 294Time is given with a suffix of
226f3799
TN
295.Cm d ,
296.Cm h ,
297.Cm m
483bb69b 298or
226f3799
TN
299.Cm s
300meaning day, hour, minute and second.
5e435c92
MD
301.Pp
302If the snapshots directive has a period of 0 and a retention time of 0
303then snapshot generation is disabled, removal of old snapshots are
304disabled, and prunes will use
305.Ar prune-everything .
306If the snapshots directive has a period of 0 but a non-zero retention time
307then this command will not create any new snapshots but will remove old
308snapshots it finds based on the retention time.
309.Pp
310By default only snapshots in the form: snap-yyyymmdd[-hhmm] are processed.
311If the
312.Ar any
313directive is specified as a third argument on the snapshots config line
314then any softlink of the form *[- or .]yyyymmdd[-hhmm] will be processed.
315.Pp
226f3799
TN
316A prune max-runtime of 0 means unlimited.
317.Pp
e0331f4f 318If period hasn't passed since the previous
483bb69b
TN
319.Ar cleanup
320run nothing is done.
321For example a day has passed when midnight is passed (localtime).
e0331f4f
SW
322By default,
323.Dx
324is set up to run
325.Nm Ar cleanup
326nightly via
327.Xr periodic 8 .
226f3799
TN
328.Pp
329The default configuration file will create a daily snapshot, do a daily
330pruning and reblocking run and a monthly recopy run.
331Reblocking is defragmentation with a level of 95%,
332and recopy is full defragmentation.
333.Pp
334By default prune and reblock operations are limited to 5 minutes per function,
335and recopy operations are limited to 10 minutes per function.
336Reblocking and recopy runs are each broken down into three separate functions
337(btree, inodes and data)
338and are thus by default limited to 15 and 30 minutes respectively.
339Also note that this directive will by default disable snapshots on
2010519f 340the following PFS's:
6a6e350f 341.Pa /tmp ,
226f3799 342.Pa /var/tmp
6a6e350f 343and
226f3799 344.Pa /usr/obj .
6a6e350f 345.Pp
226f3799
TN
346The defaults may be adjusted by modifying the
347.Pa config
348file.
6a6e350f
MD
349The pruning and reblocking commands automatically maintain a cyclefile
350for incremental operation.
226f3799
TN
351If you interrupt (^C) the program the cyclefile will be updated, but a sub-command
352may continue to run in the background for a few seconds until the
353.Nm HAMMER
6a6e350f 354ioctl detects the interrupt.
226f3799
TN
355The
356.Ar snapshots
357PFS option can be set to use another location for the snapshots directory.
6a6e350f
MD
358.Pp
359Work on this command is still in progress.
ff1c9800 360Expected additions: An ability to remove snapshots dynamically as the
226f3799 361file system becomes full.
0e999592
TN
362.\" ==== snapshot ====
363.It Ar snapshot Oo Ar filesystem Oc Ar snapshot-dir
364Takes a snapshot of the file system either explicitly given by
365.Ar filesystem
366or implicitly derived from the
367.Ar snapshot-dir
368argument and creates a symlink in the directory provided by
369.Ar snapshot-dir
370pointing to the snapshot.
371If
372.Ar snapshot-dir
373is not a directory, it is assumed to be a format string passed to
374.Xr strftime 3
375with the current time as parameter.
376If
377.Ar snapshot-dir
378refers to an existing directory, a default format string of "snap-%Y%d%m-%H%M"
379is assumed and used as name for the newly created symlink.
380.Pp
381Snapshot is a per PFS operation, so a
382.Nm HAMMER
383file system and each PFS in it have to be snapshot separately.
384.Pp
385Example, assuming that
386.Pa /mysnapshots
387is on file system
388.Pa /
389and that
390.Pa /obj
391is a file system on its own, the following invocations:
392.Bd -literal -offset indent
393hammer snapshot /mysnapshots
394
395hammer snapshot /mysnapshots/%Y-%m-%d
396
397hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d
398.Ed
399.Pp
400would create symlinks similar to:
401.Bd -literal -offset indent
402/mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16
403
404/mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16
405
406/mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16
407.Ed
15fa4caf 408.\" ==== prune ====
b5aaba7f 409.It Ar prune Ar softlink-dir
b4448f1a
TN
410Prune the file system based on previously created snapshot softlinks.
411Pruning is the act of deleting file system history.
84082922
TN
412The
413.Ar prune
414command
b4448f1a
TN
415will delete file system history such that
416the file system state is retained for the given snapshots,
84082922
TN
417and all history after the latest snapshot,
418but all other history is deleted.
419.Pp
e8969ef0 420The target directory is expected to contain softlinks pointing to
2010519f
TN
421snapshots of the file systems you wish to retain.
422The directory is scanned non-recursively and the mount points and
423transaction ids stored in the softlinks are extracted and sorted.
b4448f1a
TN
424The file system is then explicitly pruned according to what is found.
425Cleaning out portions of the file system is as simple as removing a softlink
e8969ef0 426and then running the
b5aaba7f 427.Ar prune
e8969ef0
MD
428command.
429.Pp
430As a safety measure pruning only occurs if one or more softlinks are found
431containing the @@ snapshot id extension.
e8969ef0 432Currently the scanned softlink directory must contain softlinks pointing
b4448f1a
TN
433to a single
434.Nm HAMMER
2010519f
TN
435mount.
436The softlinks may specify absolute or relative paths.
437Softlinks must use 20-character (@@0x%016llx) transaction ids,
84082922
TN
438as might be returned from
439.Dq Nm Ar synctid filesystem .
e8969ef0 440.Pp
226f3799 441Pruning is a per PFS operation, so a
15fa4caf
TN
442.Nm HAMMER
443file system and each PFS in it have to be pruned separately.
444.Pp
445Note that pruning a file system may not immediately free-up space,
446though typically some space will be freed if a large number of records are
2010519f
TN
447pruned out.
448The file system must be reblocked to completely recover all available space.
15fa4caf 449.Pp
e8969ef0 450Example, lets say your snapshot directory contains the following links:
226f3799 451.Bd -literal -offset indent
f51a18e7
SW
452lrwxr-xr-x 1 root wheel 29 May 31 17:57 snap1 ->
453/usr/obj/@@0x10d2cd05b7270d16
454
455lrwxr-xr-x 1 root wheel 29 May 31 17:58 snap2 ->
456/usr/obj/@@0x10d2cd13f3fde98f
457
458lrwxr-xr-x 1 root wheel 29 May 31 17:59 snap3 ->
459/usr/obj/@@0x10d2cd222adee364
460.Ed
e8969ef0 461.Pp
84082922
TN
462If you were to run the
463.Ar prune
b4448f1a
TN
464command on this directory, then the
465.Nm HAMMER
f51a18e7
SW
466.Pa /usr/obj
467mount will be pruned to retain the above three snapshots.
2010519f
TN
468In addition, history for modifications made to the file system older than
469the oldest snapshot will be destroyed and history for potentially fine-grained
470modifications made to the file system more recently than the most recent
471snapshot will be retained.
472.Pp
473If you then delete the
474.Pa snap2
475softlink and rerun the
84082922
TN
476.Ar prune
477command,
478history for modifications pertaining to that snapshot would be destroyed.
15fa4caf 479.\" ==== prune-everything ====
b5aaba7f 480.It Ar prune-everything Ar filesystem
b4448f1a 481This command will remove all historical records from the file system.
b5aaba7f 482This directive is not normally used on a production system.
797a0b63
MD
483.\" ==== rebalance ====
484.It Ar rebalance Ar filesystem Op Ar saturation_level
485This command will rebalance the B-Tree, nodes with small numbers of
486elements will be combined and element counts will be smoothed out
487between nodes.
488.Pp
489The saturation level is a percentage between 50 and 100. The default
490is 75 percent.
15fa4caf 491.\" ==== reblock ====
ba7b52c9
MD
492.It Ar reblock Ar filesystem Op Ar fill_percentage
493.It Ar reblock-btree Ar filesystem Op Ar fill_percentage
58c17893 494.It Ar reblock-inodes Ar filesystem Op Ar fill_percentage
9e29c876 495.It Ar reblock-dirs Ar filesystem Op Ar fill_percentage
ba7b52c9 496.It Ar reblock-data Ar filesystem Op Ar fill_percentage
9e29c876 497Attempt to defragment and free space for reuse by reblocking a live
b4448f1a
TN
498.Nm HAMMER
499file system.
500Big blocks cannot be reused by
501.Nm HAMMER
502until they are completely free.
9e29c876 503This command also has the effect of reordering all elements, effectively
b4448f1a 504defragmenting the file system.
ba7b52c9 505.Pp
b4448f1a 506The default fill percentage is 100% and will cause the file system to be
2010519f
TN
507completely defragmented.
508All specified element types will be reallocated and rewritten.
509If you wish to quickly free up space instead try specifying
15fa4caf
TN
510a smaller fill percentage, such as 90% or 80% (the
511.Sq %
512suffix is not needed).
ba7b52c9 513.Pp
9e29c876 514Since this command may rewrite the entire contents of the disk it is
84082922
TN
515best to do it incrementally from a
516.Xr cron 8
517job along with the
9e29c876
MD
518.Fl c Ar cyclefile
519and
99d6191f 520.Fl t Ar seconds
9e29c876 521options to limit the run time.
b4448f1a 522The file system would thus be defragmented over long period of time.
9e29c876
MD
523.Pp
524It is recommended that separate invocations be used for each data type.
d2ee8e9f 525B-tree nodes, inodes, and directories are typically the most important
2010519f
TN
526elements needing defragmentation.
527Data can be defragmented over a longer period of time.
15fa4caf 528.Pp
226f3799 529Reblocking is a per PFS operation, so a
15fa4caf
TN
530.Nm HAMMER
531file system and each PFS in it have to be reblocked separately.
532.\" ==== pfs-status ====
34bb69d8 533.It Ar pfs-status Ar dirpath ...
34ebae70 534Retrieve the mirroring configuration parameters for the specified
b4448f1a 535.Nm HAMMER
2010519f 536file systems or pseudo-filesystems (PFS's).
15fa4caf 537.\" ==== pfs-master ====
d4e5b69b 538.It Ar pfs-master Ar dirpath Op options
b4448f1a
TN
539Create a pseudo-filesystem (PFS) inside a
540.Nm HAMMER
541file system.
542Up to 65535 such file systems can be created.
765c85a8 543Each PFS uses an independent inode numbering space making it suitable
d4e5b69b
MD
544for use as a replication source or target.
545.Pp
546The
547.Ar pfs-master
548directive creates a PFS that you can read, write, and use as a mirroring
549source.
bb8e52c0
TN
550.Pp
551It is recommended to use a
552.Nm null
553mount to access a PFS, for more information see
554.Xr HAMMER 5 .
15fa4caf 555.\" ==== pfs-slave ====
d4e5b69b 556.It Ar pfs-slave Ar dirpath Op options
b4448f1a
TN
557Create a pseudo-filesystem (PFS) inside a
558.Nm HAMMER
559file system.
560Up to 65535 such file systems can be created.
765c85a8 561Each PFS uses an independent inode numbering space making it suitable
d4e5b69b
MD
562for use as a replication source or target.
563.Pp
564The
565.Ar pfs-slave
765c85a8 566directive creates a PFS that you can use as a mirroring target.
d4e5b69b
MD
567You will not be able to access a slave PFS until you have completed the
568first mirroring operation with it as the target (its root directory will
569not exist until then).
34ebae70 570.Pp
84082922 571Access to the pfs-slave via the special softlink,
2010519f
TN
572as described in the
573.Sx PFS NOTES
574below, allows
b4448f1a
TN
575.Nm HAMMER
576to
84082922
TN
577dynamically modify the snapshot transaction id by returning a dynamic result
578from
579.Xr readlink 2
580calls.
d4e5b69b 581.Pp
765c85a8
SW
582A PFS can only be truly destroyed with the
583.Ar pfs-destroy
d4e5b69b
MD
584directive.
585Removing the softlink will not destroy the underlying PFS.
bb8e52c0
TN
586.Pp
587It is recommended to use a
588.Nm null
589mount to access a PFS, for more information see
590.Xr HAMMER 5 .
15fa4caf 591.\" ==== pfs-update ====
34ebae70 592.It Ar pfs-update Ar dirpath Op options
b4448f1a
TN
593Update the configuration parameters for an existing
594.Nm HAMMER
595file system
2010519f
TN
596or pseudo-filesystem.
597Options that may be specified:
34ebae70
MD
598.Bl -tag -width indent
599.It sync-beg-tid=0x16llx
2010519f
TN
600This is the automatic snapshot access starting transaction id for
601mirroring slaves.
34ebae70
MD
602This parameter is normally updated automatically by the
603.Ar mirror-write
604directive.
605.Pp
606It is important to note that accessing a mirroring slave
765c85a8 607with a transaction id greater than the last fully synchronized transaction
34ebae70
MD
608id can result in an unreliable snapshot since you will be accessing
609data that is still undergoing synchronization.
610.Pp
611Manually modifying this field is dangerous and can result in a broken
612mirror.
613.It sync-end-tid=0x16llx
ddc8e722 614This is the current synchronization point for mirroring slaves.
34ebae70
MD
615This parameter is normally updated automatically by the
616.Ar mirror-write
617directive.
618.Pp
2010519f 619Manually modifying this field is dangerous and can result in a broken mirror.
34ebae70 620.It shared-uuid=<uuid>
2010519f
TN
621Set the shared UUID for this file system.
622All mirrors must have the same shared UUID.
623For safety purposes the
34bb69d8 624.Ar mirror-write
2010519f 625directives will refuse to operate on a target with a different shared UUID.
34ebae70 626.Pp
84082922 627Changing the shared UUID on an existing, non-empty mirroring target,
2010519f
TN
628including an empty but not completely pruned target,
629can lead to corruption of the mirroring target.
34ebae70 630.It unique-uuid=<uuid>
2010519f
TN
631Set the unique UUID for this file system.
632This UUID should not be used anywhere else,
633even on exact copies of the file system.
34ebae70 634.It label=<string>
b4448f1a 635Set a descriptive label for this file system.
ff1c9800 636.It snapshots=<string>
226f3799
TN
637Specify the snapshots directory which
638.Nm
639.Ar cleanup
2010519f
TN
640will use to manage this PFS.
641The snapshots directory does not need to be configured for
226f3799
TN
642PFS masters and will default to
643.Pa <pfs>/snapshots .
ff1c9800
MD
644.Pp
645PFS slaves are mirroring slaves so you cannot configure a snapshots
646directory on the slave itself to be managed by the slave's machine.
226f3799
TN
647In fact, the slave will likely have a
648.Pa snapshots
649sub-directory mirrored
ff1c9800 650from the master, but that directory contains the configuration the master
226f3799 651is using for its copy of the file system, not the configuration that we
ff1c9800
MD
652want to use for our slave.
653.Pp
226f3799
TN
654It is recommended that
655.Pa <fs>/var/slaves/<name>
656be configured for a PFS slave, where
657.Pa <fs>
658is the base
659.Nm HAMMER
660file system, and
661.Pa <name>
662is an appropriate label.
2010519f 663You can control snapshot retention on your slave independent of the master.
ff1c9800
MD
664.It snapshots-clear
665Zero out the snapshots directory path for this PFS.
34ebae70 666.El
34bb69d8
TN
667.\" ==== pfs-upgrade ====
668.It Ar pfs-upgrade Ar dirpath
2010519f
TN
669Upgrade a PFS from slave to master operation.
670The PFS will be rolled back to the current end synchronization tid
671(removing any partial synchronizations), and will then become writable.
34bb69d8
TN
672.Pp
673.Em WARNING!
674.Nm HAMMER
675currently supports only single masters and using
2010519f
TN
676this command can easily result in file system corruption
677if you don't know what you are doing.
34bb69d8
TN
678.Pp
679This directive will refuse to run if any programs have open descriptors
680in the PFS, including programs chdir'd into the PFS.
681.\" ==== pfs-downgrade ====
682.It Ar pfs-downgrade Ar dirpath
2010519f
TN
683Downgrade a master PFS from master to slave operation
684The PFS becomes read-only and access will be locked to its
34bb69d8
TN
685.Ar sync-end-tid .
686.Pp
687This directive will refuse to run if any programs have open descriptors
688in the PFS, including programs chdir'd into the PFS.
689.\" ==== pfs-destroy ====
690.It Ar pfs-destroy Ar dirpath
691This permanently destroys a PFS.
692.Pp
693This directive will refuse to run if any programs have open descriptors
694in the PFS, including programs chdir'd into the PFS.
15fa4caf 695.\" ==== mirror-read ====
34ebae70
MD
696.It Ar mirror-read Ar filesystem Op Ar <begin-tid>
697Generate a mirroring stream to stdout.
48eadef9 698The stream ends when the transaction id space has been exhausted.
15fa4caf 699.\" ==== mirror-read-stream ====
48eadef9
MD
700.It Ar mirror-read-stream Ar filesystem Op Ar <begin-tid>
701Generate a mirroring stream to stdout.
702Upon completion the stream is paused until new data is synced to the
703master, then resumed.
704Operation continues until the pipe is broken.
15fa4caf 705.\" ==== mirror-write ====
34bb69d8
TN
706.It Ar mirror-write Ar filesystem
707Take a mirroring stream on stdin.
34ebae70
MD
708.Pp
709This command will fail if the
84082922 710.Ar shared-uuid
b4448f1a 711configuration field for the two file systems do not match.
01a72c9f
MD
712.Pp
713If the target PFS does not exist this command will ask you whether
714you want to create a compatible PFS slave for the target or not.
15fa4caf 715.\" ==== mirror-dump ====
243ca327 716.It Ar mirror-dump
15fa4caf
TN
717A
718.Ar mirror-read
719can be piped into a
720.Ar mirror-dump
2010519f 721to dump an ASCII representation of the mirroring stream.
15fa4caf 722.\" ==== mirror-copy ====
34ebae70 723.It Ar mirror-copy Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem
84082922
TN
724This is a shortcut which pipes a
725.Ar mirror-read
726command to a
727.Ar mirror-write
2010519f
TN
728command.
729If a remote host specification is made the program forks a
6d9ab5c5 730.Xr ssh 1
84082922
TN
731and execs the
732.Ar mirror-read
733and/or
734.Ar mirror-write
735on the appropriate host.
9c67b4d2 736The source may be a master or slave PFS, and the target must be a slave PFS.
d4e5b69b 737.Pp
9c67b4d2 738This command also established full duplex communication and turns on
2010519f
TN
739the two-way protocol feature which automatically negotiates transaction id
740ranges without having to use a cyclefile.
84082922
TN
741If the operation completes successfully the target PFS's
742.Ar sync-end-tid
2010519f
TN
743will be updated.
744Note that you must re-chdir into the target PFS to see the updated information.
745If you do not you will still be in the previous snapshot.
01a72c9f
MD
746.Pp
747If the target PFS does not exist this command will ask you whether
748you want to create a compatible PFS slave for the target or not.
15fa4caf 749.\" ==== mirror-stream ====
48eadef9
MD
750.It Ar mirror-stream Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem
751This command works similarly to
752.Ar mirror-copy
753but does not exit unless the pipe is broken.
2010519f
TN
754This command will resume the mirroring operation whenever the master is synced.
755The command is commonly used with
48eadef9
MD
756.Fl i Ar delay
757and
758.Fl b Ar bandwidth
759options to keep the mirroring target in sync with the source on a continuing
760basis.
de1c0b31
MD
761.\" ==== version ====
762.It Ar version Ar filesystem
3f2565b9
SW
763This command returns the
764.Nm HAMMER
765filesystem version for the specified
de1c0b31
MD
766filesystem as well as the range of versions supported in the kernel.
767The
768.Fl q
769option may be used to remove the summary at the end.
770.\" ==== version-upgrade ====
771.It Ar version-upgrade Ar filesystem Ar version Op Ar force
3f2565b9
SW
772This command upgrades the
773.Nm HAMMER
774filesystem to the specified version.
de1c0b31
MD
775Once upgraded a filesystem may not be downgraded.
776If you wish to upgrade a filesystem to a version greater or equal to the
777work-in-progress version number you must specify the
778.Ar force
779directive.
780Use of WIP versions should be relegated to testing and may require wiping
781the filesystem as development progresses, even though the WIP version might
782not change.
783.Pp
3f2565b9
SW
784NOTE! This command operates on the entire
785.Nm HAMMER
786filesystem and is not a per-PFS operation.
787All PFS's will be affected.
de1c0b31
MD
788.Bl -tag -width indent
789.It 1
3f2565b9
SW
790.Dx 2.0
791default version, first
792.Nm HAMMER
793release.
de1c0b31
MD
794.It 2
795Work-in-progress version.
796This version is developing a new directory hash key.
797.El
0dfeb6c8 798.El
f51a18e7 799.\".Sh EXAMPLES
9c67b4d2 800.Sh PSEUDO FILESYSTEM (PFS) NOTES
b4448f1a
TN
801The root of a PFS is not hooked into the primary
802.Nm HAMMER
2010519f 803file system as a directory.
b4448f1a
TN
804Instead,
805.Nm HAMMER
2010519f
TN
806creates a special softlink called "@@PFS%05d" (exactly 10 characters long)
807in the primary
b4448f1a
TN
808.Nm HAMMER
809file system.
810.Nm HAMMER
811then modifies the contents of the softlink as read by
9c67b4d2 812.Xr readlink 2 ,
84082922
TN
813and thus what you see with an
814.Xr ls 1
815command or if you were to
816.Xr cd 1
817into the link.
9c67b4d2
MD
818If the PFS is a master the link reflects the current state of the PFS.
819If the PFS is a slave the link reflects the last completed snapshot, and the
820contents of the link will change when the next snapshot is completed, and
821so forth.
822.Pp
2010519f
TN
823PFS support is currently very new and experimental.
824The
9c67b4d2 825.Nm
2010519f 826utility employs numerous safeties to reduce user foot-shooting.
9c67b4d2
MD
827The
828.Ar mirror-copy
829directive requires that the target be configured as a slave and that the
830.Ar shared-uuid
831field of the mirroring source and target match.
226f3799
TN
832.Sh FILES
833.Bl -tag -width ".It Pa <fs>/var/slaves/<name>" -compact
834.It Pa snapshots
835default per PFS snapshots directory
836.It Pa <snapshots>/config
837.Nm
838.Ar cleanup
839configuration file
840.It Pa <fs>/var/slaves/<name>
841recommended slave PFS snapshots directory
842.El
19fe1c42
SW
843.Sh EXIT STATUS
844.Ex -std
0dfeb6c8 845.Sh SEE ALSO
84082922 846.Xr undo 1 ,
b4448f1a 847.Xr HAMMER 5 ,
e0331f4f 848.Xr periodic.conf 5 ,
84082922 849.Xr mount_hammer 8 ,
bb8e52c0 850.Xr mount_null 8 ,
0dfeb6c8
MD
851.Xr newfs_hammer 8
852.Sh HISTORY
853The
854.Nm
855utility first appeared in
856.Dx 1.11 .
857.Sh AUTHORS
858.An Matthew Dillon Aq dillon@backplane.com