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