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.\" 30.Dd June 9, 1993 31.Dt NFSSVC 2 32.Os 33.Sh NAME 34.Nm nfssvc 35.Nd NFS services 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In sys/param.h 40.In sys/mount.h 41.In sys/time.h 42.In nfs/rpcv2.h 43.In nfsserver/nfs.h 44.In unistd.h 45.Ft int 46.Fn nfssvc "int flags" "void *argstructp" 47.Sh DESCRIPTION 48The 49.Fn nfssvc 50system call is used by the NFS daemons to pass information into and out 51of the kernel and also to enter the kernel as a server daemon. 52The 53.Fa flags 54argument consists of several bits that show what action is to be taken 55once in the kernel and the 56.Fa argstructp 57points to one of three structures depending on which bits are set in 58flags. 59.Pp 60On the client side, 61.Xr nfsiod 8 62calls 63.Fn nfssvc 64with the 65.Fa flags 66argument set to 67.Dv NFSSVC_BIOD 68and 69.Fa argstructp 70set to 71.Dv NULL 72to enter the kernel as a block I/O server daemon. 73For 74.Tn NQNFS , 75.Xr mount_nfs 8 76calls 77.Fn nfssvc 78with the 79.Dv NFSSVC_MNTD 80flag, optionally or'd with the flags 81.Dv NFSSVC_GOTAUTH 82and 83.Dv NFSSVC_AUTHINFAIL 84along with a pointer to a 85.Bd -literal 86struct nfsd_cargs { 87 char *ncd_dirp; /* Mount dir path */ 88 uid_t ncd_authuid; /* Effective uid */ 89 int ncd_authtype; /* Type of authenticator */ 90 int ncd_authlen; /* Length of authenticator string */ 91 u_char *ncd_authstr; /* Authenticator string */ 92 int ncd_verflen; /* and the verifier */ 93 u_char *ncd_verfstr; 94 NFSKERBKEY_T ncd_key; /* Session key */ 95}; 96.Ed 97.Pp 98structure. 99The initial call has only the 100.Dv NFSSVC_MNTD 101flag set to specify service for the mount point. 102If the mount point is using Kerberos, then the 103.Xr mount_nfs 8 104utility will return from 105.Fn nfssvc 106with 107.Va errno 108== 109.Er ENEEDAUTH 110whenever the client side requires an ``rcmd'' 111authentication ticket for the user. 112The 113.Xr mount_nfs 8 114utility will 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 uint32_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 uint32_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 170utility will 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 180utility will 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 242system call 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