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$ 30.\" 31.Dd June 9, 1993 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 nfs/rpcv2.h 44.In nfsserver/nfs.h 45.In unistd.h 46.Ft int 47.Fn nfssvc "int flags" "void *argstructp" 48.Sh DESCRIPTION 49The 50.Fn nfssvc 51system call is used by the NFS daemons to pass information into and out 52of the kernel and also to enter the kernel as a server daemon. 53The 54.Fa flags 55argument consists of several bits that show what action is to be taken 56once in the kernel and the 57.Fa argstructp 58points to one of three structures depending on which bits are set in 59flags. 60.Pp 61On the client side, 62.Xr nfsiod 8 63calls 64.Fn nfssvc 65with the 66.Fa flags 67argument set to 68.Dv NFSSVC_BIOD 69and 70.Fa argstructp 71set to 72.Dv NULL 73to enter the kernel as a block I/O server daemon. 74For 75.Tn NQNFS , 76.Xr mount_nfs 8 77calls 78.Fn nfssvc 79with the 80.Dv NFSSVC_MNTD 81flag, optionally or'd with the flags 82.Dv NFSSVC_GOTAUTH 83and 84.Dv NFSSVC_AUTHINFAIL 85along with a pointer to a 86.Bd -literal 87struct 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 99structure. 100The initial call has only the 101.Dv NFSSVC_MNTD 102flag set to specify service for the mount point. 103If the mount point is using Kerberos, then the 104.Xr mount_nfs 8 105utility will return from 106.Fn nfssvc 107with 108.Va errno 109== 110.Er ENEEDAUTH 111whenever the client side requires an ``rcmd'' 112authentication ticket for the user. 113The 114.Xr mount_nfs 8 115utility will 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 uint32_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 uint32_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 171utility will 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 181utility will 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 243system call 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