Clean up a bit.
[dragonfly.git] / share / man / man5 / hammer.5
index ccf0074..d6e93bf 100644 (file)
@@ -29,9 +29,9 @@
 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $DragonFly: src/share/man/man5/hammer.5,v 1.3 2008/07/17 00:16:14 swildner Exp $
+.\" $DragonFly: src/share/man/man5/hammer.5,v 1.15 2008/11/02 18:56:47 swildner Exp $
 .\"
-.Dd July 16, 2008
+.Dd November 2, 2008
 .Os
 .Dt HAMMER 5
 .Sh NAME
@@ -52,25 +52,24 @@ module at boot time, place the following line in
 hammer_load="YES"
 .Ed
 .Pp
-In
+To mount via
 .Xr fstab 5 :
-.Bd -literal
-# single volume
-#
-/dev/disk0a    /mnt hammer rw 2 0
-
-# multi volume
-#
-/dev/disk0a:/dev/disk1a:/dev/disk2a    /mnt hammer rw 2 0
+.Bd -literal -offset indent
+/dev/ad0s1d[:/dev/ad1s1d:...]  /mnt hammer rw 2 0
 .Ed
 .Sh DESCRIPTION
 The
 .Nm
-file system provides facilities to store file system data onto a disk device
-and is intended to replace UFS as the default file system for
+file system provides facilities to store file system data onto disk devices
+and is intended to replace
+.Xr ffs 5
+as the default file system for
 .Dx .
-Among its features are fine grained history retention, file systems spanning
-multiple volumes, mirroring capability, and pseudo file systems.
+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.
 .Pp
 All functions related to managing
 .Nm
@@ -81,34 +80,180 @@ file systems are provided by the
 and
 .Xr undo 1
 utilities.
+.Pp
+For a more detailed introduction refer to the paper and slides listed in the
+.Sx SEE ALSO
+section.
+For some common usages of
+.Nm
+see the
+.Sx EXAMPLES
+section below.
+.Ss Instant Crash Recovery
+After a non-graceful system shutdown,
+.Nm
+file systems will be brought back into a fully coherent state
+when mounting the file system, usually within a few seconds.
+.Ss Large File Systems & Multi Volume
+A
+.Nm
+file system can span up to 256 volumes.
+Each volume occupies a
+.Dx
+disk slice or partition, or another special file,
+and can be up to 4096 TB in size.
+For volumes over 2 TB in size
+.Xr gpt 8
+and
+.Xr disklabel64 8
+normally need to be used.
+.Ss Data Integrity Checking
+.Nm
+has high focus on data integrity,
+CRC checks are made for all major structures and data.
+.Nm
+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
+.Fa st_dev
+field is based on the PFS
+.Ar shared-uuid
+and not on any real device.
+This means that archiving the contents of a snaphot with e.g.\&
+.Xr tar 1
+and piping it to something like
+.Xr md5 1
+will yield a consistent result.
+The consistency is also retained on mirroring targets.
 .Ss Transaction IDs
 The
 .Nm
 file system uses 64 bit, hexadecimal transaction IDs to refer to historical
 file or directory data.
-An ID has the format
-.Li 0x%016llx ,
+An ID has the
+.Xr printf 3
+format
+.Li %#016llx ,
 such as
 .Li 0x00000001061a8ba6 .
-.Ss History & Pruning
-History metadata on the media is updated with every sync operation.
-Prior versions of files or directories are accessible by appending
+.Pp
+Related
+.Xr hammer 8
+commands:
+.Ar synctid
+.Ss 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
 .Li @@
 and a transaction ID to the name.
-Pruning a
+The common way of accessing history, however, is by taking snapshots.
+.Pp
+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.
+.Pp
+Related
+.Xr hammer 8
+commands:
+.Ar cleanup ,
+.Ar history ,
+.Ar snapshot ;
+see also
+.Xr undo 1
+.Ss Pruning & Reblocking
+Pruning is the act of deleting file system history.
+Only history used by the given snapshots and history from after the latest
+snapshot will be retained.
+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
+.Ar nohistory
+.Xr mount_hammer 8
+option.
+.Pp
+Related
+.Xr hammer 8
+commands:
+.Ar cleanup ,
+.Ar prune ,
+.Ar prune-everything ,
+.Ar reblock ,
+.Ar reblock-btree ,
+.Ar reblock-inodes ,
+.Ar reblock-dirs ,
+.Ar reblock-data
+.Ss Mirroring & Pseudo File Systems
+In order to allow inode numbers to be duplicated on the slaves
+.Nm Ap s
+mirroring feature uses
+.Dq Pseudo File Systems
+(PFSs).
+A
 .Nm
