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