Commit | Line | Data |
---|---|---|
931b8415 | 1 | .\" Copyright (c) 1989, 1991 The Regents of the University of California. |
238fc413 KM |
2 | .\" All rights reserved. |
3 | .\" | |
faf7e3e0 | 4 | .\" %sccs.include.redist.roff% |
238fc413 | 5 | .\" |
3f6f0ccf | 6 | .\" @(#)nfssvc.2 8.1 (Berkeley) %G% |
238fc413 | 7 | .\" |
931b8415 CL |
8 | .Dd |
9 | .Dt NFSSVC 2 | |
faf7e3e0 | 10 | .Os |
931b8415 CL |
11 | .Sh NAME |
12 | .Nm nfssvc | |
f0db8164 | 13 | .Nd NFS services |
931b8415 CL |
14 | .Sh SYNOPSIS |
15 | .Fd #include <unistd.h> | |
f0db8164 | 16 | .Fd #include <nfs/nfs.h> |
931b8415 | 17 | .Ft int |
f0db8164 | 18 | .Fn nfssvc "int flags" "void *argstructp" |
931b8415 | 19 | .Sh DESCRIPTION |
c6ba25a1 KB |
20 | The |
21 | .Fn nfssvc | |
22 | function is used by the NFS daemons to pass information into and out | |
23 | of the kernel and also to enter the kernel as a server daemon. | |
f0db8164 KM |
24 | The |
25 | .Fa flags | |
26 | argument consists of several bits that show what action is to be taken | |
27 | once in the kernel and the | |
28 | .Fa argstructp | |
29 | points to one of three structures depending on which bits are set in | |
30 | flags. | |
31 | .Pp | |
32 | On the client side, | |
33 | .Xr nfsiod 8 | |
34 | calls | |
35 | .Fn nfssvc | |
36 | with the | |
37 | .Fa flags | |
38 | argument set to | |
39 | .Dv NFSSVC_BIOD | |
40 | and | |
41 | .Fa argstructp | |
42 | set to | |
43 | .Dv NULL | |
44 | to enter the kernel as a block I/O server daemon. | |
45 | For | |
46 | .Nm NQNFS , | |
47 | .Xr mount_nfs 8 | |
48 | calls | |
49 | .Fn nfssvc | |
50 | with the | |
51 | .Dv NFSSVC_MNTD | |
52 | flag, optionally or'd with the flags | |
53 | .Dv NFSSVC_GOTAUTH | |
54 | and | |
55 | .Dv NFSSVC_AUTHINFAIL | |
56 | along with a pointer to a | |
57 | .Bd -literal | |
58 | struct nfsd_cargs { | |
59 | char *ncd_dirp; /* Mount dir path */ | |
60 | uid_t ncd_authuid; /* Effective uid */ | |
61 | int ncd_authtype; /* Type of authenticator */ | |
62 | int ncd_authlen; /* Length of authenticator string */ | |
63 | char *ncd_authstr; /* Authenticator string */ | |
64 | }; | |
65 | .Ed | |
66 | .sp | |
67 | structure. | |
68 | The initial call has only the | |
69 | .Dv NFSSVC_MNTD | |
70 | flag set to specify service for the mount point. | |
71 | If the mount point is using Kerberos, then the | |
72 | .Xr mount_nfs 8 | |
73 | daemon will return from | |
74 | .Fn nfssvc | |
75 | with errno == ENEEDAUTH whenever the client side requires an ``rcmd'' | |
76 | authentication ticket for the user. | |
77 | .Xr Mount_nfs 8 | |
78 | will attempt to get the Kerberos ticket, and if successful will call | |
79 | .Fn nfssvc | |
80 | with the flags | |
81 | .Dv NFSSVC_MNTD | |
82 | and | |
83 | .Dv NFSSVC_GOTAUTH | |
84 | after filling the ticket into the | |
85 | ncd_authstr field | |
86 | and | |
87 | setting the ncd_authlen and ncd_authtype | |
88 | fields of the nfsd_cargs structure. | |
89 | If | |
90 | .Xr mount_nfs 8 | |
91 | failed to get the ticket, | |
92 | .Fn nfssvc | |
93 | will be called with the flags | |
94 | .Dv NFSSVC_MNTD , | |
95 | .Dv NFSSVC_GOTAUTH | |
96 | and | |
97 | .Dv NFSSVC_AUTHINFAIL | |
98 | to denote a failed authentication attempt. | |
99 | .Pp | |
100 | On the server side, | |
101 | .Fn nfssvc | |
102 | is called with the flag | |
103 | .Dv NFSSVC_NFSD | |
104 | and a pointer to a | |
105 | .Bd -literal | |
106 | struct nfsd_srvargs { | |
107 | struct nfsd *nsd_nfsd; /* Pointer to in kernel nfsd struct */ | |
108 | uid_t nsd_uid; /* Effective uid mapped to cred */ | |
109 | u_long nsd_haddr; /* Ip address of client */ | |
110 | struct ucred nsd_cr; /* Cred. uid maps to */ | |
111 | int nsd_authlen; /* Length of auth string (ret) */ | |
112 | char *nsd_authstr; /* Auth string (ret) */ | |
113 | }; | |
114 | .Ed | |
115 | .sp | |
116 | to enter the kernel as an | |
117 | .Xr nfsd 8 | |
118 | daemon. | |
119 | Whenever an | |
120 | .Xr nfsd 8 | |
121 | daemon receives a Kerberos authentication ticket, it will return from | |
122 | .Fn nfssvc | |
123 | with errno == ENEEDAUTH. | |
124 | The | |
125 | .Xr nfsd 8 | |
126 | will attempt to authenticate the ticket and generate a set of credentials | |
127 | on the server for the ``user id'' specified in the field nsd_uid. | |
128 | This is done by first authenticating the Kerberos ticket and then mapping | |
129 | the Kerberos principal to a local name and getting a set of credentials for | |
130 | that user via. | |
131 | .Xr getpwnam 3 | |
132 | and | |
133 | .Xr getgrouplist 3 . | |
134 | If successful, the | |
135 | .Xr nfsd 8 | |
136 | will call | |
137 | .Fn nfssvc | |
138 | with the | |
139 | .Dv NFSSVC_NFSD | |
140 | and | |
141 | .Dv NFSSVC_AUTHIN | |
142 | flags set to pass the credential mapping in nsd_cr into the | |
143 | kernel to be cached on the server socket for that client. | |
144 | If the authentication failed, | |
145 | .Xr nfsd 8 | |
146 | calls | |
147 | .Fn nfssvc | |
148 | with the flags | |
149 | .Dv NFSSVC_NFSD | |
150 | and | |
151 | .Dv NFSSVC_AUTHINFAIL | |
152 | to denote an authentication failure. | |
153 | .Pp | |
154 | The master | |
155 | .Xr nfsd 8 | |
156 | server daemon calls | |
157 | .Fn nfssvc | |
158 | with the flag | |
159 | .Dv NFSSVC_ADDSOCK | |
160 | and a pointer to a | |
161 | .Bd -literal | |
162 | struct nfsd_args { | |
163 | int sock; /* Socket to serve */ | |
164 | caddr_t name; /* Client address for connection based sockets */ | |
165 | int namelen; /* Length of name */ | |
166 | }; | |
167 | .Ed | |
168 | .sp | |
169 | to pass a server side | |
931b8415 | 170 | .Tn NFS |
f0db8164 KM |
171 | socket into the kernel for servicing by the |
172 | .Xr nfsd 8 | |
173 | daemons. | |
931b8415 CL |
174 | .Sh RETURN VALUES |
175 | Normally | |
176 | .Nm nfssvc | |
177 | does not return unless the server | |
f0db8164 | 178 | is terminated by a signal when a value of 0 is returned. |
931b8415 CL |
179 | Otherwise, -1 is returned and the global variable |
180 | .Va errno | |
f0db8164 | 181 | is set to specify the error. |
931b8415 | 182 | .Sh ERRORS |
f0db8164 KM |
183 | .Bl -tag -width [ENEEDAUTH] |
184 | .It Bq Er ENEEDAUTH | |
185 | This special error value | |
186 | is really used for authentication support, particularly Kerberos, | |
187 | as explained above. | |
931b8415 | 188 | .It Bq Er EPERM |
238fc413 | 189 | The caller is not the super-user. |
931b8415 CL |
190 | .El |
191 | .Sh SEE ALSO | |
f0db8164 KM |
192 | .Xr nfsd 8 , |
193 | .Xr mount_nfs 8 , | |
194 | .Xr nfsiod 8 | |
931b8415 CL |
195 | .Sh HISTORY |
196 | The | |
faf7e3e0 CL |
197 | .Nm nfssvc |
198 | function call is | |
199 | .Ud . | |
f0db8164 KM |
200 | .Sh BUGS |
201 | The | |
202 | .Nm nfssvc | |
203 | system call is designed specifically for the | |
204 | .Tn NFS | |
205 | support daemons and as such is specific to their requirements. | |
206 | It should really return values to indicate the need for authentication | |
207 | support, since | |
208 | .Dv ENEEDAUTH | |
209 | is not really an error. | |
210 | Several fields of the argument structures are assumed to be valid and | |
211 | sometimes to be unchanged from a previous call, such that | |
212 | .Nm nfssvc | |
213 | must be used with extreme care. |