lib/libc/sys/nfssvc.2

   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
  46 The
  47 .Fn nfssvc
  48 function is used by the NFS daemons to pass information into and out
  49 of the kernel and also to enter the kernel as a server daemon.
  50 The
  51 .Fa flags
  52 argument consists of several bits that show what action is to be taken
  53 once in the kernel and the
  54 .Fa argstructp
  55 points to one of three structures depending on which bits are set in
  56 flags.
  57 .Ss Calls used by Xr nfsd 8
  58 On the server side,
  59 .Fn nfssvc
  60 is called with the flag
  61 .Dv NFSSVC_NFSD
  62 and a pointer to a
  63 .Bd -literal
  64 struct 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
  74 to enter the kernel as an
  75 .Xr nfsd 8
  76 daemon.
  77 Whenever an
  78 .Xr nfsd 8
  79 daemon receives a Kerberos authentication ticket, it will return from
  80 .Fn nfssvc
  81 with errno set to
  82 .Er ENEEDAUTH .
  83 The
  84 .Xr nfsd 8
  85 will attempt to authenticate the ticket and generate a set of credentials
  86 on the server for the
  87 .Dq user id
  88 specified in the field nsd_uid.
  89 This is done by first authenticating the Kerberos ticket and then mapping
  90 the Kerberos principal to a local name and getting a set of credentials for
  91 that user via
  92 .Xr getpwnam 3
  93 and
  94 .Xr getgrouplist 3 .
  95 If successful, the
  96 .Xr nfsd 8
  97 will call
  98 .Fn nfssvc
  99 with the
 100 .Dv NFSSVC_NFSD
 101 and
 102 .Dv NFSSVC_AUTHIN
 103 flags set to pass the credential mapping in nsd_cr into the
 104 kernel to be cached on the server socket for that client.
 105 If the authentication failed,
 106 .Xr nfsd 8
 107 calls
 108 .Fn nfssvc
 109 with the flags
 110 .Dv NFSSVC_NFSD
 111 and
 112 .Dv NFSSVC_AUTHINFAIL
 113 to denote an authentication failure.
 114 .Pp
 115 The master
 116 .Xr nfsd 8
 117 server daemon calls
 118 .Fn nfssvc
 119 with the flag
 120 .Dv NFSSVC_ADDSOCK
 121 and a pointer to a
 122 .Bd -literal
 123 struct 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
 130 to pass a server side
 131 .Tn NFS
 132 socket into the kernel for servicing by the
 133 .Xr nfsd 8
 134 daemons.
 135 .Ss Calls used by Xr mountd 8
 136 The
 137 .Xr mountd 8
 138 server daemon calls
 139 .Fn nfssvc
 140 with the flag
 141 .Dv NFSSVC_SETEXPORTSLIST
 142 and a pointer to a
 143 .Ft struct mountd_exports_list
 144 object to atomically change the exports lists of a specific file system.
 145 This structure has the following fields:
 146 .Bl -tag -width ".Vt const char *mel_path"
 147 .It Vt const char *mel_path
 148 Path to the file system that will have its exports list replaced by the
 149 one described in the other fields.
 150 .It Vt size_t mel_nexports
 151 Number of valid entries in the
 152 .Vt mel_export
 153 field.
 154 If zero, the exports list will be cleared for the given file system.
 155 .It Vt struct export_args mel_export[AF_MAX]
 156 Set of exports to be used for the given file system.
 157 .El
 158 .Sh RETURN VALUES
 159 Usually
 160 .Nm
 161 does not return unless the server
 162 is terminated by a signal when a value of 0 is returned.
 163 Otherwise, \-1 is returned and the global variable
 164 .Va errno
 165 is set to specify the error.
 166 .Sh ERRORS
 167 .Bl -tag -width Er
 168 .It Bq Er ENEEDAUTH
 169 This special error value is really used for authentication support,
 170 particularly Kerberos, as explained above.
 171 .It Bq Er EPERM
 172 The caller is not the super-user.
 173 .El
 174 .Sh SEE ALSO
 175 .Xr mount_nfs 8 ,
 176 .Xr nfsd 8
 177 .Sh HISTORY
 178 The
 179 .Nm
 180 function first appeared in
 181 .Bx 4.4 .
 182 .Sh BUGS
 183 The
 184 .Nm
 185 system call is designed specifically for the
 186 .Tn NFS
 187 support daemons and as such is specific to their requirements.
 188 It should really return values to indicate the need for authentication
 189 support, since
 190 .Er ENEEDAUTH
 191 is not really an error.
 192 Several fields of the argument structures are assumed to be valid and
 193 sometimes to be unchanged from a previous call, such that
 194 .Nm
 195 must be used with extreme care.