1.\" Copyright (c) 1989, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.roff% 5.\" 6.\" @(#)nfssvc.2 8.1 (Berkeley) 06/09/93 7.\" 8.Dd 9.Dt NFSSVC 2 10.Os 11.Sh NAME 12.Nm nfssvc 13.Nd NFS services 14.Sh SYNOPSIS 15.Fd #include <unistd.h> 16.Fd #include <nfs/nfs.h> 17.Ft int 18.Fn nfssvc "int flags" "void *argstructp" 19.Sh DESCRIPTION 20The 21.Fn nfssvc 22function is used by the NFS daemons to pass information into and out 23of the kernel and also to enter the kernel as a server daemon. 24The 25.Fa flags 26argument consists of several bits that show what action is to be taken 27once in the kernel and the 28.Fa argstructp 29points to one of three structures depending on which bits are set in 30flags. 31.Pp 32On the client side, 33.Xr nfsiod 8 34calls 35.Fn nfssvc 36with the 37.Fa flags 38argument set to 39.Dv NFSSVC_BIOD 40and 41.Fa argstructp 42set to 43.Dv NULL 44to enter the kernel as a block I/O server daemon. 45For 46.Nm NQNFS , 47.Xr mount_nfs 8 48calls 49.Fn nfssvc 50with the 51.Dv NFSSVC_MNTD 52flag, optionally or'd with the flags 53.Dv NFSSVC_GOTAUTH 54and 55.Dv NFSSVC_AUTHINFAIL 56along with a pointer to a 57.Bd -literal 58struct nfsd_cargs { 59 char *ncd_dirp; /* Mount dir path */ 60 uid_t ncd_authuid; /* Effective uid */ 61 int ncd_authtype; /* Type of authenticator */ 62 int ncd_authlen; /* Length of authenticator string */ 63 char *ncd_authstr; /* Authenticator string */ 64}; 65.Ed 66.sp 67structure. 68The initial call has only the 69.Dv NFSSVC_MNTD 70flag set to specify service for the mount point. 71If the mount point is using Kerberos, then the 72.Xr mount_nfs 8 73daemon will return from 74.Fn nfssvc 75with errno == ENEEDAUTH whenever the client side requires an ``rcmd'' 76authentication ticket for the user. 77.Xr Mount_nfs 8 78will attempt to get the Kerberos ticket, and if successful will call 79.Fn nfssvc 80with the flags 81.Dv NFSSVC_MNTD 82and 83.Dv NFSSVC_GOTAUTH 84after filling the ticket into the 85ncd_authstr field 86and 87setting the ncd_authlen and ncd_authtype 88fields of the nfsd_cargs structure. 89If 90.Xr mount_nfs 8 91failed to get the ticket, 92.Fn nfssvc 93will be called with the flags 94.Dv NFSSVC_MNTD , 95.Dv NFSSVC_GOTAUTH 96and 97.Dv NFSSVC_AUTHINFAIL 98to denote a failed authentication attempt. 99.Pp 100On the server side, 101.Fn nfssvc 102is called with the flag 103.Dv NFSSVC_NFSD 104and a pointer to a 105.Bd -literal 106struct nfsd_srvargs { 107 struct nfsd *nsd_nfsd; /* Pointer to in kernel nfsd struct */ 108 uid_t nsd_uid; /* Effective uid mapped to cred */ 109 u_long nsd_haddr; /* Ip address of client */ 110 struct ucred nsd_cr; /* Cred. uid maps to */ 111 int nsd_authlen; /* Length of auth string (ret) */ 112 char *nsd_authstr; /* Auth string (ret) */ 113}; 114.Ed 115.sp 116to enter the kernel as an 117.Xr nfsd 8 118daemon. 119Whenever an 120.Xr nfsd 8 121daemon receives a Kerberos authentication ticket, it will return from 122.Fn nfssvc 123with errno == ENEEDAUTH. 124The 125.Xr nfsd 8 126will attempt to authenticate the ticket and generate a set of credentials 127on the server for the ``user id'' specified in the field nsd_uid. 128This is done by first authenticating the Kerberos ticket and then mapping 129the Kerberos principal to a local name and getting a set of credentials for 130that user via. 131.Xr getpwnam 3 132and 133.Xr getgrouplist 3 . 134If successful, the 135.Xr nfsd 8 136will call 137.Fn nfssvc 138with the 139.Dv NFSSVC_NFSD 140and 141.Dv NFSSVC_AUTHIN 142flags set to pass the credential mapping in nsd_cr into the 143kernel to be cached on the server socket for that client. 144If the authentication failed, 145.Xr nfsd 8 146calls 147.Fn nfssvc 148with the flags 149.Dv NFSSVC_NFSD 150and 151.Dv NFSSVC_AUTHINFAIL 152to denote an authentication failure. 153.Pp 154The master 155.Xr nfsd 8 156server daemon calls 157.Fn nfssvc 158with the flag 159.Dv NFSSVC_ADDSOCK 160and a pointer to a 161.Bd -literal 162struct nfsd_args { 163 int sock; /* Socket to serve */ 164 caddr_t name; /* Client address for connection based sockets */ 165 int namelen; /* Length of name */ 166}; 167.Ed 168.sp 169to pass a server side 170.Tn NFS 171socket into the kernel for servicing by the 172.Xr nfsd 8 173daemons. 174.Sh RETURN VALUES 175Normally 176.Nm nfssvc 177does not return unless the server 178is terminated by a signal when a value of 0 is returned. 179Otherwise, -1 is returned and the global variable 180.Va errno 181is set to specify the error. 182.Sh ERRORS 183.Bl -tag -width [ENEEDAUTH] 184.It Bq Er ENEEDAUTH 185This special error value 186is really used for authentication support, particularly Kerberos, 187as explained above. 188.It Bq Er EPERM 189The caller is not the super-user. 190.El 191.Sh SEE ALSO 192.Xr nfsd 8 , 193.Xr mount_nfs 8 , 194.Xr nfsiod 8 195.Sh HISTORY 196The 197.Nm nfssvc 198function first appeared in 4.4BSD. 199.Sh BUGS 200The 201.Nm nfssvc 202system call is designed specifically for the 203.Tn NFS 204support daemons and as such is specific to their requirements. 205It should really return values to indicate the need for authentication 206support, since 207.Dv ENEEDAUTH 208is not really an error. 209Several fields of the argument structures are assumed to be valid and 210sometimes to be unchanged from a previous call, such that 211.Nm nfssvc 212must be used with extreme care. 213