lib/libcr/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: src/lib/libc/sys/nfssvc.2,v 1.8.2.6 2002/12/29 16:35:34 schweikh Exp $
  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 function 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 .Nm 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 daemon 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 .Xr Mount_nfs 8
 118 will attempt to get the Kerberos ticket, and if successful will call
 119 .Fn nfssvc
 120 with the flags
 121 .Dv NFSSVC_MNTD
 122 and
 123 .Dv NFSSVC_GOTAUTH
 124 after filling the ticket into the
 125 ncd_authstr field
 126 and
 127 setting the ncd_authlen and ncd_authtype
 128 fields of the nfsd_cargs structure.
 129 If
 130 .Xr mount_nfs 8
 131 failed to get the ticket,
 132 .Fn nfssvc
 133 will be called with the flags
 134 .Dv NFSSVC_MNTD ,
 135 .Dv NFSSVC_GOTAUTH
 136 and
 137 .Dv NFSSVC_AUTHINFAIL
 138 to denote a failed authentication attempt.
 139 .Pp
 140 On the server side,
 141 .Fn nfssvc
 142 is called with the flag
 143 .Dv NFSSVC_NFSD
 144 and a pointer to a
 145 .Bd -literal
 146 struct nfsd_srvargs {
 147         struct nfsd     *nsd_nfsd;      /* Pointer to in kernel nfsd struct */
 148         uid_t           nsd_uid;        /* Effective uid mapped to cred */
 149         u_int32_t       nsd_haddr;      /* Ip address of client */
 150         struct ucred    nsd_cr;         /* Cred. uid maps to */
 151         int             nsd_authlen;    /* Length of auth string (ret) */
 152         u_char          *nsd_authstr;   /* Auth string (ret) */
 153         int             nsd_verflen;    /* and the verifier */
 154         u_char          *nsd_verfstr;
 155         struct timeval  nsd_timestamp;  /* timestamp from verifier */
 156         u_int32_t       nsd_ttl;        /* credential ttl (sec) */
 157         NFSKERBKEY_T    nsd_key;        /* Session key */
 158 };
 159 .Ed
 160 .Pp
 161 to enter the kernel as an
 162 .Xr nfsd 8
 163 daemon.
 164 Whenever an
 165 .Xr nfsd 8
 166 daemon receives a Kerberos authentication ticket, it will return from
 167 .Fn nfssvc
 168 with
 169 .Va errno
 170 ==
 171 .Er ENEEDAUTH .
 172 The
 173 .Xr nfsd 8
 174 will attempt to authenticate the ticket and generate a set of credentials
 175 on the server for the ``user id'' specified in the field nsd_uid.
 176 This is done by first authenticating the Kerberos ticket and then mapping
 177 the Kerberos principal to a local name and getting a set of credentials for
 178 that user via.
 179 .Xr getpwnam 3
 180 and
 181 .Xr getgrouplist 3 .
 182 If successful, the
 183 .Xr nfsd 8
 184 will call
 185 .Fn nfssvc
 186 with the
 187 .Dv NFSSVC_NFSD
 188 and
 189 .Dv NFSSVC_AUTHIN
 190 flags set to pass the credential mapping in nsd_cr into the
 191 kernel to be cached on the server socket for that client.
 192 If the authentication failed,
 193 .Xr nfsd 8
 194 calls
 195 .Fn nfssvc
 196 with the flags
 197 .Dv NFSSVC_NFSD
 198 and
 199 .Dv NFSSVC_AUTHINFAIL
 200 to denote an authentication failure.
 201 .Pp
 202 The master
 203 .Xr nfsd 8
 204 server daemon calls
 205 .Fn nfssvc
 206 with the flag
 207 .Dv NFSSVC_ADDSOCK
 208 and a pointer to a
 209 .Bd -literal
 210 struct nfsd_args {
 211         int     sock;   /* Socket to serve */
 212         caddr_t name;   /* Client address for connection based sockets */
 213         int     namelen;/* Length of name */
 214 };
 215 .Ed
 216 .Pp
 217 to pass a server side
 218 .Tn NFS
 219 socket into the kernel for servicing by the
 220 .Xr nfsd 8
 221 daemons.
 222 .Sh RETURN VALUES
 223 Normally
 224 .Fn nfssvc
 225 does not return unless the server
 226 is terminated by a signal when a value of 0 is returned.
 227 Otherwise, -1 is returned and the global variable
 228 .Va errno
 229 is set to specify the error.
 230 .Sh ERRORS
 231 .Bl -tag -width Er
 232 .It Bq Er ENEEDAUTH
 233 This special error value
 234 is really used for authentication support, particularly Kerberos,
 235 as explained above.
 236 .It Bq Er EPERM
 237 The caller is not the super-user.
 238 .El
 239 .Sh SEE ALSO
 240 .Xr mount_nfs 8 ,
 241 .Xr nfsd 8 ,
 242 .Xr nfsiod 8
 243 .Sh HISTORY
 244 The
 245 .Fn nfssvc
 246 function first appeared in
 247 .Bx 4.4 .
 248 .Sh BUGS
 249 The
 250 .Fn nfssvc
 251 system call is designed specifically for the
 252 .Tn NFS
 253 support daemons and as such is specific to their requirements.
 254 It should really return values to indicate the need for authentication
 255 support, since
 256 .Er ENEEDAUTH
 257 is not really an error.
 258 Several fields of the argument structures are assumed to be valid and
 259 sometimes to be unchanged from a previous call, such that
 260 .Fn nfssvc
 261 must be used with extreme care.