1.\" Copyright (c) 2011-2014 The DragonFly Project. All rights reserved. 2.\" 3.\" This code is derived from software contributed to The DragonFly Project 4.\" by Matthew Dillon <dillon@backplane.com> 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in 14.\" the documentation and/or other materials provided with the 15.\" distribution. 16.\" 3. Neither the name of The DragonFly Project nor the names of its 17.\" contributors may be used to endorse or promote products derived 18.\" from this software without specific, prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 24.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 26.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 30.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.Dd May 23, 2011 34.Dt NEWFS_HAMMER2 8 35.Os 36.Sh NAME 37.Nm newfs_hammer2 38.Nd construct a new HAMMER2 file system 39.Sh SYNOPSIS 40.Nm 41.Op Fl f 42.Op Fl b Ar bootsize 43.Op Fl r Ar redosize 44.Op Fl V Ar version 45.Op Fl L Ar label 46.Ar special 47.Sh DESCRIPTION 48The 49.Nm 50utility prepares a 51.Nm HAMMER2 52volume on the specified block device. 53.Nm HAMMER2 54volumes can contain any number of named PFSs (Pseudo FileSystems). 55Each named PFS can operate independently or be a constituent of 56of a larger cluster. 57Regardless, you must still format each block device separately using 58this command. 59.Pp 60By default the 61.Nm 62program creates three local MASTER PFSs: "LOCAL", "BOOT", and "ROOT". 63The "LOCAL" PFS is mandatory and is always created. It represents an 64unclustered mount point representative of the just block device you 65formatted. 66.Pp 67The "BOOT" and "ROOT" PFSs are optional and will be created by default. 68These provide convenient initially non-clustered mount points for your 69boot or root filesystem. 70These PFSs are not created if the 71.Fl L Ar label 72option is specified. 73You can specify 74.Fl L Ar none 75if you do not want 76.Nm 77to create any PFSs other than "LOCAL". 78.Pp 79Generally speaking this command is not used to create clusters. It is used 80to format volumes which are then made available for additional clustering 81commands. 82Once formatted the device@LOCAL volume can be mounted in order to make the 83block device available to the cluster. 84You can then use 85.Xr hammer2 8 86directives to construct your cluster, including the creation of additional 87PFSs within various volumes. 88If you are managing several machines, or a large number of machines, 89.Fl L Ar none 90is typically specified and each machine's ROOT is individually named, 91for example, "FUBAR-ROOT". 92.Pp 93.Nm HAMMER2 94file systems are sector-size agnostic, however the 95.Dx 96implementation requires the sector size to be no larger than 16K. 97.Nm HAMMER2 98file systems start at a relative offset of 0 and leave no room for 99in-band disklabels (old, traditional BSD labels). 100They may only be created using out-of-band disk labels, which is the 101default on 102.Dx 103via 104.Po 105.Xr disklabel 5 106or 107.Xr gpt 8 108labels 109.Pc , 110or with 111old style disklabels as long as 112the partition does not overlap the label area (have a starting sector 113greater than 16). 114.Pp 115.Nm HAMMER2 116file systems are designed for large storage systems, up to 1 Exabyte, and 117may not operate efficiently on small storage systems. 118The minimum recommended file system size is 50GB. 119In addition, 120.Nm HAMMER2 121file systems operating normally, with automatic snapshots, do not 122immediately reclaim space when files are deleted. 123A regular system maintenance job runs once a day by 124.Xr periodic 8 125to handle reclamation. 126.Pp 127.Nm HAMMER2 128works best when the machine's normal workload would not otherwise fill 129the file system up in the course of 60 days of operation. 130.Pp 131The options are as follows: 132.Bl -tag -width indent 133.It Fl b Ar bootsize 134Specify a fixed area in which a boot related kernel and data can be stored. 135The 136.Ar bootsize 137is specified in bytes. 138By default a boot area of approximately 4MB will be created. 139.It Fl f 140Force operation. 141This is needed for the creation of a 142.Nm HAMMER2 143file system less than 10GB size or 144with less than 500MB UNDO/REDO FIFO. 145This should not be used under normal circumstances. 146.It Fl r Ar redosize 147Specify the size of the fixed REDO FIFO. 148The 149.Ar redosize 150is specified in bytes. 151By default 0.1% of the root 152volume's size is used, with a reasonable minimum and a reasonable cap. 153The UNDO/REDO FIFO is used to sequence meta-data out to the media for 154instant crash recovery. 155.It Fl V Ar version 156Specify the 157.Nm HAMMER2 158file system version to format. 159By default 160.Nm 161formats the file system using the highest production version number 162supported by the 163.Nm HAMMER2 164VFS by checking the 165.Va vfs.hammer2.supported_version 166sysctl. 167If you need to maintain compatibility with an older version of 168.Nm HAMMER2 169you may specify the version with this option. 170.It Fl L Ar label 171By default 172.Nm 173creates three local master PFSs on the new volume: "LOCAL", "BOOT", and "ROOT". 174If you specify one or more label options 175.Nm 176will not automatically create "BOOT" or "ROOT". 177"LOCAL" is always created and should never be specified. 178If you don't want any extra PFSs to be created, use 179.Fl L Ar none . 180.Pp 181Typically simple HAMMER2 filesystems just use the defaults and 182.Fl L Ar none 183is used for more complex filesystem, followed by mounting device@LOCAL 184and using 185.Nm hammer2 186directives to create the desired cluster. 187.El 188.Pp 189The 190.Ar bootsize 191and 192.Ar redosize 193must be given with a suffix of 194.Cm K , M , G 195or 196.Cm T 197meaning kilobyte, megabyte, gigabyte and terabyte. 198Lower case can also be used for suffix. 199These options create reserved blocks of space on the target volume 200but are not currently used by the filesystem for anything. 201.Sh EXAMPLES 202.Bd -literal -offset indent 203newfs_hammer2 -L SATURN-HOME /dev/ad0s1d 204.Ed 205.Pp 206Create a file system named 207.Sq SATURN-HOME 208on 209.Pa /dev/ad0s1d . 210.Sh DIAGNOSTICS 211Exit status is 0 on success and 1 on error. 212.Sh SEE ALSO 213.Xr disklabel32 5 , 214.Xr disklabel64 5 , 215.Xr HAMMER2 5 , 216.Xr fdisk 8 , 217.Xr gpt 8 , 218.Xr newfs 8 219.Sh HISTORY 220The 221.Nm 222utility first appeared in 223.Dx 1.11 . 224.Sh AUTHORS 225.An Matthew Dillon Aq Mt dillon@backplane.com 226