| blob | 028fd06cecb31c40d389830cfcc748fcd4d85409 |
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 .\"
31 .Dd February 21, 2020
32 .Dt NFSSVC 2
33 .Os
34 .Sh NAME
35 .Nm nfssvc
36 .Nd NFS services
37 .Sh LIBRARY
38 .Lb libc
39 .Sh SYNOPSIS
40 .In sys/param.h
41 .In sys/mount.h
42 .In sys/time.h
43 .In vfs/nfs/rpcv2.h
44 .In vfs/nfs/nfs.h
45 .In unistd.h
46 .Ft int
47 .Fn nfssvc "int flags" "void *argstructp"
48 .Sh DESCRIPTION
49 The
50 .Fn nfssvc
51 function is used by the NFS daemons to pass information into and out
52 of the kernel and also to enter the kernel as a server daemon.
53 The
54 .Fa flags
55 argument consists of several bits that show what action is to be taken
56 once in the kernel and the
57 .Fa argstructp
58 points to one of three structures depending on which bits are set in
59 flags.
60 .Pp
61 On the client side,
62 .Xr nfsiod 8
63 calls
64 .Fn nfssvc
65 with the
66 .Fa flags
67 argument set to
68 .Dv NFSSVC_BIOD
69 and
70 .Fa argstructp
71 set to
72 .Dv NULL
73 to enter the kernel as a block I/O server daemon.
74 For
75 .Nm NQNFS ,
76 .Xr mount_nfs 8
77 calls
78 .Fn nfssvc
79 with the
80 .Dv NFSSVC_MNTD
81 flag, optionally or'd with the flags
82 .Dv NFSSVC_GOTAUTH
83 and
84 .Dv NFSSVC_AUTHINFAIL
85 along with a pointer to a
86 .Bd -literal
87 struct nfsd_cargs {
88 char *ncd_dirp; /* Mount dir path */
89 uid_t ncd_authuid; /* Effective uid */
90 int ncd_authtype; /* Type of authenticator */
91 int ncd_authlen; /* Length of authenticator string */
92 u_char *ncd_authstr; /* Authenticator string */
93 int ncd_verflen; /* and the verifier */
94 u_char *ncd_verfstr;
95 NFSKERBKEY_T ncd_key; /* Session key */
96 };
97 .Ed
98 .Pp
99 structure.
100 The initial call has only the
101 .Dv NFSSVC_MNTD
102 flag set to specify service for the mount point.
103 If the mount point is using Kerberos, then the
104 .Xr mount_nfs 8
105 daemon will return from
106 .Fn nfssvc
107 with
108 .Va errno
109 ==
110 .Er ENEEDAUTH
111 whenever the client side requires an ``rcmd''
112 authentication ticket for the user.
113 .Xr Mount_nfs 8
114 will attempt to get the Kerberos ticket, and if successful will call
115 .Fn nfssvc
116 with the flags
117 .Dv NFSSVC_MNTD
118 and
119 .Dv NFSSVC_GOTAUTH
120 after filling the ticket into the
121 ncd_authstr field
122 and
123 setting the ncd_authlen and ncd_authtype
124 fields of the nfsd_cargs structure.
125 If
126 .Xr mount_nfs 8
127 failed to get the ticket,
128 .Fn nfssvc
129 will be called with the flags
130 .Dv NFSSVC_MNTD ,
131 .Dv NFSSVC_GOTAUTH
132 and
133 .Dv NFSSVC_AUTHINFAIL
134 to denote a failed authentication attempt.
135 .Pp
136 On the server side,
137 .Fn nfssvc
138 is called with the flag
139 .Dv NFSSVC_NFSD
140 and a pointer to a
141 .Bd -literal
142 struct nfsd_srvargs {
143 struct nfsd *nsd_nfsd; /* Pointer to in kernel nfsd struct */
144 uid_t nsd_uid; /* Effective uid mapped to cred */
145 u_int32_t nsd_haddr; /* Ip address of client */
146 struct ucred nsd_cr; /* Cred. uid maps to */
147 int nsd_authlen; /* Length of auth string (ret) */
148 u_char *nsd_authstr; /* Auth string (ret) */
149 int nsd_verflen; /* and the verifier */
150 u_char *nsd_verfstr;
151 struct timeval nsd_timestamp; /* timestamp from verifier */
152 u_int32_t nsd_ttl; /* credential ttl (sec) */
153 NFSKERBKEY_T nsd_key; /* Session key */
154 };
155 .Ed
156 .Pp
157 to enter the kernel as an
158 .Xr nfsd 8
159 daemon.
160 Whenever an
161 .Xr nfsd 8
162 daemon receives a Kerberos authentication ticket, it will return from
163 .Fn nfssvc
164 with
165 .Va errno
166 ==
167 .Er ENEEDAUTH .
168 The
169 .Xr nfsd 8
170 will attempt to authenticate the ticket and generate a set of credentials
171 on the server for the ``user id'' specified in the field nsd_uid.
172 This is done by first authenticating the Kerberos ticket and then mapping
173 the Kerberos principal to a local name and getting a set of credentials for
174 that user via.
175 .Xr getpwnam 3
176 and
177 .Xr getgrouplist 3 .
178 If successful, the
179 .Xr nfsd 8
180 will call
181 .Fn nfssvc
182 with the
183 .Dv NFSSVC_NFSD
184 and
185 .Dv NFSSVC_AUTHIN
186 flags set to pass the credential mapping in nsd_cr into the
187 kernel to be cached on the server socket for that client.
188 If the authentication failed,
189 .Xr nfsd 8
190 calls
191 .Fn nfssvc
192 with the flags
193 .Dv NFSSVC_NFSD
194 and
195 .Dv NFSSVC_AUTHINFAIL
196 to denote an authentication failure.
197 .Pp
198 The master
199 .Xr nfsd 8
200 server daemon calls
201 .Fn nfssvc
202 with the flag
203 .Dv NFSSVC_ADDSOCK
204 and a pointer to a
205 .Bd -literal
206 struct nfsd_args {
207 int sock; /* Socket to serve */
208 caddr_t name; /* Client address for connection based sockets */
209 int namelen;/* Length of name */
210 };
211 .Ed
212 .Pp
213 to pass a server side
214 .Tn NFS
215 socket into the kernel for servicing by the
216 .Xr nfsd 8
217 daemons.
218 .Sh RETURN VALUES
219 Normally
220 .Fn nfssvc
221 does not return unless the server
222 is terminated by a signal when a value of 0 is returned.
223 Otherwise, -1 is returned and the global variable
224 .Va errno
225 is set to specify the error.
226 .Sh ERRORS
227 .Bl -tag -width Er
228 .It Bq Er ENEEDAUTH
229 This special error value
230 is really used for authentication support, particularly Kerberos,
231 as explained above.
232 .It Bq Er EPERM
233 The caller is not the super-user.
234 .El
235 .Sh SEE ALSO
236 .Xr mount_nfs 8 ,
237 .Xr nfsd 8 ,
238 .Xr nfsiod 8
239 .Sh HISTORY
240 The
241 .Fn nfssvc
242 function first appeared in
243 .Bx 4.4 .
244 .Sh BUGS
245 The
246 .Fn nfssvc
247 system call is designed specifically for the
248 .Tn NFS
249 support daemons and as such is specific to their requirements.
250 It should really return values to indicate the need for authentication
251 support, since
252 .Er ENEEDAUTH
253 is not really an error.
254 Several fields of the argument structures are assumed to be valid and
255 sometimes to be unchanged from a previous call, such that
256 .Fn nfssvc
257 must be used with extreme care.