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.9 2008/08/21 23:38:03 thomas Exp $
  33 .\"
  34 .Dd July 24, 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 disk devices
  64 and is intended to replace UFS as the default file system for
  65 .Dx .
  66 Among its features are instant crash recovery,
  67 large file systems spanning multiple volumes,
  68 fine grained history retention,
  69 mirroring capability, and pseudo file systems.
  70 For a more detailed introduction refer to the paper listed in the
  71 .Sx SEE ALSO
  72 section.
  73 For some common usages of
  74 .Nm
  75 see the
  76 .Sx EXAMPLES
  77 section below.
  78 .Pp
  79 All functions related to managing
  80 .Nm
  81 file systems are provided by the
  82 .Xr newfs_hammer 8 ,
  83 .Xr mount_hammer 8 ,
  84 .Xr hammer 8 ,
  85 and
  86 .Xr undo 1
  87 utilities.
  88 .Ss Instant Crash Recovery
  89 After a non-graceful system shutdown,
  90 .Nm
  91 file systems will be brought back into a fully coherent state
  92 when mounting the file system, usually within a few seconds.
  93 .Ss Large File Systems & Multi Volume
  94 A
  95 .Nm
  96 file system can span up to 256 volumes.
  97 Each volume occupies a
  98 .Dx
  99 disk slice or partition, or another special file,
 100 and can be up to 4096 TB in size.
 101 For volumes over 2 TB in size
 102 .Xr gpt 8
 103 and
 104 .Xr disklabel64 8
 105 normally need to be used.
 106 .Ss Transaction IDs
 107 The
 108 .Nm
 109 file system uses 64 bit, hexadecimal transaction IDs to refer to historical
 110 file or directory data.
 111 An ID has the format
 112 .Li 0x%016llx ,
 113 such as
 114 .Li 0x00000001061a8ba6 .
 115 .Pp
 116 Related
 117 .Xr hammer 8
 118 commands:
 119 .Ar synctid
 120 .Ss History & Snapshots
 121 History metadata on the media is written with every sync operation, so that
 122 by default the resolution of a file's history is 30-60 seconds until the next
 123 prune operation.
 124 Prior versions of files or directories are generally accessible by appending
 125 .Li @@
 126 and a transaction ID to the name.
 127 The common way of accessing history, however, is by taking snapshots.
 128 .Pp
 129 Snapshots are softlinks to prior versions of directories and their files.
 130 Their data will be retained across prune operations for as long as the
 131 softlink exists.
 132 Removing the softlink enables the file system to reclaim the space
 133 again upon the next prune & reblock operations.
 134 .Pp
 135 Related
 136 .Xr hammer 8
 137 commands:
 138 .Ar history ,
 139 .Ar snapshot ;
 140 see also
 141 .Xr undo 1
 142 .Ss Pruning & Reblocking
 143 Pruning is the act of deleting file system history.
 144 Only history used by the given snapshots and history from after the latest
 145 snapshot will be retained.
 146 All other history is deleted.
 147 Reblocking will reorder all elements and thus defragment the file system and
 148 free space for reuse.
 149 After pruning a file system must be reblocked to recover all available space.
 150 .Pp
 151 Related
 152 .Xr hammer 8
 153 commands:
 154 .Ar reblock ,
 155 .Ar reblock-btree ,
 156 .Ar reblock-inodes ,
 157 .Ar reblock-dirs ,
 158 .Ar reblock-data ,
 159 .Ar prune ,
 160 .Ar prune-everything
 161 .Ss Mirroring & Pseudo File Systems
 162 In order to allow inode numbers to be duplicated on the slaves
 163 .Nm Ap s
 164 mirroring feature uses
 165 .Dq Pseudo File Systems
 166 (PFSs).
 167 A
 168 .Nm
 169 file system supports up to 65535 PFSs.
 170 Multiple slaves per master are supported, but multiple masters per slave
 171 are not.
 172 Slaves are always read-only.
 173 Upgrading slaves to masters and downgrading masters to slaves are supported.
 174 .Pp
 175 Related
 176 .Xr hammer 8
 177 commands:
 178 .Ar pfs-master ,
 179 .Ar pfs-slave ,
 180 .Ar pfs-status ,
 181 .Ar pfs-update ,
 182 .Ar pfs-destroy ,
 183 .Ar pfs-upgrade ,
 184 .Ar pfs-downgrade ,
 185 .Ar mirror-copy ,
 186 .Ar mirror-stream ,
 187 .Ar mirror-read ,
 188 .Ar mirror-read-stream ,
 189 .Ar mirror-write ,
 190 .Ar mirror-dump
 191 .Sh EXAMPLES
 192 .Ss Preparing the File System
 193 To create and mount a
 194 .Nm
 195 file system use the
 196 .Xr newfs_hammer 8
 197 and
 198 .Xr mount_hammer 8
 199 commands.
 200 Note that all
 201 .Nm
 202 file systems must have a unique name on a per-machine basis.
 203 .Bd -literal
 204 newfs_hammer -L Home /dev/ad0s1d
 205 mount_hammer /dev/ad0s1d /home
 206 .Ed
 207 .Pp
 208 Similarly, multi volume file systems can be created and mounted by
 209 specifying additional arguments.
 210 .Bd -literal
 211 newfs_hammer -L MultiHome /dev/ad0s1d /dev/ad1s1d
 212 mount_hammer /dev/ad0s1d /dev/ad1s1d /home
 213 .Ed
 214 .Pp
 215 Once created and mounted,
 216 .Nm
 217 file systems need to be reblocked periodically in order not to fill up
 218 over time, either manually or with a
 219 .Xr cron 8
 220 job.
 221 It is recommended that the
 222 .Xr hammer 8
 223 utility's
 224 .Fl c
 225 and
 226 .Fl t
 227 options be used for this job;
 228 for example, to reblock the
 229 .Pa /home
 230 file system every night at 2:15 for up to 5 minutes:
 231 .Bd -literal
 232 15 2 * * * hammer -c /var/run/Home -t 300 reblock /home >/dev/null 2>&1
 233 .Ed
 234 .Ss Snapshots
 235 The
 236 .Xr hammer 8
 237 utility's
 238 .Ar snapshot
 239 command provides several ways of taking snapshots.
 240 They all assume a directory where snapshots are kept.
 241 .Bd -literal
 242 mkdir /snaps
 243 hammer snapshot /home /snaps/snap1
 244 (...after some changes in /home...)
 245 hammer snapshot /home /snaps/snap2
 246 .Ed
 247 .Pp
 248 The softlinks in
 249 .Pa /snaps
 250 point to the state of the
 251 .Pa /home
 252 directory at the time each snapshot was taken, and could now be used to copy
 253 the data somewhere else for backup purposes.
 254 .Ss Pruning
 255 A snapshot directory is also the argument to the
 256 .Xr hammer 8 Ap s
 257 .Ar prune
 258 command which frees historical data from the file system that is not
 259 pointed to by any snapshot link and is not from after the latest snapshot.
 260 .Bd -literal
 261 rm /snaps/snap1
 262 hammer prune /snaps
 263 .Ed
 264 .Pp
 265 Unless the file system is mounted with the
 266 .Ar nohistory
 267 option, it might be advisable to also set up
 268 .Xr cron 8
 269 jobs for pruning no longer used historical data regularly.
 270 .Ss Mirroring
 271 Mirroring can be set up using
 272 .Nm Ap s
 273 pseudo file systems.
 274 To associate the slave with the master its shared UUID should be set to
 275 the master's shared UUID as output by the
 276 .Nm hammer Ar pfs-master
 277 command.
 278 .Bd -literal
 279 hammer pfs-master /home/master
 280 hammer pfs-slave /home/slave shared-uuid=<master's shared uuid>
 281 .Ed
 282 .Pp
 283 The
 284 .Pa /home/slave
 285 link is unusable for as long as no mirroring operation has taken place.
 286 .Pp
 287 To mirror the master's data, either pipe a
 288 .Fa mirror-read
 289 command into a
 290 .Fa mirror-write
 291 or, as a short-cut, use the
 292 .Fa mirror-copy
 293 command (which works across a
 294 .Xr ssh 1
 295 connection as well).
 296 .Bd -literal
 297 hammer mirror-copy /home/master /home/slave
 298 .Ed
 299 .Sh SEE ALSO
 300 .Xr undo 1 ,
 301 .Xr disklabel64 8 ,
 302 .Xr gpt 8 ,
 303 .Xr hammer 8 ,
 304 .Xr mount_hammer 8 ,
 305 .Xr newfs_hammer 8
 306 .Rs
 307 .%A Matthew Dillon
 308 .%D June 2008
 309 .%T "The HAMMER Filesystem"
 310 .Re
 311 .Sh HISTORY
 312 The
 313 .Nm
 314 file system first appeared in
 315 .Dx 1.11 .
 316 .Sh AUTHORS
 317 .An -nosplit
 318 The
 319 .Nm
 320 file system was designed and implemented by
 321 .An Matthew Dillon Aq dillon@backplane.com .
 322 This manual page was written by
 323 .An Sascha Wildner .