src/gen-manpages/kerberos.M

   1 .\" Copyright 1989, 2011 by the Massachusetts Institute of Technology.
   2 .\"
   3 .\" For copying and distribution information,
   4 .\" please see the file <mit-copyright.h>.
   5 .\" "
   6 .TH KERBEROS 1
   7 .SH NAME
   8 kerberos \- introduction to the Kerberos system
   9 .SH DESCRIPTION
  10 The Kerberos system authenticates individual users in a network
  11 environment.  After authenticating yourself to Kerberos, you can use
  12 Kerberos-enabled programs without having to present passwords.
  13 .PP
  14 If you enter your username and
  15 .I kinit
  16 responds with this message:
  17 .PP
  18 kinit(v5): Client not found in Kerberos database while getting initial
  19 credentials
  20 .PP
  21 you haven't been registered as a Kerberos user.  See your system
  22 administrator.
  23 .PP
  24 A Kerberos name usually contains three parts.  The first is the
  25 .IR primary ,
  26 which is usually a user's or service's name.  The second is the
  27 .IR instance ,
  28 which in the case of a user is usually null.  Some users may have
  29 privileged instances, however, such as ``root'' or ``admin''.  In the
  30 case of a service, the instance is the fully qualified name of the
  31 machine on which it runs; i.e. there can be an
  32 .I rlogin
  33 service running on the machine ABC, which is different from the rlogin
  34 service running on the machine XYZ.  The third part of a Kerberos name
  35 is the
  36 .IR realm .
  37 The realm corresponds to the Kerberos service providing authentication
  38 for the principal.
  39 .PP
  40 When writing a Kerberos name, the principal name is separated from the
  41 instance (if not null) by a slash, and the realm (if not the local
  42 realm) follows, preceded by an ``@'' sign.  The following are examples
  43 of valid Kerberos names:
  44 .sp
  45 .nf
  46 .in +8
  47 david
  48 jennifer/admin
  49 joeuser@BLEEP.COM
  50 cbrown/root@FUBAR.ORG
  51 .in -8
  52 .fi
  53 .PP
  54 When you authenticate yourself with Kerberos you get an initial Kerberos
  55 .IR ticket .
  56 (A Kerberos ticket is an encrypted protocol message that provides
  57 authentication.)  Kerberos uses this ticket for network utilities such
  58 as
  59 .I rlogin
  60 and
  61 .IR rcp .
  62 The ticket transactions are done transparently, so you don't have to
  63 worry about their management.
  64 .PP
  65 Note, however, that tickets expire.  Privileged tickets, such as those
  66 with the instance ``root'', expire in a few minutes, while tickets that
  67 carry more ordinary privileges may be good for several hours or a day,
  68 depending on the installation's policy.  If your login session extends
  69 beyond the time limit, you will have to re-authenticate yourself to
  70 Kerberos to get new tickets.  Use the
  71 .IR kinit
  72 command to re-authenticate yourself.
  73 .PP
  74 If you use the
  75 .I kinit
  76 command to get your tickets, make sure you use the
  77 .I kdestroy
  78 command to destroy your tickets before you end your login session.  You
  79 should put the
  80 .I kdestroy
  81 command in your
  82 .I \.logout
  83 file so that your tickets will be destroyed automatically when you
  84 logout.  For more information about the
  85 .I kinit
  86 and
  87 .I kdestroy
  88 commands, see the
  89 .IR kinit (1)
  90 and
  91 .IR kdestroy (1)
  92 manual pages.
  93 .PP
  94 Kerberos tickets can be forwarded.  In order to forward tickets, you
  95 must request
  96 .I forwardable
  97 tickets when you
  98 .IR kinit .
  99 Once you have forwardable tickets, most Kerberos programs have a command
 100 line option to forward them to the remote host.
 101 .SH "ENVIRONMENT VARIABLES"
 102 Several environment variables affect the operation of Kerberos-enabled
 103 programs.  These include:
 104 .TP
 105 .B KRB5CCNAME
 106 Specifies the location of the credential cache, in the form
 107 \fITYPE\fP:\fIresidual\fP.  If no type prefix is present, the
 108 \fBFILE\fP type is assumed and \fIresidual\fP is the pathname of the
 109 cache file.  A collection of multiple caches may be used by specifying
 110 the \fBDIR\fP type and the pathname of a private directory (which must
 111 already exist).  The default cache file is /tmp/krb5cc_\fIuid\fP where
 112 \fIuid\fP is the decimal user ID of the user.
 113 .TP
 114 .B KRB5_KTNAME
 115 Specifies the location of the keytab file, in the form
 116 \fITYPE\fP:\fIresidual\fP.  If no type is present, the \fBFILE\fP type
 117 is assumed and \fIresidual\fP is the pathname of the keytab file.  The
 118 default keytab file is /etc/krb5.keytab.
 119 .TP
 120 .B KRB5_CONFIG
 121 Specifies the location of the Kerberos configuration file.  The
 122 default is /etc/krb5.conf.
 123 .TP
 124 .B KRB5_KDC_PROFILE
 125 Specifies the location of the KDC configuration file, which contains
 126 additional configuration directives for the Key Distribution Center
 127 daemon and associated programs.  The default is
 128 /usr/local/var/krb5kdc/kdc.conf.
 129 .TP
 130 .B KRB5RCACHETYPE
 131 Specifies the default type of replay cache to use for servers.  Valid
 132 types include "dfl" for the normal file type and "none" for no replay
 133 cache.
 134 .B KRB5RCACHEDIR
 135 Specifies the default directory for replay caches used by servers.
 136 The default is the value of the \fBTMPDIR\fP environment variable, or
 137 /var/tmp if \fBTMPDIR\fP is not set.
 138 .TP
 139 .B KRB5_TRACE
 140 Specifies a filename to write trace log output to.  Trace logs can
 141 help illuminate decisions made internally by the Kerberos libraries.
 142 The default is not to write trace log output anywhere.
 143 .PP
 144 Most environment variables are disabled for certain programs, such as
 145 login system programs and setuid programs, which are designed to be
 146 secure when run within an untrusted process environment.
 147 .SH "SEE ALSO"
 148 kdestroy(1), kinit(1), klist(1), kswitch(1), kpasswd(1), ksu(1),
 149 krb5.conf(5), kdc.conf(5), kadmin(1), kadmind(8), kdb5_util(8),
 150 krb5kdc(8)
 151 .SH BUGS
 152 .SH AUTHORS
 153 Steve Miller, MIT Project Athena/Digital Equipment Corporation
 154 .br
 155 Clifford Neuman, MIT Project Athena
 156 .br
 157 Greg Hudson, MIT Kerberos Consortium
 158 .SH HISTORY
 159 The MIT Kerberos 5 implementation was developed at MIT, with
 160 contributions from many outside parties.  It is currently maintained
 161 by the MIT Kerberos Consortium.
 162 .SH RESTRICTIONS
 163 Copyright 1985,1986,1989-1996,2002,2011 Massachusetts Institute of Technology