1.\" Copyright (c) 2001 Networks Associates Technology, Inc.
2.\" All rights reserved.
3.\"
4.\" This software was developed for the FreeBSD Project by Chris
5.\" Costello at Safeport Network Services and NAI Labs, the Security
6.\" Research Division of Network Associates, Inc. under DARPA/SPAWAR
7.\" contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA CHATS
8.\" research program.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\" notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\" notice, this list of conditions and the following disclaimer in the
17.\" documentation and/or other materials provided with the distribution.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\" $FreeBSD: head/share/man/man7/ffs.7 107744 2002-12-11 15:55:29Z ru $
32.\"
33.Dd December 26, 2001
34.Dt FFS 7
35.Os
36.Sh NAME
37.Nm ffs
38.Nd Berkeley fast filesystem
39.Sh SYNOPSIS
40In the kernel configuration file:
41.Cd "options FFS"
42.Cd "options QUOTA"
43.Cd "options SOFTUPDATES"
44.Cd "options SUIDDIR"
45.Cd "options UFS_ACL"
46.Cd "options UFS_DIRHASH"
47.Cd "options UFS_EXTATTR"
48.Cd "options UFS_EXTATTR_AUTOSTART"
49.Pp
50In
51.Xr fstab 5 :
52.Bd -literal -compact
53/dev/disk0a /mnt ufs rw 1 1
54.Ed
55.Sh DESCRIPTION
56The Berkeley fast filesystem
57provides facilities to store filesystem data onto a disk device.
58.Nm
59has been optimized over the years
60for speed and reliability
61and is the default
62.Fx
63filesystem.
64.Ss Quotas
65.Bl -tag -width 2n
66.It Cd "options QUOTA"
67This option allows system administrators
68to set limits on disk usage
69on a per-user basis.
70Quotas can be used only on filesystems
71mounted with the
72.Cm quota
73option;
74see
75.Xr quota 1
76and
77.Xr edquota 8 .
78.El
79.Ss Soft Updates
80.Bl -tag -width 2n
81.It Cd "options SOFTUPDATES"
82The soft updates feature tracks writes to the disk
83and enforces metadata update dependencies
84(e.g., updating free block maps)
85to ensure that the filesystem remains consistent.
86.Pp
87To enable soft updates on an
88.Em unmounted
89filesystem, use the following command:
90.Pp
91.D1 Nm tunefs Fl n Cm enable Ar fs
92.Pp
93.Ar fs
94can be either a mount point listed in
95.Xr fstab 5
96(e.g.,
97.Pa /usr ) ,
98or a disk device
99(e.g.,
100.Pa /dev/da0a ) .
101.El
102.Ss File Ownership Inheritance
103.Bl -tag -width 2n
104.It Cd "options SUIDDIR"
105For use in file sharing environments
106on networks including
107.Tn "Microsoft Windows"
108and
109.Tn "Apple Macintosh"
110computers,
111this option allows files on filesystems
112mounted with the
113.Cm suiddir
114option
115to inherit the ownership of its directory,
116i.e.,
117.Dq "if it's my directory, it must be my file."
118.El
119.Ss Access Control Lists
120.Bl -tag -width 2n
121.It Cd "options UFS_ACL"
122Access control lists allow the association of
123fine-grained discretionary access control information
124with files and directories.
125This option requires the presence of the
126.Dv UFS_EXTATTR
127option, and it is recommended that
128.Dv UFS_EXTATTR_AUTOSTART
129is included as well,
130so that ACLs are enabled atomically upon mounting the filesystem.
131.El
132.Pp
133In order to enable support for ACLs,
134two extended attributes must be available in the
135.Dv EXTATTR_NAMESPACE_SYSTEM
136namespace:
137.Pa posix1e.acl_access ,
138which holds the access ACL,
139and
140.Pa posix1e.acl_default ,
141which holds the default ACL for directories.
142If you are using filesystem extended attributes,
143the following commands may be used to
144allocate space for and create the necessary EA backing files
145for ACLs in the root of each filesystem.
146In these examples, the root filesystem is used;
147see
148.Sx "Extended Attributes"
149for more details.
150.Bd -literal -offset indent
151mkdir -p /.attribute/system
152cd /.attribute/system
153extattrctl initattr -p / 388 posix1e.acl_access
154extattrctl initattr -p / 388 posix1e.acl_default
155.Ed
156.Pp
157On the next mount of the root filesystem,
158the attributes will be automatically started
159(if
160.Dv UFS_EXTATTR_AUTOSTART
161is included in the kernel configuration),
162and ACLs will be enabled.
163.Ss Directory Hashing
164.Bl -tag -width 2n
165.It Cd "options UFS_DIRHASH"
166Implements a hash-based lookup scheme for directories
167in order to speed up accesses to very large directories.
168.El
169.Ss Extended Attributes
170.Bl -tag -width 2n
171.It Cd "options UFS_EXTATTR"
172Extended attributes allow the association of
173additional arbitrary metadata with files and directories,
174which can be assigned and retrieved from userland
175as well as from within the kernel; see
176.Xr extattrctl 8 .
177.It Cd "options UFS_EXTATTR_AUTOSTART"
178If this option is defined,
179.Nm
180will search for a
181.Pa .attribute
182subdirectory of the filesystem root during the mount operation.
183If found, extended attribute support will be
184automatically started for that filesystem.
185.El
186.Pp
187The following
188.Xr sysctl 8
189MIBs are defined for use with
190.Nm :
191.Bl -hang -width ".Va vfs.ffs.doreallocblk"
192.It Va vfs.ffs.doasyncfree
193Asynchronously write out modified i-node and indirect blocks
194upon reallocating filesystem blocks to be contiguous.
195(Default: 1.)
196.It Va vfs.ffs.doreallocblks
197Enable support for the rearrangement of blocks
198to be contiguous.
199(Default: 1.)
200.El
201.Sh SEE ALSO
202.Xr quota 1 ,
203.Xr acl 3 ,
204.Xr extattr 3 ,
205.Xr edquota 8 ,
206.Xr extattrctl 8 ,
207.Xr sysctl 8
208.Rs
209.%A M. McKusick
210.%A W. Joy
211.%A S. Lefler
212.%A R. Fabry
213.%D August 1984
214.%T "A Fast File System for UNIX"
215.%J "ACM Transactions on Computer Systems"
216.%N 2
217.%V 3
218.%P 181-197
219.Re
220.Rs
221.%A M. McKusick
222.%D June 2000
223.%T "Soft Updates: A Technique for Eliminating Most Synchronous Writes in the Fast Filesystem"
224.%J "Proceedings of the Freenix Track at the 1999 Usenix Annual Technical Conference"
225.%P 71-84
226.Re
2.\" All rights reserved.
3.\"
4.\" This software was developed for the FreeBSD Project by Chris
5.\" Costello at Safeport Network Services and NAI Labs, the Security
6.\" Research Division of Network Associates, Inc. under DARPA/SPAWAR
7.\" contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA CHATS
8.\" research program.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\" notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\" notice, this list of conditions and the following disclaimer in the
17.\" documentation and/or other materials provided with the distribution.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\" $FreeBSD: head/share/man/man7/ffs.7 107744 2002-12-11 15:55:29Z ru $
32.\"
33.Dd December 26, 2001
34.Dt FFS 7
35.Os
36.Sh NAME
37.Nm ffs
38.Nd Berkeley fast filesystem
39.Sh SYNOPSIS
40In the kernel configuration file:
41.Cd "options FFS"
42.Cd "options QUOTA"
43.Cd "options SOFTUPDATES"
44.Cd "options SUIDDIR"
45.Cd "options UFS_ACL"
46.Cd "options UFS_DIRHASH"
47.Cd "options UFS_EXTATTR"
48.Cd "options UFS_EXTATTR_AUTOSTART"
49.Pp
50In
51.Xr fstab 5 :
52.Bd -literal -compact
53/dev/disk0a /mnt ufs rw 1 1
54.Ed
55.Sh DESCRIPTION
56The Berkeley fast filesystem
57provides facilities to store filesystem data onto a disk device.
58.Nm
59has been optimized over the years
60for speed and reliability
61and is the default
62.Fx
63filesystem.
64.Ss Quotas
65.Bl -tag -width 2n
66.It Cd "options QUOTA"
67This option allows system administrators
68to set limits on disk usage
69on a per-user basis.
70Quotas can be used only on filesystems
71mounted with the
72.Cm quota
73option;
74see
75.Xr quota 1
76and
77.Xr edquota 8 .
78.El
79.Ss Soft Updates
80.Bl -tag -width 2n
81.It Cd "options SOFTUPDATES"
82The soft updates feature tracks writes to the disk
83and enforces metadata update dependencies
84(e.g., updating free block maps)
85to ensure that the filesystem remains consistent.
86.Pp
87To enable soft updates on an
88.Em unmounted
89filesystem, use the following command:
90.Pp
91.D1 Nm tunefs Fl n Cm enable Ar fs
92.Pp
93.Ar fs
94can be either a mount point listed in
95.Xr fstab 5
96(e.g.,
97.Pa /usr ) ,
98or a disk device
99(e.g.,
100.Pa /dev/da0a ) .
101.El
102.Ss File Ownership Inheritance
103.Bl -tag -width 2n
104.It Cd "options SUIDDIR"
105For use in file sharing environments
106on networks including
107.Tn "Microsoft Windows"
108and
109.Tn "Apple Macintosh"
110computers,
111this option allows files on filesystems
112mounted with the
113.Cm suiddir
114option
115to inherit the ownership of its directory,
116i.e.,
117.Dq "if it's my directory, it must be my file."
118.El
119.Ss Access Control Lists
120.Bl -tag -width 2n
121.It Cd "options UFS_ACL"
122Access control lists allow the association of
123fine-grained discretionary access control information
124with files and directories.
125This option requires the presence of the
126.Dv UFS_EXTATTR
127option, and it is recommended that
128.Dv UFS_EXTATTR_AUTOSTART
129is included as well,
130so that ACLs are enabled atomically upon mounting the filesystem.
131.El
132.Pp
133In order to enable support for ACLs,
134two extended attributes must be available in the
135.Dv EXTATTR_NAMESPACE_SYSTEM
136namespace:
137.Pa posix1e.acl_access ,
138which holds the access ACL,
139and
140.Pa posix1e.acl_default ,
141which holds the default ACL for directories.
142If you are using filesystem extended attributes,
143the following commands may be used to
144allocate space for and create the necessary EA backing files
145for ACLs in the root of each filesystem.
146In these examples, the root filesystem is used;
147see
148.Sx "Extended Attributes"
149for more details.
150.Bd -literal -offset indent
151mkdir -p /.attribute/system
152cd /.attribute/system
153extattrctl initattr -p / 388 posix1e.acl_access
154extattrctl initattr -p / 388 posix1e.acl_default
155.Ed
156.Pp
157On the next mount of the root filesystem,
158the attributes will be automatically started
159(if
160.Dv UFS_EXTATTR_AUTOSTART
161is included in the kernel configuration),
162and ACLs will be enabled.
163.Ss Directory Hashing
164.Bl -tag -width 2n
165.It Cd "options UFS_DIRHASH"
166Implements a hash-based lookup scheme for directories
167in order to speed up accesses to very large directories.
168.El
169.Ss Extended Attributes
170.Bl -tag -width 2n
171.It Cd "options UFS_EXTATTR"
172Extended attributes allow the association of
173additional arbitrary metadata with files and directories,
174which can be assigned and retrieved from userland
175as well as from within the kernel; see
176.Xr extattrctl 8 .
177.It Cd "options UFS_EXTATTR_AUTOSTART"
178If this option is defined,
179.Nm
180will search for a
181.Pa .attribute
182subdirectory of the filesystem root during the mount operation.
183If found, extended attribute support will be
184automatically started for that filesystem.
185.El
186.Pp
187The following
188.Xr sysctl 8
189MIBs are defined for use with
190.Nm :
191.Bl -hang -width ".Va vfs.ffs.doreallocblk"
192.It Va vfs.ffs.doasyncfree
193Asynchronously write out modified i-node and indirect blocks
194upon reallocating filesystem blocks to be contiguous.
195(Default: 1.)
196.It Va vfs.ffs.doreallocblks
197Enable support for the rearrangement of blocks
198to be contiguous.
199(Default: 1.)
200.El
201.Sh SEE ALSO
202.Xr quota 1 ,
203.Xr acl 3 ,
204.Xr extattr 3 ,
205.Xr edquota 8 ,
206.Xr extattrctl 8 ,
207.Xr sysctl 8
208.Rs
209.%A M. McKusick
210.%A W. Joy
211.%A S. Lefler
212.%A R. Fabry
213.%D August 1984
214.%T "A Fast File System for UNIX"
215.%J "ACM Transactions on Computer Systems"
216.%N 2
217.%V 3
218.%P 181-197
219.Re
220.Rs
221.%A M. McKusick
222.%D June 2000
223.%T "Soft Updates: A Technique for Eliminating Most Synchronous Writes in the Fast Filesystem"
224.%J "Proceedings of the Freenix Track at the 1999 Usenix Annual Technical Conference"
225.%P 71-84
226.Re