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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)nfssvc.2 8.1 (Berkeley) 6/9/93 33.\" $FreeBSD: src/lib/libc/sys/nfssvc.2,v 1.8.2.6 2002/12/29 16:35:34 schweikh Exp $ 34.\" $DragonFly: src/lib/libc/sys/nfssvc.2,v 1.2 2003/06/17 04:26:47 dillon Exp $ 35.\" 36.Dd June 9, 1993 37.Dt NFSSVC 2 38.Os 39.Sh NAME 40.Nm nfssvc 41.Nd NFS services 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In sys/param.h 46.In sys/mount.h 47.In sys/time.h 48.In nfs/rpcv2.h 49.In nfs/nfs.h 50.In unistd.h 51.Ft int 52.Fn nfssvc "int flags" "void *argstructp" 53.Sh DESCRIPTION 54The 55.Fn nfssvc 56function is used by the NFS daemons to pass information into and out 57of the kernel and also to enter the kernel as a server daemon. 58The 59.Fa flags 60argument consists of several bits that show what action is to be taken 61once in the kernel and the 62.Fa argstructp 63points to one of three structures depending on which bits are set in 64flags. 65.Pp 66On the client side, 67.Xr nfsiod 8 68calls 69.Fn nfssvc 70with the 71.Fa flags 72argument set to 73.Dv NFSSVC_BIOD 74and 75.Fa argstructp 76set to 77.Dv NULL 78to enter the kernel as a block I/O server daemon. 79For 80.Nm NQNFS , 81.Xr mount_nfs 8 82calls 83.Fn nfssvc 84with the 85.Dv NFSSVC_MNTD 86flag, optionally or'd with the flags 87.Dv NFSSVC_GOTAUTH 88and 89.Dv NFSSVC_AUTHINFAIL 90along with a pointer to a 91.Bd -literal 92struct nfsd_cargs { 93 char *ncd_dirp; /* Mount dir path */ 94 uid_t ncd_authuid; /* Effective uid */ 95 int ncd_authtype; /* Type of authenticator */ 96 int ncd_authlen; /* Length of authenticator string */ 97 u_char *ncd_authstr; /* Authenticator string */ 98 int ncd_verflen; /* and the verifier */ 99 u_char *ncd_verfstr; 100 NFSKERBKEY_T ncd_key; /* Session key */ 101}; 102.Ed 103.Pp 104structure. 105The initial call has only the 106.Dv NFSSVC_MNTD 107flag set to specify service for the mount point. 108If the mount point is using Kerberos, then the 109.Xr mount_nfs 8 110daemon will return from 111.Fn nfssvc 112with 113.Va errno 114== 115.Er ENEEDAUTH 116whenever the client side requires an ``rcmd'' 117authentication ticket for the user. 118.Xr Mount_nfs 8 119will attempt to get the Kerberos ticket, and if successful will call 120.Fn nfssvc 121with the flags 122.Dv NFSSVC_MNTD 123and 124.Dv NFSSVC_GOTAUTH 125after filling the ticket into the 126ncd_authstr field 127and 128setting the ncd_authlen and ncd_authtype 129fields of the nfsd_cargs structure. 130If 131.Xr mount_nfs 8 132failed to get the ticket, 133.Fn nfssvc 134will be called with the flags 135.Dv NFSSVC_MNTD , 136.Dv NFSSVC_GOTAUTH 137and 138.Dv NFSSVC_AUTHINFAIL 139to denote a failed authentication attempt. 140.Pp 141On the server side, 142.Fn nfssvc 143is called with the flag 144.Dv NFSSVC_NFSD 145and a pointer to a 146.Bd -literal 147struct nfsd_srvargs { 148 struct nfsd *nsd_nfsd; /* Pointer to in kernel nfsd struct */ 149 uid_t nsd_uid; /* Effective uid mapped to cred */ 150 u_int32_t nsd_haddr; /* Ip address of client */ 151 struct ucred nsd_cr; /* Cred. uid maps to */ 152 int nsd_authlen; /* Length of auth string (ret) */ 153 u_char *nsd_authstr; /* Auth string (ret) */ 154 int nsd_verflen; /* and the verifier */ 155 u_char *nsd_verfstr; 156 struct timeval nsd_timestamp; /* timestamp from verifier */ 157 u_int32_t nsd_ttl; /* credential ttl (sec) */ 158 NFSKERBKEY_T nsd_key; /* Session key */ 159}; 160.Ed 161.Pp 162to enter the kernel as an 163.Xr nfsd 8 164daemon. 165Whenever an 166.Xr nfsd 8 167daemon receives a Kerberos authentication ticket, it will return from 168.Fn nfssvc 169with 170.Va errno 171== 172.Er ENEEDAUTH . 173The 174.Xr nfsd 8 175will attempt to authenticate the ticket and generate a set of credentials 176on the server for the ``user id'' specified in the field nsd_uid. 177This is done by first authenticating the Kerberos ticket and then mapping 178the Kerberos principal to a local name and getting a set of credentials for 179that user via. 180.Xr getpwnam 3 181and 182.Xr getgrouplist 3 . 183If successful, the 184.Xr nfsd 8 185will call 186.Fn nfssvc 187with the 188.Dv NFSSVC_NFSD 189and 190.Dv NFSSVC_AUTHIN 191flags set to pass the credential mapping in nsd_cr into the 192kernel to be cached on the server socket for that client. 193If the authentication failed, 194.Xr nfsd 8 195calls 196.Fn nfssvc 197with the flags 198.Dv NFSSVC_NFSD 199and 200.Dv NFSSVC_AUTHINFAIL 201to denote an authentication failure. 202.Pp 203The master 204.Xr nfsd 8 205server daemon calls 206.Fn nfssvc 207with the flag 208.Dv NFSSVC_ADDSOCK 209and a pointer to a 210.Bd -literal 211struct nfsd_args { 212 int sock; /* Socket to serve */ 213 caddr_t name; /* Client address for connection based sockets */ 214 int namelen;/* Length of name */ 215}; 216.Ed 217.Pp 218to pass a server side 219.Tn NFS 220socket into the kernel for servicing by the 221.Xr nfsd 8 222daemons. 223.Sh RETURN VALUES 224Normally 225.Fn nfssvc 226does not return unless the server 227is terminated by a signal when a value of 0 is returned. 228Otherwise, -1 is returned and the global variable 229.Va errno 230is set to specify the error. 231.Sh ERRORS 232.Bl -tag -width Er 233.It Bq Er ENEEDAUTH 234This special error value 235is really used for authentication support, particularly Kerberos, 236as explained above. 237.It Bq Er EPERM 238The caller is not the super-user. 239.El 240.Sh SEE ALSO 241.Xr mount_nfs 8 , 242.Xr nfsd 8 , 243.Xr nfsiod 8 244.Sh HISTORY 245The 246.Fn nfssvc 247function first appeared in 248.Bx 4.4 . 249.Sh BUGS 250The 251.Fn nfssvc 252system call is designed specifically for the 253.Tn NFS 254support daemons and as such is specific to their requirements. 255It should really return values to indicate the need for authentication 256support, since 257.Er ENEEDAUTH 258is not really an error. 259Several fields of the argument structures are assumed to be valid and 260sometimes to be unchanged from a previous call, such that 261.Fn nfssvc 262must be used with extreme care. 263