1Application servers
2===================
3
4If you need to install the Kerberos V5 programs on an application
5server, please refer to the Kerberos V5 Installation Guide.  Once you
6have installed the software, you need to add that host to the Kerberos
7database (see :ref:`add_mod_del_princs`), and generate a keytab for
8that host, that contains the host's key.  You also need to make sure
9the host's clock is within your maximum clock skew of the KDCs.
10
11
12Keytabs
13-------
14
15A keytab is a host's copy of its own keylist, which is analogous to a
16user's password.  An application server that needs to authenticate
17itself to the KDC has to have a keytab that contains its own principal
18and key.  Just as it is important for users to protect their
19passwords, it is equally important for hosts to protect their keytabs.
20You should always store keytab files on local disk, and make them
21readable only by root, and you should never send a keytab file over a
22network in the clear.  Ideally, you should run the :ref:`kadmin(1)`
23command to extract a keytab on the host on which the keytab is to
24reside.
25
26
27.. _add_princ_kt:
28
29Adding principals to keytabs
30~~~~~~~~~~~~~~~~~~~~~~~~~~~~
31
32To generate a keytab, or to add a principal to an existing keytab, use
33the **ktadd** command from kadmin.
34
35.. include:: admin_commands/kadmin_local.rst
36   :start-after:  _ktadd:
37   :end-before: _ktadd_end:
38
39
40Examples
41########
42
43Here is a sample session, using configuration files that enable only
44AES encryption::
45
46    kadmin: ktadd host/daffodil.mit.edu@ATHENA.MIT.EDU
47    Entry for principal host/daffodil.mit.edu with kvno 2, encryption type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab
48    Entry for principal host/daffodil.mit.edu with kvno 2, encryption type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab
49    kadmin:
50
51
52Removing principals from keytabs
53~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
54
55To remove a principal from an existing keytab, use the kadmin
56**ktremove** command.
57
58.. include:: admin_commands/kadmin_local.rst
59   :start-after:  _ktremove:
60   :end-before: _ktremove_end:
61
62
63Using a keytab to acquire client credentials
64~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
65
66While keytabs are ordinarily used to accept credentials from clients,
67they can also be used to acquire initial credentials, allowing one
68service to authenticate to another.
69
70To manually obtain credentials using a keytab, use the :ref:`kinit(1)`
71**-k** option, together with the **-t** option if the keytab is not in
72the default location.
73
74Beginning with release 1.11, GSSAPI applications can be configured to
75automatically obtain initial credentials from a keytab as needed.  The
76recommended configuration is as follows:
77
78#. Create a keytab containing a single entry for the desired client
79   identity.
80
81#. Place the keytab in a location readable by the service, and set the
82   **KRB5_CLIENT_KTNAME** environment variable to its filename.
83   Alternatively, use the **default_client_keytab_name** profile
84   variable in :ref:`libdefaults`, or use the default location of
85   |ckeytab|.
86
87#. Set **KRB5CCNAME** to a filename writable by the service, which
88   will not be used for any other purpose.  Do not manually obtain
89   credentials at this location.  (Another credential cache type
90   besides **FILE** can be used if desired, as long the cache will not
91   conflict with another use.  A **MEMORY** cache can be used if the
92   service runs as a long-lived process.  See :ref:`ccache_definition`
93   for details.)
94
95#. Start the service.  When it authenticates using GSSAPI, it will
96   automatically obtain credentials from the client keytab into the
97   specified credential cache, and refresh them before they expire.
98
99
100Clock Skew
101----------
102
103A Kerberos application server host must keep its clock synchronized or
104it will reject authentication requests from clients.  Modern operating
105systems typically provide a facility to maintain the correct time;
106make sure it is enabled.  This is especially important on virtual
107machines, where clocks tend to drift more rapidly than normal machine
108clocks.
109
110The default allowable clock skew is controlled by the **clockskew**
111variable in :ref:`libdefaults`.
112
113
114Getting DNS information correct
115-------------------------------
116
117Several aspects of Kerberos rely on name service.  When a hostname is
118used to name a service, clients may canonicalize the hostname using
119forward and possibly reverse name resolution.  The result of this
120canonicalization must match the principal entry in the host's keytab,
121or authentication will fail.  To work with all client canonicalization
122configurations, each host's canonical name must be the fully-qualified
123host name (including the domain), and each host's IP address must
124reverse-resolve to the canonical name.
125
126Configuration of hostnames varies by operating system.  On the
127application server itself, canonicalization will typically use the
128``/etc/hosts`` file rather than the DNS.  Ensure that the line for the
129server's hostname is in the following form::
130
131    IP address      fully-qualified hostname        aliases
132
133Here is a sample ``/etc/hosts`` file::
134
135    # this is a comment
136    127.0.0.1      localhost localhost.mit.edu
137    10.0.0.6       daffodil.mit.edu daffodil trillium wake-robin
138
139The output of ``klist -k`` for this example host should look like::
140
141    viola# klist -k
142    Keytab name: /etc/krb5.keytab
143    KVNO Principal
144    ---- ------------------------------------------------------------
145       2 host/daffodil.mit.edu@ATHENA.MIT.EDU
146
147If you were to ssh to this host with a fresh credentials cache (ticket
148file), and then :ref:`klist(1)`, the output should list a service
149principal of ``host/daffodil.mit.edu@ATHENA.MIT.EDU``.
150
151
152.. _conf_firewall:
153
154Configuring your firewall to work with Kerberos V5
155--------------------------------------------------
156
157If you need off-site users to be able to get Kerberos tickets in your
158realm, they must be able to get to your KDC.  This requires either
159that you have a replica KDC outside your firewall, or that you
160configure your firewall to allow UDP requests into at least one of
161your KDCs, on whichever port the KDC is running.  (The default is port
16288; other ports may be specified in the KDC's :ref:`kdc.conf(5)`
163file.)  Similarly, if you need off-site users to be able to change
164their passwords in your realm, they must be able to get to your
165Kerberos admin server on the kpasswd port (which defaults to 464).  If
166you need off-site users to be able to administer your Kerberos realm,
167they must be able to get to your Kerberos admin server on the
168administrative port (which defaults to 749).
169
170If your on-site users inside your firewall will need to get to KDCs in
171other realms, you will also need to configure your firewall to allow
172outgoing TCP and UDP requests to port 88, and to port 464 to allow
173password changes.  If your on-site users inside your firewall will
174need to get to Kerberos admin servers in other realms, you will also
175need to allow outgoing TCP and UDP requests to port 749.
176
177If any of your KDCs are outside your firewall, you will need to allow
178kprop requests to get through to the remote KDC.  :ref:`kprop(8)` uses
179the ``krb5_prop`` service on port 754 (tcp).
180
181The book *UNIX System Security*, by David Curry, is a good starting
182point for learning to configure firewalls.
183