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