Clean up a bit.
[dragonfly.git] / share / man / man5 / hammer.5
index b5cc76d..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.7 2008/07/21 21:20:52 thomas Exp $
+.\" $DragonFly: src/share/man/man5/hammer.5,v 1.15 2008/11/02 18:56:47 swildner Exp $
 .\"
-.Dd July 18, 2008
+.Dd November 2, 2008
 .Os
 .Dt HAMMER 5
 .Sh NAME
@@ -61,15 +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, see the paper listed in the
-.Sx SEE ALSO
-section.
 .Pp
 All functions related to managing
 .Nm
@@ -80,27 +80,20 @@ file systems are provided by the
 and
 .Xr undo 1
 utilities.
-.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 ,
-such as
-.Li 0x00000001061a8ba6 .
 .Pp
-Related
-.Xr hammer 8
-commands:
-.Ar synctid
+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-gracefull system shutdown,
+After a non-graceful system shutdown,
 .Nm
 file systems will be brought back into a fully coherent state
-within a few seconds, at system startup.
-This is accomplished by mounting the file system,
-no special utility needs to be run.
+when mounting the file system, usually within a few seconds.
 .Ss Large File Systems & Multi Volume
 A
 .Nm
@@ -108,46 +101,93 @@ file system can span up to 256 volumes.
 Each volume occupies a
 .Dx
 disk slice or partition, or another special file,
-it can be up to 4096 TB in size.
-For volumes over 2 TB in size,
+and can be up to 4096 TB in size.
+For volumes over 2 TB in size
 .Xr gpt 8
 and
 .Xr disklabel64 8
-normally needs to be used.
-.Ss History
-History metadata on the media is written with every sync operation.
-Prior versions of files or directories are accessible by appending
+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
+.Xr printf 3
+format
+.Li %#016llx ,
+such as
+.Li 0x00000001061a8ba6 .
+.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.
-.Ss Snapshots
-Snapshots are symbolic links to specific versions of directories or files,
-prior or current.
+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
-symbolic link exists.
-Removing the symbolic link enables the file system to reclaim the space
-again upon the next reblock operation.
+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 snapshot
-.Ss Reblocking & Pruning
+.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.
-Pruning a
-.Nm
-file system free all historical records no longer used by any snapshots.
+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
@@ -156,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
@@ -188,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
@@ -226,28 +308,37 @@ 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...)
 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 no longer
-pointed to by any snapshot link.
-.Bd -literal
+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
-.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
@@ -256,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
@@ -274,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