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.\" 31.Dd February 21, 2020 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 vfs/nfs/rpcv2.h 44.In vfs/nfs/nfs.h 45.In unistd.h 46.Ft int 47.Fn nfssvc "int flags" "void *argstructp" 48.Sh DESCRIPTION 49The 50.Fn nfssvc 51function 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.Nm 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 105daemon 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. 113.Xr Mount_nfs 8 114will attempt to get the Kerberos ticket, and if successful will call 115.Fn nfssvc 116with the flags 117.Dv NFSSVC_MNTD 118and 119.Dv NFSSVC_GOTAUTH 120after filling the ticket into the 121ncd_authstr field 122and 123setting the ncd_authlen and ncd_authtype 124fields of the nfsd_cargs structure. 125If 126.Xr mount_nfs 8 127failed to get the ticket, 128.Fn nfssvc 129will be called with the flags 130.Dv NFSSVC_MNTD , 131.Dv NFSSVC_GOTAUTH 132and 133.Dv NFSSVC_AUTHINFAIL 134to denote a failed authentication attempt. 135.Pp 136On the server side, 137.Fn nfssvc 138is called with the flag 139.Dv NFSSVC_NFSD 140and a pointer to a 141.Bd -literal 142struct nfsd_srvargs { 143 struct nfsd *nsd_nfsd; /* Pointer to in kernel nfsd struct */ 144 uid_t nsd_uid; /* Effective uid mapped to cred */ 145 u_int32_t nsd_haddr; /* Ip address of client */ 146 struct ucred nsd_cr; /* Cred. uid maps to */ 147 int nsd_authlen; /* Length of auth string (ret) */ 148 u_char *nsd_authstr; /* Auth string (ret) */ 149 int nsd_verflen; /* and the verifier */ 150 u_char *nsd_verfstr; 151 struct timeval nsd_timestamp; /* timestamp from verifier */ 152 u_int32_t nsd_ttl; /* credential ttl (sec) */ 153 NFSKERBKEY_T nsd_key; /* Session key */ 154}; 155.Ed 156.Pp 157to enter the kernel as an 158.Xr nfsd 8 159daemon. 160Whenever an 161.Xr nfsd 8 162daemon receives a Kerberos authentication ticket, it will return from 163.Fn nfssvc 164with 165.Va errno 166== 167.Er ENEEDAUTH . 168The 169.Xr nfsd 8 170will attempt to authenticate the ticket and generate a set of credentials 171on the server for the ``user id'' specified in the field nsd_uid. 172This is done by first authenticating the Kerberos ticket and then mapping 173the Kerberos principal to a local name and getting a set of credentials for 174that user via. 175.Xr getpwnam 3 176and 177.Xr getgrouplist 3 . 178If successful, the 179.Xr nfsd 8 180will call 181.Fn nfssvc 182with the 183.Dv NFSSVC_NFSD 184and 185.Dv NFSSVC_AUTHIN 186flags set to pass the credential mapping in nsd_cr into the 187kernel to be cached on the server socket for that client. 188If the authentication failed, 189.Xr nfsd 8 190calls 191.Fn nfssvc 192with the flags 193.Dv NFSSVC_NFSD 194and 195.Dv NFSSVC_AUTHINFAIL 196to denote an authentication failure. 197.Pp 198The master 199.Xr nfsd 8 200server daemon calls 201.Fn nfssvc 202with the flag 203.Dv NFSSVC_ADDSOCK 204and a pointer to a 205.Bd -literal 206struct nfsd_args { 207 int sock; /* Socket to serve */ 208 caddr_t name; /* Client address for connection based sockets */ 209 int namelen;/* Length of name */ 210}; 211.Ed 212.Pp 213to pass a server side 214.Tn NFS 215socket into the kernel for servicing by the 216.Xr nfsd 8 217daemons. 218.Sh RETURN VALUES 219Normally 220.Fn nfssvc 221does not return unless the server 222is terminated by a signal when a value of 0 is returned. 223Otherwise, -1 is returned and the global variable 224.Va errno 225is set to specify the error. 226.Sh ERRORS 227.Bl -tag -width Er 228.It Bq Er ENEEDAUTH 229This special error value 230is really used for authentication support, particularly Kerberos, 231as explained above. 232.It Bq Er EPERM 233The caller is not the super-user. 234.El 235.Sh SEE ALSO 236.Xr mount_nfs 8 , 237.Xr nfsd 8 , 238.Xr nfsiod 8 239.Sh HISTORY 240The 241.Fn nfssvc 242function first appeared in 243.Bx 4.4 . 244.Sh BUGS 245The 246.Fn nfssvc 247system call is designed specifically for the 248.Tn NFS 249support daemons and as such is specific to their requirements. 250It should really return values to indicate the need for authentication 251support, since 252.Er ENEEDAUTH 253is not really an error. 254Several fields of the argument structures are assumed to be valid and 255sometimes to be unchanged from a previous call, such that 256.Fn nfssvc 257must be used with extreme care. 258