share/man/man5/fstab.5

   1 .\" Copyright (c) 1980, 1989, 1991, 1993
   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 .Dd April 14, 2014
  29 .Dt FSTAB 5
  30 .Os
  31 .Sh NAME
  32 .Nm fstab
  33 .Nd static information about the file systems
  34 .Sh SYNOPSIS
  35 .In fstab.h
  36 .Sh DESCRIPTION
  37 The file
  38 .Nm
  39 contains descriptive information about the various file
  40 systems.
  41 .Nm
  42 is only read by programs, and not written;
  43 it is the duty of the system administrator to properly create
  44 and maintain this file.
  45 Each file system is described on a separate line;
  46 fields on each line are separated by tabs or spaces.
  47 The order of records in
  48 .Nm
  49 is important because
  50 .Xr fsck 8 ,
  51 .Xr mount 8 ,
  52 and
  53 .Xr umount 8
  54 sequentially iterate through
  55 .Nm
  56 doing their thing.
  57 .Pp
  58 The first field,
  59 .Pq Fa fs_spec ,
  60 describes the special device or
  61 remote file system to be mounted.
  62 The contents are decoded by the
  63 .Xr strunvis 3
  64 function.
  65 This allows using spaces or tabs in the device name which would be
  66 interpreted as field separators otherwise.
  67 .Pp
  68 The second field,
  69 .Pq Fa fs_file ,
  70 describes the mount point for the file system.
  71 For swap partitions, this field should be specified as
  72 .Dq none .
  73 The contents are decoded by the
  74 .Xr strunvis 3
  75 function, as above.
  76 .Pp
  77 The third field,
  78 .Pq Fa fs_vfstype ,
  79 describes the type of the file system.
  80 The system can support various file system types.
  81 Only the root, /usr, and /tmp file systems need be statically
  82 compiled into the kernel;
  83 everything else will be automatically loaded at mount
  84 time.
  85 (Exception: the FFS cannot currently be demand-loaded.)
  86 Some people still prefer to statically
  87 compile other file systems as well.
  88 .Pp
  89 The fourth field,
  90 .Pq Fa fs_mntops ,
  91 describes the mount options associated with the file system.
  92 It is formatted as a comma separated list of options.
  93 It contains at least the type of mount (see
  94 .Fa fs_type
  95 below) plus any additional options appropriate to the file system type.
  96 See the options flag
  97 .Pq Fl o
  98 in the
  99 .Xr mount 8
 100 page and the file system specific page, such as
 101 .Xr mount_nfs 8 ,
 102 for additional options that may be specified.
 103 All options that can be given to the file system specific mount commands
 104 can be used in
 105 .Nm
 106 as well.
 107 They just need to be formatted a bit differently.
 108 The arguments of the
 109 .Fl o
 110 option can be used without the preceding
 111 .Fl o
 112 flag.
 113 Other options need both the file system specific flag and its argument,
 114 separated by an equal sign.
 115 For example, mounting an
 116 .Xr msdosfs 5
 117 filesystem, the options
 118 .Bd -literal -offset indent
 119 -o sync -o noatime -m 644 -M 755 -u foo -g bar
 120 .Ed
 121 .Pp
 122 should be written as
 123 .Bd -literal -offset indent
 124 sync,noatime,-m=644,-M=755,-u=foo,-g=bar
 125 .Ed
 126 .Pp
 127 in the option field of
 128 .Nm .
 129 .Pp
 130 If the options
 131 .Dq userquota
 132 and/or
 133 .Dq groupquota
 134 are specified,
 135 the file system is automatically processed by the
 136 .Xr quotacheck 8
 137 command, and user and/or group disk quotas are enabled with
 138 .Xr quotaon 8 .
 139 By default,
 140 file system quotas are maintained in files named
 141 .Pa quota.user
 142 and
 143 .Pa quota.group
 144 which are located at the root of the associated file system.
 145 These defaults may be overridden by putting an equal sign
 146 and an alternative absolute pathname following the quota option.
 147 Thus, if the user quota file for
 148 .Pa /tmp
 149 is stored in
 150 .Pa /var/quotas/tmp.user ,
 151 this location can be specified as:
 152 .Bd -literal -offset indent
 153 userquota=/var/quotas/tmp.user
 154 .Ed
 155 .Pp
 156 If the option
 157 .Dq failok
 158 is specified,
 159 the system will ignore any error which happens during the mount of that filesystem,
 160 which would otherwise cause the system to drop into single user mode.
 161 This option is implemented by the
 162 .Xr mount 8
 163 command and will not be passed to the kernel.
 164 .Pp
 165 If the option
 166 .Dq noauto
 167 is specified, the file system will not be automatically
 168 mounted at system startup.
 169 Note that, for network file systems
 170 of third party types
 171 (i.e., types supported by additional software
 172 not included in the base system)
 173 to be automatically mounted at system startup,
 174 the
 175 .Va extra_netfs_types
 176 .Xr rc.conf 5
 177 variable must be used to extend the
 178 .Xr rc 8
 179 startup script's list of network file system types.
 180 .Pp
 181 If the option
 182 .Dq late
 183 is specified, the file system will be automatically mounted
 184 at a stage of system startup after remote mount points are mounted.
 185 For more detail about this option,
 186 see the
 187 .Xr mount 8
 188 manual page.
 189 .Pp
 190 If the option
 191 .Dq update
 192 is specified, it indicates that the status of an already mounted file
 193 system should be changed accordingly.
 194 This allows, for example, file systems mounted read-only to be upgraded
 195 read-write and vice-versa.
 196 By default, an entry corresponding to a file systems that is already
 197 mounted is going to be skipped over when processing
 198 .Nm ,
 199 unless it's a root file system, in which case logic similar to
 200 .Dq update
 201 is applied automatically.
 202 .Pp
 203 The
 204 .Dq update
 205 option is typically used in conjunction with two
 206 .Nm
 207 files.
 208 The first
 209 .Nm
 210 file is used to set up the initial set of file systems.
 211 The second
 212 .Nm
 213 file is then run to update the initial set of file systems and
 214 to add additional file systems.
 215 .Pp
 216 The type of the mount is extracted from the
 217 .Fa fs_mntops
 218 field and stored separately in the
 219 .Fa fs_type
 220 field (it is not deleted from the
 221 .Fa fs_mntops
 222 field).
 223 If
 224 .Fa fs_type
 225 is
 226 .Dq rw
 227 or
 228 .Dq ro
 229 then the file system whose name is given in the
 230 .Fa fs_file
 231 field is normally mounted read-write or read-only on the
 232 specified special file.
 233 .Pp
 234 If
 235 .Fa fs_type
 236 is
 237 .Dq sw
 238 then the special file is made available as a piece of swap
 239 space by the
 240 .Xr swapon 8
 241 command at the end of the system reboot procedure.
 242 For swap devices, the keyword
 243 .Dq trimonce
 244 triggers the delivery of a
 245 .Dv BIO_DELETE
 246 command to the device.
 247 This command marks the device's blocks as unused, except those that
 248 might store a disk label.
 249 This marking can erase a crash dump.
 250 To delay
 251 .Nm swapon
 252 for a device until after
 253 .Nm savecore
 254 has copied the crash dump to another location, use the
 255 .Dq late
 256 option.
 257 For vnode-backed swap spaces,
 258 .Dq file
 259 is supported in the
 260 .Fa fs_mntops
 261 field.
 262 When
 263 .Fa fs_spec
 264 is an
 265 .Xr md 4
 266 device file
 267 .Pq Do md Dc or Do md[0-9]* Dc
 268 and
 269 .Dq file
 270 is specified in
 271 .Fa fs_mntopts ,
 272 an
 273 .Xr md 4
 274 device is created with the specified file used as backing store,
 275 and then the new device is used as swap space.
 276 Swap entries on
 277 .Pa .eli
 278 devices will cause automatic creation of encrypted devices.
 279 The
 280 .Dq ealgo ,
 281 .Dq aalgo ,
 282 .Dq keylen ,
 283 .Dq notrim ,
 284 and
 285 .Dq sectorsize
 286 options may be passed to control those
 287 .Xr geli 8
 288 parameters.
 289 The fields other than
 290 .Fa fs_spec
 291 and
 292 .Fa fs_type
 293 are unused.
 294 If
 295 .Fa fs_type
 296 is specified as
 297 .Dq xx
 298 the entry is ignored.
 299 This is useful to show disk partitions which are currently unused.
 300 .Pp
 301 The fifth field,
 302 .Pq Fa fs_freq ,
 303 is used for these file systems by the
 304 .Xr dump 8
 305 command to determine which file systems need to be dumped.
 306 If the fifth field is not present, a value of zero is returned and
 307 .Nm dump
 308 will assume that the file system does not need to be dumped.
 309 If the fifth field is greater than 0, then it specifies the number of days
 310 between dumps for this file system.
 311 .Pp
 312 The sixth field,
 313 .Pq Fa fs_passno ,
 314 is used by the
 315 .Xr fsck 8
 316 and
 317 .Xr quotacheck 8
 318 programs to determine the order in which file system and quota
 319 checks are done at reboot time.
 320 The
 321 .Fa fs_passno
 322 field can be any value between 0 and
 323 .Ql INT_MAX Ns -1 .
 324 .Pp
 325 The root file system should be specified with a
 326 .Fa fs_passno
 327 of 1, and other file systems should have a
 328 .Fa fs_passno
 329 of 2 or greater.
 330 A file system with a
 331 .Fa fs_passno
 332 value of 1 is always checked sequentially and be completed before
 333 another file system is processed, and it will be processed before
 334 all file systems with a larger
 335 .Fa fs_passno .
 336 .Pp
 337 For any given value of
 338 .Fa fs_passno ,
 339 file systems within a drive will be checked sequentially,
 340 but file systems on different drives will be checked at the
 341 same time to utilize parallelism available in the hardware.
 342 Once all file system checks are complete for the current
 343 .Fa fs_passno ,
 344 the same process will start over for the next
 345 .Fa fs_passno .
 346 .Pp
 347 If the sixth field is not present or is zero,
 348 a value of zero is returned and
 349 .Xr fsck 8
 350 and
 351 .Xr quotacheck 8
 352 will assume that the file system does not need to be checked.
 353 .Pp
 354 The
 355 .Fa fs_passno
 356 field can be used to implement finer control when
 357 the system utilities may determine that the file system resides
 358 on a different physical device, when it actually does not, as with a
 359 .Xr ccd 4
 360 device.
 361 All file systems with a lower
 362 .Fa fs_passno
 363 value will be completed before starting on file systems with a
 364 higher
 365 .Fa fs_passno
 366 value.
 367 E.g. all file systems with a
 368 .Fa fs_passno
 369 of 2 will be completed before any file systems with a
 370 .Fa fs_passno
 371 of 3 or greater are started.
 372 Gaps are allowed between the different
 373 .Fa fs_passno
 374 values.
 375 E.g. file systems listed in
 376 .Pa /etc/fstab
 377 may have
 378 .Fa fs_passno
 379 values such as 0, 1, 2, 15, 100, 200, 300, and may appear in any order
 380 within
 381 .Pa /etc/fstab .
 382 .Bd -literal
 383 #define FSTAB_RW        "rw"    /* read/write device */
 384 #define FSTAB_RQ        "rq"    /* read/write with quotas */
 385 #define FSTAB_RO        "ro"    /* read-only device */
 386 #define FSTAB_SW        "sw"    /* swap device */
 387 #define FSTAB_XX        "xx"    /* ignore totally */
 388
 389 struct fstab {
 390         char    *fs_spec;       /* block special device name */
 391         char    *fs_file;       /* file system path prefix */
 392         char    *fs_vfstype;    /* File system type, ufs, nfs */
 393         char    *fs_mntops;     /* Mount options ala -o */
 394         char    *fs_type;       /* FSTAB_* from fs_mntops */
 395         int     fs_freq;        /* dump frequency, in days */
 396         int     fs_passno;      /* pass number on parallel fsck */
 397 };
 398 .Ed
 399 .Pp
 400 The proper way to read records from
 401 .Pa fstab
 402 is to use the routines
 403 .Xr getfsent 3 ,
 404 .Xr getfsspec 3 ,
 405 .Xr getfstype 3 ,
 406 and
 407 .Xr getfsfile 3 .
 408 .Sh FILES
 409 .Bl -tag -width /etc/fstab -compact
 410 .It Pa /etc/fstab
 411 The file
 412 .Nm
 413 resides in
 414 .Pa /etc .
 415 .El
 416 .Sh EXAMPLES
 417 .Bd -literal
 418 # Device        Mountpoint      FStype  Options         Dump    Pass#
 419 #
 420 # UFS file system.
 421 /dev/da0p2      /               ufs     rw              1       1
 422 #
 423 # Swap space on a block device.
 424 /dev/da0p1      none            swap    sw              0       0
 425 #
 426 # Swap space using a block device with GBDE/GELI encryption.
 427 # aalgo, ealgo, keylen, sectorsize options are available
 428 # for .eli devices.
 429 /dev/da1p1.bde  none            swap    sw              0       0
 430 /dev/da1p2.eli  none            swap    sw              0       0
 431 #
 432 # tmpfs.
 433 tmpfs           /tmp            tmpfs   rw,size=1g,mode=1777    0 0
 434 #
 435 # UFS file system on a swap-backed md(4).  /dev/md10 is
 436 # automatically created.  If it is "md", a unit number
 437 # will be automatically selected.
 438 md10            /scratch        mfs     rw,-s1g         0       0
 439 #
 440 # Swap space on a vnode-backed md(4).
 441 md11            none            swap    sw,file=/swapfile       0 0
 442 #
 443 # CDROM.  "noauto" option is typically used because the
 444 # media is removable.
 445 /dev/cd0        /cdrom          cd9660  ro,noauto       0       0
 446 #
 447 # NFS-exported file system.  "serv" is an NFS server name
 448 # or IP address.
 449 serv:/export    /nfs            nfs     rw,noinet6      0       0
 450 .Ed
 451 .Sh SEE ALSO
 452 .Xr getfsent 3 ,
 453 .Xr getvfsbyname 3 ,
 454 .Xr strunvis 3 ,
 455 .Xr ccd 4 ,
 456 .Xr dump 8 ,
 457 .Xr fsck 8 ,
 458 .Xr geli 8 ,
 459 .Xr mount 8 ,
 460 .Xr quotacheck 8 ,
 461 .Xr quotaon 8 ,
 462 .Xr swapon 8 ,
 463 .Xr umount 8
 464 .Sh HISTORY
 465 The
 466 .Nm
 467 file format appeared in
 468 .Bx 4.0 .