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