rpc.gssd(8)		    System Manager's Manual		   rpc.gssd(8)



NAME
       rpc.gssd - RPCSEC_GSS daemon

SYNOPSIS
       rpc.gssd [-DfMnlvr] [-k keytab] [-p pipefsdir] [-d ccachedir] [-t time-
       out] [-R realm]

INTRODUCTION
       The RPCSEC_GSS protocol, defined in RFC 5403, is used to provide strong
       security for RPC-based protocols such as NFS.

       Before  exchanging  RPC	requests  using RPCSEC_GSS, an RPC client must
       establish a GSS security context.  A security context is	 shared	 state
       on  each	 end of a network transport that enables GSS-API security ser-
       vices.

       Security contexts are established using security credentials.   A  cre-
       dential	grants temporary access to a secure network service, much as a
       railway ticket grants temporary access to use a rail service.

       A user typically obtains a credential by providing a  password  to  the
       kinit(1)	 command,  or  via  a PAM library at login time.  A credential
       acquired with a user principal is known as a user credential (see  ker-
       beros(1) for more on principals).

       For  certain  operations,  a credential is required which represents no
       user, is otherwise unprivileged, and  is	 always	 available.   This  is
       referred to as a machine credential.

       Machine	credentials  are typically established using a service princi-
       pal, whose encrypted password, called its key, is  stored  in  a	 file,
       called  a  keytab, to avoid requiring a user prompt.  A machine creden-
       tial effectively does not expire because the system  can	 renew	it  as
       needed without user intervention.

       Once  obtained,	credentials  are  typically  stored in local temporary
       files with well-known pathnames.

DESCRIPTION
       To establish GSS security contexts using these  credential  files,  the
       Linux  kernel RPC client depends on a userspace daemon called rpc.gssd.
       The rpc.gssd daemon uses the rpc_pipefs filesystem to communicate  with
       the kernel.

   User Credentials
       When a user authenticates using a command such as kinit(1), the result-
       ing credential is stored in a file with a well-known  name  constructed
       using the user's UID.

       To  interact  with  an  NFS  server on behalf of a particular Kerberos-
       authenticated user, the Linux kernel RPC client requests that  rpc.gssd
       initialize  a  security context with the credential in that user's cre-
       dential file.

       Typically, credential files are placed in /tmp.	However, rpc.gssd  can
       search  for  credential	files  in  more	 than  one directory.  See the
       description of the -d option for details.

   Machine Credentials
       A user credential is established by a user and is then shared with  the
       kernel  and  rpc.gssd.  A machine credential is established by rpc.gssd
       for the kernel when there is no user.  Therefore rpc.gssd must  already
       have the materials on hand to establish this credential without requir-
       ing user intervention.

       rpc.gssd searches the local system's keytab for a principal and key  to
       use  to establish the machine credential.  By default, rpc.gssd assumes
       the file /etc/krb5.keytab contains principals and keys that can be used
       to obtain machine credentials.

       rpc.gssd	 searches  in the following order for a principal to use.  The
       first matching credential is used.   For	 the  search,  <hostname>  and
       <REALM>	are  replaced  with  the  local system's hostname and Kerberos
       realm.

	  <HOSTNAME>$@<REALM>
	  root/<hostname>@<REALM>
	  nfs/<hostname>@<REALM>
	  host/<hostname>@<REALM>
	  root/<anyname>@<REALM>
	  nfs/<anyname>@<REALM>
	  host/<anyname>@<REALM>

       The <anyname> 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.

       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.

       You   can   specify   another   keytab	by  using  the	-k  option  if
       /etc/krb5.keytab does not exist or does not provide one of these	 prin-
       cipals.

   Credentials for UID 0
       UID 0 is a special case.	 By default 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.

       Specify the -n option when starting rpc.gssd if you'd like to force the
       root  user  to  obtain a user credential rather than use the local sys-
       tem's machine credential.

       When -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 rpc.gssd cannot  obtain  a
       machine	credential (say, the local system has no keytab), NFSv4 opera-
       tions that require machine credentials will fail.

   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  aes256-cts-hmac-sha1-96,
       aes128-cts-hmac-sha1-96,	 des3-cbc-sha1,	 and  arcfour-hmac  encryption
       types.  This permits rpc.gssd to choose an appropriate encryption  type
       that the target NFS server supports.

       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 -l option when starting rpc.gssd.

