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