share/man/man7/ffs.7

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