sbin/mountd/exports.5

   1 .\" Copyright (c) 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 .\"     @(#)exports.5   8.3 (Berkeley) 3/29/95
  29 .\" $FreeBSD: src/sbin/mountd/exports.5,v 1.10.2.8 2002/09/28 16:31:45 markm Exp $
  30 .\" $DragonFly: src/sbin/mountd/exports.5,v 1.5 2007/11/23 23:16:36 swildner Exp $
  31 .\"
  32 .Dd March 29, 1995
  33 .Dt EXPORTS 5
  34 .Os
  35 .Sh NAME
  36 .Nm exports
  37 .Nd define remote mount points for
  38 .Tn NFS
  39 mount requests
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 file specifies remote mount points for the
  46 .Tn NFS
  47 mount protocol per the
  48 .Tn NFS
  49 server specification; see
  50 .%T "Network File System Protocol Specification" ,
  51 RFC 1094, Appendix A and
  52 .%T "NFS: Network File System Version 3 Specification" ,
  53 Appendix I.
  54 .Pp
  55 Each line in the file
  56 (other than comment lines that begin with a #)
  57 specifies the mount point(s) and export flags within one local server
  58 filesystem for one or more hosts.
  59 A host may be specified only once for each local filesystem on the
  60 server and there may be only one default entry for each server
  61 filesystem that applies to all other hosts.
  62 The latter exports the filesystem to the ``world'' and should
  63 be used only when the filesystem contains public information.
  64 .Pp
  65 In a mount entry,
  66 the first field(s) specify the directory path(s) within a server filesystem
  67 that can be mounted on by the corresponding client(s).
  68 There are two forms of this specification.
  69 The first is to list all mount points as absolute
  70 directory paths separated by whitespace.
  71 The second is to specify the pathname of the root of the filesystem
  72 followed by the
  73 .Fl alldirs
  74 flag;
  75 this form allows the host(s) to mount at any point within the filesystem,
  76 including regular files if the
  77 .Fl r
  78 option is used on
  79 .Xr mountd 8 .
  80 The pathnames must not have any symbolic links in them and should not have
  81 any "." or ".." components.
  82 Mount points for a filesystem may appear on multiple lines each with
  83 different sets of hosts and export options.
  84 .Pp
  85 The second component of a line specifies how the filesystem is to be
  86 exported to the host set.
  87 The option flags specify whether the filesystem
  88 is exported read-only or read-write and how the client uid is mapped to
  89 user credentials on the server.
  90 .Pp
  91 Export options are specified as follows:
  92 .Pp
  93 .Sm off
  94 .Fl maproot No = Sy user
  95 .Sm on
  96 The credential of the specified user is used for remote access by root.
  97 The credential includes all the groups to which the user is a member
  98 on the local machine (see
  99 .Xr id 1 ) .
 100 The user may be specified by name or number.
 101 .Pp
 102 .Sm off
 103 .Fl maproot No = Sy user:group1:group2:...
 104 .Sm on
 105 The colon separated list is used to specify the precise credential
 106 to be used for remote access by root.
 107 The elements of the list may be either names or numbers.
 108 Note that user: should be used to distinguish a credential containing
 109 no groups from a complete credential for that user.
 110 .Pp
 111 .Sm off
 112 .Fl mapall No = Sy user
 113 .Sm on
 114 or
 115 .Sm off
 116 .Fl mapall No = Sy user:group1:group2:...
 117 .Sm on
 118 specifies a mapping for all client uids (including root)
 119 using the same semantics as
 120 .Fl maproot .
 121 .Pp
 122 The option
 123 .Fl r
 124 is a synonym for
 125 .Fl maproot
 126 in an effort to be backward compatible with older export file formats.
 127 .Pp
 128 In the absence of
 129 .Fl maproot
 130 and
 131 .Fl mapall
 132 options, remote accesses by root will result in using a credential of -2:-2.
 133 All other users will be mapped to their remote credential.
 134 If a
 135 .Fl maproot
 136 option is given,
 137 remote access by root will be mapped to that credential instead of -2:-2.
 138 If a
 139 .Fl mapall
 140 option is given,
 141 all users (including root) will be mapped to that credential in
 142 place of their own.
 143 .Pp
 144 The
 145 .Fl ro
 146 option specifies that the filesystem should be exported read-only
 147 (default read/write).
 148 The option
 149 .Fl o
 150 is a synonym for
 151 .Fl ro
 152 in an effort to be backward compatible with older export file formats.
 153 .Pp
 154 .Tn WebNFS
 155 exports strictly according to the spec (RFC 2054 and RFC 2055) can
 156 be done with the
 157 .Fl public
 158 flag.
 159 However, this flag in itself allows r/w access to all files in
 160 the filesystem, not requiring reserved ports and not remapping uids.
 161 It
 162 is only provided to conform to the spec, and should normally not be used.
 163 For a
 164 .Tn WebNFS
 165 export,
 166 use the
 167 .Fl webnfs
 168 flag, which implies
 169 .Fl public ,
 170 .Sm off
 171 .Fl mapall No = Sy nobody
 172 .Sm on
 173 and
 174 .Fl ro .
 175 .Pp
 176 A
 177 .Sm off
 178 .Fl index No = Sy file
 179 .Sm on
 180 option can be used to specify a file whose handle will be returned if
 181 a directory is looked up using the public filehandle
 182 .Pq Tn WebNFS .
 183 This is to mimic the behavior of URLs.
 184 If no
 185 .Fl index
 186 option is specified, a directory filehandle will be returned as usual.
 187 The
 188 .Fl index
 189 option only makes sense in combination with the
 190 .Fl public
 191 or
 192 .Fl webnfs
 193 flags.
 194 .Pp
 195 Specifying the
 196 .Fl quiet
 197 option will inhibit some of the syslog diagnostics for bad lines in
 198 .Pa /etc/exports .
 199 This can be useful to avoid annoying error messages for known possible
 200 problems (see
 201 .Sx EXAMPLES
 202 below).
 203 .Pp
 204 The third component of a line specifies the host set to which the line applies.
 205 The set may be specified in three ways.
 206 The first way is to list the host name(s) separated by white space.
 207 (Standard Internet ``dot'' addresses may be used in place of names.)
 208 The second way is to specify a ``netgroup'' as defined in the netgroup file (see
 209 .Xr netgroup 5 ) .
 210 The third way is to specify an Internet subnetwork using a network and
 211 network mask that is defined as the set of all hosts with addresses within
 212 the subnetwork.
 213 This latter approach requires less overhead within the
 214 kernel and is recommended for cases where the export line refers to a
 215 large number of clients within an administrative subnet.
 216 .Pp
 217 The first two cases are specified by simply listing the name(s) separated
 218 by whitespace.
 219 All names are checked to see if they are ``netgroup'' names
 220 first and are assumed to be hostnames otherwise.
 221 Using the full domain specification for a hostname can normally
 222 circumvent the problem of a host that has the same name as a netgroup.
 223 The third case is specified by the flag
 224 .Sm off
 225 .Fl network No = Sy netname
 226 .Sm on
 227 and optionally
 228 .Sm off
 229 .Fl mask No = Sy netmask .
 230 .Sm on
 231 If the mask is not specified, it will default to the mask for that network
 232 class (A, B or C; see
 233 .Xr inet 4 ) .
 234 See the
 235 .Sx EXAMPLES
 236 section below.
 237 .Pp
 238 The
 239 .Xr mountd 8
 240 utility can be made to re-read the
 241 .Nm
 242 file by sending it a hangup signal as follows:
 243 .Bd -literal -offset indent
 244 kill -s HUP `cat /var/run/mountd.pid`
 245 .Ed
 246 .Pp
 247 After sending the
 248 .Dv SIGHUP ,
 249 check the
 250 .Xr syslogd 8
 251 output to see whether
 252 .Xr mountd 8
 253 logged any parsing errors in the
 254 .Nm
 255 file.
 256 .Sh FILES
 257 .Bl -tag -width /etc/exports -compact
 258 .It Pa /etc/exports
 259 the default remote mount-point file
 260 .El
 261 .Sh EXAMPLES
 262 .Bd -literal -offset indent
 263 /usr /usr/local -maproot=0:10 friends
 264 /usr -maproot=daemon grumpy.cis.uoguelph.ca 131.104.48.16
 265 /usr -ro -mapall=nobody
 266 /u -maproot=bin: -network 131.104.48 -mask 255.255.255.0
 267 /u2 -maproot=root friends
 268 /u2 -alldirs -network cis-net -mask cis-mask
 269 /cdrom -alldirs,quiet,ro -network 192.168.33.0 -mask 255.255.255.0
 270 .Ed
 271 .Pp
 272 Given that
 273 .Pa /usr ,
 274 .Pa /u
 275 and
 276 .Pa /u2
 277 are
 278 local filesystem mount points, the above example specifies the following:
 279 .Pa /usr
 280 is exported to hosts
 281 .Em friends
 282 where friends is specified in the netgroup file
 283 with users mapped to their remote credentials and
 284 root mapped to uid 0 and group 10.
 285 It is exported read-write and the hosts in ``friends'' can mount either /usr
 286 or /usr/local.
 287 It is exported to
 288 .Em 131.104.48.16
 289 and
 290 .Em grumpy.cis.uoguelph.ca
 291 with users mapped to their remote credentials and
 292 root mapped to the user and groups associated with ``daemon'';
 293 it is exported to the rest of the world as read-only with
 294 all users mapped to the user and groups associated with ``nobody''.
 295 .Pp
 296 .Pa /u
 297 is exported to all hosts on the subnetwork
 298 .Em 131.104.48
 299 with root mapped to the uid for ``bin'' and with no group access.
 300 .Pp
 301 .Pa /u2
 302 is exported to the hosts in ``friends'' with root mapped to uid and groups
 303 associated with ``root'';
 304 it is exported to all hosts on network ``cis-net'' allowing mounts at any
 305 directory within /u2.
 306 .Pp
 307 The filesystem rooted at
 308 .Pa /cdrom
 309 will exported read-only to the entire network 192.168.33.0/24, including
 310 all its subdirectories.
 311 Since
 312 .Pa /cdrom
 313 is the conventional mountpoint for a CD-ROM device, this export will
 314 fail if no CD-ROM medium is currently mounted there since that line
 315 would then attempt to export a subdirectory of the root filesystem
 316 with the
 317 .Fl alldirs
 318 option which is not allowed.
 319 The
 320 .Fl quiet
 321 option will then suppress the error message for this condition that
 322 would normally be syslogged.
 323 As soon as an actual CD-ROM is going to be mounted,
 324 .Xr mount 8
 325 will notify
 326 .Xr mountd 8
 327 about this situation, and the
 328 .Pa /cdrom
 329 filesystem will be exported as intended.
 330 Note that without using the
 331 .Fl alldirs
 332 option, the export would always succeed.
 333 While there is no CD-ROM medium mounted under
 334 .Pa /cdrom ,
 335 it would export the (normally empty) directory
 336 .Pa /cdrom
 337 of the root filesystem instead.
 338 .Sh SEE ALSO
 339 .Xr netgroup 5 ,
 340 .Xr mountd 8 ,
 341 .Xr nfsd 8 ,
 342 .Xr showmount 8
 343 .Sh BUGS
 344 The export options are tied to the local mount points in the kernel and
 345 must be non-contradictory for any exported subdirectory of the local
 346 server mount point.
 347 It is recommended that all exported directories within the same server
 348 filesystem be specified on adjacent lines going down the tree.
 349 You cannot specify a hostname that is also the name of a netgroup.
 350 Specifying the full domain specification for a hostname can normally
 351 circumvent the problem.