utils/gssd/gssd.man

   1 .\"
   2 .\" rpc.gssd(8)
   3 .\"
   4 .\" Copyright (C) 2003 J. Bruce Fields <bfields@umich.edu>
   5 .\"
   6 .TH rpc.gssd 8 "20 Feb 2013"
   7 .SH NAME
   8 rpc.gssd \- RPCSEC_GSS daemon
   9 .SH SYNOPSIS
  10 .B rpc.gssd
  11 .RB [ \-fMnlvr ]
  12 .RB [ \-k
  13 .IR keytab ]
  14 .RB [ \-p
  15 .IR pipefsdir ]
  16 .RB [ \-d
  17 .IR ccachedir ]
  18 .RB [ \-t
  19 .IR timeout ]
  20 .RB [ \-R
  21 .IR realm ]
  22 .SH INTRODUCTION
  23 The RPCSEC_GSS protocol, defined in RFC 5403, is used to provide
  24 strong security for RPC-based protocols such as NFS.
  25 .P
  26 Before exchanging RPC requests using RPCSEC_GSS, an RPC client must
  27 establish a GSS
  28 .IR "security context" .
  29 A security context is shared state on each
  30 end of a network transport that enables GSS-API security services.
  31 .P
  32 Security contexts are established using
  33 .IR "security credentials" .
  34 A credential grants temporary access to a secure network service,
  35 much as a railway ticket grants temporary access to use a rail service.
  36 .P
  37 A user typically obtains a credential by providing a password to the
  38 .BR kinit (1)
  39 command, or via a PAM library at login time.
  40 A credential acquired with a
  41 .I user principal
  42 is known as a
  43 .I user credential
  44 (see
  45 .BR kerberos (1)
  46 for more on principals).
  47 .P
  48 For certain operations, a credential is required
  49 which represents no user,
  50 is otherwise unprivileged,
  51 and is always available.
  52 This is referred to as a
  53 .IR "machine credential" .
  54 .P
  55 Machine credentials are typically established using a
  56 .IR "service principal" ,
  57 whose encrypted password, called its
  58 .IR key ,
  59 is stored in a file, called a
  60 .IR keytab ,
  61 to avoid requiring a user prompt.
  62 A machine credential effectively does not expire because the system
  63 can renew it as needed without user intervention.
  64 .P
  65 Once obtained, credentials are typically stored in local temporary files
  66 with well-known pathnames.
  67 .SH DESCRIPTION
  68 To establish GSS security contexts using these credential files,
  69 the Linux kernel RPC client depends on a userspace daemon called
  70 .BR rpc.gssd .
  71 The
  72 .B rpc.gssd
  73 daemon uses the rpc_pipefs filesystem to communicate with the kernel.
  74 .SH OPTIONS
  75 .TP
  76 .B -f
  77 Runs
  78 .B rpc.gssd
  79 in the foreground and sends output to stderr (as opposed to syslogd)
  80 .TP
  81 .B -n
  82 By default,
  83 .B rpc.gssd
  84 treats accesses by the user with UID 0 specially, and uses
  85 "machine credentials" for all accesses by that user which
  86 require Kerberos authentication.
  87 With the \-n option, "machine credentials" will not be used
  88 for accesses by UID 0.  Instead, credentials must be obtained
  89 manually like all other users.  Use of this option means that
  90 "root" must manually obtain Kerberos credentials before
  91 attempting to mount an nfs filesystem requiring Kerberos
  92 authentication.
  93 .TP
  94 .BI "-k " keytab
  95 Tells
  96 .B rpc.gssd
  97 to use the keys found in
  98 .I keytab
  99 to obtain "machine credentials".
 100 The default value is
 101 .I /etc/krb5.keytab.
 102 .IP
 103 Previous versions of
 104 .B rpc.gssd
 105 used only "nfs/*" keys found within the keytab.
 106 To be more consistent with other implementations, we now look for
 107 specific keytab entries.  The search order for keytabs to be used
 108 for "machine credentials" is now:
 109 .br
 110   <HOSTNAME>$@<REALM>
 111 .br
 112   root/<hostname>@<REALM>
 113 .br
 114   nfs/<hostname>@<REALM>
 115 .br
 116   host/<hostname>@<REALM>
 117 .br
 118   root/<anyname>@<REALM>
 119 .br
 120   nfs/<anyname>@<REALM>
 121 .br
 122   host/<anyname>@<REALM>
 123 .IP
 124 If this search order does not use the correct key then provide a
 125 keytab file that contains only correct keys.
 126 .TP
 127 .B -l
 128 Tells
 129 .B rpc.gssd
 130 to limit session keys to Single DES even if the kernel supports stronger
 131 encryption types. Service ticket encryption is still governed by what
 132 the KDC believes the target server supports. This way the client can
 133 access a server that has strong keys in its keytab for ticket decryption
 134 but whose kernel only supports Single DES.
 135 .IP
 136 The alternative is to put only Single DES keys in the server's keytab
 137 and limit encryption types for its principal to Single DES on the KDC
 138 which will cause service tickets for this server to be encrypted using
 139 only Single DES and (as a side-effect) contain only Single DES session
 140 keys.
 141 .IP
 142 This legacy behaviour is only required for older servers
 143 (pre nfs-utils-1.2.4). If the server has a recent kernel, Kerberos
 144 implementation and nfs-utils it will work just fine with stronger
 145 encryption.
 146 .IP
 147 .B Note:
 148 This option is only available with Kerberos libraries that
 149 support setable encryption types.
 150 .TP
 151 .BI "-p " path
 152 Tells
 153 .B rpc.gssd
 154 where to look for the rpc_pipefs filesystem.  The default value is
 155 .IR /var/lib/nfs/rpc_pipefs .
 156 .TP
 157 .BI "-d " search-path
 158 This option specifies a colon separated list of directories that
 159 .B rpc.gssd
 160 searches for credential files.  The default value is
 161 .IR /tmp:/run/user/%U .
 162 The literal sequence "%U" can be specified to substitue the UID
 163 of the user for whom credentials are being searched.
 164 .TP
 165 .B -M
 166 By default, machine credentials are stored in files in the first
 167 directory in the credential directory search path (see the
 168 .B -d
 169 option).  When
 170 .B -M
 171 is set,
 172 .B rpc.gssd
 173 stores machine credentials in memory instead.
 174 .TP
 175 .B -v
 176 Increases the verbosity of the output (can be specified multiple times).
 177 .TP
 178 .B -r
 179 If the RPCSEC_GSS library supports setting debug level,
 180 increases the verbosity of the output (can be specified multiple times).
 181 .TP
 182 .BI "-R " realm
 183 Kerberos tickets from this
 184 .I realm
 185 will be preferred when scanning available credentials cache files to be
 186 used to create a context.  By default, the default realm, as configured
 187 in the Kerberos configuration file, is preferred.
 188 .TP
 189 .BI "-t " timeout
 190 Timeout, in seconds, for kernel GSS contexts. This option allows you to force
 191 new kernel contexts to be negotiated after
 192 .I timeout
 193 seconds, which allows changing Kerberos tickets and identities frequently.
 194 The default is no explicit timeout, which means the kernel context will live
 195 the lifetime of the Kerberos service ticket used in its creation.
 196 .SH SEE ALSO
 197 .BR rpc.svcgssd (8),
 198 .BR kerberos (1),
 199 .BR kinit (1),
 200 .BR krb5.conf (5)
 201 .SH AUTHORS
 202 .br
 203 Dug Song <dugsong@umich.edu>
 204 .br
 205 Andy Adamson <andros@umich.edu>
 206 .br
 207 Marius Aamodt Eriksen <marius@umich.edu>
 208 .br
 209 J. Bruce Fields <bfields@umich.edu>