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