Clean up a bit.
[dragonfly.git] / share / man / man5 / hammer.5
index e373629..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.8 2008/07/25 01:21:06 swildner Exp $
+.\" $DragonFly: src/share/man/man5/hammer.5,v 1.15 2008/11/02 18:56:47 swildner Exp $
 .\"
-.Dd July 24, 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,26 +159,35 @@ again upon the next prune & reblock operations.
 Related
 .Xr hammer 8
 commands:
+.Ar cleanup ,
 .Ar history ,
-.Ar snapshot
-.Ss Reblocking & Pruning
-Reblocking will reorder all elements and thus defragment the file system and
-free space for reuse.
+.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 ,
-.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
@@ -163,26 +196,62 @@ mirroring feature uses
 (PFSs).
 A
 .Nm
-file system supports up to 65536 PFSs.
+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
 To create and mount a
@@ -195,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 -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
@@ -233,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...)
@@ -246,22 +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.
 .Ss Mirroring
 Mirroring can be set up using
 .Nm Ap s
@@ -270,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
@@ -288,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