From f0db81643104f24cf1c28a4b2a370dc831818174 Mon Sep 17 00:00:00 2001 From: Kirk McKusick Date: Thu, 4 Feb 1993 04:49:11 -0800 Subject: [PATCH] update for 4.4BSD from Rick Macklem SCCS-vsn: lib/libc/sys/nfssvc.2 6.7 --- usr/src/lib/libc/sys/nfssvc.2 | 199 ++++++++++++++++++++++++++++++---- 1 file changed, 179 insertions(+), 20 deletions(-) diff --git a/usr/src/lib/libc/sys/nfssvc.2 b/usr/src/lib/libc/sys/nfssvc.2 index d462cff181..e1475853e6 100644 --- a/usr/src/lib/libc/sys/nfssvc.2 +++ b/usr/src/lib/libc/sys/nfssvc.2 @@ -3,52 +3,211 @@ .\" .\" %sccs.include.redist.roff% .\" -.\" @(#)nfssvc.2 6.6 (Berkeley) %G% +.\" @(#)nfssvc.2 6.7 (Berkeley) %G% .\" .Dd .Dt NFSSVC 2 .Os .Sh NAME .Nm nfssvc -.Nd create a remote NFS server +.Nd NFS services .Sh SYNOPSIS .Fd #include +.Fd #include .Ft int -.Fn nfssvc "int sock" +.Fn nfssvc "int flags" "void *argstructp" .Sh DESCRIPTION -.Bf -symbolic -The calling sequence of this function is expected to change .Ef .Fn Nfssvc -starts an +is used by the various NFS daemons, to pass information in and out of +the kernel and also to enter the kernel as a server daemon. +The +.Fa flags +argument consists of several bits that show what action is to be taken +once in the kernel and the +.Fa argstructp +points to one of three structures depending on which bits are set in +flags. +.Pp +On the client side, +.Xr nfsiod 8 +calls +.Fn nfssvc +with the +.Fa flags +argument set to +.Dv NFSSVC_BIOD +and +.Fa argstructp +set to +.Dv NULL +to enter the kernel as a block I/O server daemon. +For +.Nm NQNFS , +.Xr mount_nfs 8 +calls +.Fn nfssvc +with the +.Dv NFSSVC_MNTD +flag, optionally or'd with the flags +.Dv NFSSVC_GOTAUTH +and +.Dv NFSSVC_AUTHINFAIL +along with a pointer to a +.Bd -literal +struct nfsd_cargs { + char *ncd_dirp; /* Mount dir path */ + uid_t ncd_authuid; /* Effective uid */ + int ncd_authtype; /* Type of authenticator */ + int ncd_authlen; /* Length of authenticator string */ + char *ncd_authstr; /* Authenticator string */ +}; +.Ed +.sp +structure. +The initial call has only the +.Dv NFSSVC_MNTD +flag set to specify service for the mount point. +If the mount point is using Kerberos, then the +.Xr mount_nfs 8 +daemon will return from +.Fn nfssvc +with errno == ENEEDAUTH whenever the client side requires an ``rcmd'' +authentication ticket for the user. +.Xr Mount_nfs 8 +will attempt to get the Kerberos ticket, and if successful will call +.Fn nfssvc +with the flags +.Dv NFSSVC_MNTD +and +.Dv NFSSVC_GOTAUTH +after filling the ticket into the +ncd_authstr field +and +setting the ncd_authlen and ncd_authtype +fields of the nfsd_cargs structure. +If +.Xr mount_nfs 8 +failed to get the ticket, +.Fn nfssvc +will be called with the flags +.Dv NFSSVC_MNTD , +.Dv NFSSVC_GOTAUTH +and +.Dv NFSSVC_AUTHINFAIL +to denote a failed authentication attempt. +.Pp +On the server side, +.Fn nfssvc +is called with the flag +.Dv NFSSVC_NFSD +and a pointer to a +.Bd -literal +struct nfsd_srvargs { + struct nfsd *nsd_nfsd; /* Pointer to in kernel nfsd struct */ + uid_t nsd_uid; /* Effective uid mapped to cred */ + u_long nsd_haddr; /* Ip address of client */ + struct ucred nsd_cr; /* Cred. uid maps to */ + int nsd_authlen; /* Length of auth string (ret) */ + char *nsd_authstr; /* Auth string (ret) */ +}; +.Ed +.sp +to enter the kernel as an +.Xr nfsd 8 +daemon. +Whenever an +.Xr nfsd 8 +daemon receives a Kerberos authentication ticket, it will return from +.Fn nfssvc +with errno == ENEEDAUTH. +The +.Xr nfsd 8 +will attempt to authenticate the ticket and generate a set of credentials +on the server for the ``user id'' specified in the field nsd_uid. +This is done by first authenticating the Kerberos ticket and then mapping +the Kerberos principal to a local name and getting a set of credentials for +that user via. +.Xr getpwnam 3 +and +.Xr getgrouplist 3 . +If successful, the +.Xr nfsd 8 +will call +.Fn nfssvc +with the +.Dv NFSSVC_NFSD +and +.Dv NFSSVC_AUTHIN +flags set to pass the credential mapping in nsd_cr into the +kernel to be cached on the server socket for that client. +If the authentication failed, +.Xr nfsd 8 +calls +.Fn nfssvc +with the flags +.Dv NFSSVC_NFSD +and +.Dv NFSSVC_AUTHINFAIL +to denote an authentication failure. +.Pp +The master +.Xr nfsd 8 +server daemon calls +.Fn nfssvc +with the flag +.Dv NFSSVC_ADDSOCK +and a pointer to a +.Bd -literal +struct nfsd_args { + int sock; /* Socket to serve */ + caddr_t name; /* Client address for connection based sockets */ + int namelen; /* Length of name */ +}; +.Ed +.sp +to pass a server side .Tn NFS -daemon listening on socket -.Fa sock . -The socket must be in the -.Dv AF_INET -family. +socket into the kernel for servicing by the +.Xr nfsd 8 +daemons. .Sh RETURN VALUES Normally .Nm nfssvc does not return unless the server -is terminated by a signal at which time a value of 0 is returned. +is terminated by a signal when a value of 0 is returned. Otherwise, -1 is returned and the global variable .Va errno -is set to indicate the error. +is set to specify the error. .Sh ERRORS -.Fn Nfssvc -fails if: -.Bl -tag -width [EPERM] -.It Bq Er EBADF -.Fa Fd -is not a valid open file descriptor. +.Bl -tag -width [ENEEDAUTH] +.It Bq Er ENEEDAUTH +This special error value +is really used for authentication support, particularly Kerberos, +as explained above. .It Bq Er EPERM The caller is not the super-user. .El .Sh SEE ALSO -.Xr nfsd 8 +.Xr nfsd 8 , +.Xr mount_nfs 8 , +.Xr nfsiod 8 .Sh HISTORY The .Nm nfssvc function call is .Ud . +.Sh BUGS +The +.Nm nfssvc +system call is designed specifically for the +.Tn NFS +support daemons and as such is specific to their requirements. +It should really return values to indicate the need for authentication +support, since +.Dv ENEEDAUTH +is not really an error. +Several fields of the argument structures are assumed to be valid and +sometimes to be unchanged from a previous call, such that +.Nm nfssvc +must be used with extreme care. -- 2.20.1