| blob | def61a4ab46037c71797a9de0fe3208d145e5d68 |
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
54 The
55 .Fn nfssvc
56 function is used by the NFS daemons to pass information into and out
57 of the kernel and also to enter the kernel as a server daemon.
58 The
59 .Fa flags
60 argument consists of several bits that show what action is to be taken
61 once in the kernel and the
62 .Fa argstructp
63 points to one of three structures depending on which bits are set in
64 flags.
65 .Pp
66 On the client side,
67 .Xr nfsiod 8
68 calls
69 .Fn nfssvc
70 with the
71 .Fa flags
72 argument set to
73 .Dv NFSSVC_BIOD
74 and
75 .Fa argstructp
76 set to
77 .Dv NULL
78 to enter the kernel as a block I/O server daemon.
79 For
80 .Nm NQNFS ,
81 .Xr mount_nfs 8
82 calls
83 .Fn nfssvc
84 with the
85 .Dv NFSSVC_MNTD
86 flag, optionally or'd with the flags
87 .Dv NFSSVC_GOTAUTH
88 and
89 .Dv NFSSVC_AUTHINFAIL
90 along with a pointer to a
91 .Bd -literal
92 struct 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
104 structure.
105 The initial call has only the
106 .Dv NFSSVC_MNTD
107 flag set to specify service for the mount point.
108 If the mount point is using Kerberos, then the
109 .Xr mount_nfs 8
110 daemon will return from
111 .Fn nfssvc
112 with
113 .Va errno
114 ==
115 .Er ENEEDAUTH
116 whenever the client side requires an ``rcmd''
117 authentication ticket for the user.
118 .Xr Mount_nfs 8
119 will attempt to get the Kerberos ticket, and if successful will call
120 .Fn nfssvc
121 with the flags
122 .Dv NFSSVC_MNTD
123 and
124 .Dv NFSSVC_GOTAUTH
125 after filling the ticket into the
126 ncd_authstr field
127 and
128 setting the ncd_authlen and ncd_authtype
129 fields of the nfsd_cargs structure.
130 If
131 .Xr mount_nfs 8
132 failed to get the ticket,
133 .Fn nfssvc
134 will be called with the flags
135 .Dv NFSSVC_MNTD ,
136 .Dv NFSSVC_GOTAUTH
137 and
138 .Dv NFSSVC_AUTHINFAIL
139 to denote a failed authentication attempt.
140 .Pp
141 On the server side,
142 .Fn nfssvc
143 is called with the flag
144 .Dv NFSSVC_NFSD
145 and a pointer to a
146 .Bd -literal
147 struct 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
162 to enter the kernel as an
163 .Xr nfsd 8
164 daemon.
165 Whenever an
166 .Xr nfsd 8
167 daemon receives a Kerberos authentication ticket, it will return from
168 .Fn nfssvc
169 with
170 .Va errno
171 ==
172 .Er ENEEDAUTH .
173 The
174 .Xr nfsd 8
175 will attempt to authenticate the ticket and generate a set of credentials
176 on the server for the ``user id'' specified in the field nsd_uid.
177 This is done by first authenticating the Kerberos ticket and then mapping
178 the Kerberos principal to a local name and getting a set of credentials for
179 that user via.
180 .Xr getpwnam 3
181 and
182 .Xr getgrouplist 3 .
183 If successful, the
184 .Xr nfsd 8
185 will call
186 .Fn nfssvc
187 with the
188 .Dv NFSSVC_NFSD
189 and
190 .Dv NFSSVC_AUTHIN
191 flags set to pass the credential mapping in nsd_cr into the
192 kernel to be cached on the server socket for that client.
193 If the authentication failed,
194 .Xr nfsd 8
195 calls
196 .Fn nfssvc
197 with the flags
198 .Dv NFSSVC_NFSD
199 and
200 .Dv NFSSVC_AUTHINFAIL
201 to denote an authentication failure.
202 .Pp
203 The master
204 .Xr nfsd 8
205 server daemon calls
206 .Fn nfssvc
207 with the flag
208 .Dv NFSSVC_ADDSOCK
209 and a pointer to a
210 .Bd -literal
211 struct 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
218 to pass a server side
219 .Tn NFS
220 socket into the kernel for servicing by the
221 .Xr nfsd 8
222 daemons.
223 .Sh RETURN VALUES
224 Normally
225 .Fn nfssvc
226 does not return unless the server
227 is terminated by a signal when a value of 0 is returned.
228 Otherwise, -1 is returned and the global variable
229 .Va errno
230 is set to specify the error.
231 .Sh ERRORS
232 .Bl -tag -width Er
233 .It Bq Er ENEEDAUTH
234 This special error value
235 is really used for authentication support, particularly Kerberos,
236 as explained above.
237 .It Bq Er EPERM
238 The 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
245 The
246 .Fn nfssvc
247 function first appeared in
248 .Bx 4.4 .
249 .Sh BUGS
250 The
251 .Fn nfssvc
252 system call is designed specifically for the
253 .Tn NFS
254 support daemons and as such is specific to their requirements.
255 It should really return values to indicate the need for authentication
256 support, since
257 .Er ENEEDAUTH
258 is not really an error.
259 Several fields of the argument structures are assumed to be valid and
260 sometimes to be unchanged from a previous call, such that
261 .Fn nfssvc
262 must be used with extreme care.