Clean up a bit.
[dragonfly.git] / share / man / man5 / hammer.5
index a32963d..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.11 2008/09/16 15:26:17 thomas Exp $
+.\" $DragonFly: src/share/man/man5/hammer.5,v 1.15 2008/11/02 18:56:47 swildner Exp $
 .\"
-.Dd September 9, 2008
+.Dd November 2, 2008
 .Os
 .Dt HAMMER 5
 .Sh NAME
@@ -61,20 +61,15 @@ To mount via
 The
 .Nm
 file system provides facilities to store file system data onto disk devices
-and is intended to replace UFS as the default file system for
+and is intended to replace
+.Xr ffs 5
+as the default file system for
 .Dx .
 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.
-For a more detailed introduction refer to the paper listed in the
-.Sx SEE ALSO
-section.
-For some common usages of
-.Nm
-see the
-.Sx EXAMPLES
-section below.
 .Pp
 All functions related to managing
 .Nm
@@ -85,6 +80,15 @@ 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
@@ -103,13 +107,33 @@ For volumes over 2 TB in size
 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 .
 .Pp
@@ -135,6 +159,7 @@ again upon the next prune & reblock operations.
 Related
 .Xr hammer 8
 commands:
+.Ar cleanup ,
 .Ar history ,
 .Ar snapshot ;
 see also
@@ -147,17 +172,22 @@ 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 ,
-.Ar prune ,
-.Ar prune-everything
+.Ar reblock-data
 .Ss Mirroring & Pseudo File Systems
 In order to allow inode numbers to be duplicated on the slaves
 .Nm Ap s
@@ -172,11 +202,20 @@ 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 ,
@@ -188,6 +227,31 @@ commands:
 .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
 To create and mount a
@@ -200,36 +264,42 @@ 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
 specifying additional arguments.
-.Bd -literal
-newfs_hammer -L MultiHome /dev/ad0s1d /dev/ad1s1d
+.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
-utility's
-.Fl c
-and
-.Fl t
-options be used for this job;
-for example, to reblock the
+.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
-15 2 * * * hammer -c /var/run/Home.reblock -t 300 reblock /home >/dev/null 2>&1
+.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
@@ -238,7 +308,7 @@ utility's
 .Ar snapshot
 command provides several ways of taking snapshots.
 They all assume a directory where snapshots are kept.
-.Bd -literal
+.Bd -literal -offset indent
 mkdir /snaps
 hammer snapshot /home /snaps/snap1
 (...after some changes in /home...)
@@ -251,28 +321,24 @@ 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
+.Bd -literal -offset indent
 rm /snaps/snap1
 hammer prune /snaps
 .Ed
-.Pp
-Unless the file system is mounted with the
-.Ar nohistory
-option, it might be advisable to also set up
-.Xr cron 8
-jobs for pruning no longer used historical data regularly.
-For example, to prune the
-.Pa /snaps
-directory every night at 3:15 for up to 5 minutes:
-.Bd -literal
-15 3 * * * hammer -c /var/run/snaps.prune -t 300 prune /snaps >/dev/null 2>&1
-.Ed
 .Ss Mirroring
 Mirroring can be set up using
 .Nm Ap s
@@ -281,13 +347,13 @@ 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
-hammer pfs-master /home/master
-hammer pfs-slave /home/slave shared-uuid=<master's shared uuid>
+.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/slave
+.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
@@ -299,21 +365,77 @@ or, as a short-cut, use the
 command (which works across a
 .Xr ssh 1
 connection as well).
-.Bd -literal
+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
@@ -327,12 +449,3 @@ file system was designed and implemented by
 .An Matthew Dillon Aq dillon@backplane.com .
 This manual page was written by
 .An Sascha Wildner .
-.Sh BUGS
-NFS exporting
-.Nm
-PFSs
-isn't supported yet.
-A
-.Nm
-file system with PFSs defined can be NFS exported,
-but don't export directories which contains PFSs.