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