sbin/newfs/newfs.8

   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 .\"     @(#)newfs.8     8.6 (Berkeley) 5/3/95
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd January 29, 2019
  32 .Dt NEWFS 8
  33 .Os
  34 .Sh NAME
  35 .Nm newfs
  36 .Nd construct a new UFS1/UFS2 file system
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Fl EJNUjlnt
  40 .Op Fl L Ar volname
  41 .Op Fl O Ar filesystem-type
  42 .Op Fl S Ar sector-size
  43 .Op Fl T Ar disktype
  44 .Op Fl a Ar maxcontig
  45 .Op Fl b Ar block-size
  46 .Op Fl c Ar blocks-per-cylinder-group
  47 .Op Fl d Ar max-extent-size
  48 .Op Fl e Ar maxbpg
  49 .Op Fl f Ar frag-size
  50 .Op Fl g Ar avgfilesize
  51 .Op Fl h Ar avgfpdir
  52 .Op Fl i Ar bytes
  53 .Op Fl k Ar held-for-metadata-blocks
  54 .Op Fl m Ar free-space
  55 .Op Fl o Ar optimization
  56 .Op Fl p Ar partition
  57 .Op Fl r Ar reserved
  58 .Op Fl s Ar size
  59 .Ar special
  60 .Sh DESCRIPTION
  61 The
  62 .Nm
  63 utility is used to initialize and clear file systems before first use.
  64 The
  65 .Nm
  66 utility builds a file system on the specified special file.
  67 (We often refer to the
  68 .Dq special file
  69 as the
  70 .Dq disk ,
  71 although the special file need not be a physical disk.
  72 In fact, it need not even be special.)
  73 Typically the defaults are reasonable, however
  74 .Nm
  75 has numerous options to allow the defaults to be selectively overridden.
  76 .Pp
  77 The following options define the general layout policies:
  78 .Bl -tag -width indent
  79 .It Fl E
  80 Erase the content of the disk before making the filesystem.
  81 The reserved area in front of the superblock (for bootcode) will not be erased.
  82 Erasing is only relevant to flash-memory or thinly provisioned devices.
  83 Erasing may take a long time.
  84 If the device does not support BIO_DELETE, the command will fail.
  85 .It Fl J
  86 Enable journaling on the new file system via gjournal.
  87 See
  88 .Xr gjournal 8
  89 for details.
  90 .It Fl L Ar volname
  91 Add a volume label to the new file system.
  92 Legal characters are alphanumerics, dashes, and underscores.
  93 .It Fl N
  94 Cause the file system parameters to be printed out
  95 without really creating the file system.
  96 .It Fl O Ar filesystem-type
  97 Use 1 to specify that a UFS1 format file system be built;
  98 use 2 to specify that a UFS2 format file system be built.
  99 The default format is UFS2.
 100 .It Fl T Ar disktype
 101 For backward compatibility.
 102 .It Fl U
 103 Enable soft updates on the new file system.
 104 .It Fl a Ar maxcontig
 105 Specify the maximum number of contiguous blocks that will be
 106 laid out before forcing a rotational delay.
 107 The default value is 16.
 108 See
 109 .Xr tunefs 8
 110 for more details on how to set this option.
 111 .It Fl b Ar block-size
 112 The block size of the file system, in bytes.
 113 It must be a power of 2.
 114 .\" If changing the default block size and it causes the default
 115 .\" fragment size to change, be sure to update the location of
 116 .\" the first backup superblock on the fsck_ffs.8 manual page.
 117 The
 118 default size is 32768 bytes, and the smallest allowable size is 4096 bytes.
 119 The optimal block:fragment ratio is 8:1.
 120 Other ratios are possible, but are not recommended,
 121 and may produce poor results.
 122 .It Fl c Ar blocks-per-cylinder-group
 123 The number of blocks per cylinder group in a file system.
 124 The default is to compute the maximum allowed by the other parameters.
 125 This value is
 126 dependent on a number of other parameters, in particular the block size
 127 and the number of bytes per inode.
 128 .It Fl d Ar max-extent-size
 129 The file system may choose to store large files using extents.
 130 This parameter specifies the largest extent size that may be used.
 131 The default value is the file system blocksize.
 132 It is presently limited to a maximum value of 16 times the
 133 file system blocksize and a minimum value of the file system blocksize.
 134 .It Fl e Ar maxbpg
 135 Indicate the maximum number of blocks any single file can
 136 allocate out of a cylinder group before it is forced to begin
 137 allocating blocks from another cylinder group.
 138 The default is about one quarter of the total blocks in a cylinder group.
 139 See
 140 .Xr tunefs 8
 141 for more details on how to set this option.
 142 .It Fl f Ar frag-size
 143 The fragment size of the file system in bytes.
 144 It must be a power of two
 145 ranging in value between
 146 .Ar blocksize Ns /8
 147 and
 148 .Ar blocksize .
 149 .\" If changing the default fragment size or it changes because of a
 150 .\" change to the default block size, be sure to update the location
 151 .\" of the first backup superblock on the fsck_ffs.8 manual page.
 152 The default is 4096 bytes.
 153 .It Fl g Ar avgfilesize
 154 The expected average file size for the file system.
 155 .It Fl h Ar avgfpdir
 156 The expected average number of files per directory on the file system.
 157 .It Fl i Ar bytes
 158 Specify the density of inodes in the file system.
 159 The default is to create an inode for every
 160 .Pq 2 * Ar frag-size
 161 bytes of data space.
 162 If fewer inodes are desired, a larger number should be used;
 163 to create more inodes a smaller number should be given.
 164 One inode is required for each distinct file, so this value effectively
 165 specifies the average file size on the file system.
 166 .It Fl j
 167 Enable soft updates journaling on the new file system.
 168 This flag is implemented by running the
 169 .Xr tunefs 8
 170 utility found in the user's
 171 .Dv $PATH .
 172 .It Fl k Ar held-for-metadata-blocks
 173 Set the amount of space to be held for metadata blocks in each cylinder group.
 174 When set, the file system preference routines will try to save
 175 the specified amount of space immediately following the inode blocks
 176 in each cylinder group for use by metadata blocks.
 177 Clustering the metadata blocks speeds up random file access
 178 and decreases the running time of
 179 .Xr fsck 8 .
 180 By default
 181 .Nm
 182 sets it to half of the space reserved to minfree.
 183 .It Fl l
 184 Enable multilabel MAC on the new file system.
 185 .It Fl m Ar free-space
 186 The percentage of space reserved from normal users; the minimum free
 187 space threshold.
 188 The default value used is
 189 defined by
 190 .Dv MINFREE
 191 from
 192 .In ufs/ffs/fs.h ,
 193 currently 8%.
 194 See
 195 .Xr tunefs 8
 196 for more details on how to set this option.
 197 .It Fl n
 198 Do not create a
 199 .Pa .snap
 200 directory on the new file system.
 201 The resulting file system will not support snapshot generation, so
 202 .Xr dump 8
 203 in live mode and background
 204 .Xr fsck 8
 205 will not function properly.
 206 The traditional
 207 .Xr fsck 8
 208 and offline
 209 .Xr dump 8
 210 will work on the file system.
 211 This option is intended primarily for memory or vnode-backed file systems that
 212 do not require
 213 .Xr dump 8
 214 or
 215 .Xr fsck 8
 216 support.
 217 .It Fl o Ar optimization
 218 .Cm ( space
 219 or
 220 .Cm time ) .
 221 The file system can either be instructed to try to minimize the time spent
 222 allocating blocks, or to try to minimize the space fragmentation on the disk.
 223 If the value of minfree (see above) is less than 8%,
 224 the default is to optimize for
 225 .Cm space ;
 226 if the value of minfree is greater than or equal to 8%,
 227 the default is to optimize for
 228 .Cm time .
 229 See
 230 .Xr tunefs 8
 231 for more details on how to set this option.
 232 .It Fl p Ar partition
 233 The partition name (a..h) you want to use in case the underlying image
 234 is a file, so you do not have access to individual partitions through the
 235 filesystem.
 236 Can also be used with a device, e.g.,
 237 .Nm
 238 .Fl p Ar f
 239 .Ar /dev/da1s3
 240 is equivalent to
 241 .Nm
 242 .Ar /dev/da1s3f .
 243 .It Fl r Ar reserved
 244 The size, in sectors, of reserved space
 245 at the end of the partition specified in
 246 .Ar special .
 247 This space will not be occupied by the file system;
 248 it can be used by other consumers such as
 249 .Xr geom 4 .
 250 Defaults to 0.
 251 .It Fl s Ar size
 252 The size of the file system in sectors.
 253 This value defaults to the size of the
 254 raw partition specified in
 255 .Ar special
 256 less the
 257 .Ar reserved
 258 space at its end (see
 259 .Fl r ) .
 260 A
 261 .Ar size
 262 of 0 can also be used to choose the default value.
 263 A valid
 264 .Ar size
 265 value cannot be larger than the default one,
 266 which means that the file system cannot extend into the reserved space.
 267 .It Fl t
 268 Turn on the TRIM enable flag.
 269 If enabled, and if the underlying device supports the BIO_DELETE
 270 command, the file system will send a delete request to the underlying
 271 device for each freed block.
 272 The trim enable flag is typically set for flash-memory devices to
 273 reduce write amplification which reduces wear on write-limited
 274 flash-memory and often improves long-term performance.
 275 Thinly provisioned storage also benefits by returning unused blocks to
 276 the global pool.
 277 .El
 278 .Pp
 279 The following options override the standard sizes for the disk geometry.
 280 Their default values are taken from the disk label.
 281 Changing these defaults is useful only when using
 282 .Nm
 283 to build a file system whose raw image will eventually be used on a
 284 different type of disk than the one on which it is initially created
 285 (for example on a write-once disk).
 286 Note that changing any of these values from their defaults will make
 287 it impossible for
 288 .Xr fsck 8
 289 to find the alternate superblocks if the standard superblock is lost.
 290 .Bl -tag -width indent
 291 .It Fl S Ar sector-size
 292 The size of a sector in bytes (almost never anything but 512).
 293 .El
 294 .Sh EXAMPLES
 295 .Dl newfs /dev/ada3s1a
 296 .Pp
 297 Creates a new ufs file system on
 298 .Pa ada3s1a .
 299 The
 300 .Nm
 301 utility will use a block size of 32768 bytes, a fragment size of 4096 bytes
 302 and the largest possible number of blocks per cylinders group.
 303 These values tend to produce better performance for most applications
 304 than the historical defaults
 305 (8192 byte block size and 1024 byte fragment size).
 306 This large fragment size may lead to much wasted space
 307 on file systems that contain many small files.
 308 .Sh SEE ALSO
 309 .Xr fdformat 1 ,
 310 .Xr geom 4 ,
 311 .Xr disktab 5 ,
 312 .Xr fs 5 ,
 313 .Xr camcontrol 8 ,
 314 .Xr dump 8 ,
 315 .Xr dumpfs 8 ,
 316 .Xr fsck 8 ,
 317 .Xr gpart 8 ,
 318 .Xr gjournal 8 ,
 319 .Xr growfs 8 ,
 320 .Xr gvinum 8 ,
 321 .Xr makefs 8 ,
 322 .Xr mount 8 ,
 323 .Xr tunefs 8
 324 .Rs
 325 .%A M. McKusick
 326 .%A W. Joy
 327 .%A S. Leffler
 328 .%A R. Fabry
 329 .%T A Fast File System for UNIX
 330 .%J ACM Transactions on Computer Systems 2
 331 .%V 3
 332 .%P pp 181-197
 333 .%D August 1984
 334 .%O (reprinted in the BSD System Manager's Manual)
 335 .Re
 336 .Sh HISTORY
 337 The
 338 .Nm
 339 utility appeared in
 340 .Bx 4.2 .