1.\" Copyright (c) 1983, 1987, 1991, 1993, 1994 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd May 18, 2024 29.Dt NEWFS 8 30.Os 31.Sh NAME 32.Nm newfs 33.Nd construct a new UFS1/UFS2 file system 34.Sh SYNOPSIS 35.Nm 36.Op Fl EJNUjlnt 37.Op Fl L Ar volname 38.Op Fl O Ar filesystem-type 39.Op Fl S Ar sector-size 40.Op Fl T Ar disktype 41.Op Fl a Ar maxcontig 42.Op Fl b Ar block-size 43.Op Fl c Ar blocks-per-cylinder-group 44.Op Fl d Ar max-extent-size 45.Op Fl e Ar maxbpg 46.Op Fl f Ar frag-size 47.Op Fl g Ar avgfilesize 48.Op Fl h Ar avgfpdir 49.Op Fl i Ar bytes 50.Op Fl k Ar held-for-metadata-blocks 51.Op Fl m Ar free-space 52.Op Fl o Ar optimization 53.Op Fl p Ar partition 54.Op Fl r Ar reserved 55.Op Fl s Ar size 56.Ar special 57.Sh DESCRIPTION 58The 59.Nm 60utility is used to initialize and clear file systems before first use. 61The 62.Nm 63utility builds a file system on the specified special file. 64(We often refer to the 65.Dq special file 66as the 67.Dq disk , 68although the special file need not be a physical disk. 69In fact, it need not even be special.) 70Typically the defaults are reasonable, however 71.Nm 72has numerous options to allow the defaults to be selectively overridden. 73.Pp 74The following options define the general layout policies: 75.Bl -tag -width indent 76.It Fl E 77Erase the content of the disk before making the filesystem. 78The reserved area in front of the superblock (for bootcode) will not be erased. 79Erasing is only relevant to flash-memory or thinly provisioned devices. 80Erasing may take a long time. 81If the device does not support BIO_DELETE, the command will fail. 82.It Fl J 83Enable journaling on the new file system via gjournal. 84See 85.Xr gjournal 8 86for details. 87.It Fl L Ar volname 88Add a volume label to the new file system. 89Legal characters are alphanumerics, dashes, and underscores. 90.It Fl N 91Cause the file system parameters to be printed out 92without really creating the file system. 93.It Fl O Ar filesystem-type 94Use 1 to specify that a UFS1 format file system be built; 95use 2 to specify that a UFS2 format file system be built. 96The default format is UFS2. 97.It Fl T Ar disktype 98For backward compatibility. 99.It Fl U 100Enable soft updates on the new file system. 101Soft updates are enabled by default for UFS2 format file systems. 102Use 103.Xr tunefs 8 104to disable soft updates if they are not wanted. 105.It Fl a Ar maxcontig 106Specify the maximum number of contiguous blocks that will be 107laid out before forcing a rotational delay. 108The default value is 16. 109See 110.Xr tunefs 8 111for more details on how to set this option. 112.It Fl b Ar block-size 113The block size of the file system, in bytes. 114It must be a power of 2. 115.\" If changing the default block size and it causes the default 116.\" fragment size to change, be sure to update the location of 117.\" the first backup superblock on the fsck_ffs.8 manual page. 118The 119default size is 32768 bytes, and the smallest allowable size is 4096 bytes. 120The optimal block:fragment ratio is 8:1. 121Other ratios are possible, but are not recommended, 122and may produce poor results. 123.It Fl c Ar blocks-per-cylinder-group 124The number of blocks per cylinder group in a file system. 125The default is to compute the maximum allowed by the other parameters. 126This value is 127dependent on a number of other parameters, in particular the block size 128and the number of bytes per inode. 129.It Fl d Ar max-extent-size 130The file system may choose to store large files using extents. 131This parameter specifies the largest extent size that may be used. 132The default value is the file system blocksize. 133It is presently limited to a maximum value of 16 times the 134file system blocksize and a minimum value of the file system blocksize. 135.It Fl e Ar maxbpg 136Indicate the maximum number of blocks any single file can 137allocate out of a cylinder group before it is forced to begin 138allocating blocks from another cylinder group. 139The default is about one quarter of the total blocks in a cylinder group. 140See 141.Xr tunefs 8 142for more details on how to set this option. 143.It Fl f Ar frag-size 144The fragment size of the file system in bytes. 145It must be a power of two 146ranging in value between 147.Ar blocksize Ns /8 148and 149.Ar blocksize . 150.\" If changing the default fragment size or it changes because of a 151.\" change to the default block size, be sure to update the location 152.\" of the first backup superblock on the fsck_ffs.8 manual page. 153The default is 4096 bytes. 154.It Fl g Ar avgfilesize 155The expected average file size for the file system. 156.It Fl h Ar avgfpdir 157The expected average number of files per directory on the file system. 158.It Fl i Ar bytes 159Specify the density of inodes in the file system. 160The default is to create an inode for every 161.Pq 2 * Ar frag-size 162bytes of data space. 163If fewer inodes are desired, a larger number should be used; 164to create more inodes a smaller number should be given. 165One inode is required for each distinct file, so this value effectively 166specifies the average file size on the file system. 167.It Fl j 168Enable soft updates journaling on the new file system. 169This flag is implemented by running the 170.Xr tunefs 8 171utility found in the user's 172.Dv $PATH . 173.Pp 174Enabling journaling reduces the time spent by 175.Xr fsck_ffs 8 176cleaning up a filesystem after a crash to a few seconds from minutes to hours. 177Without journaling, the time to recover after a crash is a function 178of the number of files in the filesystem and the size of the filesystem. 179With journaling, the time to recover after a crash is a function of the 180amount of activity in the filesystem in the minute before the crash. 181Journaled recovery time is usually only a few seconds and never 182exceeds a minute. 183.Pp 184The drawback to using journaling is that the writes to its log adds 185an extra write load to the media containing the filesystem. 186Thus a write-intensive workload will have reduced throughput on a 187filesystem running with journaling. 188.Pp 189Like all journaling filesystems, the journal recovery will only fix 190issues known to the journal. 191Specifically if a media error occurs, 192the journal will not know about it and hence will not fix it. 193Thus when using journaling, it is still necessary to run a full fsck 194every few months or after a filesystem panic to check for and fix 195any errors brought on by media failure. 196A full fsck can be done by running a background fsck on a live 197filesystem or by running with the 198.Fl f 199flag on an unmounted filesystem. 200When running 201.Xr fsck_ffs 8 202in background on a live filesystem the filesystem performance 203will be about half of normal during the time that the background 204.Xr fsck_ffs 8 205is running. 206Running a full fsck on a UFS filesystem is the equivalent of 207running a scrub on a ZFS filesystem. 208.It Fl k Ar held-for-metadata-blocks 209Set the amount of space to be held for metadata blocks in each cylinder group. 210When set, the file system preference routines will try to save 211the specified amount of space immediately following the inode blocks 212in each cylinder group for use by metadata blocks. 213Clustering the metadata blocks speeds up random file access 214and decreases the running time of 215.Xr fsck 8 . 216By default 217.Nm 218sets it to half of the space reserved to minfree. 219.It Fl l 220Enable multilabel MAC on the new file system. 221.It Fl m Ar free-space 222The percentage of space reserved from normal users; the minimum free 223space threshold. 224The default value used is 225defined by 226.Dv MINFREE 227from 228.In ufs/ffs/fs.h , 229currently 8%. 230See 231.Xr tunefs 8 232for more details on how to set this option. 233.It Fl n 234Do not create a 235.Pa .snap 236directory on the new file system. 237The resulting file system will not support snapshot generation, so 238.Xr dump 8 239in live mode and background 240.Xr fsck 8 241will not function properly. 242The traditional 243.Xr fsck 8 244and offline 245.Xr dump 8 246will work on the file system. 247This option is intended primarily for memory or vnode-backed file systems that 248do not require 249.Xr dump 8 250or 251.Xr fsck 8 252support. 253.It Fl o Ar optimization 254.Cm ( space 255or 256.Cm time ) . 257The file system can either be instructed to try to minimize the time spent 258allocating blocks, or to try to minimize the space fragmentation on the disk. 259If the value of minfree (see above) is less than 8%, 260the default is to optimize for 261.Cm space ; 262if the value of minfree is greater than or equal to 8%, 263the default is to optimize for 264.Cm time . 265See 266.Xr tunefs 8 267for more details on how to set this option. 268.It Fl p Ar partition 269The partition name (a..h) you want to use in case the underlying image 270is a file, so you do not have access to individual partitions through the 271filesystem. 272Can also be used with a device, e.g., 273.Nm 274.Fl p Ar f 275.Ar /dev/da1s3 276is equivalent to 277.Nm 278.Ar /dev/da1s3f . 279.It Fl r Ar reserved 280The size, in sectors, of reserved space 281at the end of the partition specified in 282.Ar special . 283This space will not be occupied by the file system; 284it can be used by other consumers such as 285.Xr geom 4 . 286Defaults to 0. 287.It Fl s Ar size 288The size of the file system in sectors. 289This value defaults to the size of the 290raw partition specified in 291.Ar special 292less the 293.Ar reserved 294space at its end (see 295.Fl r ) . 296A 297.Ar size 298of 0 can also be used to choose the default value. 299A valid 300.Ar size 301value cannot be larger than the default one, 302which means that the file system cannot extend into the reserved space. 303.It Fl t 304Turn on the TRIM enable flag. 305If enabled, and if the underlying device supports the BIO_DELETE 306command, the file system will send a delete request to the underlying 307device for each freed block. 308The trim enable flag is typically set for flash-memory devices to 309reduce write amplification which reduces wear on write-limited 310flash-memory and often improves long-term performance. 311Thinly provisioned storage also benefits by returning unused blocks to 312the global pool. 313.El 314.Pp 315The following options override the standard sizes for the disk geometry. 316Their default values are taken from the disk label. 317Changing these defaults is useful only when using 318.Nm 319to build a file system whose raw image will eventually be used on a 320different type of disk than the one on which it is initially created 321(for example on a write-once disk). 322Note that changing any of these values from their defaults will make 323it impossible for 324.Xr fsck 8 325to find the alternate superblocks if the standard superblock is lost. 326.Bl -tag -width indent 327.It Fl S Ar sector-size 328The size of a sector in bytes (almost never anything but 512). 329.El 330.Sh NOTES ON THE NAMING 331.Dq newfs 332is a common name prefix for utilities creating filesystems, with the suffix 333indicating the type of the filesystem, for instance 334.Xr newfs_msdos 8 . 335The 336.Nm 337utility is a special case which predates that convention. 338.Sh EXAMPLES 339.Dl newfs /dev/ada3s1a 340.Pp 341Creates a new ufs file system on 342.Pa ada3s1a . 343The 344.Nm 345utility will use a block size of 32768 bytes, a fragment size of 4096 bytes 346and the largest possible number of blocks per cylinders group. 347These values tend to produce better performance for most applications 348than the historical defaults 349(8192 byte block size and 1024 byte fragment size). 350This large fragment size may lead to much wasted space 351on file systems that contain many small files. 352.Sh SEE ALSO 353.Xr fdformat 8 , 354.Xr geom 4 , 355.Xr disktab 5 , 356.Xr fs 5 , 357.Xr camcontrol 8 , 358.Xr dump 8 , 359.Xr dumpfs 8 , 360.Xr fsck 8 , 361.Xr gjournal 8 , 362.Xr gpart 8 , 363.Xr growfs 8 , 364.Xr gvinum 8 , 365.Xr makefs 8 , 366.Xr mount 8 , 367.Xr newfs_msdos 8 , 368.Xr tunefs 8 369.Rs 370.%A M. McKusick 371.%A W. Joy 372.%A S. Leffler 373.%A R. Fabry 374.%T A Fast File System for UNIX 375.%J ACM Transactions on Computer Systems 2 376.%V 3 377.%P pp 181-197 378.%D August 1984 379.%O (reprinted in the BSD System Manager's Manual) 380.Re 381.Sh HISTORY 382The 383.Nm 384utility appeared in 385.Bx 4.2 . 386