X-Git-Url: https://git.decadent.org.uk/gitweb/?p=nfs-utils.git;a=blobdiff_plain;f=utils%2Fgssd%2Fgssd.man;h=fb3ab9788260d19a37d405b697bab7d390375091;hp=d8f9a0f4c52f40f57647912ccba2e0cc4bd1e7fa;hb=e661019a2827aa0b303f4b2be54f0670c68812bf;hpb=f1bfe0916c04d93de7a4fae5315fff6e4ccac23f diff --git a/utils/gssd/gssd.man b/utils/gssd/gssd.man index d8f9a0f..fb3ab97 100644 --- a/utils/gssd/gssd.man +++ b/utils/gssd/gssd.man @@ -2,22 +2,75 @@ .\" rpc.gssd(8) .\" .\" Copyright (C) 2003 J. Bruce Fields -.TH rpc.gssd 8 "17 Mar 2003" +.\" +.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] [-k keytab] [-p pipefsdir] [-v]" -.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 .B rpc.gssd -to establish security contexts. The +.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 +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 files in the rpc_pipefs filesystem to communicate with the kernel. - +daemon uses the rpc_pipefs filesystem to communicate with the kernel. .SH OPTIONS .TP .B -f @@ -25,33 +78,126 @@ Runs .B rpc.gssd in the foreground and sends output to stderr (as opposed to syslogd) .TP -.B -k keytab +.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 +attempting to mount an nfs filesystem requiring Kerberos +authentication. +.TP +.BI "-k " keytab Tells .B rpc.gssd -to use the keys for principals nfs/hostname in +to use the keys found in .I keytab -to obtain machine credentials. -The default value is "/etc/krb5.keytab". -.\".TP -.\".B -m -.\"Ordinarily, -.\".B rpc.gssd -.\"looks for a cached ticket for user $UID in /tmp/krb5cc_$UID. -.\"With the -m option, the user with uid 0 will be treated specially, and will -.\"be mapped instead to the credentials for the principal nfs/hostname found in -.\"the keytab file. -.\"(This option is now the default and is ignored if specified.) -.TP -.B -p path +to obtain "machine credentials". +The default value is +.I /etc/krb5.keytab. +.IP +Previous versions of +.B rpc.gssd +used only "nfs/*" keys found within the keytab. +To be more consistent with other implementations, we now look for +specific keytab entries. The search order for keytabs to be used +for "machine credentials" is now: +.br + $@ +.br + root/@ +.br + nfs/@ +.br + host/@ +.br + root/@ +.br + nfs/@ +.br + host/@ +.IP +If this search order does not use the correct key then provide a +keytab file that contains only correct keys. +.TP +.B -l +Tells +.B rpc.gssd +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 +.BI "-p " path Tells .B rpc.gssd where to look for the rpc_pipefs filesystem. The default value is -"/var/lib/nfs/rpc_pipefs". +.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, +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