OPTIONS
       -D     The server name passed to GSSAPI for authentication is  normally
	      the  name	 exactly  as requested.	 e.g. for NFS it is the server
	      name in the "servername:/path"  mount  request.	Only  if  this
	      servername  appears  to  be  an  IP address (IPv4 or IPv6) or an
	      unqualified name (no dots) will a reverse	 DNS  lookup  will  be
	      performed to get the canoncial server name.

	      If -D is present, a reverse DNS lookup will always be used, even
	      if the server name looks like a canonical name.  So it is needed
	      if  partially  qualified,	 or  non canonical names are regularly
	      used.

	      Using -D can introduce a security vulnerability, so it is recom-
	      mended  that  -D not be used, and that canonical names always be
	      used when requesting services.

       -f     Runs rpc.gssd in the foreground and sends output to  stderr  (as
	      opposed to syslogd)

       -n     When specified, UID 0 is forced to obtain user credentials which
	      are used instead of the local system's machine credentials.

       -k keytab
	      Tells rpc.gssd to use the keys found in keytab to obtain machine
	      credentials.  The default value is /etc/krb5.keytab.

       -l     When  specified,	restricts rpc.gssd to sessions to weak encryp-
	      tion types such as des-cbc-crc.  This option is  available  only
	      when  the	 local	system's  Kerberos  library  supports settable
	      encryption types.

       -p path
	      Tells rpc.gssd where to look for the rpc_pipefs filesystem.  The
	      default value is /var/lib/nfs/rpc_pipefs.

       -d search-path
	      This option specifies a colon separated list of directories that
	      rpc.gssd searches for credential files.  The  default  value  is
	      /tmp:/run/user/%U.   The	literal sequence "%U" can be specified
	      to substitue the UID of the user for whom credentials are	 being
	      searched.

       -M     By default, machine credentials are stored in files in the first
	      directory in the credential directory search path	 (see  the  -d
	      option).	When -M is set, rpc.gssd stores machine credentials in
	      memory instead.

       -v     Increases the verbosity of the output (can be specified multiple
	      times).

       -r     If   the	 RPCSEC_GSS  library  supports	setting	 debug	level,
	      increases the verbosity of the output (can be specified multiple
	      times).

       -R realm
	      Kerberos tickets from this realm will be preferred when scanning
	      available credentials cache files to be used to  create  a  con-
	      text.   By default, the default realm, as configured in the Ker-
	      beros configuration file, is preferred.

       -t timeout
	      Timeout, in seconds, for kernel GSS contexts. This option allows
	      you  to force new kernel contexts to be negotiated after 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.

       -T timeout
	      Timeout,	in  seconds, to create an RPC connection with a server
	      while establishing an authenticated gss context for a user.  The
	      default  timeout	is set to 5 seconds.  If you get messages like
	      "WARNING: can't create tcp rpc_clnt to server  %servername%  for
	      user with uid %uid%: RPC: Remote system error - Connection timed
	      out", you should consider an increase of this timeout.

SEE ALSO
       rpc.svcgssd(8), kerberos(1), kinit(1), krb5.conf(5)

AUTHORS
       Dug Song <dugsong@umich.edu>
       Andy Adamson <andros@umich.edu>
       Marius Aamodt Eriksen <marius@umich.edu>
       J. Bruce Fields <bfields@umich.edu>



				  20 Feb 2013			   rpc.gssd(8)