1.\" $NetBSD: nfssvc.2,v 1.22 2005/09/23 20:27:10 wiz Exp $ 2.\" 3.\" Copyright (c) 1989, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)nfssvc.2 8.1 (Berkeley) 6/9/93 31.\" 32.Dd September 23, 2005 33.Dt NFSSVC 2 34.Os 35.Sh NAME 36.Nm nfssvc 37.Nd NFS services 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In unistd.h 42.In nfs/nfs.h 43.Ft int 44.Fn nfssvc "int flags" "void *argstructp" 45.Sh DESCRIPTION 46The 47.Fn nfssvc 48function 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.Ss Calls used by Xr mount_nfs 8 58On the client side, 59.Fn nfssvc 60is only used for 61.Li NQNFS . 62.Xr mount_nfs 8 63calls 64.Fn nfssvc 65with the 66.Dv NFSSVC_MNTD 67flag, optionally or'd with the flags 68.Dv NFSSVC_GOTAUTH 69and 70.Dv NFSSVC_AUTHINFAIL 71along with a pointer to a 72.Bd -literal 73struct nfsd_cargs { 74 char *ncd_dirp; /* Mount dir path */ 75 uid_t ncd_authuid; /* Effective uid */ 76 int ncd_authtype; /* Type of authenticator */ 77 int ncd_authlen; /* Length of authenticator string */ 78 char *ncd_authstr; /* Authenticator string */ 79}; 80.Ed 81.Pp 82structure. 83The initial call has only the 84.Dv NFSSVC_MNTD 85flag set to specify service for the mount point. 86If the mount point is using Kerberos, then the 87.Xr mount_nfs 8 88daemon will return from 89.Fn nfssvc 90with errno set to 91.Er ENEEDAUTH 92whenever the client side requires an 93.Dq rcmd 94authentication ticket for the user. 95The 96.Xr mount_nfs 8 97program will attempt to get the Kerberos ticket, and if successful will call 98.Fn nfssvc 99with the flags 100.Dv NFSSVC_MNTD 101and 102.Dv NFSSVC_GOTAUTH 103after filling the ticket into the 104ncd_authstr field 105and 106setting the ncd_authlen and ncd_authtype 107fields of the nfsd_cargs structure. 108If 109.Xr mount_nfs 8 110failed to get the ticket, 111.Fn nfssvc 112will be called with the flags 113.Dv NFSSVC_MNTD , 114.Dv NFSSVC_GOTAUTH , 115and 116.Dv NFSSVC_AUTHINFAIL 117to denote a failed authentication attempt. 118.Ss Calls used by Xr nfsd 8 119On the server side, 120.Fn nfssvc 121is called with the flag 122.Dv NFSSVC_NFSD 123and a pointer to a 124.Bd -literal 125struct nfsd_srvargs { 126 struct nfsd *nsd_nfsd; /* Pointer to in kernel nfsd struct */ 127 uid_t nsd_uid; /* Effective uid mapped to cred */ 128 u_long nsd_haddr; /* Ip address of client */ 129 struct ucred nsd_cr; /* Cred. uid maps to */ 130 int nsd_authlen; /* Length of auth string (ret) */ 131 char *nsd_authstr; /* Auth string (ret) */ 132}; 133.Ed 134.Pp 135to enter the kernel as an 136.Xr nfsd 8 137daemon. 138Whenever an 139.Xr nfsd 8 140daemon receives a Kerberos authentication ticket, it will return from 141.Fn nfssvc 142with errno set to 143.Er ENEEDAUTH . 144The 145.Xr nfsd 8 146will attempt to authenticate the ticket and generate a set of credentials 147on the server for the 148.Dq user id 149specified in the field nsd_uid. 150This is done by first authenticating the Kerberos ticket and then mapping 151the Kerberos principal to a local name and getting a set of credentials for 152that user via 153.Xr getpwnam 3 154and 155.Xr getgrouplist 3 . 156If successful, the 157.Xr nfsd 8 158will call 159.Fn nfssvc 160with the 161.Dv NFSSVC_NFSD 162and 163.Dv NFSSVC_AUTHIN 164flags set to pass the credential mapping in nsd_cr into the 165kernel to be cached on the server socket for that client. 166If the authentication failed, 167.Xr nfsd 8 168calls 169.Fn nfssvc 170with the flags 171.Dv NFSSVC_NFSD 172and 173.Dv NFSSVC_AUTHINFAIL 174to denote an authentication failure. 175.Pp 176The master 177.Xr nfsd 8 178server daemon calls 179.Fn nfssvc 180with the flag 181.Dv NFSSVC_ADDSOCK 182and a pointer to a 183.Bd -literal 184struct nfsd_args { 185 int sock; /* Socket to serve */ 186 caddr_t name; /* Client address for connection based sockets */ 187 int namelen; /* Length of name */ 188}; 189.Ed 190.Pp 191to pass a server side 192.Tn NFS 193socket into the kernel for servicing by the 194.Xr nfsd 8 195daemons. 196.Ss Calls used by Xr mountd 8 197The 198.Xr mountd 8 199server daemon calls 200.Fn nfssvc 201with the flag 202.Dv NFSSVC_SETEXPORTSLIST 203and a pointer to a 204.Ft struct mountd_exports_list 205object to atomically change the exports lists of a specific file system. 206This structure has the following fields: 207.Bl -tag 208.It Vt const char *mel_path 209Path to the file system that will have its exports list replaced by the 210one described in the other fields. 211.It Vt size_t mel_nexports 212Number of valid entries in the 213.Vt mel_export 214field. 215If zero, the exports list will be cleared for the given file system. 216.It Vt struct export_args mel_export[AF_MAX] 217Set of exports to be used for the given file system. 218.El 219.Sh RETURN VALUES 220Usually 221.Nm 222does not return unless the server 223is terminated by a signal when a value of 0 is returned. 224Otherwise, \-1 is returned and the global variable 225.Va errno 226is set to specify the error. 227.Sh ERRORS 228.Bl -tag -width Er 229.It Bq Er ENEEDAUTH 230This special error value is really used for authentication support, 231particularly Kerberos, as 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.Sh HISTORY 239The 240.Nm 241function first appeared in 242.Bx 4.4 . 243.Sh BUGS 244The 245.Nm 246system call is designed specifically for the 247.Tn NFS 248support daemons and as such is specific to their requirements. 249It should really return values to indicate the need for authentication 250support, since 251.Er ENEEDAUTH 252is not really an error. 253Several fields of the argument structures are assumed to be valid and 254sometimes to be unchanged from a previous call, such that 255.Nm 256must be used with extreme care. 257