-file system will free all unused historical records.
-.Ss Snapshots
-A snapshot can be taken by creating a symbolic link to a specific
-version of a file or directory.
-Snapshots created this way will be retained across subsequent prune
-operations.
-Removing the symbolic link enables the file system to reclaim the space
-again.
-.\".Ss Mirroring
-.\".Ss Pseudo File Systems
+file system supports up to 65535 PFSs.
+Multiple slaves per master are supported, but multiple masters per slave
+are not.
+Slaves are always read-only.
+Upgrading slaves to masters and downgrading masters to slaves are supported.
+.Pp
+It is recommended to use a
+.Nm 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
+.Nm
+file system.
+.Pp
+Related
+.Xr hammer 8
+commands:
+.Ar pfs-master ,
+.Ar pfs-slave ,
+.Ar pfs-cleanup ,
+.Ar pfs-status ,
+.Ar pfs-update ,
+.Ar pfs-destroy ,
+.Ar pfs-upgrade ,
+.Ar pfs-downgrade ,
+.Ar mirror-copy ,
+.Ar mirror-stream ,
+.Ar mirror-read ,
+.Ar mirror-read-stream ,
+.Ar mirror-write ,
+.Ar mirror-dump
+.Ss NFS Export
+.Nm
+file systems support NFS export.
+NFS export of PFSs is done using
+.Nm null
+mounts.
+For example, to export the PFS
+.Pa /hammer/pfs/data ,
+create a
+.Nm null
+mount, e.g.\& to
+.Pa /hammer/data
+and export the latter path.
+.Pp
+Don't export a directory containing a PFS (e.g.\&
+.Pa /hammer/pfs
+above).
+Only
+.Nm null
+mount for PFS root
+(e.g.\&
+.Pa /hammer/data
+above)
+should be exported
+(subdirectory may be escaped if exported).
 .Sh EXAMPLES
-.Ss Preparing the file system
+.Ss Preparing the File System
 To create and mount a
 .Nm
 file system use the
@@ -119,44 +264,178 @@ commands.
 Note that all
 .Nm
 file systems must have a unique name on a per-machine basis.
-.Bd -literal
-newfs_hammer -L Home /dev/ad0s1d
+.Bd -literal -offset indent
+newfs_hammer -L HOME /dev/ad0s1d
 mount_hammer /dev/ad0s1d /home
 .Ed
 .Pp
-Similarly, multi volume file systems can be created and mounted by just
-specifying more arguments.
-.Bd -literal
-newfs_hammer -L MultiHome /dev/ad0s1d /dev/ad1s1d
+Similarly, multi volume file systems can be created and mounted by
+specifying additional arguments.
+.Bd -literal -offset indent
+newfs_hammer -L MULTIHOME /dev/ad0s1d /dev/ad1s1d
 mount_hammer /dev/ad0s1d /dev/ad1s1d /home
 .Ed
 .Pp
 Once created and mounted,
 .Nm
-file systems need to be reblocked periodically in order not to fill up
-over time, either manually or with a
-.Xr cron 8
-job.
-It is recommended that the
+file systems need periodic clean up making 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
+.Xr hammer 8
+.Ar cleanup
+metacommand.
+.Pp
+By default,
+.Dx
+is set up to run
+.Nm hammer Ar cleanup
+nightly via
+.Xr periodic 8 .
+.Pp
+It is also possible to perform these operations individually via
+.Xr crontab 5 .
+For example, to reblock the
+.Pa /home
+file system every night at 2:15 for up to 5 minutes:
+.Bd -literal -offset indent
+15 2 * * * hammer -c /var/run/HOME.reblock -t 300 reblock /home \e
+       >/dev/null 2>&1
+.Ed
+.Ss Snapshots
+The
 .Xr hammer 8
 utility's
