.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd February 10, 2011
+.Dd April 19, 2011
.Dt HAMMER 8
.Os
.Sh NAME
.Nm
.Fl h
.Nm
-.Op Fl 2BqrvXy
+.Op Fl 2BFqrvXy
.Op Fl b Ar bandwidth
+.Op Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead
.Op Fl c Ar cyclefile
.Op Fl f Ar blkdevs
.\" .Op Fl s Ar linkpath
.Op Fl i Ar delay
.Op Fl p Ar ssh-port
-.Op Fl t Ar seconds
-.Op Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead
.Op Fl S Ar splitsize
+.Op Fl t Ar seconds
.Ar command
.Op Ar argument ...
.Sh DESCRIPTION
.Pp
The options are as follows:
.Bl -tag -width indent
-.It Fl h
-Get help.
.It Fl 2
Tell the mirror commands to use a 2-way protocol, which allows
automatic negotiation of transaction id ranges.
This option is automatically enabled by the
.Cm mirror-copy
command.
+.It Fl B
+Bulk transfer.
+.Cm Mirror-stream
+will not attempt to break-up large initial bulk transfers into smaller
+pieces.
+This can save time but if the link is lost in the middle of the
+initial bulk transfer you will have to start over from scratch.
+For more information see the
+.Fl S
+option.
.It Fl b Ar bandwidth
Specify a bandwidth limit in bytes per second for mirroring streams.
This option is typically used to prevent batch mirroring operations from
pipe or a
.Xr pf 4
queue.
+.It Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead
+Set the memory cache size for any raw
+.Tn I/O .
+The default is 16MB.
+A suffix of
+.Cm k
+for kilobytes and
+.Cm m
+for megabytes is allowed,
+else the cache size is specified in bytes.
+.Pp
+The read-behind/read-ahead defaults to 4
+.Nm HAMMER
+blocks.
+.Pp
+This option is typically only used with diagnostic commands
+as kernel-supported commands will use the kernel's buffer cache.
.It Fl c Ar cyclefile
When pruning, rebalancing or reblocking you can tell the utility
to start at the object id stored in the specified file.
will start at the beginning.
If
.Nm
-is told to run for a
-specific period of time and is unable to complete the operation it will
-write out the current object id so the next run can pick up where it left off.
+is told to run for a specific period of time
+.Pq Fl t
+and is unable to complete the operation it will write out
+the current object id so the next run can pick up where it left off.
If
.Nm
runs to completion it will delete
.Ar cyclefile .
+.It Fl F
+Force operation.
+E.g.\&
+.Cm cleanup
+will not check that time period has elapsed if this option is given.
.It Fl f Ar blkdevs
Specify the volumes making up a
.Nm HAMMER
is a colon-separated list of devices, each specifying a
.Nm HAMMER
volume.
+.It Fl h
+Show usage.
.It Fl i Ar delay
+Specify delay in seconds for
+.Cm mirror-read-stream .
When maintaining a streaming mirroring this option specifies the
minimum delay after a batch ends before the next batch is allowed
to start.
The default is five seconds.
.It Fl p Ar ssh-port
-This passes the
+Pass the
.Fl p Ar ssh-port
option to
.Xr ssh 1
May be specified multiple times.
.It Fl r
Specify recursion for those commands which support it.
-.It Fl t Ar seconds
-When pruning, rebalancing or reblocking you can tell the utility to stop
-after a certain period of time.
-This option is used along with the
-.Fl c Ar cyclefile
-option to prune, rebalance or reblock incrementally.
-.It Fl v
-Increase verboseness.
-May be specified multiple times.
-.It Fl y
-Force "yes" for any interactive question.
-.It Fl B
-Bulk transfer.
-.Cm Mirror-stream
-will not attempt to break-up large initial bulk transfers into smaller
-pieces.
-This can save time but if the link is lost in the middle of the
-initial bulk transfer you will have to start over from scratch.
-This option is not recommended.
-For more information see the
-.Fl S
-option.
-.It Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead
-Set the memory cache size for any raw
-.Tn I/O .
-The default is 16MB.
-A suffix of
-.Cm k
-for kilobytes and
-.Cm m
-for megabytes is allowed,
-else the cache size is specified in bytes.
-.Pp
-The read-behind/read-ahead defaults to 4
-.Nm HAMMER
-blocks.
-.Pp
-This option is typically only used with diagnostic commands
-as kernel-supported commands will use the kernel's buffer cache.
.It Fl S Ar splitsize
Specify the bulk splitup size in bytes for mirroring streams.
When a
restart points in case the stream is interrupted.
If we don't do this and the stream is interrupted it might
have to start all over again.
-The default is a splitsize of 4G.
+The default is a
+.Ar splitsize
+of 4GB.
.Pp
At the moment the run-through is disk-bandwidth-heavy but some
future version will limit the run-through to just the B-Tree
If no suffix is specified, bytes is assumed.
.Pp
When mirroring very large filesystems the minimum recommended
-split side is 4G.
+split size is 4GB.
A small split size may wind up generating a great deal of overhead
but very little actual incremental data and is not recommended.
+.It Fl t Ar seconds
+Specify timeout in seconds.
+When pruning, rebalancing, reblocking or mirror-reading
+you can tell the utility to stop after a certain period of time.
+A value of 0 means unlimited.
+This option is used along with the
+.Fl c Ar cyclefile
+option to prune, rebalance or reblock incrementally.
+.It Fl v
+Increase verboseness.
+May be specified multiple times.
.It Fl X
Enable compression for any remote ssh specifications.
-Unfortunately the
-.Fl C
-option has already been reserved for other purposes so we had to use
-a different letter.
This option is typically used with the mirroring directives.
.It Fl y
-Force "yes" for any interactive question.
+Force
+.Dq yes
+for interactive questions.
.El
.Pp
The commands are as follows:
.Bl -tag -width indent
.\" ==== synctid ====
.It Cm synctid Ar filesystem Op Cm quick
-Generates a guaranteed, formal 64 bit transaction id representing the
+Generate a guaranteed, formal 64-bit transaction id representing the
current state of the specified
.Nm HAMMER
file system.
to track temporary fine-grained changes to a subset of files and
will only remain valid for
.Ql @@
-snapshot access purposes for the
+access purposes for the
.Cm prune-min
period configured for the PFS.
If you desire a real snapshot then the
seconds between each display.
The default interval is one second.
.\" ==== history ====
-.It Cm history Ar path ...
-Show the modification history for
+.It Cm history Ns Oo Cm @ Ns Ar offset Ns Oo Cm \&, Ns Ar length Oc Oc Ar path ...
+Show the modification history for inode and data of
.Nm HAMMER
-file's inode and data.
+files.
+If
+.Ar offset
+is given history is shown for data block at given offset,
+otherwise history is shown for inode.
+If
+.Fl v
+is specified
+.Ar length
+data bytes at given offset are dumped for each version,
+default is 32.
+.Pp
+For each
+.Ar path
+this directive shows object id and sync status,
+and for each object version it shows transaction id and time stamp.
+Files has to exist for this directive to be applicable,
+to track inodes which has been deleted or renamed see
+.Xr undo 1 .
.\" ==== blockmap ====
.It Cm blockmap
Dump the blockmap for the file system.
This means the free byte count can legally go negative.
.Pp
This command needs the
-.Fl f
-flag.
+.Fl f Ar blkdevs
+option.
.\" ==== checkmap ====
.It Cm checkmap
Check the blockmap allocation count.
.Nm
will scan the B-Tree, collect allocation information, and
-construct a blockmap in-memory. It will then check that blockmap
-against the on-disk blockmap.
+construct a blockmap in-memory.
+It will then check that blockmap against the on-disk blockmap.
.Pp
This command needs the
-.Fl f
-flag.
+.Fl f Ar blkdevs
+option.
.\" ==== show ====
-.It Cm show Op Ar lo Ns Cm \&: Ns Ar objid
+.It Cm show Op Ar localization Ns Op Cm \&: Ns Ar object_id
Dump the B-Tree.
By default this command will validate all B-Tree
linkages and CRCs, including data CRCs, and will report the most verbose
in column 1 along with various
other error flags.
.Pp
-If you specify a localization field or a localization:obj_id field,
-.Ar lo Ns Cm \&: Ns Ar objid ,
+If you specify
+.Ar localization
+or
+.Ar localization Ns Cm \&: Ns Ar object_id
the dump will
search for the key printing nodes as it recurses down, and then
will iterate forwards.
These fields are specified in HEX.
-Note that the pfsid is the top 16 bits of the 32 bit localization
+Note that the pfsid is the top 16 bits of the 32-bit localization
field so PFS #1 would be 00010000.
.Pp
If you use
B-Tree CRCs and linkages are still checked.
.Pp
This command needs the
-.Fl f
-flag.
+.Fl f Ar blkdevs
+option.
.\" ==== show-undo ====
.It Cm show-undo
.Nm ( HAMMER
VERSION 4+)
-Dump the UNDO map.
+Dump the UNDO/REDO map.
.Pp
This command needs the
-.Fl f
-flag.
+.Fl f Ar blkdevs
+option.
.\" .It Ar blockmap
.\" Dump the B-Tree, record, large-data, and small-data blockmaps, showing
.\" physical block assignments and free space percentages.
.\" ==== recover ====
.It Cm recover Ar targetdir
+Recover data from a corrupted
+.Nm HAMMER
+filesystem.
This is a low level command which operates on the filesystem image and
-attempts to locate and recover files from a corrupted filesystem. The
-entire image is scanned linearly looking for B-Tree nodes. Any node
-found which passes its crc test is scanned for file, inode, and directory
+attempts to locate and recover files from a corrupted filesystem.
+The entire image is scanned linearly looking for B-Tree nodes.
+Any node
+found which passes its CRC test is scanned for file, inode, and directory
fragments and the target directory is populated with the resulting data.
files and directories in the target directory are initially named after
the object id and are renamed as fragmentary information is processed.
.Pp
-This command keeps track of filename/objid translations and may eat a
+This command keeps track of filename/object_id translations and may eat a
considerably amount of memory while operating.
.Pp
This command is literally the last line of defense when it comes to
recovering data from a dead filesystem.
.Pp
This command needs the
-.Fl f
-flag.
+.Fl f Ar blkdevs
+option.
.\" ==== namekey1 ====
.It Cm namekey1 Ar filename
Generate a
.Nm HAMMER
-64 bit directory hash for the specified file name, using
+64-bit directory hash for the specified file name, using
the original directory hash algorithm in version 1 of the file system.
The low 32 bits are used as an iterator for hash collisions and will be
output as 0.
.It Cm namekey2 Ar filename
Generate a
.Nm HAMMER
-64 bit directory hash for the specified file name, using
+64-bit directory hash for the specified file name, using
the new directory hash algorithm in version 2 of the file system.
The low 32 bits are still used as an iterator but will start out containing
part of the hash key.
64 bit directory hash for the specified file name.
.\" ==== info ====
.It Cm info
-Shows extended information about all the mounted
+Show extended information about
.Nm HAMMER
file systems.
The information is divided into sections:
.Cm snapshots
directive has a period of 0 but a non-zero retention time
then this command will not create any new snapshots but will remove old
-snapshots it finds based on the retention time. This form should be
+snapshots it finds based on the retention time.
+This form should be
used on PFS masters where you are generating your own snapshot softlinks
manually and on PFS slaves when all you wish to do is prune away existing
snapshots inherited via the mirroring stream.
.Ql *. Ns Ar yyyymmdd Ns Op - Ns Ar HHMM
will be processed.
.Pp
-A prune max-runtime of 0 means unlimited.
+A period of 0 for prune, rebalance, reblock or recopy disables the directive.
+A max-runtime of 0 means unlimited.
.Pp
If period hasn't passed since the previous
.Cm cleanup
run nothing is done.
For example a day has passed when midnight is passed (localtime).
+If the
+.Fl F
+flag is given the period is ignored.
By default,
.Dx
is set up to run
-.Nm Ar cleanup
+.Nm Cm cleanup
nightly via
.Xr periodic 8 .
.Pp
Reblocking is defragmentation with a level of 95%,
and recopy is full defragmentation.
.Pp
-By default prune and rebalance operations are time limited to 5 minutes,
-dedup and reblock operations to a bit over 5 minutes,
+By default prune, dedup and rebalance operations are time limited to 5 minutes,
+and reblock operations to a bit over 5 minutes,
and recopy operations to a bit over 10 minutes.
Reblocking and recopy runs are each broken down into four separate functions:
btree, inodes, dirs and data.
Zero arguments specifies the PFS containing the current directory.
.\" ==== volume-add ====
.It Cm volume-add Ar device Ar filesystem
-This command will format
+Add volume
+.Ar device
+to
+.Ar filesystem .
+This will format
.Ar device
and add all of its space to
.Ar filesystem .
+A
+.Nm HAMMER
+file system can use up to 256 volumes.
.Pp
.Em NOTE!
All existing data contained on
contains a valid
.Nm HAMMER
file system, formatting will be denied.
-You can overcome this sanity check
-by using
+You can overcome this sanity check by using
.Xr dd 1
to erase the beginning sectors of the device.
-Also remember that you have to specify
+.Pp
+Remember that you have to specify
.Ar device ,
together with any other device that make up the file system,
colon-separated to
.Pa /etc/fstab
and
.Xr mount_hammer 8 .
+If
+.Ar filesystem
+is root file system, also remember to add
+.Ar device
+to
+.Va vfs.root.mountfrom
+in
+.Pa /boot/loader.conf ,
+see
+.Xr loader 8 .
.\" ==== volume-del ====
.It Cm volume-del Ar device Ar filesystem
-This command will remove volume
+Remove volume
.Ar device
from
.Ar filesystem .
.Pa /etc/fstab
and
.Xr mount_hammer 8 .
+If
+.Ar filesystem
+is root file system, also remember to remove
+.Ar device
+from
+.Va vfs.root.mountfrom
+in
+.Pa /boot/loader.conf ,
+see
+.Xr loader 8 .
.\" ==== volume-list ====
.It Cm volume-list Ar filesystem
-This command will list the volumes that make up
+List the volumes that make up
.Ar filesystem .
.\" ==== snapshot ====
.It Cm snapshot Oo Ar filesystem Oc Ar snapshot-dir
.It Cm snapshot Ar filesystem Ar snapshot-dir Op Ar note
-Takes a snapshot of the file system either explicitly given by
+Take a snapshot of the file system either explicitly given by
.Ar filesystem
or implicitly derived from the
.Ar snapshot-dir
If
.Ar snapshot-dir
refers to an existing directory, a default format string of
-.Ql snap-%Y%d%m-%H%M
+.Ql snap-%Y%m%d-%H%M
is assumed and used as name for the newly created symlink.
.Pp
-Snapshot is a per PFS operation, so a
+Snapshot is a per PFS operation, so each PFS in a
.Nm HAMMER
-file system and each PFS in it have to be snapshot separately.
+file system have to be snapshot separately.
.Pp
Example, assuming that
.Pa /mysnapshots
snap and snapshot directives the snapshot transaction id will be registered
in the file system meta-data.
.It Cm snaprm Ar path Ar ...
-.It Cm snaprm Ar transid Ar ...
-.It Cm snaprm Ar filesystem Ar transid Ar ...
+.It Cm snaprm Ar transaction_id Ar ...
+.It Cm snaprm Ar filesystem Ar transaction_id Ar ...
.Nm ( HAMMER
VERSION 3+)
Remove a snapshot given its softlink or transaction id.
.Pp
If a softlink path is specified the filesystem and transaction id
is derived from the contents of the softlink.
-If just a transaction id is specified it is assumed to be a snapshot
-in the HAMMER filesystem you are currently chdir'd into.
+If just a transaction id is specified it is assumed to be a snapshot in the
+.Nm HAMMER
+filesystem you are currently chdir'd into.
You can also specify the filesystem and transaction id explicitly.
.It Cm snapls Op Ar path ...
.Nm ( HAMMER
transaction ids, as might be returned from
.Nm Cm synctid Ar filesystem .
.Pp
-Pruning is a per PFS operation, so a
+Pruning is a per PFS operation, so each PFS in a
.Nm HAMMER
-file system and each PFS in it have to be pruned separately.
+file system have to be pruned separately.
.Pp
Note that pruning a file system may not immediately free-up space,
though typically some space will be freed if a large number of records are
in the file system meta-data and includes them in the prune.
.\" ==== prune-everything ====
.It Cm prune-everything Ar filesystem
-This command will remove all historical records from the file system.
-This directive is not normally used on a production system.
+Remove all historical records from
+.Ar filesystem .
+Use this directive with caution on PFSs where you intend to use history.
.Pp
This command does not remove snapshot softlinks but will delete all
snapshots recorded in file system meta-data (for file system version 3+).
The user is responsible for deleting any softlinks.
.Pp
-Pruning is a per PFS operation, so a
+Pruning is a per PFS operation, so each PFS in a
.Nm HAMMER
-file system and each PFS in it have to be pruned separately.
+file system have to be pruned separately.
.\" ==== rebalance ====
.It Cm rebalance Ar filesystem Op Ar saturation_percentage
-This command will rebalance the B-Tree, nodes with small number of
+Rebalance the B-Tree, nodes with small number of
elements will be combined and element counts will be smoothed out
between nodes.
.Pp
.Sq %
suffix is not needed).
.Pp
-Rebalancing is a per PFS operation, so a
+Rebalancing is a per PFS operation, so each PFS in a
.Nm HAMMER
-file system and each PFS in it have to be rebalanced separately.
+file system have to be rebalanced separately.
.\" ==== dedup ====
.It Cm dedup Ar filesystem
.Nm ( HAMMER
VERSION 5+)
-Perform offline (post-process) deduplication. Deduplication occurs at
+Perform offline (post-process) deduplication.
+Deduplication occurs at
the block level, currently only data blocks of the same size can be
-deduped, metadata blocks can not. The hash function used for comparing
+deduped, metadata blocks can not.
+The hash function used for comparing
data blocks is CRC-32 (CRCs are computed anyways as part of
.Nm HAMMER
-data integrity features, so there's no additional overhead). Since CRC
-is a weak hash function a byte-by-byte comparison is done before actual
-deduping. In case of a CRC collision (two data blocks have the same CRC
+data integrity features, so there's no additional overhead).
+Since CRC is a weak hash function a byte-by-byte comparison is done
+before actual deduping.
+In case of a CRC collision (two data blocks have the same CRC
but different contents) the checksum is upgraded to SHA-256.
.Pp
Currently
operation is to reallocate every record, so it's possible for deduped
blocks to be re-expanded back).
.Pp
-Deduplication is a per PFS operation, so a
+Deduplication is a per PFS operation, so each PFS in a
.Nm HAMMER
-file system and each PFS in it have to be deduped separately. This also
+file system have to be deduped separately.
+This also
means that if you have duplicated data in two different PFSs that data
won't be deduped, however the addition of such feature is planned.
.\" ==== dedup-simulate ====
.It Cm dedup-simulate Ar filesystem
-.Nm ( HAMMER
-VERSION 5+)
Shows potential space savings (simulated dedup ratio) one can get after
running
.Cm dedup
-command. If the estimated dedup ratio is greater than 1.00 you will see
-dedup space savings. Remember that this is an estimated number, in
+command.
+If the estimated dedup ratio is greater than 1.00 you will see
+dedup space savings.
+Remember that this is an estimated number, in
practice real dedup ratio will be slightly smaller because of
.Nm HAMMER
bigblock underflows, B-Tree locking issues and other factors.
elements needing defragmentation.
Data can be defragmented over a longer period of time.
.Pp
-Reblocking is a per PFS operation, so a
+Reblocking is a per PFS operation, so each PFS in a
.Nm HAMMER
-file system and each PFS in it have to be reblocked separately.
+file system have to be reblocked separately.
.\" ==== pfs-status ====
.It Cm pfs-status Ar dirpath ...
Retrieve the mirroring configuration parameters for the specified
Create a pseudo-filesystem (PFS) inside a
.Nm HAMMER
file system.
-Up to 65535 such file systems can be created.
+Up to 65536 PFSs can be created.
Each PFS uses an independent inode numbering space making it suitable
-for use as a replication source or target.
+for replication.
.Pp
The
.Cm pfs-master
directive creates a PFS that you can read, write, and use as a mirroring
source.
.Pp
+A PFS can only be truly destroyed with the
+.Cm pfs-destroy
+directive.
+Removing the softlink will not destroy the underlying PFS.
+.Pp
+A PFS can only be created in the root PFS (PFS# 0),
+not in a PFS created by
+.Cm pfs-master
+or
+.Cm pfs-slave
+(PFS# >0).
+.Pp
+It is recommended that
+.Ar dirpath
+is of the form
+.Pa <fs>/pfs/<name>
+(i.e.\& located in
+.Pa pfs
+directory at root of
+.Nm HAMMER
+file system).
+.Pp
It is recommended to use a
.Nm null
-mount to access a PFS, for more information see
+mount to access a PFS, except for root PFS, for more information see
.Xr HAMMER 5 .
.\" ==== pfs-slave ====
.It Cm pfs-slave Ar dirpath Op Ar options
Create a pseudo-filesystem (PFS) inside a
.Nm HAMMER
file system.
-Up to 65535 such file systems can be created.
+Up to 65536 PFSs can be created.
Each PFS uses an independent inode numbering space making it suitable
-for use as a replication source or target.
+for replication.
.Pp
The
.Cm pfs-slave
-directive creates a PFS that you can use as a mirroring target.
+directive creates a PFS that you can use as a mirroring source or target.
You will not be able to access a slave PFS until you have completed the
first mirroring operation with it as the target (its root directory will
not exist until then).
directive.
Removing the softlink will not destroy the underlying PFS.
.Pp
+A PFS can only be created in the root PFS (PFS# 0),
+not in a PFS created by
+.Cm pfs-master
+or
+.Cm pfs-slave
+(PFS# >0).
+.Pp
+It is recommended that
+.Ar dirpath
+is of the form
+.Pa <fs>/pfs/<name>
+(i.e.\& located in
+.Pa pfs
+directory at root of
+.Nm HAMMER
+file system).
+.Pp
It is recommended to use a
.Nm null
-mount to access a PFS, for more information see
+mount to access a PFS, except for root PFS, for more information see
.Xr HAMMER 5 .
.\" ==== pfs-update ====
.It Cm pfs-update Ar dirpath Op Ar options
You can extend the retention period further by specifying a non-zero
pruning minimum.
Any snapshot softlinks within the retention period are ignored
-for the purposes of pruning (the fine grained history is retained).
+for the purposes of pruning (i.e.\& the fine grained history is retained).
Number of days, hours, minutes and seconds are given as
.Ar N , hh , mm
and
.Pp
This directive will refuse to run if any programs have open descriptors
in the PFS, including programs chdir'd into the PFS.
+As safety measure the
+.Fl y
+flag have no effect on this directive.
.\" ==== mirror-read ====
.It Cm mirror-read Ar filesystem Op Ar begin-tid
Generate a mirroring stream to stdout.
The stream ends when the transaction id space has been exhausted.
+.Ar filesystem
+may be a master or slave PFS.
.\" ==== mirror-read-stream ====
.It Cm mirror-read-stream Ar filesystem Op Ar begin-tid
Generate a mirroring stream to stdout.
.\" ==== mirror-write ====
.It Cm mirror-write Ar filesystem
Take a mirroring stream on stdin.
+.Ar filesystem
+must be a slave PFS.
.Pp
This command will fail if the
.Cm shared-uuid
.Pp
This command also detects the initial-mirroring case and spends some
time scanning the B-Tree to find good break points, allowing the initial
-bulk mirroring operation to be broken down into 100MB pieces.
+bulk mirroring operation to be broken down into 4GB pieces.
This means that the user can kill and restart the operation and it will
not have to start from scratch once it has gotten past the first chunk.
The
option may be used to remove the summary at the end.
.\" ==== version-upgrade ====
.It Cm version-upgrade Ar filesystem Ar version Op Cm force
-This command upgrades the
+Upgrade the
.Nm HAMMER
.Ar filesystem
to the specified
.Ar version .
Once upgraded a file system may not be downgraded.
If you wish to upgrade a file system to a version greater or equal to the
-work-in-progress version number you must specify the
+work-in-progress (WIP) version number you must specify the
.Cm force
directive.
Use of WIP versions should be relegated to testing and may require wiping
.It 4
.Dx 2.6
default version.
-New undo/redo/flush, giving HAMMER a much faster sync and fsync.
+New undo/redo/flush, giving
+.Nm HAMMER
+a much faster sync and fsync.
.It 5
.Dx 2.9 .
-Offline deduplication support.
+Deduplication support.
+.It 6
+.Dx 2.9 .
+Directory hash ALG1.
+Tends to maintain inode number / directory name entry ordering better
+for files after minor renaming.
.El
.El
.Sh PSEUDO-FILESYSTEM (PFS) NOTES
blown away when operating on large numbers of files even if the system has
sufficient memory to hold the file data.
.Pp
-If you turn on hammer's double buffer mode by setting
+If you turn on
+.Nm HAMMER Ns 's
+double buffer mode by setting the
+.Xr sysctl 8
+node
.Va vfs.hammer.double_buffer
to 1
.Nm HAMMER
.Va vm.swapcache.data_enable
is turned on in order to prevent unnecessary re-caching of file data
due to vnode recycling.
-The swapcache will save the cached VM pages related to hammer's block
+The swapcache will save the cached VM pages related to
+.Nm HAMMER Ns 's
+block
device (which doesn't recycle unless you umount the filesystem) instead
of the cached VM pages backing the file vnodes.
.Pp
.Sh UPGRADE INSTRUCTIONS HAMMER V3 TO V4
This upgrade changes undo/flush, giving faster sync.
It is possible to upgrade a V3 file system to V4 in place.
-This upgrade reformats the UNDO FIFO (typically 1GB), so upgrade might take
-a minute or two depending.
+This upgrade reformats the UNDO/REDO FIFO (typically 1GB),
+so upgrade might take a minute or two depending.
.Pp
-Version 4 allows the UNDO FIFO to be flushed without also having
+Version 4 allows the UNDO/REDO FIFO to be flushed without also having
to flush the volume header, removing 2 of the 4 disk syncs typically
required for an
.Fn fsync
and removing 1 of the 2 disk syncs typically
required for a flush sequence.
-Version 4 also implements the REDO log (see below) which is capable
+Version 4 also implements the REDO log (see
+.Sx FSYNC FLUSH MODES
+below) which is capable
of fsync()ing with either one disk flush or zero disk flushes.
.Sh UPGRADE INSTRUCTIONS HAMMER V4 TO V5
-This upgrade brings in offline deduplication support. It is possible to
-upgrade a V4 file system to V5 in place. Technically it makes the
-layer2
-.Fa bytes_free
-field a signed value instead of unsigned, allowing it
-to go negative. A version 5 filesystem is required for dedup operation.
+This upgrade brings in deduplication support.
+It is possible to upgrade a V4 file system to V5 in place.
+Technically it makes the layer2
+.Va bytes_free
+field a signed value instead of unsigned, allowing it to go negative.
+A version 5 filesystem is required for dedup operation.
+.Sh UPGRADE INSTRUCTIONS HAMMER V5 TO V6
+It is possible to upgrade a V5 file system to V6 in place.
.Sh FSYNC FLUSH MODES
.Nm HAMMER
implements five different fsync flush modes via the
.Pp
.It mode 2
Full synchronous fsync semantics using REDO.
-NOTE: If not running
-a HAMMER version 4 filesystem or later mode 0 is silently used.
+NOTE: If not running a
+.Nm HAMMER
+version 4 filesystem or later mode 0 is silently used.
.Pp
.Nm HAMMER
will generate REDOs in the UNDO/REDO FIFO based on a heuristic.
If this is sufficient to satisfy the
.Fn fsync
-operation the blocks
-will be written out and
+operation the blocks will be written out and
.Nm HAMMER
will wait for the I/Os to complete,
and then followup with a disk sync command to guarantee the data
.Pp
.It mode 3
Relaxed asynchronous fsync semantics using REDO.
-NOTE: If not running
-a HAMMER version 4 filesystem or later mode 1 is silently used.
+NOTE: If not running a
+.Nm HAMMER
+version 4 filesystem or later mode 1 is silently used.
.Pp
.Nm HAMMER
will generate REDOs in the UNDO/REDO FIFO based on a heuristic.
.Nm cpdup
.Fl VV
.Fl v
-when doing the copyback. Also make sure you traverse the snapshot softlink
-by appending a ".", as in "<snapshotpath>/.", and you match up the directory
-properly.
+when doing the copyback.
+Also make sure you traverse the snapshot softlink by appending a ".",
+as in "<snapshotpath>/.", and you match up the directory properly.
+.Sh RESTORING A PFS FROM A MIRROR
+A PFS can be restored from a mirror with
+.Cm mirror-copy .
+.Cm config
+data must be copied separately.
+At last the PFS can be upgraded to master using
+.Cm pfs-upgrade .
+.Pp
+It is not possible to restore the root PFS (PFS# 0) by using mirroring,
+as the root PFS is always a master PFS.
+A normal copy (e.g.\& using
+.Xr cpdup 1 )
+must be done, ignoring history.
+If history is important, old root PFS can me restored to a new PFS, and
+important directories/files can be
+.Nm null
+mounted to the new PFS.
.Sh EXIT STATUS
.Ex -std
.Sh ENVIRONMENT
recommended slave PFS snapshots directory
.Nm ( HAMMER
VERSION 2-)
+.It Pa <fs>/pfs
+recommended PFS directory
.El
.\".Sh EXAMPLES
.Sh SEE ALSO
.Xr undo 1 ,
.Xr HAMMER 5 ,
.Xr periodic.conf 5 ,
+.Xr loader 8 ,
.Xr mount_hammer 8 ,
.Xr mount_null 8 ,
-.Xr newfs_hammer 8
+.Xr newfs_hammer 8 ,
+.Xr swapcache 8 ,
+.Xr sysctl 8
.Sh HISTORY
The
.Nm
projects / dragonfly.git / commitdiff