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.3 2008/07/25 03:16:12 swildner 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 .Ss Reblocking & Pruning
 141 Reblocking will reorder all elements and thus defragment the file system and
 142 free space for reuse.
 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 .Pp
 148 Related
 149 .Xr hammer 8
 150 commands:
 151 .Ar reblock ,
 152 .Ar reblock-btree ,
 153 .Ar reblock-inodes ,
 154 .Ar reblock-dirs ,
 155 .Ar reblock-data ,
 156 .Ar prune ,
 157 .Ar prune-everything
 158 .Ss Mirroring & Pseudo File Systems
 159 In order to allow inode numbers to be duplicated on the slaves
 160 .Nm Ap s
 161 mirroring feature uses
 162 .Dq Pseudo File Systems
 163 (PFSs).
 164 A
 165 .Nm
 166 file system supports up to 65536 PFSs.
 167 Multiple slaves per master are supported, but multiple masters per slave
 168 are not.
 169 Slaves are always read-only.
 170 Upgrading slaves to masters and downgrading masters to slaves are supported.
 171 .Pp
 172 Related
 173 .Xr hammer 8
 174 commands:
 175 .Ar pfs-master ,
 176 .Ar pfs-slave ,
 177 .Ar pfs-status ,
 178 .Ar pfs-update ,
 179 .Ar pfs-destroy ,
 180 .Ar pfs-upgrade ,
 181 .Ar pfs-downgrade ,
 182 .Ar mirror-copy ,
 183 .Ar mirror-read ,
 184 .Ar mirror-write ,
 185 .Ar mirror-dump
 186 .Sh EXAMPLES
 187 .Ss Preparing the File System
 188 To create and mount a
 189 .Nm
 190 file system use the
 191 .Xr newfs_hammer 8
 192 and
 193 .Xr mount_hammer 8
 194 commands.
 195 Note that all
 196 .Nm
 197 file systems must have a unique name on a per-machine basis.
 198 .Bd -literal
 199 newfs_hammer -L Home /dev/ad0s1d
 200 mount_hammer /dev/ad0s1d /home
 201 .Ed
 202 .Pp
 203 Similarly, multi volume file systems can be created and mounted by
 204 specifying additional arguments.
 205 .Bd -literal
 206 newfs_hammer -L MultiHome /dev/ad0s1d /dev/ad1s1d
 207 mount_hammer /dev/ad0s1d /dev/ad1s1d /home
 208 .Ed
 209 .Pp
 210 Once created and mounted,
 211 .Nm
 212 file systems need to be reblocked periodically in order not to fill up
 213 over time, either manually or with a
 214 .Xr cron 8
 215 job.
 216 It is recommended that the
 217 .Xr hammer 8
 218 utility's
 219 .Fl c
 220 and
 221 .Fl t
 222 options be used for this job;
 223 for example, to reblock the
 224 .Pa /home
 225 file system every night at 2:15 for up to 5 minutes:
 226 .Bd -literal
 227 15 2 * * * hammer -c /var/run/Home -t 300 reblock /home >/dev/null 2>&1
 228 .Ed
 229 .Ss Snapshots
 230 The
 231 .Xr hammer 8
 232 utility's
 233 .Ar snapshot
 234 command provides several ways of taking snapshots.
 235 They all assume a directory where snapshots are kept.
 236 .Bd -literal
 237 mkdir /snaps
 238 hammer snapshot /home /snaps/snap1
 239 (...after some changes in /home...)
 240 hammer snapshot /home /snaps/snap2
 241 .Ed
 242 .Pp
 243 The softlinks in
 244 .Pa /snaps
 245 point to the state of the
 246 .Pa /home
 247 directory at the time each snapshot was taken, and could now be used to copy
 248 the data somewhere else for backup purposes.
 249 .Ss Pruning
 250 A snapshot directory is also the argument to the
 251 .Xr hammer 8 Ap s
 252 .Ar prune
 253 command which frees historical data from the file system that is not
 254 pointed to by any snapshot link and is not from after the latest snapshot.
 255 .Bd -literal
 256 rm /snaps/snap1
 257 hammer prune /snaps
 258 .Ed
 259 .Pp
 260 Unless the file system is mounted with the
 261 .Ar nohistory
 262 option, it might be advisable to also set up
 263 .Xr cron 8
 264 jobs for pruning no longer used historical data regularly.
 265 .Ss Mirroring
 266 Mirroring can be set up using
 267 .Nm Ap s
 268 pseudo file systems.
 269 To associate the slave with the master its shared UUID should be set to
 270 the master's shared UUID as output by the
 271 .Nm hammer Ar pfs-master
 272 command.
 273 .Bd -literal
 274 hammer pfs-master /home/master
 275 hammer pfs-slave /home/slave shared-uuid=<master's shared uuid>
 276 .Ed
 277 .Pp
 278 The
 279 .Pa /home/slave
 280 link is unusable for as long as no mirroring operation has taken place.
 281 .Pp
 282 To mirror the master's data, either pipe a
 283 .Fa mirror-read
 284 command into a
 285 .Fa mirror-write
 286 or, as a short-cut, use the
 287 .Fa mirror-copy
 288 command (which works across a
 289 .Xr ssh 1
 290 connection as well).
 291 .Bd -literal
 292 hammer mirror-copy /home/master /home/slave
 293 .Ed
 294 .Sh SEE ALSO
 295 .Xr undo 1 ,
 296 .Xr disklabel64 8 ,
 297 .Xr gpt 8 ,
 298 .Xr hammer 8 ,
 299 .Xr mount_hammer 8 ,
 300 .Xr newfs_hammer 8
 301 .Rs
 302 .%A Matthew Dillon
 303 .%D June 2008
 304 .%T "The HAMMER Filesystem"
 305 .Re
 306 .Sh HISTORY
 307 The
 308 .Nm
 309 file system first appeared in
 310 .Dx 1.11 .
 311 .Sh AUTHORS
 312 .An -nosplit
 313 The
 314 .Nm
 315 file system was designed and implemented by
 316 .An Matthew Dillon Aq dillon@backplane.com .
 317 This manual page was written by
 318 .An Sascha Wildner .