-.Fl c
-and
-.Fl t
-options be used for this job (for example, every night up to 5 minutes).
-.Bd -literal
-2 15 * * * hammer -c /var/run/Home -t 300 reblock /home >/dev/null 2>&1
+.Ar snapshot
+command provides several ways of taking snapshots.
+They all assume a directory where snapshots are kept.
+.Bd -literal -offset indent
+mkdir /snaps
+hammer snapshot /home /snaps/snap1
+(...after some changes in /home...)
+hammer snapshot /home /snaps/snap2
+.Ed
+.Pp
+The softlinks in
+.Pa /snaps
+point to the state of the
+.Pa /home
+directory at the time each snapshot was taken, and could now be used to copy
+the data somewhere else for backup purposes.
+.Pp
+By default,
+.Dx
+is set up to create nightly snapshots of all
+.Nm
+file systems via
+.Xr periodic 8
+and to keep them for 60 days.
+.Ss Pruning
+A snapshot directory is also the argument to the
+.Xr hammer 8 Ap s
+.Ar prune
+command 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.
+.Bd -literal -offset indent
+rm /snaps/snap1
+hammer prune /snaps
+.Ed
+.Ss Mirroring
+Mirroring can be set up using
+.Nm Ap 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
+.Nm hammer Ar pfs-master
+command.
+.Bd -literal -offset indent
+hammer pfs-master /home/pfs/master
+hammer pfs-slave /home/pfs/slave shared-uuid=<master's shared uuid>
+.Ed
+.Pp
+The
+.Pa /home/pfs/slave
+link is unusable for as long as no mirroring operation has taken place.
+.Pp
+To mirror the master's data, either pipe a
+.Fa mirror-read
+command into a
+.Fa mirror-write
+or, as a short-cut, use the
+.Fa mirror-copy
+command (which works across a
+.Xr ssh 1
+connection as well).
+Initial mirroring operation has to be done to the PFS path (as
+.Xr mount_null 8
+can't access it yet).
+.Bd -literal -offset indent
+hammer mirror-copy /home/pfs/master /home/pfs/slave
+.Ed
+.Pp
+After this initial step
+.Nm null
+mount can be setup for
+.Pa /home/pfs/slave .
+Further operations can use
+.Nm null
+mounts.
+.Bd -literal -offset indent
+mount_null /home/pfs/master /home/master
+mount_null /home/pfs/slave /home/slave
+
+hammer mirror-copy /home/master /home/slave
+.Ed
+.Ss NFS Export
+To NFS export from the
+.Nm
+file system
+.Pa /hammer
+the directory
+.Pa /hammer/non-pfs
+without PFSs, and the PFS
+.Pa /hammer/pfs/data ,
+the latter is null mounted to
+.Pa /hammer/data .
+.Pp
+Add to
+.Pa /etc/fstab
+(see
+.Xr fstab 5 ) :
+.Bd -literal -offset indent
+/hammer/pfs/data /hammer/data null rw
+.Ed
+.Pp
+Add to
+.Pa /etc/exports
+(see
+.Xr exports 5 ) :
+.Bd -literal -offset indent
+/hammer/non-pfs
+/hammer/data
 .Ed
 .Sh SEE ALSO
+.Xr md5 1 ,
+.Xr tar 1 ,
 .Xr undo 1 ,
+.Xr ffs 5 ,
+.Xr disklabel64 8 ,
+.Xr gpt 8 ,
 .Xr hammer 8 ,
 .Xr mount_hammer 8 ,
+.Xr mount_null 8 ,
 .Xr newfs_hammer 8
 .Rs
 .%A Matthew Dillon
 .%D June 2008
+.%O http://www.dragonflybsd.org/hammer/hammer.pdf
 .%T "The HAMMER Filesystem"
 .Re
+.Rs
+.%A Matthew Dillon
+.%D October 2008
+.%O http://www.dragonflybsd.org/hammer/nycbsdcon/
+.%T "Slideshow from NYCBSDCon 2008"
+.Re
 .Sh HISTORY
 The
 .Nm