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 .SS User Credentials
  75 When a user authenticates using a command such as
  76 .BR kinit (1),
  77 the resulting credential is stored in a file with a well-known name
  78 constructed using the user's UID.
  79 .P
  80 To interact with an NFS server
  81 on behalf of a particular Kerberos-authenticated user,
  82 the Linux kernel RPC client requests that
  83 .B rpc.gssd
  84 initialize a security context with the credential
  85 in that user's credential file.
  86 .P
  87 Typically, credential files are placed in
  88 .IR /tmp .
  89 However,
  90 .B rpc.gssd
  91 can search for credential files in more than one directory.
  92 See the description of the
  93 .B -d
  94 option for details.
  95 .SS Machine Credentials
  96 A user credential is established by a user and
  97 is then shared with the kernel and
  98 .BR rpc.gssd .
  99 A machine credential is established by
 100 .B rpc.gssd
 101 for the kernel when there is no user.
 102 Therefore
 103 .B rpc.gssd
 104 must already have the materials on hand to establish this credential
 105 without requiring user intervention.
 106 .P
 107 .B rpc.gssd
 108 searches the local system's keytab for a principal and key to use
 109 to establish the machine credential.
 110 By default,
 111 .B rpc.gssd
 112 assumes the file
 113 .I /etc/krb5.keytab
 114 contains principals and keys that can be used to obtain machine credentials.
 115 .P
 116 .B rpc.gssd
 117 searches in the following order for a principal to use.
 118 The first matching credential is used.
 119 For the search, <hostname> and <REALM> are replaced with the local
 120 system's hostname and Kerberos realm.
 121 .sp
 122    <HOSTNAME>$@<REALM>
 123 .br
 124    root/<hostname>@<REALM>
 125 .br
 126    nfs/<hostname>@<REALM>
 127 .br
 128    host/<hostname>@<REALM>
 129 .br
 130    root/<anyname>@<REALM>
 131 .br
 132    nfs/<anyname>@<REALM>
 133 .br
 134    host/<anyname>@<REALM>
 135 .sp
 136 The <anyname> entries match on the service name and realm, but ignore the hostname.
 137 These can be used if a principal matching the local host's name is not found.
 138 .P
 139 Note that the first principal in the search order is a user principal
 140 that enables Kerberized NFS when the local system is joined
 141 to an Active Directory domain using Samba.
 142 A password for this principal must be provided in the local system's keytab.
 143 .P
 144 You can specify another keytab by using the
 145 .B -k
 146 option if
 147 .I /etc/krb5.keytab
 148 does not exist or does not provide one of these principals.
 149 .SS Credentials for UID 0
 150 UID 0 is a special case.
 151 By default
 152 .B rpc.gssd
 153 uses the system's machine credentials for UID 0 accesses
 154 that require GSS authentication.
 155 This limits the privileges of the root user
 156 when accessing network resources that require authentication.
 157 .P
 158 Specify the
 159 .B -n
 160 option when starting
 161 .B rpc.gssd
 162 if you'd like to force the root user to obtain a user credential
 163 rather than use the local system's machine credential.
 164 .P
 165 When
 166 .B -n
 167 is specified,
 168 the kernel continues to request a GSS context established
 169 with a machine credential for NFSv4 operations,
 170 such as SETCLIENTID or RENEW, that manage state.
 171 If
 172 .B rpc.gssd
 173 cannot obtain a machine credential (say, the local system has
 174 no keytab), NFSv4 operations that require machine credentials will fail.
 175 .SS Encryption types
 176 A realm administrator can choose to add keys encoded in a number of different
 177 encryption types to the local system's keytab.
 178 For instance, a host/ principal might have keys for the
 179 .BR aes256-cts-hmac-sha1-96 ,
 180 .BR aes128-cts-hmac-sha1-96 ,
 181 .BR des3-cbc-sha1 ", and"
 182 .BR arcfour-hmac " encryption types."
 183 This permits
 184 .B rpc.gssd
 185 to choose an appropriate encryption type that the target NFS server
 186 supports.
 187 .P
 188 These encryption types are stronger than legacy single-DES encryption types.
 189 To interoperate in environments where servers support
 190 only weak encryption types,
 191 you can restrict your client to use only single-DES encryption types
 192 by specifying the
 193 .B -l
 194 option when starting
 195 .BR rpc.gssd .
 196 .SH OPTIONS
 197 .TP
 198 .B -f
 199 Runs
 200 .B rpc.gssd
 201 in the foreground and sends output to stderr (as opposed to syslogd)
 202 .TP
 203 .B -n
 204 When specified, UID 0 is forced to obtain user credentials
 205 which are used instead of the local system's machine credentials.
 206 .TP
 207 .BI "-k " keytab
 208 Tells
 209 .B rpc.gssd
 210 to use the keys found in
 211 .I keytab
 212 to obtain machine credentials.
 213 The default value is
 214 .IR /etc/krb5.keytab .
 215 .TP
 216 .B -l
 217 When specified, restricts
 218 .B rpc.gssd
 219 to sessions to weak encryption types such as
 220 .BR des-cbc-crc .
 221 This option is available only when the local system's Kerberos library
 222 supports settable encryption types.
 223 .TP
 224 .BI "-p " path
 225 Tells
 226 .B rpc.gssd
 227 where to look for the rpc_pipefs filesystem.  The default value is
 228 .IR /var/lib/nfs/rpc_pipefs .
 229 .TP
 230 .BI "-d " search-path
 231 This option specifies a colon separated list of directories that
 232 .B rpc.gssd
 233 searches for credential files.  The default value is
 234 .IR /tmp:/run/user/%U .
 235 The literal sequence "%U" can be specified to substitue the UID
 236 of the user for whom credentials are being searched.
 237 .TP
 238 .B -M
 239 By default, machine credentials are stored in files in the first
 240 directory in the credential directory search path (see the
 241 .B -d
 242 option).  When
 243 .B -M
 244 is set,
 245 .B rpc.gssd
 246 stores machine credentials in memory instead.
 247 .TP
 248 .B -v
 249 Increases the verbosity of the output (can be specified multiple times).
 250 .TP
 251 .B -r
 252 If the RPCSEC_GSS library supports setting debug level,
 253 increases the verbosity of the output (can be specified multiple times).
 254 .TP
 255 .BI "-R " realm
 256 Kerberos tickets from this
 257 .I realm
 258 will be preferred when scanning available credentials cache files to be
 259 used to create a context.  By default, the default realm, as configured
 260 in the Kerberos configuration file, is preferred.
 261 .TP
 262 .BI "-t " timeout
 263 Timeout, in seconds, for kernel GSS contexts. This option allows you to force
 264 new kernel contexts to be negotiated after
 265 .I timeout
 266 seconds, which allows changing Kerberos tickets and identities frequently.
 267 The default is no explicit timeout, which means the kernel context will live
 268 the lifetime of the Kerberos service ticket used in its creation.
 269 .SH SEE ALSO
 270 .BR rpc.svcgssd (8),
 271 .BR kerberos (1),
 272 .BR kinit (1),
 273 .BR krb5.conf (5)
 274 .SH AUTHORS
 275 .br
 276 Dug Song <dugsong@umich.edu>
 277 .br
 278 Andy Adamson <andros@umich.edu>
 279 .br
 280 Marius Aamodt Eriksen <marius@umich.edu>
 281 .br
 282 J. Bruce Fields <bfields@umich.edu>