TRIM support
[dragonfly.git] / sbin / newfs / newfs.8
CommitLineData
984263bc
MD
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. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)newfs.8 8.6 (Berkeley) 5/3/95
33.\" $FreeBSD: src/sbin/newfs/newfs.8,v 1.26.2.15 2003/05/13 12:16:08 joerg Exp $
41e59acb 34.\" $DragonFly: src/sbin/newfs/newfs.8,v 1.7 2007/05/20 19:29:21 dillon Exp $
984263bc 35.\"
b796e0dd 36.Dd November 24, 2010
984263bc
MD
37.Dt NEWFS 8
38.Os
39.Sh NAME
40.Nm newfs ,
41.Nm mount_mfs
8895c5fa 42.Nd construct a new UFS file system
984263bc
MD
43.Sh SYNOPSIS
44.Nm
b796e0dd 45.Op Fl L Ar volname
e0fb398b 46.Op Fl NCOURE
984263bc
MD
47.Op Fl S Ar sector-size
48.Op Fl T Ar disktype
49.Op Fl a Ar maxcontig
50.Op Fl b Ar block-size
51.Op Fl c Ar cylinders
52.Op Fl d Ar rotdelay
53.Op Fl e Ar maxbpg
54.Op Fl f Ar frag-size
55.Op Fl g Ar avgfilesize
56.Op Fl h Ar avfpdir
57.Op Fl i Ar bytes
58.Op Fl k Ar skew
59.Op Fl l Ar interleave
60.Op Fl m Ar free space
61.Op Fl n Ar rotational positions
62.Op Fl o Ar optimization
63.Op Fl p Ar sectors
64.Op Fl r Ar revolutions
65.Op Fl s Ar size
66.Op Fl t Ar tracks
67.Op Fl u Ar sectors
68.Op Fl v
69.Op Fl x Ar sectors
70.Ar special
71.Nm mount_mfs
72.Op Fl NU
73.Op Fl F Ar file
74.Op Fl T Ar disktype
75.Op Fl a Ar maxcontig
76.Op Fl b Ar block-size
77.Op Fl c Ar cylinders
78.Op Fl d Ar rotdelay
79.Op Fl e Ar maxbpg
80.Op Fl f Ar frag-size
81.Op Fl i Ar bytes
82.Op Fl m Ar free space
83.Op Fl n Ar rotational positions
84.Op Fl o Ar options
85.Op Fl s Ar size
86.Op Fl v
87.Ar special node
88.Sh DESCRIPTION
89.Nm Newfs
90is used to initialize and clear filesystems before first use.
91Before running
92.Nm
93or
94.Nm mount_mfs ,
95the disk must be labeled using
96.Xr disklabel 8 .
97.Nm Newfs
98builds a file system on the specified special file.
99(We often refer to the
100.Dq special file
101as the
102.Dq disk ,
103although the special file need not be a physical disk.
104In fact, it need not even be special.)
105Typically the defaults are reasonable, however
106.Nm
107has numerous options to allow the defaults to be selectively overridden.
108.Pp
109.Nm Mount_mfs
110is used to build a file system in virtual memory and then mount it
111on a specified node.
112.Nm Mount_mfs
113exits and the contents of the file system are lost
114when the file system is unmounted.
115If
116.Nm mount_mfs
117is sent a signal while running,
118for example during system shutdown,
119it will attempt to unmount its
120corresponding file system.
121The parameters to
122.Nm mount_mfs
123are the same as those to
124.Nm .
125If the
126.Fl T
127flag is specified (see below), the special file is unused.
128Otherwise, it is only used to read the disk label which provides
129a set of configuration parameters for the memory based file system.
130The special file is typically that of the primary swap area,
131since that is where the file system will be backed up when
132free memory gets low and the memory supporting
133the file system has to be paged.
134.Pp
e4c9c0c8
MD
135.Nm mount_mfs
136creates the raw character device
137.Pa /dev/mfs<PID>
138to represent the backing store while the mount is active. This device may
139be read but not written and allows swap-based MFS filesystems to be dumped
140if desired.
141.Pp
984263bc
MD
142The following options define the general layout policies:
143.Bl -tag -width indent
144.It Fl T Ar disktype
145For backward compatibility and for
146.Nm mount_mfs .
147.It Fl F Ar file
148.Nm Mount_mfs
149will use this file for the image of the filesystem. When
150.Nm mount_mfs
151exits, this file will be left behind.
65087744
MD
152.It Fl C
153Tell
154.Nm Mount_mfs
155to copy the underlying filesystem into the MFS mount being created
156over it.
b796e0dd
AH
157.It Fl L Ar volname
158Add a volume label to the new file system.
984263bc
MD
159.It Fl N
160Cause the file system parameters to be printed out
161without really creating the file system.
162.It Fl O
163Create a
164.Bx 4.3
165format filesystem.
166This options is primarily used to build root filesystems
167that can be understood by older boot ROMs.
168.It Fl T
169Use information for the specified disk from
170.Pa /etc/disktab
41e59acb
MD
171instead of trying to get geometry information from the
172storage device.
984263bc
MD
173.It Fl U
174Enables soft updates on the new filesystem.
e0fb398b
T
175.It Fl E
176Use TRIM to erase the device's data before creating the file system. The
177underlying device must have the Trim sysctl enabled. Only devices that support
178TRIM will have such a sysctl option (kern.cam.da.X.trim_enabled).
984263bc
MD
179.It Fl a Ar maxcontig
180Specify the maximum number of contiguous blocks that will be
181laid out before forcing a rotational delay (see the
182.Fl d
183option).
184The default value is 1.
185See
186.Xr tunefs 8
187for more details on how to set this option.
188.It Fl b Ar block-size
189The block size of the file system, in bytes. It must be a power of 2. The
190default size is 16384 bytes, and the smallest allowable size is 4096 bytes.
191The optimal block:fragment ratio is 8:1.
192Other ratios are possible, but are not recommended,
193and may produce unpredictable results.
194.It Fl c Ar #cylinders/group
195The number of cylinders per cylinder group in a file system. The default
196is to compute the maximum allowed by the other parameters. This value is
197dependent on a number of other parameters, in particular the block size
198and the number of bytes per inode.
199.It Fl d Ar rotdelay
200This parameter once specified the minimum time in milliseconds required to
201initiate another disk transfer on the same cylinder. It was used in determining
202the rotationally optimal layout for disk blocks within a file. Modern disks
203with read/write-behind achieve higher performance with this feature disabled, so
204this value should be left at the default value of 0 milliseconds. See
205.Xr tunefs 8
206for more details on how to set this option.
207.It Fl e Ar maxbpg
208Indicate the maximum number of blocks any single file can
209allocate out of a cylinder group before it is forced to begin
210allocating blocks from another cylinder group.
211The default is about one quarter of the total blocks in a cylinder group.
212See
213.Xr tunefs 8
214for more details on how to set this option.
215.It Fl f Ar frag-size
216The fragment size of the file system in bytes. It must be a power of two
217ranging in value between
218.Ar blocksize Ns /8
219and
220.Ar blocksize .
221The default is 2048 bytes.
222.It Fl g Ar avgfilesize
223The expected average file size for the file system.
224.It Fl h Ar avgfpdir
225The expected average number of files per directory on the file system.
226.It Fl i Ar number of bytes per inode
227Specify the density of inodes in the file system.
228The default is to create an inode for every
229.Pq 4 * Ar frag-size
230bytes of data space.
231If fewer inodes are desired, a larger number should be used;
232to create more inodes a smaller number should be given.
233One inode is required for each distinct file, so this value effectively
234specifies the average file size on the file system.
235.It Fl m Ar free space \&%
236The percentage of space reserved from normal users; the minimum free
237space threshold.
238The default value used is
239defined by
240.Dv MINFREE
241from
44cb301e 242.In ufs/ffs/fs.h ,
984263bc
MD
243currently 8%.
244See
245.Xr tunefs 8
246for more details on how to set this option.
247.It Fl n Ar number of distinguished rotational positions
167c1ad2
SW
248.Xr UFS 5
249has the ability to keep track of the availability of blocks at different
984263bc
MD
250rotational positions, so that it could lay out the data to be picked up with
251minimum rotational latency. This parameter specifies the default number of
252rotational positions to distinguish.
253.Pp
254Nowadays this value should be set to 1 (which essentially disables the
255rotational position table) because modern drives with read-ahead and
256write-behind do better without the rotational position table.
257.It Fl o Ar optimization\ preference
8895c5fa 258.Pq Cm space No or Cm time .
984263bc
MD
259The file system can either be instructed to try to minimize the time spent
260allocating blocks, or to try to minimize the space fragmentation on the disk.
261If the value of minfree (see above) is less than 8%,
262the default is to optimize for
8895c5fa 263.Cm space ;
984263bc
MD
264if the value of minfree is greater than or equal to 8%,
265the default is to optimize for
8895c5fa 266.Cm time .
984263bc
MD
267See
268.Xr tunefs 8
269for more details on how to set this option.
270.It Fl s Ar size
271The size of the file system in sectors. This value defaults to the size of the
272raw partition specified in
273.Ar special
274(in other words,
275.Nm
276will use the entire partition for the file system).
277.It Fl v
278Specify that the disk does not contain any partitions, and that
279.Nm
280should build a file system on the whole disk.
281This option is useful for synthetic disks such as
282.Nm vinum .
41e59acb
MD
283It may also be used to allow
284.Nm
285to operate on regular files.
286When operating on a regular file,
287.Nm
288will synthesize a reasonable geometry for the filesystem.
984263bc
MD
289.El
290.Pp
291The following options override the standard sizes for the disk geometry.
292Their default values are taken from the disk label.
293Changing these defaults is useful only when using
294.Nm
295to build a file system whose raw image will eventually be used on a
296different type of disk than the one on which it is initially created
297(for example on a write-once disk).
298Note that changing any of these values from their defaults will make
299it impossible for
300.Xr fsck 8
301to find the alternate superblocks if the standard superblock is lost.
302.Bl -tag -width indent
303.It Fl S Ar sector-size
304The size of a sector in bytes (almost never anything but 512).
305.It Fl k Ar sector \&0 skew , per track
306Used to describe perturbations in the media format to compensate for
307a slow controller.
308Track skew is the offset of sector 0 on track N relative to sector 0
309on track N-1 on the same cylinder.
310This option is of historical importance only; modern controllers are always fast
311enough to handle operations back-to-back.
312.It Fl l Ar hardware sector interleave
313Used to describe perturbations in the media format to compensate for
314a slow controller.
315Interleave is physical sector interleave on each track,
316specified as the denominator of the ratio:
317.Dl sectors read/sectors passed over
318Thus an interleave of 1/1 implies contiguous layout, while 1/2 implies
319logical sector 0 is separated by one sector from logical sector 1.
320This option is of historical importance only; the physical sector layout of
321modern disks is not visible from outside.
322.It Fl p Ar spare sectors per track
323Spare sectors (bad sector replacements) are physical sectors that occupy
324space at the end of each track.
325They are not counted as part of the sectors/track
326.Pq Fl u
327since they are not available to the file system for data allocation.
328This option is of historical importance only. Modern disks perform their own
329bad sector allocation.
330.It Fl r Ar revolutions/minute
331The speed of the disk in revolutions per minute. This value is no longer of
332interest, since all the parameters which depend on it are usually disabled.
333.It Fl t Ar #tracks/cylinder
334The number of tracks/cylinder available for data allocation by the file
335system.
336The default is 1.
41e59acb 337If zero is specified, the value from the device geometry will be used.
984263bc
MD
338.It Fl u Ar sectors/track
339The number of sectors per track available for data allocation by the file
340system.
341The default is 4096.
41e59acb 342If zero is specified, the value from the device geometry will be used.
984263bc
MD
343This does not include sectors reserved at the end of each track for bad
344block replacement (see the
345.Fl p
346option).
347.It Fl x Ar spare sectors per cylinder
348Spare sectors (bad sector replacements) are physical sectors that occupy
349space at the end of the last track in the cylinder.
350They are deducted from the sectors/track
351.Pq Fl u
352of the last track of each cylinder since they are not available to the file
353system for data allocation.
354This option is of historical importance only. Modern disks perform their own
355bad sector allocation.
356.El
357.Pp
358The options to the
359.Nm mount_mfs
360command are as described for the
361.Nm
362command, except for the
363.Fl o
364option.
365.Pp
366That option is as follows:
367.Bl -tag -width indent
368.It Fl o
369Options are specified with a
370.Fl o
371flag followed by a comma separated string of options.
372See the
373.Xr mount 8
374man page for possible options and their meanings.
375.El
376.Sh EXAMPLES
377.Dl newfs /dev/ad3s1a
378.Pp
167c1ad2 379Creates a new
745e5aed 380.Xr UFS 5
167c1ad2 381file system on
984263bc
MD
382.Pa ad3s1a .
383.Nm
384will use a block size of 16384 bytes, a fragment size of 2048 bytes
385and the largest possible number of cylinders per group.
386These values tend to produce better performance for most applications
387than the historical defaults
388(8192 byte block size and 1024 byte fragment size).
389This large fragment size
390may lead to large amounts of wasted space
391on filesystems that contain a large number of small files.
392.Pp
393.Dl mount_mfs -s 131072 -o nosuid,nodev,nosymfollow /dev/da0s1b /tmp
394.Pp
395Mount a 64 MB large memory file system on
396.Pa /tmp ,
397with
398.Xr mount 8
399options
8895c5fa
TN
400.Cm nosuid ,
401.Cm nodev ,
984263bc 402and
8895c5fa 403.Cm nosymfollow .
984263bc
MD
404.Sh SEE ALSO
405.Xr fdformat 1 ,
8895c5fa 406.Xr UFS 5 ,
984263bc
MD
407.Xr disktab 5 ,
408.Xr fs 5 ,
409.Xr camcontrol 8 ,
410.Xr disklabel 8 ,
984263bc
MD
411.Xr dumpfs 8 ,
412.Xr fsck 8 ,
413.Xr mount 8 ,
414.Xr tunefs 8 ,
415.Xr vinum 8
416.Rs
417.%A M. McKusick
418.%A W. Joy
419.%A S. Leffler
420.%A R. Fabry
421.%T A Fast File System for UNIX
422.%J ACM Transactions on Computer Systems 2
423.%V 3
424.%P pp 181-197
425.%D August 1984
426.%O (reprinted in the BSD System Manager's Manual)
427.Re
428.Sh HISTORY
429The
430.Nm
431command appeared in
432.Bx 4.2 .