Add a incomplete hammer(5) manual page.
authorSascha Wildner <swildner@dragonflybsd.org>
Wed, 16 Jul 2008 12:45:13 +0000 (12:45 +0000)
committerSascha Wildner <swildner@dragonflybsd.org>
Wed, 16 Jul 2008 12:45:13 +0000 (12:45 +0000)
It's intention is to give an introduction to the hammer file system
features along with examples, a la vkernel(7).

share/man/man5/Makefile
share/man/man5/hammer.5 [new file with mode: 0644]

index 36473ce..670bb8f 100644 (file)
@@ -1,6 +1,6 @@
 #      @(#)Makefile    8.1 (Berkeley) 6/5/93
 #      $FreeBSD: src/share/man/man5/Makefile,v 1.27.2.12 2003/05/23 22:20:24 dwhite Exp $
-#      $DragonFly: src/share/man/man5/Makefile,v 1.16 2008/07/14 23:59:34 swildner Exp $
+#      $DragonFly: src/share/man/man5/Makefile,v 1.17 2008/07/16 12:45:13 swildner Exp $
 
 #MISSING: dump.5 plot.5
 MAN=   acct.5 \
@@ -22,6 +22,7 @@ MAN=  acct.5 \
        gb18030.5 \
        gbk.5 \
        group.5 \
+       hammer.5 \
        host.conf.5 \
        hosts.5 \
        hosts.equiv.5 \
@@ -58,6 +59,7 @@ MAN=  acct.5 \
 
 MLINKS=        dir.5 dirent.5
 MLINKS+=fs.5 inode.5
+MLINKS+=hammer.5 HAMMER.5
 MLINKS+=hosts.equiv.5 rhosts.5
 MLINKS+=passwd.5 master.passwd.5
 MLINKS+=resolver.5 resolv.conf.5
diff --git a/share/man/man5/hammer.5 b/share/man/man5/hammer.5
new file mode 100644 (file)
index 0000000..88ccf6c
--- /dev/null
@@ -0,0 +1,137 @@
+.\"
+.\" Copyright (c) 2008
+.\"    The DragonFly Project.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\" 3. Neither the name of The DragonFly Project nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific, prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
+.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
+.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $DragonFly: src/share/man/man5/hammer.5,v 1.1 2008/07/16 12:45:13 swildner Exp $
+.\"
+.Dd July 16, 2008
+.Os
+.Dt HAMMER 5
+.Sh NAME
+.Nm HAMMER
+.Nd HAMMER file system
+.Sh SYNOPSIS
+.Cd options HAMMER
+.Pp
+In
+.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
+.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
+.Dx .
+Among its features are fine grained history retention, file systems spanning
+multiple volumes, mirroring capability, and pseudo file systems.
+.Pp
+.Nm
+file systems are constructed with
+.Xr newfs_hammer 8
+and mounted with
+.Xr mount_hammer 8 .
+All other functions related to managing a
+.Nm
+file system are provided by the
+.Xr hammer 8
+and
+.Xr undo 1
+utilities.
+.Pp
+.Em NOTE:
+It is recommended that a nightly
+.Xr cron 8
+job be set up to reblock each
+.Nm
+file system over a longer period of time (using the
+.Fl c
+and
+.Fl t
+options of the
+.Xr hammer 8
+utility), for example up to 5 minutes every night.
+.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 .
+.Ss History & Pruning
+History metadata on the media is updated with every sync operation.
+Prior versions of files or directories are accessible by appending
+.Li @@
+and a transaction ID to the name.
+Pruning 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
+.\".Sh EXAMPLES
+.Sh SEE ALSO
+.Xr undo 1 ,
+.Xr hammer 8 ,
+.Xr mount_hammer 8 ,
+.Xr newfs_hammer 8
+.Rs
+.%A Matthew Dillon
+.%D June 2008
+.%T "The HAMMER Filesystem"
+.Re
+.Sh HISTORY
+The
+.Nm
+file system first appeared in
+.Dx 1.11 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+file system was designed and implemented by
+.An Matthew Dillon Aq dillon@backplane.com .
+This manual page was written by
+.An Sascha Wildner .