6/lib/libc/sys/nfssvc.2

   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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)nfssvc.2    8.1 (Berkeley) 6/9/93
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd June 9, 1993
  36 .Dt NFSSVC 2
  37 .Os
  38 .Sh NAME
  39 .Nm nfssvc
  40 .Nd NFS services
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In sys/param.h
  45 .In sys/mount.h
  46 .In sys/time.h
  47 .In nfs/rpcv2.h
  48 .In nfs/nfs.h
  49 .In unistd.h
  50 .Ft int
  51 .Fn nfssvc "int flags" "void *argstructp"
  52 .Sh DESCRIPTION
  53 The
  54 .Fn nfssvc
  55 system call is used by the NFS daemons to pass information into and out
  56 of the kernel and also to enter the kernel as a server daemon.
  57 The
  58 .Fa flags
  59 argument consists of several bits that show what action is to be taken
  60 once in the kernel and the
  61 .Fa argstructp
  62 points to one of three structures depending on which bits are set in
  63 flags.
  64 .Pp
  65 On the client side,
  66 .Xr nfsiod 8
  67 calls
  68 .Fn nfssvc
  69 with the
  70 .Fa flags
  71 argument set to
  72 .Dv NFSSVC_BIOD
  73 and
  74 .Fa argstructp
  75 set to
  76 .Dv NULL
  77 to enter the kernel as a block I/O server daemon.
  78 For
  79 .Tn NQNFS ,
  80 .Xr mount_nfs 8
  81 calls
  82 .Fn nfssvc
  83 with the
  84 .Dv NFSSVC_MNTD
  85 flag, optionally or'd with the flags
  86 .Dv NFSSVC_GOTAUTH
  87 and
  88 .Dv NFSSVC_AUTHINFAIL
  89 along with a pointer to a
  90 .Bd -literal
  91 struct nfsd_cargs {
  92         char            *ncd_dirp;      /* Mount dir path */
  93         uid_t           ncd_authuid;    /* Effective uid */
  94         int             ncd_authtype;   /* Type of authenticator */
  95         int             ncd_authlen;    /* Length of authenticator string */
  96         u_char          *ncd_authstr;   /* Authenticator string */
  97         int             ncd_verflen;    /* and the verifier */
  98         u_char          *ncd_verfstr;
  99         NFSKERBKEY_T    ncd_key;        /* Session key */
 100 };
 101 .Ed
 102 .Pp
 103 structure.
 104 The initial call has only the
 105 .Dv NFSSVC_MNTD
 106 flag set to specify service for the mount point.
 107 If the mount point is using Kerberos, then the
 108 .Xr mount_nfs 8
 109 utility will return from
 110 .Fn nfssvc
 111 with
 112 .Va errno
 113 ==
 114 .Er ENEEDAUTH
 115 whenever the client side requires an ``rcmd''
 116 authentication ticket for the user.
 117 The
 118 .Xr mount_nfs 8
 119 utility will attempt to get the Kerberos ticket, and if successful will call
 120 .Fn nfssvc
 121 with the flags
 122 .Dv NFSSVC_MNTD
 123 and
 124 .Dv NFSSVC_GOTAUTH
 125 after filling the ticket into the
 126 ncd_authstr field
 127 and
 128 setting the ncd_authlen and ncd_authtype
 129 fields of the nfsd_cargs structure.
 130 If
 131 .Xr mount_nfs 8
 132 failed to get the ticket,
 133 .Fn nfssvc
 134 will be called with the flags
 135 .Dv NFSSVC_MNTD ,
 136 .Dv NFSSVC_GOTAUTH
 137 and
 138 .Dv NFSSVC_AUTHINFAIL
 139 to denote a failed authentication attempt.
 140 .Pp
 141 On the server side,
 142 .Fn nfssvc
 143 is called with the flag
 144 .Dv NFSSVC_NFSD
 145 and a pointer to a
 146 .Bd -literal
 147 struct nfsd_srvargs {
 148         struct nfsd     *nsd_nfsd;      /* Pointer to in kernel nfsd struct */
 149         uid_t           nsd_uid;        /* Effective uid mapped to cred */
 150         u_int32_t       nsd_haddr;      /* Ip address of client */
 151         struct ucred    nsd_cr;         /* Cred. uid maps to */
 152         int             nsd_authlen;    /* Length of auth string (ret) */
 153         u_char          *nsd_authstr;   /* Auth string (ret) */
 154         int             nsd_verflen;    /* and the verifier */
 155         u_char          *nsd_verfstr;
 156         struct timeval  nsd_timestamp;  /* timestamp from verifier */
 157         u_int32_t       nsd_ttl;        /* credential ttl (sec) */
 158         NFSKERBKEY_T    nsd_key;        /* Session key */
 159 };
 160 .Ed
 161 .Pp
 162 to enter the kernel as an
 163 .Xr nfsd 8
 164 daemon.
 165 Whenever an
 166 .Xr nfsd 8
 167 daemon receives a Kerberos authentication ticket, it will return from
 168 .Fn nfssvc
 169 with
 170 .Va errno
 171 ==
 172 .Er ENEEDAUTH .
 173 The
 174 .Xr nfsd 8
 175 utility will attempt to authenticate the ticket and generate a set of credentials
 176 on the server for the ``user id'' specified in the field nsd_uid.
 177 This is done by first authenticating the Kerberos ticket and then mapping
 178 the Kerberos principal to a local name and getting a set of credentials for
 179 that user via
 180 .Xr getpwnam 3
 181 and
 182 .Xr getgrouplist 3 .
 183 If successful, the
 184 .Xr nfsd 8
 185 utility will call
 186 .Fn nfssvc
 187 with the
 188 .Dv NFSSVC_NFSD
 189 and
 190 .Dv NFSSVC_AUTHIN
 191 flags set to pass the credential mapping in nsd_cr into the
 192 kernel to be cached on the server socket for that client.
 193 If the authentication failed,
 194 .Xr nfsd 8
 195 calls
 196 .Fn nfssvc
 197 with the flags
 198 .Dv NFSSVC_NFSD
 199 and
 200 .Dv NFSSVC_AUTHINFAIL
 201 to denote an authentication failure.
 202 .Pp
 203 The master
 204 .Xr nfsd 8
 205 server daemon calls
 206 .Fn nfssvc
 207 with the flag
 208 .Dv NFSSVC_ADDSOCK
 209 and a pointer to a
 210 .Bd -literal
 211 struct nfsd_args {
 212         int     sock;   /* Socket to serve */
 213         caddr_t name;   /* Client address for connection based sockets */
 214         int     namelen;/* Length of name */
 215 };
 216 .Ed
 217 .Pp
 218 to pass a server side
 219 .Tn NFS
 220 socket into the kernel for servicing by the
 221 .Xr nfsd 8
 222 daemons.
 223 .Sh RETURN VALUES
 224 Normally
 225 .Fn nfssvc
 226 does not return unless the server
 227 is terminated by a signal when a value of 0 is returned.
 228 Otherwise, -1 is returned and the global variable
 229 .Va errno
 230 is set to specify the error.
 231 .Sh ERRORS
 232 .Bl -tag -width Er
 233 .It Bq Er ENEEDAUTH
 234 This special error value
 235 is really used for authentication support, particularly Kerberos,
 236 as explained above.
 237 .It Bq Er EPERM
 238 The caller is not the super-user.
 239 .El
 240 .Sh SEE ALSO
 241 .Xr mount_nfs 8 ,
 242 .Xr nfsd 8 ,
 243 .Xr nfsiod 8
 244 .Sh HISTORY
 245 The
 246 .Fn nfssvc
 247 system call first appeared in
 248 .Bx 4.4 .
 249 .Sh BUGS
 250 The
 251 .Fn nfssvc
 252 system call is designed specifically for the
 253 .Tn NFS
 254 support daemons and as such is specific to their requirements.
 255 It should really return values to indicate the need for authentication
 256 support, since
 257 .Er ENEEDAUTH
 258 is not really an error.
 259 Several fields of the argument structures are assumed to be valid and
 260 sometimes to be unchanged from a previous call, such that
 261 .Fn nfssvc
 262 must be used with extreme care.