1 .\" Copyright (c) 2007 The DragonFly Project. All rights reserved.
3 .\" This code is derived from software contributed to The DragonFly Project
4 .\" by Matthew Dillon <dillon@backplane.com>
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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
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.
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
33 .\" $DragonFly: src/sbin/hammer/hammer.8,v 1.58 2008/11/13 02:04:27 dillon Exp $
35 .Dd September 28, 2009
40 .Nd HAMMER file system utility
47 .Op Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead
49 .Op Fl f Ar blkdev Ns Oo Ns Cm \&: Ns Ar blkdev Oc Ns *
50 .\" .Op Fl s Ar linkpath
56 This manual page documents the
58 utility which provides miscellaneous functions related to managing a
61 For a general introduction to the
63 file system, its features, and
64 examples on how to set up and maintain one, see
67 The options are as follows:
68 .Bl -tag -width indent
72 Tell the mirror commands to use a 2-way protocol, which allows
73 automatic negotiation of transaction id ranges.
74 This option is automatically enabled by the
80 will not attempt to break-up large initial bulk transfers into smaller pieces.
81 This can save time but if the link is lost in the middle of the
82 initial bulk transfer you will have to start over from scratch.
84 Specify a bandwidth limit in bytes per second for mirroring streams.
85 This option is typically used to prevent batch mirroring operations from
86 loading down the machine.
87 The bandwidth may be suffixed with
91 to specify values in kilobytes, megabytes, and gigabytes per second.
92 If no suffix is specified, bytes per second is assumed.
93 .It Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead
94 Set the memory cache size for any raw
101 for megabytes is allowed,
102 else the cache size is specified in bytes.
104 The read-behind/read-ahead defaults to 4 hammer blocks.
106 This option is typically only used with diagnostic commands
107 as kernel-supported commands will use the kernel's buffer cache.
108 .It Fl c Ar cyclefile
109 When pruning and reblocking you can instruction
111 to start at the object id stored in the specified file.
112 If the file does not exist
114 will start at the beginning.
118 specific period of time and is unable to complete the operation it will
119 write out the current object id so the next run can pick up where it left off.
122 runs to completion it will delete
124 .It Fl f Ar blkdev Ns Oo Ns Cm \&: Ns Ar blkdev Oc Ns *
125 Specify the volumes making up a
129 When maintaining a streaming mirroring this option specifies the
130 minimum delay after a batch ends before the next batch is allowed
132 The default is five seconds.
134 Decrease verboseness.
135 May be specified multiple times.
137 Specify recursion for those commands which support it.
139 When pruning and reblocking you can tell the utility to stop after a
140 certain period of time.
141 This option is used along with the
143 option to prune or reblock a portion of the file system incrementally.
145 Increase verboseness.
146 May be specified multiple times.
148 Force "yes" for any interactive question.
151 The commands are as follows:
152 .Bl -tag -width indent
153 .\" ==== synctid ====
154 .It Cm synctid Ar filesystem Op Cm quick
155 Generates a guaranteed, formal 64 bit transaction id representing the
156 current state of the specified
159 The file system will be synced to the media.
163 keyword is specified the file system will be soft-synced, meaning that a
164 crash might still undo the state of the file system as of the transaction
165 id returned but any new modifications will occur after the returned
166 transaction id as expected.
168 .It Cm bstats Op Ar interval
171 B-tree statistics until interrupted.
174 seconds between each display.
175 The default interval is one second.
176 .\" ==== iostats ====
177 .It Cm iostats Op Ar interval
181 statistics until interrupted.
184 seconds between each display.
185 The default interval is one second.
186 .\" ==== history ====
187 .It Cm history Ar path ...
188 Show the modification history for
190 file's inode and data.
191 .\" ==== blockmap ====
193 Dump the blockmap for the file system.
196 blockmap is two-layer
197 blockmap representing the maximum possible file system size of 1 Exabyte.
198 Needless to say the second layer is only present for blocks which exist.
200 blockmap represents 8-Megabyte blocks, called big-blocks.
201 Each big-block has an append
202 point, a free byte count, and a typed zone id which allows content to be
203 reverse engineered to some degree.
207 allocations essentially appended to a selected big-block using
208 the append offset and deducted from the free byte count.
209 When space is freed the free byte count is adjusted but
211 does not track holes in big-blocks for reallocation.
212 A big-block must be completely freed, either
213 through normal file system operations or through reblocking, before
216 Data blocks can be shared by deducting the space used from the free byte
217 count for each shared references, though
219 does not yet make use of this feature.
220 This means the free byte count can legally go negative.
222 This command needs the
226 .It Cm show Op Ar lo Ns Cm \&: Ns Ar objid
228 By default this command will validate all B-Tree
229 linkages and CRCs, including data CRCs, and will report the most verbose
230 information it can dig up.
231 Any errors will show up with a 'B' in column 1 along with various
234 If you specify a localization and object id field the dump will
235 search for the key printing nodes as it recurses down, and then
236 will iterate forwards.
240 the command will report less information about the inode contents.
244 the command will not report the content of the inode or other typed
249 the command will not report volume header information, big-block fill
250 ratios, mirror transaction ids, or report or check data CRCs.
251 B-tree CRCs and linkages are still checked.
253 This command needs the
257 .\" Dump the B-tree, record, large-data, and small-data blockmaps, showing
258 .\" physical block assignments and free space percentages.
259 .\" ==== namekey1 ====
260 .It Cm namekey1 Ar filename
263 64 bit directory hash for the specified file name, using
264 the original directory hash algorithm in version 1 of the file system.
265 The low 32 bits are used as an iterator for hash collisions and will be
267 .\" ==== namekey2 ====
268 .It Cm namekey2 Ar filename
271 64 bit directory hash for the specified file name, using
272 the new directory hash algorithm in version 2 of the file system.
273 The low 32 bits are still used as an iterator but will start out containing
274 part of the hash key.
275 .\" ==== namekey32 ====
276 .It Cm namekey32 Ar filename
277 Generate the top 32 bits of a
279 64 bit directory hash for the specified file name.
282 Shows extended information about all the mounted
285 At the moment volume identification, big-blocks information and space details
287 .\" ==== cleanup ====
288 .It Cm cleanup Op Ar filesystem ...
289 This is a meta-command which executes snapshot, prune, rebalance and reblock
290 commands on the specified
295 is specified this command will clean-up all
297 file systems in use, including PFS's.
298 To do this it will scan all
302 mounts, extract PFS id's, and clean-up each PFS found.
304 This command will by default access a
310 creating them if necessary.
311 The format of the configuration file is:
312 .Bd -literal -offset indent
313 snapshots <period> <retention-time> [any]
314 prune <period> <max-runtime>
315 rebalance <period> <max-runtime>
316 reblock <period> <max-runtime>
317 recopy <period> <max-runtime>
321 .Bd -literal -offset indent
322 snapshots 1d 60d # 0d 0d for PFS /tmp, /var/tmp, /usr/obj
329 Time is given with a suffix of
335 meaning day, hour, minute and second.
339 directive has a period of 0 and a retention time of 0
340 then snapshot generation is disabled, removal of old snapshots are
341 disabled, and prunes will use
342 .Cm prune-everything .
345 directive has a period of 0 but a non-zero retention time
346 then this command will not create any new snapshots but will remove old
347 snapshots it finds based on the retention time.
349 By default only snapshots in the form
350 .Ql snap- Ns Ar yyyymmdd Ns Op - Ns Ar HHMM
354 directive is specified as a third argument on the
356 config line then any softlink of the form
357 .Ql *- Ns Ar yyyymmdd Ns Op - Ns Ar HHMM
359 .Ql *. Ns Ar yyyymmdd Ns Op - Ns Ar HHMM
362 A prune max-runtime of 0 means unlimited.
364 If period hasn't passed since the previous
367 For example a day has passed when midnight is passed (localtime).
375 The default configuration file will create a daily snapshot, do a daily
376 pruning, rebalancing and reblocking run and a monthly recopy run.
377 Reblocking is defragmentation with a level of 95%,
378 and recopy is full defragmentation.
380 By default prune and rebalance operations are time limited to 5 minutes,
381 reblock operations to a bit over 5 minutes,
382 and recopy operations to a bit over 10 minutes.
383 Reblocking and recopy runs are each broken down into four separate functions:
384 btree, inodes, dirs and data.
385 Each function is time limited to the time given in the configuration file,
386 but the btree, inodes and dirs functions usually does not take very long time,
387 full defragmentation is always used for these three functions.
388 Also note that this directive will by default disable snapshots on
395 The defaults may be adjusted by modifying the
398 The pruning and reblocking commands automatically maintain a cyclefile
399 for incremental operation.
400 If you interrupt (^C) the program the cyclefile will be updated,
402 may continue to run in the background for a few seconds until the
404 ioctl detects the interrupt.
407 PFS option can be set to use another location for the snapshots directory.
409 Work on this command is still in progress.
411 An ability to remove snapshots dynamically as the
412 file system becomes full.
414 .It Cm expand Ar filesystem Ar device
415 This command will format
417 and add all of its space to
421 All existing data contained on
423 will be destroyed by this operation!
428 filesystem, formatting will be denied. You can overcome this sanity check
431 to erase the beginning sectors of the device.
432 Also remember that you have to specify
434 together with any other device that make the filesystem, colon-separated to
436 .\" ==== snapshot ====
437 .It Cm snapshot Oo Ar filesystem Oc Ar snapshot-dir
438 Takes a snapshot of the file system either explicitly given by
440 or implicitly derived from the
442 argument and creates a symlink in the directory provided by
444 pointing to the snapshot.
447 is not a directory, it is assumed to be a format string passed to
449 with the current time as parameter.
452 refers to an existing directory, a default format string of
454 is assumed and used as name for the newly created symlink.
456 Snapshot is a per PFS operation, so a
458 file system and each PFS in it have to be snapshot separately.
460 Example, assuming that
466 is a file system on its own, the following invocations:
467 .Bd -literal -offset indent
468 hammer snapshot /mysnapshots
470 hammer snapshot /mysnapshots/%Y-%m-%d
472 hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d
475 would create symlinks similar to:
476 .Bd -literal -offset indent
477 /mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16
479 /mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16
481 /mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16
484 .It Cm prune Ar softlink-dir
485 Prune the file system based on previously created snapshot softlinks.
486 Pruning is the act of deleting file system history.
489 command will delete file system history such that
490 the file system state is retained for the given snapshots,
491 and all history after the latest snapshot.
492 By setting the per PFS parameter
494 history is guaranteed to be saved at least this time interval.
495 All other history is deleted.
497 The target directory is expected to contain softlinks pointing to
498 snapshots of the file systems you wish to retain.
499 The directory is scanned non-recursively and the mount points and
500 transaction ids stored in the softlinks are extracted and sorted.
501 The file system is then explicitly pruned according to what is found.
502 Cleaning out portions of the file system is as simple as removing a
503 snapshot softlink and then running the
507 As a safety measure pruning only occurs if one or more softlinks are found
510 snapshot id extension.
511 Currently the scanned softlink directory must contain softlinks pointing
515 The softlinks may specify absolute or relative paths.
516 Softlinks must use 20-character
518 transaction ids, as might be returned from
519 .Nm Cm synctid Ar filesystem .
521 Pruning is a per PFS operation, so a
523 file system and each PFS in it have to be pruned separately.
525 Note that pruning a file system may not immediately free-up space,
526 though typically some space will be freed if a large number of records are
528 The file system must be reblocked to completely recover all available space.
530 Example, lets say your that you didn't set
532 and snapshot directory contains the following links:
533 .Bd -literal -offset indent
534 lrwxr-xr-x 1 root wheel 29 May 31 17:57 snap1 ->
535 /usr/obj/@@0x10d2cd05b7270d16
537 lrwxr-xr-x 1 root wheel 29 May 31 17:58 snap2 ->
538 /usr/obj/@@0x10d2cd13f3fde98f
540 lrwxr-xr-x 1 root wheel 29 May 31 17:59 snap3 ->
541 /usr/obj/@@0x10d2cd222adee364
544 If you were to run the
546 command on this directory, then the
549 mount will be pruned to retain the above three snapshots.
550 In addition, history for modifications made to the file system older than
551 the oldest snapshot will be destroyed and history for potentially fine-grained
552 modifications made to the file system more recently than the most recent
553 snapshot will be retained.
555 If you then delete the
557 softlink and rerun the
560 history for modifications pertaining to that snapshot would be destroyed.
561 .\" ==== prune-everything ====
562 .It Cm prune-everything Ar filesystem
563 This command will remove all historical records from the file system.
564 This directive is not normally used on a production system.
565 .\" ==== rebalance ====
566 .It Cm rebalance Ar filesystem Op Ar saturation_level
567 This command will rebalance the B-tree, nodes with small number of
568 elements will be combined and element counts will be smoothed out
571 The saturation level is a percentage between 50 and 100.
572 The default is 75 percent.
573 .\" ==== reblock ====
574 .It Cm reblock Ar filesystem Op Ar fill_percentage
575 .It Cm reblock-btree Ar filesystem Op Ar fill_percentage
576 .It Cm reblock-inodes Ar filesystem Op Ar fill_percentage
577 .It Cm reblock-dirs Ar filesystem Op Ar fill_percentage
578 .It Cm reblock-data Ar filesystem Op Ar fill_percentage
579 Attempt to defragment and free space for reuse by reblocking a live
582 Big-blocks cannot be reused by
584 until they are completely free.
585 This command also has the effect of reordering all elements, effectively
586 defragmenting the file system.
588 The default fill percentage is 100% and will cause the file system to be
589 completely defragmented.
590 All specified element types will be reallocated and rewritten.
591 If you wish to quickly free up space instead try specifying
592 a smaller fill percentage, such as 90% or 80% (the
594 suffix is not needed).
596 Since this command may rewrite the entire contents of the disk it is
597 best to do it incrementally from a
603 options to limit the run time.
604 The file system would thus be defragmented over long period of time.
606 It is recommended that separate invocations be used for each data type.
607 B-tree nodes, inodes, and directories are typically the most important
608 elements needing defragmentation.
609 Data can be defragmented over a longer period of time.
611 Reblocking is a per PFS operation, so a
613 file system and each PFS in it have to be reblocked separately.
614 .\" ==== pfs-status ====
615 .It Cm pfs-status Ar dirpath ...
616 Retrieve the mirroring configuration parameters for the specified
618 file systems or pseudo-filesystems (PFS's).
619 .\" ==== pfs-master ====
620 .It Cm pfs-master Ar dirpath Op Ar options
621 Create a pseudo-filesystem (PFS) inside a
624 Up to 65535 such file systems can be created.
625 Each PFS uses an independent inode numbering space making it suitable
626 for use as a replication source or target.
630 directive creates a PFS that you can read, write, and use as a mirroring
633 It is recommended to use a
635 mount to access a PFS, for more information see
637 .\" ==== pfs-slave ====
638 .It Cm pfs-slave Ar dirpath Op Ar options
639 Create a pseudo-filesystem (PFS) inside a
642 Up to 65535 such file systems can be created.
643 Each PFS uses an independent inode numbering space making it suitable
644 for use as a replication source or target.
648 directive creates a PFS that you can use as a mirroring target.
649 You will not be able to access a slave PFS until you have completed the
650 first mirroring operation with it as the target (its root directory will
651 not exist until then).
653 Access to the pfs-slave via the special softlink, as described in the
658 dynamically modify the snapshot transaction id by returning a dynamic result
663 A PFS can only be truly destroyed with the
666 Removing the softlink will not destroy the underlying PFS.
668 It is recommended to use a
670 mount to access a PFS, for more information see
672 .\" ==== pfs-update ====
673 .It Cm pfs-update Ar dirpath Op Ar options
674 Update the configuration parameters for an existing
676 file system or pseudo-filesystem.
677 Options that may be specified:
678 .Bl -tag -width indent
679 .It Cm sync-beg-tid= Ns Ar 0x16llx
680 This is the automatic snapshot access starting transaction id for
682 This parameter is normally updated automatically by the
686 It is important to note that accessing a mirroring slave
687 with a transaction id greater than the last fully synchronized transaction
688 id can result in an unreliable snapshot since you will be accessing
689 data that is still undergoing synchronization.
691 Manually modifying this field is dangerous and can result in a broken mirror.
692 .It Cm sync-end-tid= Ns Ar 0x16llx
693 This is the current synchronization point for mirroring slaves.
694 This parameter is normally updated automatically by the
698 Manually modifying this field is dangerous and can result in a broken mirror.
699 .It Cm shared-uuid= Ns Ar uuid
700 Set the shared UUID for this file system.
701 All mirrors must have the same shared UUID.
702 For safety purposes the
704 directives will refuse to operate on a target with a different shared UUID.
706 Changing the shared UUID on an existing, non-empty mirroring target,
707 including an empty but not completely pruned target,
708 can lead to corruption of the mirroring target.
709 .It Cm unique-uuid= Ns Ar uuid
710 Set the unique UUID for this file system.
711 This UUID should not be used anywhere else,
712 even on exact copies of the file system.
713 .It Cm label= Ns Ar string
714 Set a descriptive label for this file system.
715 .It Cm snapshots= Ns Ar string
716 Specify the snapshots directory which
719 will use to manage this PFS.
720 The snapshots directory does not need to be configured for
721 PFS masters and will default to
722 .Pa <pfs>/snapshots .
724 PFS slaves are mirroring slaves so you cannot configure a snapshots
725 directory on the slave itself to be managed by the slave's machine.
726 In fact, the slave will likely have a
728 sub-directory mirrored
729 from the master, but that directory contains the configuration the master
730 is using for its copy of the file system, not the configuration that we
731 want to use for our slave.
733 It is recommended that
734 .Pa <fs>/var/slaves/<name>
735 be configured for a PFS slave, where
741 is an appropriate label.
742 You can control snapshot retention on your slave independent of the master.
743 .It Cm snapshots-clear
746 directory path for this PFS.
747 .It Cm prune-min= Ns Ar N Ns Cm d
748 .It Cm prune-min= Ns Xo
750 .Ar hh Ns Op Cm \&: Ns Ar mm Ns Op Cm \&: Ns Ar ss
752 Set the minimum fine-grained data retention period.
754 always retains fine-grained history up to the most recent snapshot.
755 You can extend the retention period further by specifying a non-zero
757 Any snapshot softlinks within the retention period are ignored
758 for the purposes of pruning (the fine grained history is retained).
759 Number of days, hours, minutes and seconds are given as
764 Because the transaction id in the snapshot softlink cannot be used
765 to calculate a timestamp,
767 uses the earlier of the
771 field of the softlink to
772 determine which snapshots fall within the retention period.
773 Users must be sure to retain one of these two fields when manipulating
776 .\" ==== pfs-upgrade ====
777 .It Cm pfs-upgrade Ar dirpath
778 Upgrade a PFS from slave to master operation.
779 The PFS will be rolled back to the current end synchronization transaction id
780 (removing any partial synchronizations), and will then become writable.
784 currently supports only single masters and using
785 this command can easily result in file system corruption
786 if you don't know what you are doing.
788 This directive will refuse to run if any programs have open descriptors
789 in the PFS, including programs chdir'd into the PFS.
790 .\" ==== pfs-downgrade ====
791 .It Cm pfs-downgrade Ar dirpath
792 Downgrade a master PFS from master to slave operation
793 The PFS becomes read-only and access will be locked to its
796 This directive will refuse to run if any programs have open descriptors
797 in the PFS, including programs chdir'd into the PFS.
798 .\" ==== pfs-destroy ====
799 .It Cm pfs-destroy Ar dirpath
800 This permanently destroys a PFS.
802 This directive will refuse to run if any programs have open descriptors
803 in the PFS, including programs chdir'd into the PFS.
804 .\" ==== mirror-read ====
805 .It Cm mirror-read Ar filesystem Op Ar begin-tid
806 Generate a mirroring stream to stdout.
807 The stream ends when the transaction id space has been exhausted.
808 .\" ==== mirror-read-stream ====
809 .It Cm mirror-read-stream Ar filesystem Op Ar begin-tid
810 Generate a mirroring stream to stdout.
811 Upon completion the stream is paused until new data is synced to the
812 master, then resumed.
813 Operation continues until the pipe is broken.
814 .\" ==== mirror-write ====
815 .It Cm mirror-write Ar filesystem
816 Take a mirroring stream on stdin.
818 This command will fail if the
820 configuration field for the two file systems do not match.
822 If the target PFS does not exist this command will ask you whether
823 you want to create a compatible PFS slave for the target or not.
824 .\" ==== mirror-dump ====
830 to dump an ASCII representation of the mirroring stream.
831 .\" ==== mirror-copy ====
832 .\".It Cm mirror-copy Ar [[user@]host:]filesystem [[user@]host:]filesystem
833 .It Cm mirror-copy Xo
834 .Oo Oo Ar user Oc Ns Cm @ Ns Ar host Ns Cm \&: Oc Ns Ar filesystem
835 .Oo Oo Ar user Oc Ns Cm @ Ns Ar host Ns Cm \&: Oc Ns Ar filesystem
837 This is a shortcut which pipes a
842 If a remote host specification is made the program forks a
848 on the appropriate host.
849 The source may be a master or slave PFS, and the target must be a slave PFS.
851 This command also established full duplex communication and turns on
852 the two-way protocol feature which automatically negotiates transaction id
853 ranges without having to use a cyclefile.
854 If the operation completes successfully the target PFS's
857 Note that you must re-chdir into the target PFS to see the updated information.
858 If you do not you will still be in the previous snapshot.
860 If the target PFS does not exist this command will ask you whether
861 you want to create a compatible PFS slave for the target or not.
862 .\" ==== mirror-stream ====
863 .\".It Cm mirror-stream Ar [[user@]host:]filesystem [[user@]host:]filesystem
864 .It Cm mirror-stream Xo
865 .Oo Oo Ar user Oc Ns Cm @ Ns Ar host Ns Cm \&: Oc Ns Ar filesystem
866 .Oo Oo Ar user Oc Ns Cm @ Ns Ar host Ns Cm \&: Oc Ns Ar filesystem
868 This command works similarly to
870 but does not exit after the initial mirroring completes.
871 The mirroring operation will resume as changes continue to be made to the
873 The command is commonly used with
877 options to keep the mirroring target in sync with the source on a continuing
880 If the pipe is broken the command will automatically retry after sleeping
882 The time slept will be 15 seconds plus the time given in the
886 This command also detects the initial-mirroring case and spends some
887 time scanning the B-Tree to find good break points, allowing the initial
888 bulk mirroring operation to be broken down into about 20 separate pieces.
889 This means that the user can kill and restart the operation and it will
890 not have to start from scratch once it has gotten past the first chunk.
893 option may be used to disable this feature and perform an initial bulk
895 .\" ==== version ====
896 .It Cm version Ar filesystem
897 This command returns the
899 file system version for the specified
901 as well as the range of versions supported in the kernel.
904 option may be used to remove the summary at the end.
905 .\" ==== version-upgrade ====
906 .It Cm version-upgrade Ar filesystem Ar version Op Cm force
907 This command upgrades the
912 Once upgraded a file system may not be downgraded.
913 If you wish to upgrade a file system to a version greater or equal to the
914 work-in-progress version number you must specify the
917 Use of WIP versions should be relegated to testing and may require wiping
918 the filesystem as development progresses, even though the WIP version might
922 This command operates on the entire
924 file system and is not a per PFS operation.
925 All PFS's will be affected.
926 .Bl -tag -width indent
929 default version, first
934 default version, new directory entry layout.
935 This version is using a new directory hash key.
939 .Sh PSEUDO-FILESYSTEM (PFS) NOTES
940 The root of a PFS is not hooked into the primary
942 file system as a directory.
945 creates a special softlink called
947 (exactly 10 characters long) in the primary
951 then modifies the contents of the softlink as read by
953 and thus what you see with an
955 command or if you were to
958 If the PFS is a master the link reflects the current state of the PFS.
959 If the PFS is a slave the link reflects the last completed snapshot, and the
960 contents of the link will change when the next snapshot is completed, and
965 utility employs numerous safeties to reduce user foot-shooting.
968 directive requires that the target be configured as a slave and that the
970 field of the mirroring source and target match.
972 .Bl -tag -width ".It Pa <fs>/var/slaves/<name>" -compact
973 .It Pa <pfs>/snapshots
974 default per PFS snapshots directory
975 .It Pa <snapshots>/config
980 .It Pa <fs>/var/slaves/<name>
981 recommended slave PFS snapshots directory
989 .Xr periodic.conf 5 ,
996 utility first appeared in
999 .An Matthew Dillon Aq dillon@backplane.com