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 $
40 .Nd HAMMER file system utility
49 .\" .Op Fl s Ar linkpath
53 .Op Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead
58 This manual page documents the
60 utility which provides miscellaneous functions related to managing a
63 For a general introduction to the
65 file system, its features, and
66 examples on how to set up and maintain one, see
69 The options are as follows:
70 .Bl -tag -width indent
74 Tell the mirror commands to use a 2-way protocol, which allows
75 automatic negotiation of transaction id ranges.
76 This option is automatically enabled by the
80 Specify a bandwidth limit in bytes per second for mirroring streams.
81 This option is typically used to prevent batch mirroring operations from
82 loading down the machine.
83 The bandwidth may be suffixed with
87 to specify values in kilobytes, megabytes, and gigabytes per second.
88 If no suffix is specified, bytes per second is assumed.
90 When pruning, rebalancing or reblocking you can tell the utility
91 to start at the object id stored in the specified file.
92 If the file does not exist
94 will start at the beginning.
98 specific period of time and is unable to complete the operation it will
99 write out the current object id so the next run can pick up where it left off.
102 runs to completion it will delete
105 Specify the volumes making up a
109 is a colon-separated list of devices, each specifying a
113 When maintaining a streaming mirroring this option specifies the
114 minimum delay after a batch ends before the next batch is allowed
116 The default is five seconds.
123 specification for the source and/or destination.
125 Decrease verboseness.
126 May be specified multiple times.
128 Specify recursion for those commands which support it.
130 When pruning, rebalancing or reblocking you can tell the utility to stop
131 after a certain period of time.
132 This option is used along with the
134 option to prune, rebalance or reblock incrementally.
136 Increase verboseness.
137 May be specified multiple times.
139 Force "yes" for any interactive question.
143 will not attempt to break-up large initial bulk transfers into smaller
145 This can save time but if the link is lost in the middle of the
146 initial bulk transfer you will have to start over from scratch.
147 This option is not recommended.
148 For more information see the
151 .It Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead
152 Set the memory cache size for any raw
159 for megabytes is allowed,
160 else the cache size is specified in bytes.
162 The read-behind/read-ahead defaults to 4
166 This option is typically only used with diagnostic commands
167 as kernel-supported commands will use the kernel's buffer cache.
168 .It Fl S Ar splitsize
169 Specify the bulk splitup size in bytes for mirroring streams.
174 will do an initial run-through of the data to calculate good
175 transaction ids to cut up the bulk transfers, creating
176 restart points in case the stream is interrupted.
177 If we don't do this and the stream is interrupted it might
178 have to start all over again.
179 The default is a splitsize of 100MB.
181 At the moment the run-through is disk-bandwidth-heavy but some
182 future version will limit the run-through to just the B-Tree
183 records and not the record data.
185 The splitsize may be suffixed with
189 to specify values in kilobytes, megabytes, or gigabytes.
190 If no suffix is specified, bytes is assumed.
192 Enable compression for any remote ssh specifications.
195 option has already been reserved for other purposes so we had to use
197 This option is typically used with the mirroring directives.
199 Force "yes" for any interactive question.
202 The commands are as follows:
203 .Bl -tag -width indent
204 .\" ==== synctid ====
205 .It Cm synctid Ar filesystem Op Cm quick
206 Generates a guaranteed, formal 64 bit transaction id representing the
207 current state of the specified
210 The file system will be synced to the media.
214 keyword is specified the file system will be soft-synced, meaning that a
215 crash might still undo the state of the file system as of the transaction
216 id returned but any new modifications will occur after the returned
217 transaction id as expected.
219 This operation does not create a snapshot.
220 It is meant to be used
221 to track temporary fine-grained changes to a subset of files and
222 will only remain valid for
224 snapshot access purposes for the
226 period configured for the PFS.
227 If you desire a real snapshot then the
229 directive may be what you are looking for.
231 .It Cm bstats Op Ar interval
234 B-Tree statistics until interrupted.
237 seconds between each display.
238 The default interval is one second.
239 .\" ==== iostats ====
240 .It Cm iostats Op Ar interval
244 statistics until interrupted.
247 seconds between each display.
248 The default interval is one second.
249 .\" ==== history ====
250 .It Cm history Ar path ...
251 Show the modification history for
253 file's inode and data.
254 .\" ==== blockmap ====
256 Dump the blockmap for the file system.
259 blockmap is two-layer
260 blockmap representing the maximum possible file system size of 1 Exabyte.
261 Needless to say the second layer is only present for blocks which exist.
263 blockmap represents 8-Megabyte blocks, called big-blocks.
264 Each big-block has an append
265 point, a free byte count, and a typed zone id which allows content to be
266 reverse engineered to some degree.
270 allocations are essentially appended to a selected big-block using
271 the append offset and deducted from the free byte count.
272 When space is freed the free byte count is adjusted but
274 does not track holes in big-blocks for reallocation.
275 A big-block must be completely freed, either
276 through normal file system operations or through reblocking, before
279 Data blocks can be shared by deducting the space used from the free byte
280 count for each shared references, though
282 does not yet make use of this feature.
283 This means the free byte count can legally go negative.
285 This command needs the
289 .It Cm show Op Ar lo Ns Cm \&: Ns Ar objid
291 By default this command will validate all B-Tree
292 linkages and CRCs, including data CRCs, and will report the most verbose
293 information it can dig up.
294 Any errors will show up with a
296 in column 1 along with various
299 If you specify a localization field or a localization:obj_id field,
300 .Ar lo Ns Cm \&: Ns Ar objid ,
302 search for the key printing nodes as it recurses down, and then
303 will iterate forwards.
304 These fields are specified in HEX.
305 Note that the pfsid is the top 16 bits of the 32 bit localization
306 field so PFS #1 would be 00010000.
310 the command will report less information about the inode contents.
314 the command will not report the content of the inode or other typed
319 the command will not report volume header information, big-block fill
320 ratios, mirror transaction ids, or report or check data CRCs.
321 B-Tree CRCs and linkages are still checked.
323 This command needs the
326 .\" ==== show-undo ====
332 This command needs the
336 .\" Dump the B-Tree, record, large-data, and small-data blockmaps, showing
337 .\" physical block assignments and free space percentages.
338 .\" ==== namekey1 ====
339 .It Cm namekey1 Ar filename
342 64 bit directory hash for the specified file name, using
343 the original directory hash algorithm in version 1 of the file system.
344 The low 32 bits are used as an iterator for hash collisions and will be
346 .\" ==== namekey2 ====
347 .It Cm namekey2 Ar filename
350 64 bit directory hash for the specified file name, using
351 the new directory hash algorithm in version 2 of the file system.
352 The low 32 bits are still used as an iterator but will start out containing
353 part of the hash key.
354 .\" ==== namekey32 ====
355 .It Cm namekey32 Ar filename
356 Generate the top 32 bits of a
358 64 bit directory hash for the specified file name.
361 Shows extended information about all the mounted
364 The information is divided into sections:
365 .Bl -tag -width indent
366 .It Volume identification
367 General information, like the label of the
369 filesystem, the number of volumes it contains, the FSID, and the
372 .It Big block information
373 Big block statistics, such as total, used, reserved and free big blocks.
374 .It Space information
375 Information about space used on the filesystem.
376 Currently total size, used, reserved and free space are displayed.
378 Basic information about the PFSs currently present on a
383 is the ID of the PFS, with 0 being the root PFS.
385 is the current snapshot count on the PFS.
387 displays the mount point of the PFS is currently mounted on (if any).
389 .\" ==== cleanup ====
390 .It Cm cleanup Op Ar filesystem ...
391 This is a meta-command which executes snapshot, prune, rebalance and reblock
392 commands on the specified
397 is specified this command will clean-up all
399 file systems in use, including PFS's.
400 To do this it will scan all
404 mounts, extract PFS id's, and clean-up each PFS found.
406 This command will access a snapshots
407 directory and a configuration file for each
409 creating them if necessary.
410 .Bl -tag -width indent
411 .It Nm HAMMER No version 2-
412 The configuration file is
414 in the snapshots directory which defaults to
415 .Pa <pfs>/snapshots .
416 .It Nm HAMMER No version 3+
417 The configuration file is saved in file system meta-data, see
420 The snapshots directory defaults to
421 .Pa /var/hammer/<pfs>
422 .Pa ( /var/hammer/root
426 The format of the configuration file is:
427 .Bd -literal -offset indent
428 snapshots <period> <retention-time> [any]
429 prune <period> <max-runtime>
430 rebalance <period> <max-runtime>
431 reblock <period> <max-runtime>
432 recopy <period> <max-runtime>
436 .Bd -literal -offset indent
437 snapshots 1d 60d # 0d 0d for PFS /tmp, /var/tmp, /usr/obj
444 Time is given with a suffix of
450 meaning day, hour, minute and second.
454 directive has a period of 0 and a retention time of 0
455 then snapshot generation is disabled, removal of old snapshots are
456 disabled, and prunes will use
457 .Cm prune-everything .
460 directive has a period of 0 but a non-zero retention time
461 then this command will not create any new snapshots but will remove old
462 snapshots it finds based on the retention time.
464 By default only snapshots in the form
465 .Ql snap- Ns Ar yyyymmdd Ns Op - Ns Ar HHMM
469 directive is specified as a third argument on the
471 config line then any softlink of the form
472 .Ql *- Ns Ar yyyymmdd Ns Op - Ns Ar HHMM
474 .Ql *. Ns Ar yyyymmdd Ns Op - Ns Ar HHMM
477 A prune max-runtime of 0 means unlimited.
479 If period hasn't passed since the previous
482 For example a day has passed when midnight is passed (localtime).
490 The default configuration file will create a daily snapshot, do a daily
491 pruning, rebalancing and reblocking run and a monthly recopy run.
492 Reblocking is defragmentation with a level of 95%,
493 and recopy is full defragmentation.
495 By default prune and rebalance operations are time limited to 5 minutes,
496 reblock operations to a bit over 5 minutes,
497 and recopy operations to a bit over 10 minutes.
498 Reblocking and recopy runs are each broken down into four separate functions:
499 btree, inodes, dirs and data.
500 Each function is time limited to the time given in the configuration file,
501 but the btree, inodes and dirs functions usually does not take very long time,
502 full defragmentation is always used for these three functions.
503 Also note that this directive will by default disable snapshots on
510 The defaults may be adjusted by modifying the configuration file.
511 The pruning and reblocking commands automatically maintain a cyclefile
512 for incremental operation.
513 If you interrupt (^C) the program the cyclefile will be updated,
515 may continue to run in the background for a few seconds until the
517 ioctl detects the interrupt.
520 PFS option can be set to use another location for the snapshots directory.
522 Work on this command is still in progress.
524 An ability to remove snapshots dynamically as the
525 file system becomes full.
527 .It Cm config Op Ar filesystem Op Ar configfile
530 Show or change configuration for
532 If zero or one arguments are specified this function dumps the current
533 configuration file to stdout.
534 Zero arguments specifies the PFS containing the current directory.
535 This configuration file is stored in file system meta-data.
536 If two arguments are specified this function installs a new config file.
540 versions less than 3 the configuration file is by default stored in
541 .Pa <pfs>/snapshots/config ,
542 but in all later versions the configuration file is stored in file system
544 .\" ==== viconfig ====
545 .It Cm viconfig Op Ar filesystem
548 Edit the configuration file and reinstall into file system meta-data when done.
549 Zero arguments specifies the PFS containing the current directory.
550 .\" ==== volume-add ====
551 .It Cm volume-add Ar device Ar filesystem
552 This command will format
554 and add all of its space to
558 All existing data contained on
560 will be destroyed by this operation!
565 file system, formatting will be denied.
566 You can overcome this sanity check
569 to erase the beginning sectors of the device.
570 Also remember that you have to specify
572 together with any other device that make up the file system,
577 .\" ==== volume-del ====
578 .It Cm volume-del Ar device Ar filesystem
579 This command will remove volume
584 Remember that you have to remove
586 from the colon-separated list in
590 .\" ==== snapshot ====
591 .It Cm snapshot Oo Ar filesystem Oc Ar snapshot-dir
592 .It Cm snapshot Ar filesystem Ar snapshot-dir Op Ar note
593 Takes a snapshot of the file system either explicitly given by
595 or implicitly derived from the
597 argument and creates a symlink in the directory provided by
599 pointing to the snapshot.
602 is not a directory, it is assumed to be a format string passed to
604 with the current time as parameter.
607 refers to an existing directory, a default format string of
609 is assumed and used as name for the newly created symlink.
611 Snapshot is a per PFS operation, so a
613 file system and each PFS in it have to be snapshot separately.
615 Example, assuming that
623 are file systems on their own, the following invocations:
624 .Bd -literal -offset indent
625 hammer snapshot /mysnapshots
627 hammer snapshot /mysnapshots/%Y-%m-%d
629 hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d
631 hammer snapshot /usr /my/snaps/usr "note"
634 Would create symlinks similar to:
635 .Bd -literal -offset indent
636 /mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16
638 /mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16
640 /mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16
642 /my/snaps/usr/snap-20080627-1210 -> /usr@@0x10d2cd05b7270d16
647 version 3+ file system the snapshot is also recorded in file system meta-data
648 along with the optional
654 .It Cm snap Ar path Op Ar note
657 Create a snapshot for the PFS containing
659 and create a snapshot softlink.
660 If the path specified is a
661 directory a standard snapshot softlink will be created in the directory.
662 The snapshot softlink points to the base of the mounted PFS.
663 .It Cm snaplo Ar path Op Ar note
666 Create a snapshot for the PFS containing
668 and create a snapshot softlink.
669 If the path specified is a
670 directory a standard snapshot softlink will be created in the directory.
671 The snapshot softlink points into the directory it is contained in.
672 .It Cm snapq Ar dir Op Ar note
675 Create a snapshot for the PFS containing the specified directory but do
676 not create a softlink.
677 Instead output a path which can be used to access
678 the directory via the snapshot.
680 An absolute or relative path may be specified.
681 The path will be used as-is as a prefix in the path output to stdout.
683 snap and snapshot directives the snapshot transaction id will be registered
684 in the file system meta-data.
685 .It Cm snaprm Ar path Ar ...
686 .It Cm snaprm Ar transid Ar ...
687 .It Cm snaprm Ar filesystem Ar transid Ar ...
690 Remove a snapshot given its softlink or transaction id.
691 If specifying a transaction id
692 the snapshot is removed from file system meta-data but you are responsible
693 for removing any related softlinks.
695 If a softlink path is specified the filesystem and transaction id
696 is derived from the contents of the softlink.
697 If just a transaction id is specified it is assumed to be a snapshot
698 in the HAMMER filesystem you are currently chdir'd into.
699 You can also specify the filesystem and transaction id explicitly.
700 .It Cm snapls Op Ar path ...
703 Dump the snapshot meta-data for PFSs containing each
705 listing all available snapshots and their notes.
706 If no arguments are specified snapshots for the PFS containing the
707 current directory are listed.
708 This is the definitive list of snapshots for the file system.
710 .It Cm prune Ar softlink-dir
711 Prune the file system based on previously created snapshot softlinks.
712 Pruning is the act of deleting file system history.
715 command will delete file system history such that
716 the file system state is retained for the given snapshots,
717 and all history after the latest snapshot.
718 By setting the per PFS parameter
720 history is guaranteed to be saved at least this time interval.
721 All other history is deleted.
723 The target directory is expected to contain softlinks pointing to
724 snapshots of the file systems you wish to retain.
725 The directory is scanned non-recursively and the mount points and
726 transaction ids stored in the softlinks are extracted and sorted.
727 The file system is then explicitly pruned according to what is found.
728 Cleaning out portions of the file system is as simple as removing a
729 snapshot softlink and then running the
733 As a safety measure pruning only occurs if one or more softlinks are found
736 snapshot id extension.
737 Currently the scanned softlink directory must contain softlinks pointing
741 The softlinks may specify absolute or relative paths.
742 Softlinks must use 20-character
744 transaction ids, as might be returned from
745 .Nm Cm synctid Ar filesystem .
747 Pruning is a per PFS operation, so a
749 file system and each PFS in it have to be pruned separately.
751 Note that pruning a file system may not immediately free-up space,
752 though typically some space will be freed if a large number of records are
754 The file system must be reblocked to completely recover all available space.
756 Example, lets say your that you didn't set
758 and snapshot directory contains the following links:
759 .Bd -literal -offset indent
760 lrwxr-xr-x 1 root wheel 29 May 31 17:57 snap1 ->
761 /usr/obj/@@0x10d2cd05b7270d16
763 lrwxr-xr-x 1 root wheel 29 May 31 17:58 snap2 ->
764 /usr/obj/@@0x10d2cd13f3fde98f
766 lrwxr-xr-x 1 root wheel 29 May 31 17:59 snap3 ->
767 /usr/obj/@@0x10d2cd222adee364
770 If you were to run the
772 command on this directory, then the
775 mount will be pruned to retain the above three snapshots.
776 In addition, history for modifications made to the file system older than
777 the oldest snapshot will be destroyed and history for potentially fine-grained
778 modifications made to the file system more recently than the most recent
779 snapshot will be retained.
781 If you then delete the
783 softlink and rerun the
786 history for modifications pertaining to that snapshot would be destroyed.
790 file system versions 3+ this command also scans the snapshots stored
791 in the file system meta-data and includes them in the prune.
792 .\" ==== prune-everything ====
793 .It Cm prune-everything Ar filesystem
794 This command will remove all historical records from the file system.
795 This directive is not normally used on a production system.
797 This command does not remove snapshot softlinks but will delete all
798 snapshots recorded in file system meta-data (for file system version 3+).
799 The user is responsible for deleting any softlinks.
801 Pruning is a per PFS operation, so a
803 file system and each PFS in it have to be pruned separately.
804 .\" ==== rebalance ====
805 .It Cm rebalance Ar filesystem Op Ar saturation_percentage
806 This command will rebalance the B-Tree, nodes with small number of
807 elements will be combined and element counts will be smoothed out
810 The saturation percentage is between 50% and 100%.
811 The default is 75% (the
813 suffix is not needed).
815 Rebalancing is a per PFS operation, so a
817 file system and each PFS in it have to be rebalanced separately.
818 .\" ==== reblock* ====
819 .It Cm reblock Ar filesystem Op Ar fill_percentage
820 .It Cm reblock-btree Ar filesystem Op Ar fill_percentage
821 .It Cm reblock-inodes Ar filesystem Op Ar fill_percentage
822 .It Cm reblock-dirs Ar filesystem Op Ar fill_percentage
823 .It Cm reblock-data Ar filesystem Op Ar fill_percentage
824 Attempt to defragment and free space for reuse by reblocking a live
827 Big-blocks cannot be reused by
829 until they are completely free.
830 This command also has the effect of reordering all elements, effectively
831 defragmenting the file system.
833 The default fill percentage is 100% and will cause the file system to be
834 completely defragmented.
835 All specified element types will be reallocated and rewritten.
836 If you wish to quickly free up space instead try specifying
837 a smaller fill percentage, such as 90% or 80% (the
839 suffix is not needed).
841 Since this command may rewrite the entire contents of the disk it is
842 best to do it incrementally from a
848 options to limit the run time.
849 The file system would thus be defragmented over long period of time.
851 It is recommended that separate invocations be used for each data type.
852 B-Tree nodes, inodes, and directories are typically the most important
853 elements needing defragmentation.
854 Data can be defragmented over a longer period of time.
856 Reblocking is a per PFS operation, so a
858 file system and each PFS in it have to be reblocked separately.
859 .\" ==== pfs-status ====
860 .It Cm pfs-status Ar dirpath ...
861 Retrieve the mirroring configuration parameters for the specified
863 file systems or pseudo-filesystems (PFS's).
864 .\" ==== pfs-master ====
865 .It Cm pfs-master Ar dirpath Op Ar options
866 Create a pseudo-filesystem (PFS) inside a
869 Up to 65535 such file systems can be created.
870 Each PFS uses an independent inode numbering space making it suitable
871 for use as a replication source or target.
875 directive creates a PFS that you can read, write, and use as a mirroring
878 It is recommended to use a
880 mount to access a PFS, for more information see
882 .\" ==== pfs-slave ====
883 .It Cm pfs-slave Ar dirpath Op Ar options
884 Create a pseudo-filesystem (PFS) inside a
887 Up to 65535 such file systems can be created.
888 Each PFS uses an independent inode numbering space making it suitable
889 for use as a replication source or target.
893 directive creates a PFS that you can use as a mirroring target.
894 You will not be able to access a slave PFS until you have completed the
895 first mirroring operation with it as the target (its root directory will
896 not exist until then).
898 Access to the pfs-slave via the special softlink, as described in the
903 dynamically modify the snapshot transaction id by returning a dynamic result
908 A PFS can only be truly destroyed with the
911 Removing the softlink will not destroy the underlying PFS.
913 It is recommended to use a
915 mount to access a PFS, for more information see
917 .\" ==== pfs-update ====
918 .It Cm pfs-update Ar dirpath Op Ar options
919 Update the configuration parameters for an existing
921 file system or pseudo-filesystem.
922 Options that may be specified:
923 .Bl -tag -width indent
924 .It Cm sync-beg-tid= Ns Ar 0x16llx
925 This is the automatic snapshot access starting transaction id for
927 This parameter is normally updated automatically by the
931 It is important to note that accessing a mirroring slave
932 with a transaction id greater than the last fully synchronized transaction
933 id can result in an unreliable snapshot since you will be accessing
934 data that is still undergoing synchronization.
936 Manually modifying this field is dangerous and can result in a broken mirror.
937 .It Cm sync-end-tid= Ns Ar 0x16llx
938 This is the current synchronization point for mirroring slaves.
939 This parameter is normally updated automatically by the
943 Manually modifying this field is dangerous and can result in a broken mirror.
944 .It Cm shared-uuid= Ns Ar uuid
945 Set the shared UUID for this file system.
946 All mirrors must have the same shared UUID.
947 For safety purposes the
949 directives will refuse to operate on a target with a different shared UUID.
951 Changing the shared UUID on an existing, non-empty mirroring target,
952 including an empty but not completely pruned target,
953 can lead to corruption of the mirroring target.
954 .It Cm unique-uuid= Ns Ar uuid
955 Set the unique UUID for this file system.
956 This UUID should not be used anywhere else,
957 even on exact copies of the file system.
958 .It Cm label= Ns Ar string
959 Set a descriptive label for this file system.
960 .It Cm snapshots= Ns Ar string
961 Specify the snapshots directory which
964 will use to manage this PFS.
965 .Bl -tag -width indent
966 .It Nm HAMMER No version 2-
967 The snapshots directory does not need to be configured for
968 PFS masters and will default to
969 .Pa <pfs>/snapshots .
971 PFS slaves are mirroring slaves so you cannot configure a snapshots
972 directory on the slave itself to be managed by the slave's machine.
973 In fact, the slave will likely have a
975 sub-directory mirrored
976 from the master, but that directory contains the configuration the master
977 is using for its copy of the file system, not the configuration that we
978 want to use for our slave.
980 It is recommended that
981 .Pa <fs>/var/slaves/<name>
982 be configured for a PFS slave, where
988 is an appropriate label.
989 .It Nm HAMMER No version 3+
990 The snapshots directory does not need to be configured for PFS masters or
992 The snapshots directory defaults to
993 .Pa /var/hammer/<pfs>
994 .Pa ( /var/hammer/root
998 You can control snapshot retention on your slave independent of the master.
999 .It Cm snapshots-clear
1002 directory path for this PFS.
1003 .It Cm prune-min= Ns Ar N Ns Cm d
1004 .It Cm prune-min= Ns Oo Ar N Ns Cm d/ Oc Ns \
1005 Ar hh Ns Op Cm \&: Ns Ar mm Ns Op Cm \&: Ns Ar ss
1006 Set the minimum fine-grained data retention period.
1008 always retains fine-grained history up to the most recent snapshot.
1009 You can extend the retention period further by specifying a non-zero
1011 Any snapshot softlinks within the retention period are ignored
1012 for the purposes of pruning (the fine grained history is retained).
1013 Number of days, hours, minutes and seconds are given as
1018 Because the transaction id in the snapshot softlink cannot be used
1019 to calculate a timestamp,
1021 uses the earlier of the
1025 field of the softlink to
1026 determine which snapshots fall within the retention period.
1027 Users must be sure to retain one of these two fields when manipulating
1030 .\" ==== pfs-upgrade ====
1031 .It Cm pfs-upgrade Ar dirpath
1032 Upgrade a PFS from slave to master operation.
1033 The PFS will be rolled back to the current end synchronization transaction id
1034 (removing any partial synchronizations), and will then become writable.
1038 currently supports only single masters and using
1039 this command can easily result in file system corruption
1040 if you don't know what you are doing.
1042 This directive will refuse to run if any programs have open descriptors
1043 in the PFS, including programs chdir'd into the PFS.
1044 .\" ==== pfs-downgrade ====
1045 .It Cm pfs-downgrade Ar dirpath
1046 Downgrade a master PFS from master to slave operation.
1047 The PFS becomes read-only and access will be locked to its
1050 This directive will refuse to run if any programs have open descriptors
1051 in the PFS, including programs chdir'd into the PFS.
1052 .\" ==== pfs-destroy ====
1053 .It Cm pfs-destroy Ar dirpath
1054 This permanently destroys a PFS.
1056 This directive will refuse to run if any programs have open descriptors
1057 in the PFS, including programs chdir'd into the PFS.
1058 .\" ==== mirror-read ====
1059 .It Cm mirror-read Ar filesystem Op Ar begin-tid
1060 Generate a mirroring stream to stdout.
1061 The stream ends when the transaction id space has been exhausted.
1062 .\" ==== mirror-read-stream ====
1063 .It Cm mirror-read-stream Ar filesystem Op Ar begin-tid
1064 Generate a mirroring stream to stdout.
1065 Upon completion the stream is paused until new data is synced to the
1068 Operation continues until the pipe is broken.
1071 command for more details.
1072 .\" ==== mirror-write ====
1073 .It Cm mirror-write Ar filesystem
1074 Take a mirroring stream on stdin.
1076 This command will fail if the
1078 configuration field for the two file systems do not match.
1081 command for more details.
1083 If the target PFS does not exist this command will ask you whether
1084 you want to create a compatible PFS slave for the target or not.
1085 .\" ==== mirror-dump ====
1091 to dump an ASCII representation of the mirroring stream.
1092 .\" ==== mirror-copy ====
1093 .\".It Cm mirror-copy Ar [[user@]host:]filesystem [[user@]host:]filesystem
1094 .It Cm mirror-copy \
1095 Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem \
1096 Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem
1097 This is a shortcut which pipes a
1102 If a remote host specification is made the program forks a
1108 on the appropriate host.
1109 The source may be a master or slave PFS, and the target must be a slave PFS.
1111 This command also establishes full duplex communication and turns on
1112 the 2-way protocol feature
1114 which automatically negotiates transaction id
1115 ranges without having to use a cyclefile.
1116 If the operation completes successfully the target PFS's
1119 Note that you must re-chdir into the target PFS to see the updated information.
1120 If you do not you will still be in the previous snapshot.
1122 If the target PFS does not exist this command will ask you whether
1123 you want to create a compatible PFS slave for the target or not.
1124 .\" ==== mirror-stream ====
1125 .\".It Cm mirror-stream Ar [[user@]host:]filesystem [[user@]host:]filesystem
1126 .It Cm mirror-stream \
1127 Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem \
1128 Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem
1129 This is a shortcut which pipes a
1130 .Cm mirror-read-stream
1134 This command works similarly to
1136 but does not exit after the initial mirroring completes.
1137 The mirroring operation will resume as changes continue to be made to the
1139 The command is commonly used with
1143 options to keep the mirroring target in sync with the source on a continuing
1146 If the pipe is broken the command will automatically retry after sleeping
1148 The time slept will be 15 seconds plus the time given in the
1152 This command also detects the initial-mirroring case and spends some
1153 time scanning the B-Tree to find good break points, allowing the initial
1154 bulk mirroring operation to be broken down into 100MB pieces.
1155 This means that the user can kill and restart the operation and it will
1156 not have to start from scratch once it has gotten past the first chunk.
1159 option may be used to change the size of pieces and the
1161 option may be used to disable this feature and perform an initial bulk
1163 .\" ==== version ====
1164 .It Cm version Ar filesystem
1165 This command returns the
1167 file system version for the specified
1169 as well as the range of versions supported in the kernel.
1172 option may be used to remove the summary at the end.
1173 .\" ==== version-upgrade ====
1174 .It Cm version-upgrade Ar filesystem Ar version Op Cm force
1175 This command upgrades the
1180 Once upgraded a file system may not be downgraded.
1181 If you wish to upgrade a file system to a version greater or equal to the
1182 work-in-progress version number you must specify the
1185 Use of WIP versions should be relegated to testing and may require wiping
1186 the file system as development progresses, even though the WIP version might
1190 This command operates on the entire
1192 file system and is not a per PFS operation.
1193 All PFS's will be affected.
1194 .Bl -tag -width indent
1197 default version, first
1202 New directory entry layout.
1203 This version is using a new directory hash key.
1206 New snapshot management, using file system meta-data for saving
1207 configuration file and snapshots (transaction ids etc.).
1208 Also default snapshots directory has changed.
1212 New undo/redo/flush, giving HAMMER a much faster sync and fsync.
1215 .Sh PSEUDO-FILESYSTEM (PFS) NOTES
1216 The root of a PFS is not hooked into the primary
1218 file system as a directory.
1221 creates a special softlink called
1223 (exactly 10 characters long) in the primary
1227 then modifies the contents of the softlink as read by
1229 and thus what you see with an
1231 command or if you were to
1234 If the PFS is a master the link reflects the current state of the PFS.
1235 If the PFS is a slave the link reflects the last completed snapshot, and the
1236 contents of the link will change when the next snapshot is completed, and
1241 utility employs numerous safeties to reduce user foot-shooting.
1244 directive requires that the target be configured as a slave and that the
1246 field of the mirroring source and target match.
1247 .Sh UPGRADE INSTRUCTIONS HAMMER V1 TO V2
1248 This upgrade changes the way directory entries are stored.
1249 It is possible to upgrade a V1 file system to V2 in place, but
1250 directories created prior to the upgrade will continue to use
1253 Note that the slave mirroring code in the target kernel had bugs in
1254 V1 which can create an incompatible root directory on the slave.
1257 master created after the upgrade with a
1259 slave created prior to the upgrade.
1261 Any directories created after upgrading will use a new layout.
1262 .Sh UPGRADE INSTRUCTIONS HAMMER V2 TO V3
1263 This upgrade adds meta-data elements to the B-Tree.
1264 It is possible to upgrade a V2 file system to V3 in place.
1265 After issuing the upgrade be sure to run a
1268 to perform post-upgrade tasks.
1270 After making this upgrade running a
1275 directory for each PFS mount into
1276 .Pa /var/hammer/<pfs> .
1279 root mount will migrate
1282 .Pa /var/hammer/root .
1283 Migration occurs only once and only if you have not specified
1284 a snapshots directory in the PFS configuration.
1285 If you have specified a snapshots directory in the PFS configuration no
1286 automatic migration will occur.
1288 For slaves, if you desire, you can migrate your snapshots
1289 config to the new location manually and then clear the
1290 snapshot directory configuration in the slave PFS.
1291 The new snapshots hierarchy is designed to work with
1292 both master and slave PFSs equally well.
1294 In addition, the old config file will be moved to file system meta-data,
1295 editable via the new
1299 The old config file will be deleted.
1300 Migration occurs only once.
1302 The V3 file system has new
1304 directives for creating snapshots.
1305 All snapshot directives, including the original, will create
1306 meta-data entries for the snapshots and the pruning code will
1307 automatically incorporate these entries into its list and
1308 expire them the same way it expires softlinks.
1309 If you by accident blow away your snapshot softlinks you can use the
1311 directive to get a definitive list from the file system meta-data and
1312 regenerate them from that list.
1317 to backup file systems your scripts may be using the
1319 directive to generate transaction ids.
1320 This directive does not create a snapshot.
1321 You will have to modify your scripts to use the
1323 directive to generate the linkbuf for the softlink you create, or
1324 use one of the other
1329 directive will continue to work as expected and in V3 it will also
1330 record the snapshot transaction id in file system meta-data.
1331 You may also want to make use of the new
1333 tag for the meta-data.
1336 If you used to remove snapshot softlinks with
1338 you should probably start using the
1340 directive instead to also remove the related meta-data.
1341 The pruning code scans the meta-data so just removing the
1342 softlink is not sufficient.
1343 .Sh UPGRADE INSTRUCTIONS HAMMER V3 TO V4
1344 This upgrade changes undo/flush, giving faster sync.
1345 It is possible to upgrade a V3 file system to V4 in place.
1346 This upgrade reformats the UNDO FIFO (typically 1GB), so upgrade might take
1347 a minute or two depending.
1349 Version 4 allows the UNDO FIFO to be flushed without also having
1350 to flush the volume header, removing 2 of the 4 disk syncs typically
1353 and removing 1 of the 2 disk syncs typically
1354 required for a flush sequence.
1355 Version 4 also implements the REDO log (see below) which is capable
1356 of fsync()ing with either one disk flush or zero disk flushes.
1357 .Sh FSYNC FLUSH MODES
1359 implements five different fsync flush modes via the
1360 .Va vfs.hammer.fsync_mode
1363 version 4+ file systems.
1367 fsync mode 3 is set by default.
1368 REDO operation and recovery is enabled by default.
1369 .Bl -tag -width indent
1371 Full synchronous fsync semantics without REDO.
1374 will not generate REDOs.
1377 will completely sync
1378 the data and meta-data and double-flush the FIFO, including
1379 issuing two disk synchronization commands.
1380 The data is guaranteed
1381 to be on the media as of when
1384 Needless to say, this is slow.
1386 Relaxed asynchronous fsync semantics without REDO.
1388 This mode works the same as mode 0 except the last disk synchronization
1389 command is not issued.
1390 It is faster than mode 0 but not even remotely
1391 close to the speed you get with mode 2 or mode 3.
1393 Note that there is no chance of meta-data corruption when using this
1394 mode, it simply means that the data you wrote and then
1396 might not have made it to the media if the storage system crashes at a bad
1400 Full synchronous fsync semantics using REDO.
1401 NOTE: If not running
1402 a HAMMER version 4 filesystem or later mode 0 is silently used.
1405 will generate REDOs in the UNDO/REDO FIFO based on a heuristic.
1406 If this is sufficient to satisfy the
1408 operation the blocks
1409 will be written out and
1411 will wait for the I/Os to complete,
1412 and then followup with a disk sync command to guarantee the data
1413 is on the media before returning.
1414 This is slower than mode 3 and can result in significant disk or
1415 SSDs overheads, though not as bad as mode 0 or mode 1.
1418 Relaxed asynchronous fsync semantics using REDO.
1419 NOTE: If not running
1420 a HAMMER version 4 filesystem or later mode 1 is silently used.
1423 will generate REDOs in the UNDO/REDO FIFO based on a heuristic.
1424 If this is sufficient to satisfy the
1426 operation the blocks
1427 will be written out and
1429 will wait for the I/Os to complete,
1432 issue a disk synchronization command.
1434 Note that there is no chance of meta-data corruption when using this
1435 mode, it simply means that the data you wrote and then
1438 not have made it to the media if the storage system crashes at a bad
1441 This mode is the fastest production fsyncing mode available.
1442 This mode is equivalent to how the UFS fsync in the
1452 This mode is primarily designed
1453 for testing and should not be used on a production system.
1458 If the following environment variables exist, they will be used by:
1459 .Bl -tag -width ".Ev EDITOR"
1461 The editor program specified in the variable
1463 will be invoked instead of the default editor, which is
1471 .Bl -tag -width ".It Pa <fs>/var/slaves/<name>" -compact
1472 .It Pa <pfs>/snapshots
1473 default per PFS snapshots directory
1476 .It Pa /var/hammer/<pfs>
1477 default per PFS snapshots directory (not root)
1480 .It Pa /var/hammer/root
1481 default snapshots directory for root directory
1484 .It Pa <snapshots>/config
1491 .It Pa <fs>/var/slaves/<name>
1492 recommended slave PFS snapshots directory
1501 .Xr periodic.conf 5 ,
1502 .Xr mount_hammer 8 ,
1508 utility first appeared in
1511 .An Matthew Dillon Aq dillon@backplane.com
projects / dragonfly.git / blob