1.\" $NetBSD: nfssvc.2,v 1.24 2009/03/10 21:00:47 joerg 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 December 30, 2006 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 nfsd 8 58On the server side, 59.Fn nfssvc 60is called with the flag 61.Dv NFSSVC_NFSD 62and a pointer to a 63.Bd -literal 64struct nfsd_srvargs { 65 struct nfsd *nsd_nfsd; /* Pointer to in kernel nfsd struct */ 66 uid_t nsd_uid; /* Effective uid mapped to cred */ 67 u_long nsd_haddr; /* Ip address of client */ 68 struct ucred nsd_cr; /* Cred. uid maps to */ 69 int nsd_authlen; /* Length of auth string (ret) */ 70 char *nsd_authstr; /* Auth string (ret) */ 71}; 72.Ed 73.Pp 74to enter the kernel as an 75.Xr nfsd 8 76daemon. 77Whenever an 78.Xr nfsd 8 79daemon receives a Kerberos authentication ticket, it will return from 80.Fn nfssvc 81with errno set to 82.Er ENEEDAUTH . 83The 84.Xr nfsd 8 85will attempt to authenticate the ticket and generate a set of credentials 86on the server for the 87.Dq user id 88specified in the field nsd_uid. 89This is done by first authenticating the Kerberos ticket and then mapping 90the Kerberos principal to a local name and getting a set of credentials for 91that user via 92.Xr getpwnam 3 93and 94.Xr getgrouplist 3 . 95If successful, the 96.Xr nfsd 8 97will call 98.Fn nfssvc 99with the 100.Dv NFSSVC_NFSD 101and 102.Dv NFSSVC_AUTHIN 103flags set to pass the credential mapping in nsd_cr into the 104kernel to be cached on the server socket for that client. 105If the authentication failed, 106.Xr nfsd 8 107calls 108.Fn nfssvc 109with the flags 110.Dv NFSSVC_NFSD 111and 112.Dv NFSSVC_AUTHINFAIL 113to denote an authentication failure. 114.Pp 115The master 116.Xr nfsd 8 117server daemon calls 118.Fn nfssvc 119with the flag 120.Dv NFSSVC_ADDSOCK 121and a pointer to a 122.Bd -literal 123struct nfsd_args { 124 int sock; /* Socket to serve */ 125 caddr_t name; /* Client address for connection based sockets */ 126 int namelen; /* Length of name */ 127}; 128.Ed 129.Pp 130to pass a server side 131.Tn NFS 132socket into the kernel for servicing by the 133.Xr nfsd 8 134daemons. 135.Ss Calls used by Xr mountd 8 136The 137.Xr mountd 8 138server daemon calls 139.Fn nfssvc 140with the flag 141.Dv NFSSVC_SETEXPORTSLIST 142and a pointer to a 143.Ft struct mountd_exports_list 144object to atomically change the exports lists of a specific file system. 145This structure has the following fields: 146.Bl -tag -width ".Vt const char *mel_path" 147.It Vt const char *mel_path 148Path to the file system that will have its exports list replaced by the 149one described in the other fields. 150.It Vt size_t mel_nexports 151Number of valid entries in the 152.Vt mel_export 153field. 154If zero, the exports list will be cleared for the given file system. 155.It Vt struct export_args mel_export[AF_MAX] 156Set of exports to be used for the given file system. 157.El 158.Sh RETURN VALUES 159Usually 160.Nm 161does not return unless the server 162is terminated by a signal when a value of 0 is returned. 163Otherwise, \-1 is returned and the global variable 164.Va errno 165is set to specify the error. 166.Sh ERRORS 167.Bl -tag -width Er 168.It Bq Er ENEEDAUTH 169This special error value is really used for authentication support, 170particularly Kerberos, as explained above. 171.It Bq Er EPERM 172The caller is not the super-user. 173.El 174.Sh SEE ALSO 175.Xr mount_nfs 8 , 176.Xr nfsd 8 177.Sh HISTORY 178The 179.Nm 180function first appeared in 181.Bx 4.4 . 182.Sh BUGS 183The 184.Nm 185system call is designed specifically for the 186.Tn NFS 187support daemons and as such is specific to their requirements. 188It should really return values to indicate the need for authentication 189support, since 190.Er ENEEDAUTH 191is not really an error. 192Several fields of the argument structures are assumed to be valid and 193sometimes to be unchanged from a previous call, such that 194.Nm 195must be used with extreme care. 196