|
Packit |
fd8b60 |
Installing KDCs
|
|
Packit |
fd8b60 |
===============
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
When setting up Kerberos in a production environment, it is best to
|
|
Packit |
fd8b60 |
have multiple replica KDCs alongside with a master KDC to ensure the
|
|
Packit |
fd8b60 |
continued availability of the Kerberized services. Each KDC contains
|
|
Packit |
fd8b60 |
a copy of the Kerberos database. The master KDC contains the writable
|
|
Packit |
fd8b60 |
copy of the realm database, which it replicates to the replica KDCs at
|
|
Packit |
fd8b60 |
regular intervals. All database changes (such as password changes)
|
|
Packit |
fd8b60 |
are made on the master KDC. Replica KDCs provide Kerberos
|
|
Packit |
fd8b60 |
ticket-granting services, but not database administration, when the
|
|
Packit |
fd8b60 |
master KDC is unavailable. MIT recommends that you install all of
|
|
Packit |
fd8b60 |
your KDCs to be able to function as either the master or one of the
|
|
Packit |
fd8b60 |
replicas. This will enable you to easily switch your master KDC with
|
|
Packit |
fd8b60 |
one of the replicas if necessary (see :ref:`switch_master_replica`).
|
|
Packit |
fd8b60 |
This installation procedure is based on that recommendation.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. warning::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
- The Kerberos system relies on the availability of correct time
|
|
Packit |
fd8b60 |
information. Ensure that the master and all replica KDCs have
|
|
Packit |
fd8b60 |
properly synchronized clocks.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
- It is best to install and run KDCs on secured and dedicated
|
|
Packit |
fd8b60 |
hardware with limited access. If your KDC is also a file
|
|
Packit |
fd8b60 |
server, FTP server, Web server, or even just a client machine,
|
|
Packit |
fd8b60 |
someone who obtained root access through a security hole in any
|
|
Packit |
fd8b60 |
of those areas could potentially gain access to the Kerberos
|
|
Packit |
fd8b60 |
database.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Install and configure the master KDC
|
|
Packit |
fd8b60 |
------------------------------------
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Install Kerberos either from the OS-provided packages or from the
|
|
Packit |
fd8b60 |
source (See :ref:`do_build`).
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. note::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
For the purpose of this document we will use the following
|
|
Packit |
fd8b60 |
names::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
kerberos.mit.edu - master KDC
|
|
Packit |
fd8b60 |
kerberos-1.mit.edu - replica KDC
|
|
Packit |
fd8b60 |
ATHENA.MIT.EDU - realm name
|
|
Packit |
fd8b60 |
.k5.ATHENA.MIT.EDU - stash file
|
|
Packit |
fd8b60 |
admin/admin - admin principal
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
See :ref:`mitK5defaults` for the default names and locations
|
|
Packit |
fd8b60 |
of the relevant to this topic files. Adjust the names and
|
|
Packit |
fd8b60 |
paths to your system environment.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Edit KDC configuration files
|
|
Packit |
fd8b60 |
----------------------------
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Modify the configuration files, :ref:`krb5.conf(5)` and
|
|
Packit |
fd8b60 |
:ref:`kdc.conf(5)`, to reflect the correct information (such as
|
|
Packit |
fd8b60 |
domain-realm mappings and Kerberos servers names) for your realm.
|
|
Packit |
fd8b60 |
(See :ref:`mitK5defaults` for the recommended default locations for
|
|
Packit |
fd8b60 |
these files).
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Most of the tags in the configuration have default values that will
|
|
Packit |
fd8b60 |
work well for most sites. There are some tags in the
|
|
Packit |
fd8b60 |
:ref:`krb5.conf(5)` file whose values must be specified, and this
|
|
Packit |
fd8b60 |
section will explain those.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
If the locations for these configuration files differs from the
|
|
Packit |
fd8b60 |
default ones, set **KRB5_CONFIG** and **KRB5_KDC_PROFILE** environment
|
|
Packit |
fd8b60 |
variables to point to the krb5.conf and kdc.conf respectively. For
|
|
Packit |
fd8b60 |
example::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
export KRB5_CONFIG=/yourdir/krb5.conf
|
|
Packit |
fd8b60 |
export KRB5_KDC_PROFILE=/yourdir/kdc.conf
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
krb5.conf
|
|
Packit |
fd8b60 |
~~~~~~~~~
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
If you are not using DNS TXT records (see :ref:`mapping_hostnames`),
|
|
Packit |
fd8b60 |
you must specify the **default_realm** in the :ref:`libdefaults`
|
|
Packit |
fd8b60 |
section. If you are not using DNS URI or SRV records (see
|
|
Packit |
fd8b60 |
:ref:`kdc_hostnames` and :ref:`kdc_discovery`), you must include the
|
|
Packit |
fd8b60 |
**kdc** tag for each *realm* in the :ref:`realms` section. To
|
|
Packit |
fd8b60 |
communicate with the kadmin server in each realm, the **admin_server**
|
|
Packit |
fd8b60 |
tag must be set in the
|
|
Packit |
fd8b60 |
:ref:`realms` section.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
An example krb5.conf file::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
[libdefaults]
|
|
Packit |
fd8b60 |
default_realm = ATHENA.MIT.EDU
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
[realms]
|
|
Packit |
fd8b60 |
ATHENA.MIT.EDU = {
|
|
Packit |
fd8b60 |
kdc = kerberos.mit.edu
|
|
Packit |
fd8b60 |
kdc = kerberos-1.mit.edu
|
|
Packit |
fd8b60 |
admin_server = kerberos.mit.edu
|
|
Packit |
fd8b60 |
}
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
kdc.conf
|
|
Packit |
fd8b60 |
~~~~~~~~
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
The kdc.conf file can be used to control the listening ports of the
|
|
Packit |
fd8b60 |
KDC and kadmind, as well as realm-specific defaults, the database type
|
|
Packit |
fd8b60 |
and location, and logging.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
An example kdc.conf file::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
[kdcdefaults]
|
|
Packit |
fd8b60 |
kdc_listen = 88
|
|
Packit |
fd8b60 |
kdc_tcp_listen = 88
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
[realms]
|
|
Packit |
fd8b60 |
ATHENA.MIT.EDU = {
|
|
Packit |
fd8b60 |
kadmind_port = 749
|
|
Packit |
fd8b60 |
max_life = 12h 0m 0s
|
|
Packit |
fd8b60 |
max_renewable_life = 7d 0h 0m 0s
|
|
Packit |
fd8b60 |
master_key_type = aes256-cts
|
|
Packit |
fd8b60 |
supported_enctypes = aes256-cts:normal aes128-cts:normal
|
|
Packit |
fd8b60 |
# If the default location does not suit your setup,
|
|
Packit |
fd8b60 |
# explicitly configure the following values:
|
|
Packit |
fd8b60 |
# database_name = /var/krb5kdc/principal
|
|
Packit |
fd8b60 |
# key_stash_file = /var/krb5kdc/.k5.ATHENA.MIT.EDU
|
|
Packit |
fd8b60 |
# acl_file = /var/krb5kdc/kadm5.acl
|
|
Packit |
fd8b60 |
}
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
[logging]
|
|
Packit |
fd8b60 |
# By default, the KDC and kadmind will log output using
|
|
Packit |
fd8b60 |
# syslog. You can instead send log output to files like this:
|
|
Packit |
fd8b60 |
kdc = FILE:/var/log/krb5kdc.log
|
|
Packit |
fd8b60 |
admin_server = FILE:/var/log/kadmin.log
|
|
Packit |
fd8b60 |
default = FILE:/var/log/krb5lib.log
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Replace ``ATHENA.MIT.EDU`` and ``kerberos.mit.edu`` with the name of
|
|
Packit |
fd8b60 |
your Kerberos realm and server respectively.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. note::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
You have to have write permission on the target directories
|
|
Packit |
fd8b60 |
(these directories must exist) used by **database_name**,
|
|
Packit |
fd8b60 |
**key_stash_file**, and **acl_file**.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. _create_db:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Create the KDC database
|
|
Packit |
fd8b60 |
-----------------------
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
You will use the :ref:`kdb5_util(8)` command on the master KDC to
|
|
Packit |
fd8b60 |
create the Kerberos database and the optional :ref:`stash_definition`.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. note::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
If you choose not to install a stash file, the KDC will
|
|
Packit |
fd8b60 |
prompt you for the master key each time it starts up. This
|
|
Packit |
fd8b60 |
means that the KDC will not be able to start automatically,
|
|
Packit |
fd8b60 |
such as after a system reboot.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
:ref:`kdb5_util(8)` will prompt you for the master password for the
|
|
Packit |
fd8b60 |
Kerberos database. This password can be any string. A good password
|
|
Packit |
fd8b60 |
is one you can remember, but that no one else can guess. Examples of
|
|
Packit |
fd8b60 |
bad passwords are words that can be found in a dictionary, any common
|
|
Packit |
fd8b60 |
or popular name, especially a famous person (or cartoon character),
|
|
Packit |
fd8b60 |
your username in any form (e.g., forward, backward, repeated twice,
|
|
Packit |
fd8b60 |
etc.), and any of the sample passwords that appear in this manual.
|
|
Packit |
fd8b60 |
One example of a password which might be good if it did not appear in
|
|
Packit |
fd8b60 |
this manual is "MITiys4K5!", which represents the sentence "MIT is
|
|
Packit |
fd8b60 |
your source for Kerberos 5!" (It's the first letter of each word,
|
|
Packit |
fd8b60 |
substituting the numeral "4" for the word "for", and includes the
|
|
Packit |
fd8b60 |
punctuation mark at the end.)
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
The following is an example of how to create a Kerberos database and
|
|
Packit |
fd8b60 |
stash file on the master KDC, using the :ref:`kdb5_util(8)` command.
|
|
Packit |
fd8b60 |
Replace ``ATHENA.MIT.EDU`` with the name of your Kerberos realm::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
shell% kdb5_util create -r ATHENA.MIT.EDU -s
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU',
|
|
Packit |
fd8b60 |
master key name 'K/M@ATHENA.MIT.EDU'
|
|
Packit |
fd8b60 |
You will be prompted for the database Master Password.
|
|
Packit |
fd8b60 |
It is important that you NOT FORGET this password.
|
|
Packit |
fd8b60 |
Enter KDC database master key: <= Type the master password.
|
|
Packit |
fd8b60 |
Re-enter KDC database master key to verify: <= Type it again.
|
|
Packit |
fd8b60 |
shell%
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
This will create five files in |kdcdir| (or at the locations specified
|
|
Packit |
fd8b60 |
in :ref:`kdc.conf(5)`):
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
* two Kerberos database files, ``principal``, and ``principal.ok``
|
|
Packit |
fd8b60 |
* the Kerberos administrative database file, ``principal.kadm5``
|
|
Packit |
fd8b60 |
* the administrative database lock file, ``principal.kadm5.lock``
|
|
Packit |
fd8b60 |
* the stash file, in this example ``.k5.ATHENA.MIT.EDU``. If you do
|
|
Packit |
fd8b60 |
not want a stash file, run the above command without the **-s**
|
|
Packit |
fd8b60 |
option.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
For more information on administrating Kerberos database see
|
|
Packit |
fd8b60 |
:ref:`db_operations`.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. _admin_acl:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Add administrators to the ACL file
|
|
Packit |
fd8b60 |
----------------------------------
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Next, you need create an Access Control List (ACL) file and put the
|
|
Packit |
fd8b60 |
Kerberos principal of at least one of the administrators into it.
|
|
Packit |
fd8b60 |
This file is used by the :ref:`kadmind(8)` daemon to control which
|
|
Packit |
fd8b60 |
principals may view and make privileged modifications to the Kerberos
|
|
Packit |
fd8b60 |
database files. The ACL filename is determined by the **acl_file**
|
|
Packit |
fd8b60 |
variable in :ref:`kdc.conf(5)`; the default is |kdcdir|\
|
|
Packit |
fd8b60 |
``/kadm5.acl``.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
For more information on Kerberos ACL file see :ref:`kadm5.acl(5)`.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. _addadmin_kdb:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Add administrators to the Kerberos database
|
|
Packit |
fd8b60 |
-------------------------------------------
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Next you need to add administrative principals (i.e., principals who
|
|
Packit |
fd8b60 |
are allowed to administer Kerberos database) to the Kerberos database.
|
|
Packit |
fd8b60 |
You *must* add at least one principal now to allow communication
|
|
Packit |
fd8b60 |
between the Kerberos administration daemon kadmind and the kadmin
|
|
Packit |
fd8b60 |
program over the network for further administration. To do this, use
|
|
Packit |
fd8b60 |
the kadmin.local utility on the master KDC. kadmin.local is designed
|
|
Packit |
fd8b60 |
to be run on the master KDC host without using Kerberos authentication
|
|
Packit |
fd8b60 |
to an admin server; instead, it must have read and write access to the
|
|
Packit |
fd8b60 |
Kerberos database on the local filesystem.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
The administrative principals you create should be the ones you added
|
|
Packit |
fd8b60 |
to the ACL file (see :ref:`admin_acl`).
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
In the following example, the administrative principal ``admin/admin``
|
|
Packit |
fd8b60 |
is created::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
shell% kadmin.local
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
kadmin.local: addprinc admin/admin@ATHENA.MIT.EDU
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
No policy specified for "admin/admin@ATHENA.MIT.EDU";
|
|
Packit |
fd8b60 |
assigning "default".
|
|
Packit |
fd8b60 |
Enter password for principal admin/admin@ATHENA.MIT.EDU: <= Enter a password.
|
|
Packit |
fd8b60 |
Re-enter password for principal admin/admin@ATHENA.MIT.EDU: <= Type it again.
|
|
Packit |
fd8b60 |
Principal "admin/admin@ATHENA.MIT.EDU" created.
|
|
Packit |
fd8b60 |
kadmin.local:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. _start_kdc_daemons:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Start the Kerberos daemons on the master KDC
|
|
Packit |
fd8b60 |
--------------------------------------------
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
At this point, you are ready to start the Kerberos KDC
|
|
Packit |
fd8b60 |
(:ref:`krb5kdc(8)`) and administrative daemons on the Master KDC. To
|
|
Packit |
fd8b60 |
do so, type::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
shell% krb5kdc
|
|
Packit |
fd8b60 |
shell% kadmind
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Each server daemon will fork and run in the background.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. note::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Assuming you want these daemons to start up automatically at
|
|
Packit |
fd8b60 |
boot time, you can add them to the KDC's ``/etc/rc`` or
|
|
Packit |
fd8b60 |
``/etc/inittab`` file. You need to have a
|
|
Packit |
fd8b60 |
:ref:`stash_definition` in order to do this.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
You can verify that they started properly by checking for their
|
|
Packit |
fd8b60 |
startup messages in the logging locations you defined in
|
|
Packit |
fd8b60 |
:ref:`krb5.conf(5)` (see :ref:`logging`). For example::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
shell% tail /var/log/krb5kdc.log
|
|
Packit |
fd8b60 |
Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation
|
|
Packit |
fd8b60 |
shell% tail /var/log/kadmin.log
|
|
Packit |
fd8b60 |
Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Any errors the daemons encounter while starting will also be listed in
|
|
Packit |
fd8b60 |
the logging output.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
As an additional verification, check if :ref:`kinit(1)` succeeds
|
|
Packit |
fd8b60 |
against the principals that you have created on the previous step
|
|
Packit |
fd8b60 |
(:ref:`addadmin_kdb`). Run::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
shell% kinit admin/admin@ATHENA.MIT.EDU
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Install the replica KDCs
|
|
Packit |
fd8b60 |
------------------------
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
You are now ready to start configuring the replica KDCs.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. note::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Assuming you are setting the KDCs up so that you can easily
|
|
Packit |
fd8b60 |
switch the master KDC with one of the replicas, you should
|
|
Packit |
fd8b60 |
perform each of these steps on the master KDC as well as the
|
|
Packit |
fd8b60 |
replica KDCs, unless these instructions specify otherwise.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. _replica_host_key:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Create host keytabs for replica KDCs
|
|
Packit |
fd8b60 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Each KDC needs a ``host`` key in the Kerberos database. These keys
|
|
Packit |
fd8b60 |
are used for mutual authentication when propagating the database dump
|
|
Packit |
fd8b60 |
file from the master KDC to the secondary KDC servers.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
On the master KDC, connect to administrative interface and create the
|
|
Packit |
fd8b60 |
host principal for each of the KDCs' ``host`` services. For example,
|
|
Packit |
fd8b60 |
if the master KDC were called ``kerberos.mit.edu``, and you had a
|
|
Packit |
fd8b60 |
replica KDC named ``kerberos-1.mit.edu``, you would type the
|
|
Packit |
fd8b60 |
following::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
shell% kadmin
|
|
Packit |
fd8b60 |
kadmin: addprinc -randkey host/kerberos.mit.edu
|
|
Packit |
fd8b60 |
No policy specified for "host/kerberos.mit.edu@ATHENA.MIT.EDU"; assigning "default"
|
|
Packit |
fd8b60 |
Principal "host/kerberos.mit.edu@ATHENA.MIT.EDU" created.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
kadmin: addprinc -randkey host/kerberos-1.mit.edu
|
|
Packit |
fd8b60 |
No policy specified for "host/kerberos-1.mit.edu@ATHENA.MIT.EDU"; assigning "default"
|
|
Packit |
fd8b60 |
Principal "host/kerberos-1.mit.edu@ATHENA.MIT.EDU" created.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
It is not strictly necessary to have the master KDC server in the
|
|
Packit |
fd8b60 |
Kerberos database, but it can be handy if you want to be able to swap
|
|
Packit |
fd8b60 |
the master KDC with one of the replicas.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Next, extract ``host`` random keys for all participating KDCs and
|
|
Packit |
fd8b60 |
store them in each host's default keytab file. Ideally, you should
|
|
Packit |
fd8b60 |
extract each keytab locally on its own KDC. If this is not feasible,
|
|
Packit |
fd8b60 |
you should use an encrypted session to send them across the network.
|
|
Packit |
fd8b60 |
To extract a keytab directly on a replica KDC called
|
|
Packit |
fd8b60 |
``kerberos-1.mit.edu``, you would execute the following command::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
kadmin: ktadd host/kerberos-1.mit.edu
|
|
Packit |
fd8b60 |
Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
|
|
Packit |
fd8b60 |
type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
|
|
Packit |
fd8b60 |
Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
|
|
Packit |
fd8b60 |
type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
|
|
Packit |
fd8b60 |
Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
|
|
Packit |
fd8b60 |
type aes256-cts-hmac-sha384-192 added to keytab FILE:/etc/krb5.keytab.
|
|
Packit |
fd8b60 |
Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
|
|
Packit |
fd8b60 |
type arcfour-hmac added to keytab FILE:/etc/krb5.keytab.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
If you are instead extracting a keytab for the replica KDC called
|
|
Packit |
fd8b60 |
``kerberos-1.mit.edu`` on the master KDC, you should use a dedicated
|
|
Packit |
fd8b60 |
temporary keytab file for that machine's keytab::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
kadmin: ktadd -k /tmp/kerberos-1.keytab host/kerberos-1.mit.edu
|
|
Packit |
fd8b60 |
Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
|
|
Packit |
fd8b60 |
type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
|
|
Packit |
fd8b60 |
Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
|
|
Packit |
fd8b60 |
type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
The file ``/tmp/kerberos-1.keytab`` can then be installed as
|
|
Packit |
fd8b60 |
``/etc/krb5.keytab`` on the host ``kerberos-1.mit.edu``.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Configure replica KDCs
|
|
Packit |
fd8b60 |
~~~~~~~~~~~~~~~~~~~~~~
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Database propagation copies the contents of the master's database, but
|
|
Packit |
fd8b60 |
does not propagate configuration files, stash files, or the kadm5 ACL
|
|
Packit |
fd8b60 |
file. The following files must be copied by hand to each replica (see
|
|
Packit |
fd8b60 |
:ref:`mitK5defaults` for the default locations for these files):
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
* krb5.conf
|
|
Packit |
fd8b60 |
* kdc.conf
|
|
Packit |
fd8b60 |
* kadm5.acl
|
|
Packit |
fd8b60 |
* master key stash file
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Move the copied files into their appropriate directories, exactly as
|
|
Packit |
fd8b60 |
on the master KDC. kadm5.acl is only needed to allow a replica to
|
|
Packit |
fd8b60 |
swap with the master KDC.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
The database is propagated from the master KDC to the replica KDCs via
|
|
Packit |
fd8b60 |
the :ref:`kpropd(8)` daemon. You must explicitly specify the
|
|
Packit |
fd8b60 |
principals which are allowed to provide Kerberos dump updates on the
|
|
Packit |
fd8b60 |
replica machine with a new database. Create a file named kpropd.acl
|
|
Packit |
fd8b60 |
in the KDC state directory containing the ``host`` principals for each
|
|
Packit |
fd8b60 |
of the KDCs::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
host/kerberos.mit.edu@ATHENA.MIT.EDU
|
|
Packit |
fd8b60 |
host/kerberos-1.mit.edu@ATHENA.MIT.EDU
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. note::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
If you expect that the master and replica KDCs will be
|
|
Packit |
fd8b60 |
switched at some point of time, list the host principals
|
|
Packit |
fd8b60 |
from all participating KDC servers in kpropd.acl files on
|
|
Packit |
fd8b60 |
all of the KDCs. Otherwise, you only need to list the
|
|
Packit |
fd8b60 |
master KDC's host principal in the kpropd.acl files of the
|
|
Packit |
fd8b60 |
replica KDCs.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Then, add the following line to ``/etc/inetd.conf`` on each KDC
|
|
Packit |
fd8b60 |
(adjust the path to kpropd)::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
krb5_prop stream tcp nowait root /usr/local/sbin/kpropd kpropd
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
You also need to add the following line to ``/etc/services`` on each
|
|
Packit |
fd8b60 |
KDC, if it is not already present (assuming that the default port is
|
|
Packit |
fd8b60 |
used)::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
krb5_prop 754/tcp # Kerberos replica propagation
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Restart inetd daemon.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Alternatively, start :ref:`kpropd(8)` as a stand-alone daemon. This is
|
|
Packit |
fd8b60 |
required when incremental propagation is enabled.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Now that the replica KDC is able to accept database propagation,
|
|
Packit |
fd8b60 |
you’ll need to propagate the database from the master server.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
NOTE: Do not start the replica KDC yet; you still do not have a copy
|
|
Packit |
fd8b60 |
of the master's database.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. _kprop_to_replicas:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Propagate the database to each replica KDC
|
|
Packit |
fd8b60 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
First, create a dump file of the database on the master KDC, as
|
|
Packit |
fd8b60 |
follows::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
shell% kdb5_util dump /usr/local/var/krb5kdc/replica_datatrans
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Then, manually propagate the database to each replica KDC, as in the
|
|
Packit |
fd8b60 |
following example::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
shell% kprop -f /usr/local/var/krb5kdc/replica_datatrans kerberos-1.mit.edu
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Database propagation to kerberos-1.mit.edu: SUCCEEDED
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
You will need a script to dump and propagate the database. The
|
|
Packit |
fd8b60 |
following is an example of a Bourne shell script that will do this.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. note::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Remember that you need to replace ``/usr/local/var/krb5kdc``
|
|
Packit |
fd8b60 |
with the name of the KDC state directory.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#!/bin/sh
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
kdclist = "kerberos-1.mit.edu kerberos-2.mit.edu"
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
kdb5_util dump /usr/local/var/krb5kdc/replica_datatrans
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
for kdc in $kdclist
|
|
Packit |
fd8b60 |
do
|
|
Packit |
fd8b60 |
kprop -f /usr/local/var/krb5kdc/replica_datatrans $kdc
|
|
Packit |
fd8b60 |
done
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
You will need to set up a cron job to run this script at the intervals
|
|
Packit |
fd8b60 |
you decided on earlier (see :ref:`db_prop`).
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Now that the replica KDC has a copy of the Kerberos database, you can
|
|
Packit |
fd8b60 |
start the krb5kdc daemon::
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
shell% krb5kdc
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
As with the master KDC, you will probably want to add this command to
|
|
Packit |
fd8b60 |
the KDCs' ``/etc/rc`` or ``/etc/inittab`` files, so they will start
|
|
Packit |
fd8b60 |
the krb5kdc daemon automatically at boot time.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Propagation failed?
|
|
Packit |
fd8b60 |
###################
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
You may encounter the following error messages. For a more detailed
|
|
Packit |
fd8b60 |
discussion on possible causes and solutions click on the error link
|
|
Packit |
fd8b60 |
to be redirected to :ref:`troubleshoot` section.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. include:: ./troubleshoot.rst
|
|
Packit |
fd8b60 |
:start-after: _prop_failed_start:
|
|
Packit |
fd8b60 |
:end-before: _prop_failed_end:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Add Kerberos principals to the database
|
|
Packit |
fd8b60 |
---------------------------------------
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Once your KDCs are set up and running, you are ready to use
|
|
Packit |
fd8b60 |
:ref:`kadmin(1)` to load principals for your users, hosts, and other
|
|
Packit |
fd8b60 |
services into the Kerberos database. This procedure is described
|
|
Packit |
fd8b60 |
fully in :ref:`add_mod_del_princs`.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
You may occasionally want to use one of your replica KDCs as the
|
|
Packit |
fd8b60 |
master. This might happen if you are upgrading the master KDC, or if
|
|
Packit |
fd8b60 |
your master KDC has a disk crash. See the following section for the
|
|
Packit |
fd8b60 |
instructions.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
.. _switch_master_replica:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Switching master and replica KDCs
|
|
Packit |
fd8b60 |
---------------------------------
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
You may occasionally want to use one of your replica KDCs as the
|
|
Packit |
fd8b60 |
master. This might happen if you are upgrading the master KDC, or if
|
|
Packit |
fd8b60 |
your master KDC has a disk crash.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Assuming you have configured all of your KDCs to be able to function
|
|
Packit |
fd8b60 |
as either the master KDC or a replica KDC (as this document
|
|
Packit |
fd8b60 |
recommends), all you need to do to make the changeover is:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
If the master KDC is still running, do the following on the *old*
|
|
Packit |
fd8b60 |
master KDC:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#. Kill the kadmind process.
|
|
Packit |
fd8b60 |
#. Disable the cron job that propagates the database.
|
|
Packit |
fd8b60 |
#. Run your database propagation script manually, to ensure that the
|
|
Packit |
fd8b60 |
replicas all have the latest copy of the database (see
|
|
Packit |
fd8b60 |
:ref:`kprop_to_replicas`).
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
On the *new* master KDC:
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#. Start the :ref:`kadmind(8)` daemon (see :ref:`start_kdc_daemons`).
|
|
Packit |
fd8b60 |
#. Set up the cron job to propagate the database (see
|
|
Packit |
fd8b60 |
:ref:`kprop_to_replicas`).
|
|
Packit |
fd8b60 |
#. Switch the CNAMEs of the old and new master KDCs. If you can't do
|
|
Packit |
fd8b60 |
this, you'll need to change the :ref:`krb5.conf(5)` file on every
|
|
Packit |
fd8b60 |
client machine in your Kerberos realm.
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
Incremental database propagation
|
|
Packit |
fd8b60 |
--------------------------------
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
If you expect your Kerberos database to become large, you may wish to
|
|
Packit |
fd8b60 |
set up incremental propagation to replica KDCs. See
|
|
Packit |
fd8b60 |
:ref:`incr_db_prop` for details.
|