bsd/man/man2/nfssvc.2

   1 .\"     $NetBSD: nfssvc.2,v 1.6 1995/02/27 12:35:08 cgd Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)nfssvc.2    8.1 (Berkeley) 6/9/93
  35 .\"
  36 .Dd June 9, 1993
  37 .Dt NFSSVC 2
  38 .Os
  39 .Sh NAME
  40 .Nm nfssvc
  41 .Nd NFS services
  42 .Sh SYNOPSIS
  43 .Fd #include <unistd.h>
  44 .Fd #include <nfs/nfs.h>
  45 .Ft int
  46 .Fn nfssvc "int flags" "void *argstructp"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn nfssvc
  50 function is used by the NFS daemons to pass information into and out
  51 of the kernel and also to enter the kernel as a server daemon.
  52 The
  53 .Fa flags
  54 argument consists of several bits that show what action is to be taken
  55 once in the kernel and the
  56 .Fa argstructp
  57 points to one of three structures depending on which bits are set in
  58 flags.
  59 .Pp
  60 On the client side,
  61 .Xr nfsiod 8
  62 calls
  63 .Fn nfssvc
  64 with the
  65 .Fa flags
  66 argument set to
  67 .Dv NFSSVC_BIOD
  68 and
  69 .Fa argstructp
  70 set to
  71 .Dv NULL
  72 to enter the kernel as a block I/O server daemon.
  73 For
  74 .Nm NQNFS ,
  75 .Xr mount_nfs 8
  76 calls
  77 .Fn nfssvc
  78 with the
  79 .Dv NFSSVC_MNTD
  80 flag, optionally or'd with the flags
  81 .Dv NFSSVC_GOTAUTH
  82 and
  83 .Dv NFSSVC_AUTHINFAIL
  84 along with a pointer to a
  85 .Bd -literal
  86 struct nfsd_cargs {
  87         char            *ncd_dirp;      /* Mount dir path */
  88         uid_t           ncd_authuid;    /* Effective uid */
  89         int             ncd_authtype;   /* Type of authenticator */
  90         int             ncd_authlen;    /* Length of authenticator string */
  91         char            *ncd_authstr;   /* Authenticator string */
  92 };
  93 .Ed
  94 .sp
  95 structure.
  96 The initial call has only the
  97 .Dv NFSSVC_MNTD
  98 flag set to specify service for the mount point.
  99 If the mount point is using Kerberos, then the
 100 .Xr mount_nfs 8
 101 daemon will return from
 102 .Fn nfssvc
 103 with errno == ENEEDAUTH whenever the client side requires an ``rcmd''
 104 authentication ticket for the user.
 105 .Xr Mount_nfs 8
 106 will attempt to get the Kerberos ticket, and if successful will call
 107 .Fn nfssvc
 108 with the flags
 109 .Dv NFSSVC_MNTD
 110 and
 111 .Dv NFSSVC_GOTAUTH
 112 after filling the ticket into the
 113 ncd_authstr field
 114 and
 115 setting the ncd_authlen and ncd_authtype
 116 fields of the nfsd_cargs structure.
 117 If
 118 .Xr mount_nfs 8
 119 failed to get the ticket,
 120 .Fn nfssvc
 121 will be called with the flags
 122 .Dv NFSSVC_MNTD ,
 123 .Dv NFSSVC_GOTAUTH
 124 and
 125 .Dv NFSSVC_AUTHINFAIL
 126 to denote a failed authentication attempt.
 127 .Pp
 128 On the server side,
 129 .Fn nfssvc
 130 is called with the flag
 131 .Dv NFSSVC_NFSD
 132 and a pointer to a
 133 .Bd -literal
 134 struct nfsd_srvargs {
 135         struct nfsd     *nsd_nfsd;      /* Pointer to in kernel nfsd struct */
 136         uid_t           nsd_uid;        /* Effective uid mapped to cred */
 137         u_long          nsd_haddr;      /* Ip address of client */
 138         struct ucred    nsd_cr;         /* Cred. uid maps to */
 139         int             nsd_authlen;    /* Length of auth string (ret) */
 140         char            *nsd_authstr;   /* Auth string (ret) */
 141 };
 142 .Ed
 143 .sp
 144 to enter the kernel as an
 145 .Xr nfsd 8
 146 daemon.
 147 Whenever an
 148 .Xr nfsd 8
 149 daemon receives a Kerberos authentication ticket, it will return from
 150 .Fn nfssvc
 151 with errno == ENEEDAUTH.
 152 The
 153 .Xr nfsd 8
 154 will attempt to authenticate the ticket and generate a set of credentials
 155 on the server for the ``user id'' specified in the field nsd_uid.
 156 This is done by first authenticating the Kerberos ticket and then mapping
 157 the Kerberos principal to a local name and getting a set of credentials for
 158 that user via.
 159 .Xr getpwnam 3
 160 and
 161 .Xr getgrouplist 3 .
 162 If successful, the
 163 .Xr nfsd 8
 164 will call
 165 .Fn nfssvc
 166 with the
 167 .Dv NFSSVC_NFSD
 168 and
 169 .Dv NFSSVC_AUTHIN
 170 flags set to pass the credential mapping in nsd_cr into the
 171 kernel to be cached on the server socket for that client.
 172 If the authentication failed,
 173 .Xr nfsd 8
 174 calls
 175 .Fn nfssvc
 176 with the flags
 177 .Dv NFSSVC_NFSD
 178 and
 179 .Dv NFSSVC_AUTHINFAIL
 180 to denote an authentication failure.
 181 .Pp
 182 The master
 183 .Xr nfsd 8
 184 server daemon calls
 185 .Fn nfssvc
 186 with the flag
 187 .Dv NFSSVC_ADDSOCK
 188 and a pointer to a
 189 .Bd -literal
 190 struct nfsd_args {
 191         int     sock;           /* Socket to serve */
 192         caddr_t name;           /* Client address for connection based sockets */
 193         int     namelen;        /* Length of name */
 194 };
 195 .Ed
 196 .sp
 197 to pass a server side
 198 .Tn NFS
 199 socket into the kernel for servicing by the
 200 .Xr nfsd 8
 201 daemons.
 202 .Sh RETURN VALUES
 203 Normally
 204 .Nm nfssvc
 205 does not return unless the server
 206 is terminated by a signal when a value of 0 is returned.
 207 Otherwise, -1 is returned and the global variable
 208 .Va errno
 209 is set to specify the error.
 210 .Sh ERRORS
 211 .Bl -tag -width Er
 212 .It Bq Er ENEEDAUTH
 213 This special error value
 214 is really used for authentication support, particularly Kerberos,
 215 as explained above.
 216 .It Bq Er EPERM
 217 The caller is not the super-user.
 218 .El
 219 .Sh SEE ALSO
 220 .Xr nfsd 8 ,
 221 .Xr mount_nfs 8 ,
 222 .Xr nfsiod 8
 223 .Sh HISTORY
 224 The
 225 .Nm nfssvc
 226 function first appeared in 4.4BSD.
 227 .Sh BUGS
 228 The
 229 .Nm nfssvc
 230 system call is designed specifically for the
 231 .Tn NFS
 232 support daemons and as such is specific to their requirements.
 233 It should really return values to indicate the need for authentication
 234 support, since
 235 .Dv ENEEDAUTH
 236 is not really an error.
 237 Several fields of the argument structures are assumed to be valid and
 238 sometimes to be unchanged from a previous call, such that
 239 .Nm nfssvc
 240 must be used with extreme care.