X-Git-Url: https://git.decadent.org.uk/gitweb/?p=nfs-utils.git;a=blobdiff_plain;f=utils%2Fgssd%2Fgssd.man;h=1d6fb4c66b71340770c1a4392e673ae319325e1e;hp=f2ecd69995f589832198066f78b90136bceba951;hb=6888d305d8683d178239170794ce8debdaaaacd8;hpb=fbff46da25a0a578136fd92a6b66e807b6599ca3 diff --git a/utils/gssd/gssd.man b/utils/gssd/gssd.man index f2ecd69..1d6fb4c 100644 --- a/utils/gssd/gssd.man +++ b/utils/gssd/gssd.man @@ -2,22 +2,176 @@ .\" rpc.gssd(8) .\" .\" Copyright (C) 2003 J. Bruce Fields -.TH rpc.gssd 8 "14 Mar 2007" +.\" +.TH rpc.gssd 8 "20 Feb 2013" .SH NAME -rpc.gssd \- rpcsec_gss daemon +rpc.gssd \- RPCSEC_GSS daemon .SH SYNOPSIS -.B "rpc.gssd [-f] [-n] [-k keytab] [-p pipefsdir] [-v] [-r] [-d ccachedir]" +.B rpc.gssd +.RB [ \-fMnlvr ] +.RB [ \-k +.IR keytab ] +.RB [ \-p +.IR pipefsdir ] +.RB [ \-d +.IR ccachedir ] +.RB [ \-t +.IR timeout ] +.RB [ \-R +.IR realm ] +.SH INTRODUCTION +The RPCSEC_GSS protocol, defined in RFC 5403, is used to provide +strong security for RPC-based protocols such as NFS. +.P +Before exchanging RPC requests using RPCSEC_GSS, an RPC client must +establish a GSS +.IR "security context" . +A security context is shared state on each +end of a network transport that enables GSS-API security services. +.P +Security contexts are established using +.IR "security credentials" . +A credential grants temporary access to a secure network service, +much as a railway ticket grants temporary access to use a rail service. +.P +A user typically obtains a credential by providing a password to the +.BR kinit (1) +command, or via a PAM library at login time. +A credential acquired with a +.I user principal +is known as a +.I user credential +(see +.BR kerberos (1) +for more on principals). +.P +For certain operations, a credential is required +which represents no user, +is otherwise unprivileged, +and is always available. +This is referred to as a +.IR "machine credential" . +.P +Machine credentials are typically established using a +.IR "service principal" , +whose encrypted password, called its +.IR key , +is stored in a file, called a +.IR keytab , +to avoid requiring a user prompt. +A machine credential effectively does not expire because the system +can renew it as needed without user intervention. +.P +Once obtained, credentials are typically stored in local temporary files +with well-known pathnames. .SH DESCRIPTION -The rpcsec_gss protocol gives a means of using the gss-api generic security -api to provide security for protocols using rpc (in particular, nfs). Before -exchanging any rpc requests using rpcsec_gss, the rpc client must first -establish a security context. The linux kernel's implementation of rpcsec_gss -depends on the userspace daemon +To establish GSS security contexts using these credential files, +the Linux kernel RPC client depends on a userspace daemon called +.BR rpc.gssd . +The +.B rpc.gssd +daemon uses the rpc_pipefs filesystem to communicate with the kernel. +.SS User Credentials +When a user authenticates using a command such as +.BR kinit (1), +the resulting credential is stored in a file with a well-known name +constructed using the user's UID. +.P +To interact with an NFS server +on behalf of a particular Kerberos-authenticated user, +the Linux kernel RPC client requests that +.B rpc.gssd +initialize a security context with the credential +in that user's credential file. +.P +Typically, credential files are placed in +.IR /tmp . +However, +.B rpc.gssd +can search for credential files in more than one directory. +See the description of the +.B -d +option for details. +.SS Machine Credentials +A user credential is established by a user and +is then shared with the kernel and +.BR rpc.gssd . +A machine credential is established by +.B rpc.gssd +for the kernel when there is no user. +Therefore +.B rpc.gssd +must already have the materials on hand to establish this credential +without requiring user intervention. +.P +.B rpc.gssd +searches the local system's keytab for a principal and key to use +to establish the machine credential. +By default, +.B rpc.gssd +assumes the file +.I /etc/krb5.keytab +contains principals and keys that can be used to obtain machine credentials. +.P +.B rpc.gssd +searches in the following order for a principal to use. +The first matching credential is used. +For the search, and are replaced with the local +system's hostname and Kerberos realm. +.sp + $@ +.br + root/@ +.br + nfs/@ +.br + host/@ +.br + root/@ +.br + nfs/@ +.br + host/@ +.sp +The entries match on the service name and realm, but ignore the hostname. +These can be used if a principal matching the local host's name is not found. +.P +Note that the first principal in the search order is a user principal +that enables Kerberized NFS when the local system is joined +to an Active Directory domain using Samba. +A password for this principal must be provided in the local system's keytab. +.P +You can specify another keytab by using the +.B -k +option if +.I /etc/krb5.keytab +does not exist or does not provide one of these principals. +.SS Credentials for UID 0 +UID 0 is a special case. +By default +.B rpc.gssd +uses the system's machine credentials for UID 0 accesses +that require GSS authentication. +This limits the privileges of the root user +when accessing network resources that require authentication. +.P +Specify the +.B -n +option when starting .B rpc.gssd -to establish security contexts. The +if you'd like to force the root user to obtain a user credential +rather than use the local system's machine credential. +.P +When +.B -n +is specified, +the kernel continues to request a GSS context established +with a machine credential for NFSv4 operations, +such as SETCLIENTID or RENEW, that manage state. +If .B rpc.gssd -daemon uses files in the rpc_pipefs filesystem to communicate with the kernel. - +cannot obtain a machine credential (say, the local system has +no keytab), NFSv4 operations that require machine credentials will fail. .SH OPTIONS .TP .B -f @@ -26,53 +180,92 @@ Runs in the foreground and sends output to stderr (as opposed to syslogd) .TP .B -n -By default, -.B rpc.gssd -treats accesses by the user with UID 0 specially, and uses -"machine credentials" for all accesses by that user which -require Kerberos authentication. -With the \-n option, "machine credentials" will not be used -for accesses by UID 0. Instead, credentials must be obtained -manually like all other users. Use of this option means that -"root" must manually obtain Kerberos credentials before -attemtpting to mount an nfs filesystem requiring Kerberos -authentication. +When specified, UID 0 is forced to obtain user credentials +which are used instead of the local system's machine credentials. .TP -.B -k keytab +.BI "-k " keytab Tells .B rpc.gssd to use the keys found in .I keytab -to obtain "machine credentials". -The default value is "/etc/krb5.keytab". -Previous versions of -.B rpc.gssd -used only "nfs/*" keys found within the keytab. -Now, the first keytab entry for each distinct Kerberos realm -within the keytab is used. This means that an NFS client -no longer needs an "nfs/hostname" principal and keytab entry, -but can instead use a "host/hostname" (or any other) keytab -entry that is available. +to obtain machine credentials. +The default value is +.IR /etc/krb5.keytab . .TP -.B -p path +.B -l Tells .B rpc.gssd -where to look for the rpc_pipefs filesystem. The default value is -"/var/lib/nfs/rpc_pipefs". +to limit session keys to Single DES even if the kernel supports stronger +encryption types. Service ticket encryption is still governed by what +the KDC believes the target server supports. This way the client can +access a server that has strong keys in its keytab for ticket decryption +but whose kernel only supports Single DES. +.IP +The alternative is to put only Single DES keys in the server's keytab +and limit encryption types for its principal to Single DES on the KDC +which will cause service tickets for this server to be encrypted using +only Single DES and (as a side-effect) contain only Single DES session +keys. +.IP +This legacy behaviour is only required for older servers +(pre nfs-utils-1.2.4). If the server has a recent kernel, Kerberos +implementation and nfs-utils it will work just fine with stronger +encryption. +.IP +.B Note: +This option is only available with Kerberos libraries that +support setable encryption types. .TP -.B -d directory +.BI "-p " path Tells .B rpc.gssd -where to look for kerberos credential files. The default value is "/tmp". +where to look for the rpc_pipefs filesystem. The default value is +.IR /var/lib/nfs/rpc_pipefs . +.TP +.BI "-d " search-path +This option specifies a colon separated list of directories that +.B rpc.gssd +searches for credential files. The default value is +.IR /tmp:/run/user/%U . +The literal sequence "%U" can be specified to substitue the UID +of the user for whom credentials are being searched. +.TP +.B -M +By default, machine credentials are stored in files in the first +directory in the credential directory search path (see the +.B -d +option). When +.B -M +is set, +.B rpc.gssd +stores machine credentials in memory instead. .TP .B -v Increases the verbosity of the output (can be specified multiple times). .TP .B -r -If the rpcsec_gss library supports setting debug level, +If the RPCSEC_GSS library supports setting debug level, increases the verbosity of the output (can be specified multiple times). +.TP +.BI "-R " realm +Kerberos tickets from this +.I realm +will be preferred when scanning available credentials cache files to be +used to create a context. By default, the default realm, as configured +in the Kerberos configuration file, is preferred. +.TP +.BI "-t " timeout +Timeout, in seconds, for kernel GSS contexts. This option allows you to force +new kernel contexts to be negotiated after +.I timeout +seconds, which allows changing Kerberos tickets and identities frequently. +The default is no explicit timeout, which means the kernel context will live +the lifetime of the Kerberos service ticket used in its creation. .SH SEE ALSO -.BR rpc.svcgssd(8) +.BR rpc.svcgssd (8), +.BR kerberos (1), +.BR kinit (1), +.BR krb5.conf (5) .SH AUTHORS .br Dug Song