X-Git-Url: https://git.decadent.org.uk/gitweb/?p=nfs-utils.git;a=blobdiff_plain;f=utils%2Fgssd%2Fgssd.man;h=1df75c57e1f6f09fb5a2891a4554751583b5cf1c;hp=fb3ab9788260d19a37d405b697bab7d390375091;hb=fb06ed9fc1fa11a95544fb2d89adb6c51ef5d946;hpb=e661019a2827aa0b303f4b2be54f0670c68812bf diff --git a/utils/gssd/gssd.man b/utils/gssd/gssd.man index fb3ab97..1df75c5 100644 --- a/utils/gssd/gssd.man +++ b/utils/gssd/gssd.man @@ -8,7 +8,7 @@ rpc.gssd \- RPCSEC_GSS daemon .SH SYNOPSIS .B rpc.gssd -.RB [ \-fMnlvr ] +.RB [ \-DfMnlvr ] .RB [ \-k .IR keytab ] .RB [ \-p @@ -71,82 +71,161 @@ the Linux kernel RPC client depends on a userspace daemon called 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 +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 +cannot obtain a machine credential (say, the local system has +no keytab), NFSv4 operations that require machine credentials will fail. +.SS Encryption types +A realm administrator can choose to add keys encoded in a number of different +encryption types to the local system's keytab. +For instance, a host/ principal might have keys for the +.BR aes256-cts-hmac-sha1-96 , +.BR aes128-cts-hmac-sha1-96 , +.BR des3-cbc-sha1 ", and" +.BR arcfour-hmac " encryption types." +This permits +.B rpc.gssd +to choose an appropriate encryption type that the target NFS server +supports. +.P +These encryption types are stronger than legacy single-DES encryption types. +To interoperate in environments where servers support +only weak encryption types, +you can restrict your client to use only single-DES encryption types +by specifying the +.B -l +option when starting +.BR rpc.gssd . .SH OPTIONS .TP +.B -D +DNS Reverse lookups are not used for determining the +server names pass to GSSAPI. This option will reverses that and forces +the use of DNS Reverse resolution of the server's IP address to +retrieve the server name to use in GSAPI authentication. +.TP .B -f Runs .B rpc.gssd 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 -attempting 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 .BI "-k " keytab Tells .B rpc.gssd to use the keys found in .I keytab -to obtain "machine credentials". +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. +.IR /etc/krb5.keytab . .TP .B -l -Tells +When specified, restricts .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. +to sessions to weak encryption types such as +.BR des-cbc-crc . +This option is available only when the local system's Kerberos library +supports settable encryption types. .TP .BI "-p " path Tells