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.Dd May 3, 2020 32.Dt FFS 4 33.Os 34.Sh NAME 35.Nm ffs 36.Nd Berkeley fast file system 37.Sh SYNOPSIS 38In the kernel configuration file: 39.Cd "options FFS" 40.Cd "options QUOTA" 41.Cd "options SOFTUPDATES" 42.Cd "options SUIDDIR" 43.Cd "options UFS_ACL" 44.Cd "options UFS_DIRHASH" 45.Cd "options UFS_EXTATTR" 46.Cd "options UFS_EXTATTR_AUTOSTART" 47.Cd "options UFS_GJOURNAL" 48.Pp 49In 50.Xr fstab 5 : 51.Bd -literal -compact 52/dev/disk0a /mnt ufs rw 1 1 53.Ed 54.Sh DESCRIPTION 55The Berkeley fast file system 56provides facilities to store file system data onto a disk device. 57.Nm 58has been optimized over the years 59for speed and reliability 60and is the default 61.Fx 62file system. 63.Ss Quotas 64.Bl -tag -width 2n 65.It Cd "options QUOTA" 66This option allows system administrators 67to set limits on disk usage 68on a per-user basis. 69Quotas can be used only on file systems 70mounted with the 71.Cm quota 72option; 73see 74.Xr quota 1 75and 76.Xr edquota 8 . 77.El 78.Ss Soft Updates 79.Bl -tag -width 2n 80.It Cd "options SOFTUPDATES" 81The soft updates feature tracks writes to the disk 82and enforces metadata update dependencies 83(e.g., updating free block maps) 84to ensure that the file system remains consistent. 85.Pp 86To create a new file system with the soft updates 87enabled, 88use 89.Xr newfs 8 90command: 91.Pp 92.D1 Nm newfs Fl U Ar fs 93.Pp 94.Ar fs 95can be either a mount point listed in 96.Xr fstab 5 97.Pq e.g. , Pa /usr , 98or a disk device 99.Pq e.g., Pa /dev/da0a . 100.Pp 101It is possible to enable soft updates on an 102.Em unmounted 103file system by using 104.Xr tunefs 8 105command: 106.Pp 107.D1 Nm tunefs Fl n Cm enable Ar fs 108.Pp 109Soft updates can also add journaling that reduces the time spent by 110.Xr fsck_ffs 8 111cleaning up a filesystem after a crash from several minutes to a few seconds. 112The journal is placed in an inode named 113.Pa .sujournal , 114and is kept as a circular log of segments containing 115records that describe metadata operations. 116.Pp 117To create a new file system with both the soft updates 118and soft updates journaling enabled, 119use the following command: 120.Pp 121.D1 Nm newfs Fl j Ar fs 122.Pp 123This runs 124.Xr tunefs 8 125command after 126.Xr newfs 8 127command with 128.Fl U 129flag enabled. 130It is possible to enable soft updates journaling on an 131.Em unmounted 132file system by using 133.Xr tunefs 8 134command: 135.Pp 136.D1 Nm tunefs Fl j Cm enable Ar fs 137.Pp 138This flag automatically enables the soft updates feature 139when it is not enabled. 140Note that this 141.Xr tunefs 8 142command will fail if a file 143.Pa .sujournal 144already exists before enabling the soft updates journaling. 145.El 146.Ss File Ownership Inheritance 147.Bl -tag -width 2n 148.It Cd "options SUIDDIR" 149For use in file sharing environments 150on networks including 151.Tn "Microsoft Windows" 152and 153.Tn "Apple Macintosh" 154computers, 155this option allows files on file systems 156mounted with the 157.Cm suiddir 158option 159to inherit the ownership of its directory, 160i.e., 161.Dq "if it's my directory, it must be my file." 162.El 163.Ss Access Control Lists 164.Bl -tag -width 2n 165.It Cd "options UFS_ACL" 166Access control lists allow the association of 167fine-grained discretionary access control information 168with files and directories. 169This option requires the presence of the 170.Dv UFS_EXTATTR 171option, and it is recommended that 172.Dv UFS_EXTATTR_AUTOSTART 173is included as well, 174so that ACLs are enabled atomically upon mounting the file system. 175.El 176.Pp 177In order to enable support for ACLs, 178two extended attributes must be available in the 179.Dv EXTATTR_NAMESPACE_SYSTEM 180namespace: 181.Pa posix1e.acl_access , 182which holds the access ACL, 183and 184.Pa posix1e.acl_default , 185which holds the default ACL for directories. 186If you are using file system extended attributes, 187the following commands may be used to 188allocate space for and create the necessary EA backing files 189for ACLs in the root of each file system. 190In these examples, the root file system is used; 191see 192.Sx "Extended Attributes" 193for more details. 194.Bd -literal -offset indent 195mkdir -p /.attribute/system 196cd /.attribute/system 197extattrctl initattr -p / 388 posix1e.acl_access 198extattrctl initattr -p / 388 posix1e.acl_default 199.Ed 200.Pp 201On the next mount of the root file system, 202the attributes will be automatically started if 203.Dv UFS_EXTATTR_AUTOSTART 204is included in the kernel configuration, 205and ACLs will be enabled. 206.Ss Directory Hashing 207.Bl -tag -width 2n 208.It Cd "options UFS_DIRHASH" 209Implements a hash-based lookup scheme for directories 210in order to speed up accesses to very large directories. 211.El 212.Ss Extended Attributes 213.Bl -tag -width 2n 214.It Cd "options UFS_EXTATTR" 215Extended attributes allow the association of 216additional arbitrary metadata with files and directories, 217which can be assigned and retrieved from userland 218as well as from within the kernel; see 219.Xr extattrctl 8 . 220.It Cd "options UFS_EXTATTR_AUTOSTART" 221If this option is defined, 222.Nm 223will search for a 224.Pa .attribute 225subdirectory of the file system root during the mount operation. 226If found, extended attribute support will be 227automatically started for that file system. 228.El 229.Ss GEOM-based Journaling 230.Bl -tag -width 2n 231.It Cd "options UFS_GJOURNAL" 232Implements a block level journaling of a UFS file system, 233which is for both data and metadata. 234To enable this, 235create a 236.Xr gjournal 8 237GEOM provider for a block device by using the 238following command: 239.Pp 240.D1 Nm gjournal label Ar da0 241.Pp 242In this example, 243.Pa /dev/da0 244is used as the target block device, 245and 246.Pa /dev/da0.journal 247is created. 248Then create a new file system by using 249.Xr newfs 8 250with the block level journaling flag and mount it: 251.Pp 252.D1 Nm newfs Fl J Ar /dev/da0.journal 253.D1 Nm mount Fl o Cm async Ar /dev/da0.journal Ar /mnt 254.Pp 255.Cm async 256option is not mandatory but recommended for better performance 257because the journaling guarantees the consistency of an 258.Cm async 259mount. 260.Pp 261It is also possible to enable the block level journaling 262on an existing file system. 263To do so, 264use 265.Xr gjournal 8 266utility to label the underlying block device and 267.Xr tunefs 8 268utility to enable the block level journaling flag: 269.Pp 270.D1 Nm gjournal label Ar da0 271.D1 Nm tunefs Fl J Cm enable Ar /dev/da0.journal 272.D1 Nm mount Fl o Cm async Ar /dev/da0.journal Ar /mnt 273.El 274.Ss Xr sysctl 8 MIBs 275The following 276.Xr sysctl 8 277MIBs are defined for use with 278.Nm : 279.Bl -hang -width ".Va vfs.ffs.doreallocblk" 280.It Va vfs.ffs.doasyncfree 281Asynchronously write out modified i-node and indirect blocks 282upon reallocating file system blocks to be contiguous. 283.Pq Default: 1 . 284.It Va vfs.ffs.doreallocblks 285Enable support for the rearrangement of blocks 286to be contiguous. 287.Pq Default: 1 . 288.El 289.Sh HISTORY 290The 291.Nm 292manual page first appeared in 293.Fx 4.5 . 294.Sh SEE ALSO 295.Xr quota 1 , 296.Xr acl 3 , 297.Xr extattr 3 , 298.Xr edquota 8 , 299.Xr extattrctl 8 , 300.Xr fsck_ffs 8 , 301.Xr sysctl 8 , 302.Xr tunefs 8 303.Rs 304.%A M. McKusick 305.%A W. Joy 306.%A S. Leffler 307.%A R. Fabry 308.%D August 1984 309.%T "A Fast File System for UNIX" 310.%J "ACM Transactions on Computer Systems" 311.%N 2 312.%V 3 313.%P 181-197 314.Re 315.Rs 316.%A M. McKusick 317.%D June 2000 318.%T "Soft Updates: A Technique for Eliminating Most Synchronous Writes in the Fast Filesystem" 319.%J "Proceedings of the Freenix Track at the 1999 Usenix Annual Technical Conference" 320.%P 71-84 321.Re 322.Rs 323.%A M. McKusick 324.%A J. Roberson 325.%D May 2010 326.%T "Journaled Soft-updates" 327.%J "BSD Canada Conference 2010 (BSDCan)" 328.Re 329