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