share/man/man5/hammer.5

   1 .\"
   2 .\" Copyright (c) 2008
   3 .\"     The DragonFly Project.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\" 3. Neither the name of The DragonFly Project nor the names of its
  16 .\"    contributors may be used to endorse or promote products derived
  17 .\"    from this software without specific, prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $DragonFly: src/share/man/man5/hammer.5,v 1.2.2.1 2008/07/17 10:18:37 swildner Exp $
  33 .\"
  34 .Dd July 16, 2008
  35 .Os
  36 .Dt HAMMER 5
  37 .Sh NAME
  38 .Nm HAMMER
  39 .Nd HAMMER file system
  40 .Sh SYNOPSIS
  41 To compile this driver into the kernel,
  42 place the following line in your
  43 kernel configuration file:
  44 .Bd -ragged -offset indent
  45 .Cd options HAMMER
  46 .Ed
  47 .Pp
  48 Alternatively, to load the driver as a
  49 module at boot time, place the following line in
  50 .Xr loader.conf 5 :
  51 .Bd -literal -offset indent
  52 hammer_load="YES"
  53 .Ed
  54 .Pp
  55 To mount via
  56 .Xr fstab 5 :
  57 .Bd -literal -offset indent
  58 /dev/ad0s1d[:/dev/ad1s1d:...]   /mnt hammer rw 2 0
  59 .Ed
  60 .Sh DESCRIPTION
  61 The
  62 .Nm
  63 file system provides facilities to store file system data onto a disk device
  64 and is intended to replace UFS as the default file system for
  65 .Dx .
  66 Among its features are fine grained history retention, file systems spanning
  67 multiple volumes, mirroring capability, and pseudo file systems.
  68 .Pp
  69 All functions related to managing
  70 .Nm
  71 file systems are provided by the
  72 .Xr newfs_hammer 8 ,
  73 .Xr mount_hammer 8 ,
  74 .Xr hammer 8 ,
  75 and
  76 .Xr undo 1
  77 utilities.
  78 .Ss Transaction IDs
  79 The
  80 .Nm
  81 file system uses 64 bit, hexadecimal transaction IDs to refer to historical
  82 file or directory data.
  83 An ID has the format
  84 .Li 0x%016llx ,
  85 such as
  86 .Li 0x00000001061a8ba6 .
  87 .Ss History & Pruning
  88 History metadata on the media is updated with every sync operation.
  89 Prior versions of files or directories are accessible by appending
  90 .Li @@
  91 and a transaction ID to the name.
  92 Pruning a
  93 .Nm
  94 file system will free all unused historical records.
  95 .Ss Snapshots
  96 A snapshot can be taken by creating a symbolic link to a specific
  97 version of a file or directory.
  98 Snapshots created this way will be retained across subsequent prune
  99 operations.
 100 Removing the symbolic link enables the file system to reclaim the space
 101 again.
 102 .\".Ss Mirroring
 103 .\".Ss Pseudo File Systems
 104 .Sh EXAMPLES
 105 .Ss Preparing the file system
 106 To create and mount a
 107 .Nm
 108 file system use the
 109 .Xr newfs_hammer 8
 110 and
 111 .Xr mount_hammer 8
 112 commands.
 113 Note that all
 114 .Nm
 115 file systems must have a unique name on a per-machine basis.
 116 .Bd -literal
 117 newfs_hammer -L Home /dev/ad0s1d
 118 mount_hammer /dev/ad0s1d /home
 119 .Ed
 120 .Pp
 121 Similarly, multi volume file systems can be created and mounted by
 122 specifying additional arguments.
 123 .Bd -literal
 124 newfs_hammer -L MultiHome /dev/ad0s1d /dev/ad1s1d
 125 mount_hammer /dev/ad0s1d /dev/ad1s1d /home
 126 .Ed
 127 .Pp
 128 Once created and mounted,
 129 .Nm
 130 file systems need to be reblocked periodically in order not to fill up
 131 over time, either manually or with a
 132 .Xr cron 8
 133 job.
 134 It is recommended that the
 135 .Xr hammer 8
 136 utility's
 137 .Fl c
 138 and
 139 .Fl t
 140 options be used for this job (for example, every night at 2:15 up to 5
 141 minutes).
 142 .Bd -literal
 143 15 2 * * * hammer -c /var/run/Home -t 300 reblock /home >/dev/null 2>&1
 144 .Ed
 145 .Sh SEE ALSO
 146 .Xr undo 1 ,
 147 .Xr hammer 8 ,
 148 .Xr mount_hammer 8 ,
 149 .Xr newfs_hammer 8
 150 .Rs
 151 .%A Matthew Dillon
 152 .%D June 2008
 153 .%T "The HAMMER Filesystem"
 154 .Re
 155 .Sh HISTORY
 156 The
 157 .Nm
 158 file system first appeared in
 159 .Dx 1.11 .
 160 .Sh AUTHORS
 161 .An -nosplit
 162 The
 163 .Nm
 164 file system was designed and implemented by
 165 .An Matthew Dillon Aq dillon@backplane.com .
 166 This manual page was written by
 167 .An Sascha Wildner .