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: src/lib/libc/sys/nfssvc.2,v 1.8.2.6 2002/12/29 16:35:34 schweikh Exp $
  34 .\" $DragonFly: src/lib/libc/sys/nfssvc.2,v 1.2 2003/06/17 04:26:47 dillon Exp $
  35 .\"
  36 .Dd June 9, 1993
  37 .Dt NFSSVC 2
  38 .Os
  39 .Sh NAME
  40 .Nm nfssvc
  41 .Nd NFS services
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In sys/param.h
  46 .In sys/mount.h
  47 .In sys/time.h
  48 .In nfs/rpcv2.h
  49 .In nfs/nfs.h
  50 .In unistd.h
  51 .Ft int
  52 .Fn nfssvc "int flags" "void *argstructp"
  53 .Sh DESCRIPTION
  54 The
  55 .Fn nfssvc
  56 function is used by the NFS daemons to pass information into and out
  57 of the kernel and also to enter the kernel as a server daemon.
  58 The
  59 .Fa flags
  60 argument consists of several bits that show what action is to be taken
  61 once in the kernel and the
  62 .Fa argstructp
  63 points to one of three structures depending on which bits are set in
  64 flags.
  65 .Pp
  66 On the client side,
  67 .Xr nfsiod 8
  68 calls
  69 .Fn nfssvc
  70 with the
  71 .Fa flags
  72 argument set to
  73 .Dv NFSSVC_BIOD
  74 and
  75 .Fa argstructp
  76 set to
  77 .Dv NULL
  78 to enter the kernel as a block I/O server daemon.
  79 For
  80 .Nm NQNFS ,
  81 .Xr mount_nfs 8
  82 calls
  83 .Fn nfssvc
  84 with the
  85 .Dv NFSSVC_MNTD
  86 flag, optionally or'd with the flags
  87 .Dv NFSSVC_GOTAUTH
  88 and
  89 .Dv NFSSVC_AUTHINFAIL
  90 along with a pointer to a
  91 .Bd -literal
  92 struct nfsd_cargs {
  93         char            *ncd_dirp;      /* Mount dir path */
  94         uid_t           ncd_authuid;    /* Effective uid */
  95         int             ncd_authtype;   /* Type of authenticator */
  96         int             ncd_authlen;    /* Length of authenticator string */
  97         u_char          *ncd_authstr;   /* Authenticator string */
  98         int             ncd_verflen;    /* and the verifier */
  99         u_char          *ncd_verfstr;
 100         NFSKERBKEY_T    ncd_key;        /* Session key */
 101 };
 102 .Ed
 103 .Pp
 104 structure.
 105 The initial call has only the
 106 .Dv NFSSVC_MNTD
 107 flag set to specify service for the mount point.
 108 If the mount point is using Kerberos, then the
 109 .Xr mount_nfs 8
 110 daemon will return from
 111 .Fn nfssvc
 112 with
 113 .Va errno
 114 ==
 115 .Er ENEEDAUTH
 116 whenever the client side requires an ``rcmd''
 117 authentication ticket for the user.
 118 .Xr Mount_nfs 8
 119 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 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 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 function 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.