DragonFly On-Line Manual Pages
HAMMER(5) DragonFly File Formats Manual HAMMER(5)
NAME
HAMMER -- HAMMER file system
SYNOPSIS
To compile this driver into the kernel, place the following line in your
kernel configuration file:
options HAMMER
Alternatively, to load the driver as a module at boot time, place the
following line in loader.conf(5):
hammer_load="YES"
To mount via fstab(5):
/dev/ad0s1d[:/dev/ad1s1d:...] /mnt hammer rw 2 0
DESCRIPTION
The HAMMER file system provides facilities to store file system data onto
disk devices and is intended to replace ffs(5) as the default file system
for DragonFly. Among its features are instant crash recovery, large file
systems spanning multiple volumes, data integrity checking, fine grained
history retention, mirroring capability, and pseudo file systems.
All functions related to managing HAMMER file systems are provided by the
newfs_hammer(8), mount_hammer(8), hammer(8), chflags(1), and undo(1)
utilities.
For a more detailed introduction refer to the paper and slides listed in
the SEE ALSO section. For some common usages of HAMMER see the EXAMPLES
section below.
Instant Crash Recovery
After a non-graceful system shutdown, HAMMER file systems will be brought
back into a fully coherent state when mounting the file system, usually
within a few seconds.
Large File Systems & Multi Volume
A HAMMER file system can be up to 1 Exabyte in size. It can span up to
256 volumes, each volume occupies a DragonFly disk slice or partition, or
another special file, and can be up to 4096 TB in size. Minimum recom-
mended HAMMER file system size is 50 GB. For volumes over 2 TB in size
gpt(8) and disklabel64(8) normally need to be used.
Data Integrity Checking
HAMMER has high focus on data integrity, CRC checks are made for all
major structures and data. HAMMER snapshots implements features to make
data integrity checking easier: The atime and mtime fields are locked to
the ctime for files accessed via a snapshot. The st_dev field is based
on the PFS shared-uuid and not on any real device. This means that ar-
chiving the contents of a snapshot with e.g. tar(1) and piping it to
something like md5(1) will yield a consistent result. The consistency is
also retained on mirroring targets.
Transaction IDs
The HAMMER file system uses 64 bit, hexadecimal transaction IDs to refer
to historical file or directory data. An ID has the printf(3) format
%#016llx, such as 0x00000001061a8ba6.
Related hammer(8) commands: snapshot, synctid
History & Snapshots
History metadata on the media is written with every sync operation, so
that by default the resolution of a file's history is 30-60 seconds until
the next prune operation. Prior versions of files or directories are
generally accessible by appending @@ and a transaction ID to the name.
The common way of accessing history, however, is by taking snapshots.
Snapshots are softlinks to prior versions of directories and their files.
Their data will be retained across prune operations for as long as the
softlink exists. Removing the softlink enables the file system to
reclaim the space again upon the next prune & reblock operations.
Related hammer(8) commands: cleanup, history, snapshot; see also undo(1)
Pruning & Reblocking
Pruning is the act of deleting file system history. By default only his-
tory used by the given snapshots and history from after the latest snap-
shot will be retained. By setting the per PFS parameter prune-min, his-
tory is guaranteed to be saved at least this time interval. All other
history is deleted. Reblocking will reorder all elements and thus
defragment the file system and free space for reuse. After pruning a
file system must be reblocked to recover all available space. Reblocking
is needed even when using the nohistory mount_hammer(8) option or
chflags(1) flag.
Related hammer(8) commands: cleanup, snapshot, prune, prune-everything,
rebalance, reblock, reblock-btree, reblock-inodes, reblock-dirs,
reblock-data
Mirroring & Pseudo File Systems
In order to allow inode numbers to be duplicated on the slaves HAMMER's
mirroring feature uses ``Pseudo File Systems'' (PFSs). A HAMMER file
system supports up to 65535 PFSs. Multiple slaves per master are sup-
ported, but multiple masters per slave are not. Slaves are always read-
only. Upgrading slaves to masters and downgrading masters to slaves are
supported.
It is recommended to use a null mount to access a PFS; this way no tools
are confused by the PFS root being a symlink and inodes not being unique
across a HAMMER file system.
Related hammer(8) commands: pfs-master, pfs-slave, pfs-cleanup,
pfs-status, pfs-update, pfs-destroy, pfs-upgrade, pfs-downgrade,
mirror-copy, mirror-stream, mirror-read, mirror-read-stream,
mirror-write, mirror-dump
NFS Export
HAMMER file systems support NFS export. NFS export of PFSs is done using
null mounts. For example, to export the PFS /hammer/pfs/data, create a
null mount, e.g. to /hammer/data and export the latter path.
Don't export a directory containing a PFS (e.g. /hammer/pfs above). Only
null mount for PFS root (e.g. /hammer/data above) should be exported
(subdirectory may be escaped if exported).
EXAMPLES
Preparing the File System
To create and mount a HAMMER file system use the newfs_hammer(8) and
mount_hammer(8) commands. Note that all HAMMER file systems must have a
unique name on a per-machine basis.
newfs_hammer -L HOME /dev/ad0s1d
mount_hammer /dev/ad0s1d /home
Similarly, multi volume file systems can be created and mounted by speci-
fying additional arguments.
newfs_hammer -L MULTIHOME /dev/ad0s1d /dev/ad1s1d
mount_hammer /dev/ad0s1d /dev/ad1s1d /home
Once created and mounted, HAMMER file systems need periodic clean up mak-
ing snapshots, pruning and reblocking, in order to have access to history
and file system not to fill up. For this it is recommended to use the
hammer(8) cleanup metacommand.
By default, DragonFly is set up to run hammer cleanup nightly via
periodic(8).
It is also possible to perform these operations individually via
crontab(5). For example, to reblock the /home file system every night at
2:15 for up to 5 minutes:
15 2 * * * hammer -c /var/run/HOME.reblock -t 300 reblock /home \
>/dev/null 2>&1
Snapshots
The hammer(8) utility's snapshot command provides several ways of taking
snapshots. They all assume a directory where snapshots are kept.
mkdir /snaps
hammer snapshot /home /snaps/snap1
(...after some changes in /home...)
hammer snapshot /home /snaps/snap2
The softlinks in /snaps point to the state of the /home directory at the
time each snapshot was taken, and could now be used to copy the data
somewhere else for backup purposes.
By default, DragonFly is set up to create nightly snapshots of all HAMMER
file systems via periodic(8) and to keep them for 60 days.
Pruning
A snapshot directory is also the argument to the hammer(8)'s prune com-
mand which frees historical data from the file system that is not pointed
to by any snapshot link and is not from after the latest snapshot.
rm /snaps/snap1
hammer prune /snaps
Mirroring
Mirroring can be set up using HAMMER's pseudo file systems. To associate
the slave with the master its shared UUID should be set to the master's
shared UUID as output by the hammer pfs-master command.
hammer pfs-master /home/pfs/master
hammer pfs-slave /home/pfs/slave shared-uuid=<master's shared uuid>
The /home/pfs/slave link is unusable for as long as no mirroring opera-
tion has taken place.
To mirror the master's data, either pipe a mirror-read command into a
mirror-write or, as a short-cut, use the mirror-copy command (which works
across a ssh(1) connection as well). Initial mirroring operation has to
be done to the PFS path (as mount_null(8) can't access it yet).
hammer mirror-copy /home/pfs/master /home/pfs/slave
After this initial step null mount can be setup for /home/pfs/slave.
Further operations can use null mounts.
mount_null /home/pfs/master /home/master
mount_null /home/pfs/slave /home/slave
hammer mirror-copy /home/master /home/slave
NFS Export
To NFS export from the HAMMER file system /hammer the directory
/hammer/non-pfs without PFSs, and the PFS /hammer/pfs/data, the latter is
null mounted to /hammer/data.
Add to /etc/fstab (see fstab(5)):
/hammer/pfs/data /hammer/data null rw
Add to /etc/exports (see exports(5)):
/hammer/non-pfs
/hammer/data
SEE ALSO
chflags(1), md5(1), tar(1), undo(1), exports(5), ffs(5), fstab(5),
disklabel64(8), gpt(8), hammer(8), mount_hammer(8), mount_null(8),
newfs_hammer(8)
Matthew Dillon, The HAMMER Filesystem, June 2008,
http://www.dragonflybsd.org/hammer/hammer.pdf.
Matthew Dillon, Slideshow from NYCBSDCon 2008, October 2008,
http://www.dragonflybsd.org/hammer/nycbsdcon/.
Michael Neumann, Slideshow for a presentation held at KIT
(http://www.kit.edu)., January 2010,
http://www.ntecs.de/sysarch09/HAMMER.pdf.
FILESYSTEM PERFORMANCE
The HAMMER file system has a front-end which processes VNOPS and issues
necessary block reads from disk, and a back-end which handles meta-data
updates on-media and performs all meta-data write operations. Bulk file
write operations are handled by the front-end. Because HAMMER defers
meta-data updates virtually no meta-data read operations will be issued
by the frontend while writing large amounts of data to the file system or
even when creating new files or directories, and even though the kernel
prioritizes reads over writes the fact that writes are cached by the
drive itself tends to lead to excessive priority given to writes.
There are four bioq sysctls, shown below with default values, which can
be adjusted to give reads a higher priority:
kern.bioq_reorder_minor_bytes: 262144
kern.bioq_reorder_burst_bytes: 3000000
kern.bioq_reorder_minor_interval: 5
kern.bioq_reorder_burst_interval: 60
If a higher read priority is desired it is recommended that the
kern.bioq_reorder_minor_interval be increased to 15, 30, or even 60, and
the kern.bioq_reorder_burst_bytes be decreased to 262144 or 524288.
HISTORY
The HAMMER file system first appeared in DragonFly 1.11.
AUTHORS
The HAMMER file system was designed and implemented by Matthew Dillon
<dillon@backplane.com>. This manual page was written by Sascha Wildner.
DragonFly 2.7 April 8, 2010 DragonFly 2.7