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