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