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