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