From 9abb8d8cec6d9948bc985820e16795b4ba7294f6 Mon Sep 17 00:00:00 2001 From: Greg Hudson Date: Fri, 2 Mar 2012 19:18:33 +0000 Subject: [PATCH] Consolidate RST install docs into larger files Create two larger files (install_kdc.rst and install_clients.rst) and remove the install_kdc and install_clients directories. No significant changes to content. git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25724 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/rst_source/krb_admins/install.rst | 4 +- ...mac_osX_config.rst => install_clients.rst} | 35 +- .../krb_admins/install_clients/cl_config.rst | 23 - .../krb_admins/install_clients/index.rst | 29 - doc/rst_source/krb_admins/install_kdc.rst | 633 ++++++++++++++++++ .../krb_admins/install_kdc/admins_to_acl.rst | 111 --- .../krb_admins/install_kdc/admins_to_db.rst | 38 -- .../krb_admins/install_kdc/create_db.rst | 61 -- .../krb_admins/install_kdc/index.rst | 116 ---- .../krb_admins/install_kdc/kdc_prop_slave.rst | 88 --- .../krb_admins/install_kdc/krb_daemon.rst | 43 -- .../krb_admins/install_kdc/mod_conf.rst | 95 --- .../krb_admins/install_kdc/slave_install.rst | 110 --- .../install_kdc/switch_master_slave.rst | 37 - .../{install_kdc => }/stash_file_def.rst | 0 doc/rst_source/krb_admins/troubleshoot.rst | 2 +- 16 files changed, 670 insertions(+), 755 deletions(-) rename doc/rst_source/krb_admins/{install_clients/mac_osX_config.rst => install_clients.rst} (68%) delete mode 100644 doc/rst_source/krb_admins/install_clients/cl_config.rst delete mode 100644 doc/rst_source/krb_admins/install_clients/index.rst create mode 100644 doc/rst_source/krb_admins/install_kdc.rst delete mode 100644 doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst delete mode 100644 doc/rst_source/krb_admins/install_kdc/admins_to_db.rst delete mode 100644 doc/rst_source/krb_admins/install_kdc/create_db.rst delete mode 100644 doc/rst_source/krb_admins/install_kdc/index.rst delete mode 100644 doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst delete mode 100644 doc/rst_source/krb_admins/install_kdc/krb_daemon.rst delete mode 100644 doc/rst_source/krb_admins/install_kdc/mod_conf.rst delete mode 100644 doc/rst_source/krb_admins/install_kdc/slave_install.rst delete mode 100644 doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst rename doc/rst_source/krb_admins/{install_kdc => }/stash_file_def.rst (100%) diff --git a/doc/rst_source/krb_admins/install.rst b/doc/rst_source/krb_admins/install.rst index 8ccb29434..0c18129c7 100644 --- a/doc/rst_source/krb_admins/install.rst +++ b/doc/rst_source/krb_admins/install.rst @@ -14,8 +14,8 @@ Contents .. toctree:: :maxdepth: 2 - install_kdc/index.rst - install_clients/index.rst + install_kdc.rst + install_clients.rst install_appl_srv.rst diff --git a/doc/rst_source/krb_admins/install_clients/mac_osX_config.rst b/doc/rst_source/krb_admins/install_clients.rst similarity index 68% rename from doc/rst_source/krb_admins/install_clients/mac_osX_config.rst rename to doc/rst_source/krb_admins/install_clients.rst index 2b1179310..1eb20fc3f 100644 --- a/doc/rst_source/krb_admins/install_clients/mac_osX_config.rst +++ b/doc/rst_source/krb_admins/install_clients.rst @@ -1,5 +1,38 @@ +Installing and configuring UNIX client machines +=============================================== + +The Kerberized client programs are :ref:`kinit(1)`, :ref:`klist(1)`, +:ref:`kdestroy(1)`, :ref:`kpasswd(1)`, and :ref:`ksu(1)`. All of +these programs are in the directory ``/usr/local/bin``. MIT +recommends that you use login.krb5 in place of ``/bin/login`` to give +your users a single-sign-on system. You will need to make sure your +users know to use their Kerberos passwords when they log in. + +You will also need to educate your users to use the ticket management +programs kinit, klist, kdestroy, and to use the Kerberos programs ksu +and kpasswd in place of their non-Kerberos counterparts su and passwd. + + +Client machine configuration files +---------------------------------- + +Each machine running Kerberos must have a :ref:`krb5.conf(5)` file. + +Also, for most UNIX systems, you must add the appropriate Kerberos +services to each client machine's ``/etc/services`` file. If you are +using the default configuration for Kerberos V5, you should be able to +just insert the following code:: + + kerberos 88/udp kdc # Kerberos V5 KDC + kerberos 88/tcp kdc # Kerberos V5 KDC + kerberos-adm 749/tcp # Kerberos 5 admin/changepw + kerberos-adm 749/udp # Kerberos 5 admin/changepw + krb5_prop 754/tcp # Kerberos slave propagation + krb524 4444/tcp # Kerberos 5 to 4 ticket translator + + Mac OS X configuration -====================== +---------------------- To install Kerberos V5 on Mac OS X and Mac OS X Server, follow the directions for generic Unix-based OS's, except for the diff --git a/doc/rst_source/krb_admins/install_clients/cl_config.rst b/doc/rst_source/krb_admins/install_clients/cl_config.rst deleted file mode 100644 index e0ba0a349..000000000 --- a/doc/rst_source/krb_admins/install_clients/cl_config.rst +++ /dev/null @@ -1,23 +0,0 @@ -Client machine configuration files -================================== - -Each machine running Kerberos must have a :ref:`krb5.conf(5)` file. - -Also, for most UNIX systems, you must add the appropriate Kerberos -services to each client machine's ``/etc/services`` file. If you are -using the default configuration for Kerberos V5, you should be able to -just insert the following code:: - - kerberos 88/udp kdc # Kerberos V5 KDC - kerberos 88/tcp kdc # Kerberos V5 KDC - kerberos-adm 749/tcp # Kerberos 5 admin/changepw - kerberos-adm 749/udp # Kerberos 5 admin/changepw - krb5_prop 754/tcp # Kerberos slave propagation - krb524 4444/tcp # Kerberos 5 to 4 ticket translator - - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___cl_install diff --git a/doc/rst_source/krb_admins/install_clients/index.rst b/doc/rst_source/krb_admins/install_clients/index.rst deleted file mode 100644 index ca795a80c..000000000 --- a/doc/rst_source/krb_admins/install_clients/index.rst +++ /dev/null @@ -1,29 +0,0 @@ -Installing and configuring UNIX client machines -=============================================== - -The Kerberized client programs are :ref:`kinit(1)`, :ref:`klist(1)`, -:ref:`kdestroy(1)`, :ref:`kpasswd(1)`, and :ref:`ksu(1)`. All of -these programs are in the directory ``/usr/local/bin``. MIT -recommends that you use login.krb5 in place of ``/bin/login`` to give -your users a single-sign-on system. You will need to make sure your -users know to use their Kerberos passwords when they log in. - -You will also need to educate your users to use the ticket management -programs kinit, klist, kdestroy, and to use the Kerberos programs ksu -and kpasswd in place of their non-Kerberos counterparts su and passwd. - -.. toctree:: - :maxdepth: 1 - - cl_config.rst - mac_osX_config.rst - - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___cl_install - - - diff --git a/doc/rst_source/krb_admins/install_kdc.rst b/doc/rst_source/krb_admins/install_kdc.rst new file mode 100644 index 000000000..5a487c063 --- /dev/null +++ b/doc/rst_source/krb_admins/install_kdc.rst @@ -0,0 +1,633 @@ +.. note:: This document was copied from **Kerberos V5 Installation + Guide** with minor changes. Currently it is under + review. Please, send your feedback, corrections and + additions to krb5-bugs@mit.edu. Your contribution is greatly + appreciated. + + +Installing KDCs +=============== + +When setting up Kerberos in a production environment, it is best to +have multiple slave KDCs alongside with a master KDC to ensure the +continued availability of the Kerberized services. Each KDC contains +a copy of the Kerberos database. The master KDC contains the writable +copy of the realm database, which it replicates to the slave KDCs at +regular intervals. All database changes (such as password changes) +are made on the master KDC. Slave KDCs provide Kerberos +ticket-granting services, but not database administration, when the +master KDC is unavailable. MIT recommends that you install all of +your KDCs to be able to function as either the master or one of the +slaves. This will enable you to easily switch your master KDC with +one of the slaves if necessary (see :ref:`switch_master_slave`). This +installation procedure is based on that recommendation. + +.. warning:: + - The Kerberos system relies on the availability of correct time + information. Ensure that the master and all slave KDCs have + properly synchronized clocks. + + - It is best to install and run KDCs on secured and dedicated + hardware with limited access. If your KDC is also a file + server, FTP server, Web server, or even just a client machine, + someone who obtained root access through a security hole in any + of those areas could potentially gain access to the Kerberos + database. + + +Install and configure the master KDC +------------------------------------ + +Install Kerberos either from the OS-provided packages or from the +source (See :ref:`do_build`). + +.. note:: For the purpose of this document we will use the following + names:: + + kerberos.mit.edu - master KDC + kerberos-1.mit.edu - slave KDC + ATHENA.MIT.EDU - realm name + .k5.ATHENA.MIT.EDU - stash file + admin/admin - admin principal + + See :ref:`mitK5defaults` for the default names and locations + of the relevant to this topic files. Adjust the names and + paths to your system environment. + + +Edit KDC configuration files +---------------------------- + +Modify the configuration files, :ref:`krb5.conf(5)` and +:ref:`kdc.conf(5)`, to reflect the correct information (such as +domain-realm mappings and Kerberos servers names) for your realm. +(See :ref:`mitK5defaults` for the recommended default locations for +these files). + +Most of the tags in the configuration have default values that will +work well for most sites. There are some tags in the +:ref:`krb5.conf(5)` file whose values must be specified, and this +section will explain those. + +If the locations for these configuration files differs from the +default ones, set **KRB5_CONFIG** and **KRB5_KDC_PROFILE** environment +variables to point to the krb5.conf and kdc.conf respectively. For +example:: + + export KRB5_CONFIG=/yourdir/krb5.conf + export KRB5_KDC_PROFILE=/yourdir/kdc.conf + + +krb5.conf +~~~~~~~~~ + +If you are not using DNS TXT records (see :ref:`mapping_hostnames`), +you must specify the **default_realm** in the :ref:`libdefaults` +section. If you are not using DNS SRV records (see +:ref:`kdc_hostnames`), you must include the **kdc** tag for each +*realm* in the :ref:`realms` section. To communicate with the kadmin +server in each realm, the **admin_server** tag must be set in the +:ref:`realms` section. If your domain name and realm name are not the +same, you must provide a translation in :ref:`domain_realm`. + +An example krb5.conf file:: + + [libdefaults] + default_realm = ATHENA.MIT.EDU + + [realms] + ATHENA.MIT.EDU = { + kdc = kerberos.mit.edu + kdc = kerberos-1.mit.edu + admin_server = kerberos.mit.edu + } + + +kdc.conf +~~~~~~~~ + +The kdc.conf file can be used to control the listening ports of the +KDC and kadmind, as well as realm-specific defaults, the database type +and location, and logging. + +An example kdc.conf file:: + + [kdcdefaults] + kdc_ports = 88,750 + + [realms] + ATHENA.MIT.EDU = { + kadmind_port = 749 + max_life = 12h 0m 0s + max_renewable_life = 7d 0h 0m 0s + master_key_type = aes256-cts + supported_enctypes = aes256-cts:normal aes128-cts:normal + # If the default location does not suit your setup, + # explicitly configure the following four values: + # database_name = /var/krb5kdc/principal + # key_stash_file = /var/krb5kdc/.k5.ATHENA.MIT.EDU + # admin_keytab = FILE:/var/krb5kdc/kadm5.keytab + # acl_file = /var/krb5kdc/kadm5.acl + } + + [logging] + # By default, the KDC and kadmind will log output using + # syslog. You can instead send log output to files like this: + kdc = FILE:/var/log/krb5kdc.log + admin_server = FILE:/var/log/kadmin.log + default = FILE:/var/log/krb5lib.log + +Replace ``ATHENA.MIT.EDU`` and ``kerberos.mit.edu`` with the name of +your Kerberos realm and server respectively. + +.. note:: You have to have write permission on the target directories + (these directories must exist) used by **database_name**, + **key_stash_file**, **admin_keytab**, and **acl_file**. + + +.. _create_db: + +Create the KDC database +----------------------- + +You will use the :ref:`kdb5_util(8)` command on the master KDC to +create the Kerberos database and the optional :ref:`stash_definition`. + +.. note:: If you choose not to install a stash file, the KDC will + prompt you for the master key each time it starts up. This + means that the KDC will not be able to start automatically, + such as after a system reboot. + +:ref:`kdb5_util(8)` will prompt you for the master password for the +Kerberos database. This password can be any string. A good password +is one you can remember, but that no one else can guess. Examples of +bad passwords are words that can be found in a dictionary, any common +or popular name, especially a famous person (or cartoon character), +your username in any form (e.g., forward, backward, repeated twice, +etc.), and any of the sample passwords that appear in this manual. +One example of a password which might be good if it did not appear in +this manual is "MITiys4K5!", which represents the sentence "MIT is +your source for Kerberos 5!" (It's the first letter of each word, +substituting the numeral "4" for the word "for", and includes the +punctuation mark at the end.) + +The following is an example of how to create a Kerberos database and +stash file on the master KDC, using the :ref:`kdb5_util(8)` command. +Replace ``ATHENA.MIT.EDU`` with the name of your Kerberos realm:: + + shell% /usr/local/sbin/kdb5_util create -r ATHENA.MIT.EDU -s + + Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU', + master key name 'K/M@ATHENA.MIT.EDU' + You will be prompted for the database Master Password. + It is important that you NOT FORGET this password. + Enter KDC database master key: <= Type the master password. + Re-enter KDC database master key to verify: <= Type it again. + shell% + +This will create five files in the directory specified in your +:ref:`kdc.conf(5)` file (the default location is +``/usr/local/var/krb5kdc`` directory; see :ref:`mitK5defaults`): + +* two Kerberos database files, ``principal``, and ``principal.ok`` +* the Kerberos administrative database file, ``principal.kadm5`` +* the administrative database lock file, ``principal.kadm5.lock`` +* the stash file, in this example ``.k5.ATHENA.MIT.EDU`` (by default + it is ``.k5.`` prefix followed by the realm name of the database). + If you do not want a stash file, run the above command without the + **-s** option. + +For more information on administrating Kerberos database see +:ref:`db_operations`. + + +.. _admin_acl: + +Add administrators to the ACL file +---------------------------------- + +Next, you need create an Access Control List (ACL) file and put the +Kerberos principal of at least one of the administrators into it. +This file is used by the :ref:`kadmind(8)` daemon to control which +principals may view and make privileged modifications to the Kerberos +database files. The filename should match the value you have set for +**acl_file** (see :ref:`kdc_realms`) in your :ref:`kdc.conf(5)` file. +The default file name is ``/usr/local/var/krb5kdc/kadm5.acl`` (See +:ref:`mitK5defaults`). + +The format of the file is:: + + client_principal permissions [target_principal] [restrictions] + +The *client_principal* (and optional *target_principal*) can include +the ``*`` wildcard, so if you want any principal with the instance +``admin`` to have full permissions on the database, you could use the +principal ``*/admin@REALM`` where *REALM* is your Kerberos realm. +*target_principal* can also include backreferences to +*client_principal*, in which ``*number`` matches the component number +in *client_principal*. + +.. note:: A common use of an admin instance is so you can grant + separate permissions (such as administrator access to the + Kerberos database) to a separate kerberos principal. For + example, the user ``joeadmin`` might have a principal for + his administrative use, called ``joeadmin/admin``. This + way, ``joeadmin`` would obtain ``joeadmin/admin`` tickets + only when he actually needs to use those permissions. + +The permissions are represented by single letters. A lowercase +character specifies that operation can be performed by the principal, +while its uppercase counterpart indicates negative permission. The +permissions are: + + ==== ========================================================== + a [Dis]allows the addition of principals or policies in the database + c [Dis]allows the changing of passwords for principals in the database + d [Dis]allows the deletion of principals or policies in the database + i [Dis]allows inquiries to the database + l [Dis]allows the listing of principals or policies in the database + m [Dis]allows the modification of principals or policies in the database + s [Dis]allows the explicit setting of the key for a principal + \* All privileges (admcil) + x All privileges (admcil); identical to "\*" + ==== ========================================================== + +*Restrictions* are a string of flags. Allowed restrictions are: + + ====================== =============================== + [+\|-]flagname flag is forced to indicated value. The permissible flags are the same as the + and - flags for the kadmin :ref:`add_principal` and :ref:`modify_principal` commands. + -clearpolicy policy is forced to clear + -policy *pol* policy is forced to be *pol* + expire *time* associated value will be forced to MIN(*time*, requested value) + pwexpire *time* associated value will be forced to MIN(*time*, requested value) + maxlife *time* associated value will be forced to MIN(*time*, requested value) + maxrenewlife *time* associated value will be forced to MIN(*time*, requested value) + ====================== =============================== + +The above flags act as restrictions on any add or modify operation +which is allowed due to that ACL line. + +Here is an example of a kadm5.acl file. + +.. warning:: The order of lines is important; permissions are + determined by the first matching entry. + +:: + + */admin@ATHENA.MIT.EDU * + joeadmin@ATHENA.MIT.EDU ADMCIL + joeadmin/*@ATHENA.MIT.EDU il */root@ATHENA.MIT.EDU + *@ATHENA.MIT.EDU cil *1/admin@ATHENA.MIT.EDU + */*@ATHENA.MIT.EDU i + */admin@EXAMPLE.COM * -maxlife 9h -postdateable + +In the above file, any principal in the ``ATHENA.MIT.EDU`` realm with +an ``admin`` instance has all administrative privileges. + +The user ``joeadmin`` has all permissions with his ``admin`` instance, +``joeadmin/admin@ATHENA.MIT.EDU`` (matches the first line). He has no +permissions at all with his null instance, ``joeadmin@ATHENA.MIT.EDU`` +(matches the second line). His root instance has inquire and list +permissions with any other principal that has the instance root. + +Any principal in ``ATHENA.MIT.EDU`` can inquire, list, or change the +password of their ``admin`` instance, but not any other admin +instance. + +Any principal in the realm ``ATHENA.MIT.EDU`` (except for +``joeadmin@ATHENA.MIT.EDU``, as mentioned above) has inquire +privileges. + +Finally, any principal with an ``admin`` instance in ``EXAMPLE.COM`` +has all permissions, but any principal that they create or modify will +not be able to get postdateable tickets or tickets with a life of +longer than 9 hours. + +.. warning:: If the kadmind ACL file is modified, the kadmind + daemon needs to be restarted for changes to take effect. + + +.. _addadmin_kdb: + +Add administrators to the Kerberos database +------------------------------------------- + +Next you need to add administrative principals (i.e. principals who +are allowed to administer Kerberos database) to the Kerberos database. +You *must* add at least one principal now to allow communication +between the Kerberos administration daemon kadmind and the kadmin +program over the network for further administration. To do this, use +the kadmin.local utility on the master KDC. kadmin.local is designed +to be run on the master KDC host without using Kerberos authentication +to its database; instead, it must have read and write access to the +Kerberos database on the local filesystem. + +The administrative principals you create should be the ones you added +to the ACL file (see :ref:`admin_acl`). + +In the following example, the administrative principal ``admin/admin`` +is created:: + + shell% /usr/local/sbin/kadmin.local + + kadmin.local: addprinc admin/admin@ATHENA.MIT.EDU + + WARNING: no policy specified for "admin/admin@ATHENA.MIT.EDU"; + assigning "default". + Enter password for principal admin/admin@ATHENA.MIT.EDU: <= Enter a password. + Re-enter password for principal admin/admin@ATHENA.MIT.EDU: <= Type it again. + Principal "admin/admin@ATHENA.MIT.EDU" created. + kadmin.local: + + +Start the Kerberos daemons on the master KDC +-------------------------------------------- + +At this point, you are ready to start the Kerberos KDC +(:ref:`krb5kdc(8)`) and administrative daemons on the Master KDC. To +do so, type:: + + shell% /usr/local/sbin/krb5kdc + shell% /usr/local/sbin/kadmind + +Each server daemon will fork and run in the background. + +.. note:: Assuming you want these daemons to start up automatically at + boot time, you can add them to the KDC's ``/etc/rc`` or + ``/etc/inittab`` file. You need to have a + :ref:`stash_definition` in order to do this. + +You can verify that they started properly by checking for their +startup messages in the logging locations you defined in +:ref:`krb5.conf(5)` (see :ref:`logging`). For example:: + + shell% tail /var/log/krb5kdc.log + Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation + shell% tail /var/log/kadmin.log + Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting + +Any errors the daemons encounter while starting will also be listed in +the logging output. + +As an additional verification, check if :ref:`kinit(1)` succeeds +against the principals that you have created on the previous step +(:ref:`addadmin_kdb`). Run:: + + shell% /usr/local/bin/kinit admin/admin@ATHENA.MIT.EDU + + +Install the slave KDCs +---------------------- + +You are now ready to start configuring the slave KDCs. + +.. note:: Assuming you are setting the KDCs up so that you can easily + switch the master KDC with one of the slaves, you should + perform each of these steps on the master KDC as well as the + slave KDCs, unless these instructions specify otherwise. + + +.. _slave_host_key: + +Create host keytabs for slave KDCs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each KDC needs a ``host`` key in the Kerberos database. These keys +are used for mutual authentication when propagating the database dump +file from the master KDC to the secondary KDC servers. + +On the master KDC, connect to administrative interface and create the +host principal for each of the KDCs' ``host`` services. For example, +if the master KDC were called ``kerberos.mit.edu``, and you had a +slave KDC named ``kerberos-1.mit.edu``, you would type the following:: + + shell% /usr/local/bin/kadmin + kadmin: addprinc -randkey host/kerberos.mit.edu + NOTICE: no policy specified for "host/kerberos.mit.edu@ATHENA.MIT.EDU"; assigning "default" + Principal "host/kerberos.mit.edu@ATHENA.MIT.EDU" created. + + kadmin: addprinc -randkey host/kerberos-1.mit.edu + NOTICE: no policy specified for "host/kerberos-1.mit.edu@ATHENA.MIT.EDU"; assigning "default" + Principal "host/kerberos-1.mit.edu@ATHENA.MIT.EDU" created. + +It is not strictly necessary to have the master KDC server in the +Kerberos database, but it can be handy if you want to be able to swap +the master KDC with one of the slaves. + +Next, extract ``host`` random keys for all participating KDCs and +store them in each host's default keytab file. Ideally, you should +extract each keytab locally on its own KDC. If this is not feasible, +you should use an encrypted session to send them across the network. +To extract a keytab on a slave KDC called ``kerberos-1.mit.edu``, you +would execute the following command:: + + kadmin: ktadd host/kerberos-1.mit.edu + Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption + type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab. + Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption + type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab. + Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption + type des3-cbc-sha1 added to keytab FILE:/etc/krb5.keytab. + Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption + type arcfour-hmac added to keytab FILE:/etc/krb5.keytab. + + +Configure slave KDCs +~~~~~~~~~~~~~~~~~~~~ + +Database propagation copies the contents of the master's database, but +does not propagate configuration files, stash files, or the kadm5 ACL +file. The following files must be copied by hand to each slave (see +:ref:`mitK5defaults` for the default locations for these files): + +* krb5.conf +* kdc.conf +* kadm5.acl +* master key stash file + +Move the copied files into their appropriate directories, exactly as +on the master KDC. kadm5.acl is only needed to allow a slave to swap +with the master KDC. + +The database is propagated from the master KDC to the slave KDCs via +the :ref:`kpropd(8)` daemon. You must explicitly specify the +principals which are allowed to provide Kerberos dump updates on the +slave machine with a new database. Create a file named kpropd.acl in +the KDC state directory containing the ``host`` principals for each of +the KDCs: + + host/kerberos.mit.edu@ATHENA.MIT.EDU + host/kerberos-1.mit.edu@ATHENA.MIT.EDU + +.. note:: If you expect that the master and slave KDCs will be + switched at some point of time, list the host principals + from all participating KDC servers in kpropd.acl files on + all of the KDCs. Otherwise, you only need to list the + master KDC's host principal in the kpropd.acl files of the + slave KDCs. + +Then, add the following line to ``/etc/inetd.conf`` on each KDC +(Adjust the path to kpropd):: + + krb5_prop stream tcp nowait root /usr/local/sbin/kpropd kpropd + +You also need to add the following line to ``/etc/services`` on each +KDC, if it is not already present (assuming that the default port is +used):: + + krb5_prop 754/tcp # Kerberos slave propagation + +Restart inetd daemon. + +Alternatively, start :ref:`kpropd(8)` as a stand-alone daemon with +``kpropd -S``. + +Now that the slave KDC is able to accept database propagation, you’ll +need to propagate the database from the master server. + +NOTE: Do not start the slave KDC yet; you still do not have a copy of +the master's database. + + +.. _kprop_to_slaves: + +Propagate the database to each slave KDC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, create a dump file of the database on the master KDC, as +follows:: + + shell% /usr/local/sbin/kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans + +Then, manually propagate the database to each slave KDC, as in the +following example:: + + shell% /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans kerberos-1.mit.edu + + Database propagation to kerberos-1.mit.edu: SUCCEEDED + +You will need a script to dump and propagate the database. The +following is an example of a Bourne shell script that will do this. + +.. note:: Remember that you need to replace ``/usr/local/var/krb5kdc`` + with the name of the KDC state directory. + +:: + + #!/bin/sh + + kdclist = "kerberos-1.mit.edu kerberos-2.mit.edu" + + /usr/local/sbin/kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans + + for kdc in $kdclist + do + /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans $kdc + done + +You will need to set up a cron job to run this script at the intervals +you decided on earlier (see :ref:`db_prop`). + +Now that the slave KDC has a copy of the Kerberos database, you can +start the krb5kdc daemon:: + + shell% /usr/local/sbin/krb5kdc + +As with the master KDC, you will probably want to add this command to +the KDCs' ``/etc/rc`` or ``/etc/inittab`` files, so they will start +the krb5kdc daemon automatically at boot time. + + +Propagation failed? +################### + +.. _prop_failed_start: + +.. error:: kprop: No route to host while connecting to server + +Make sure that the hostname of the slave (as given to kprop) is +correct, and that any firewalls beween the master and the slave allow +a connection on port 754. + +.. error:: kprop: Connection refused in call to connect while opening + connection + +If the slave is intended to run kpropd out of inetd, make sure that +inetd is configured to accept krb5_prop connections. inetd may need +to be restarted or sent a SIGHUP to recognize the new configuration. +If the slave is intended to run kpropd in standalone mode, make sure +that it is running. + +.. error:: kprop: Server rejected authentication while authenticating + to server + +Make sure that: + +#. The time is syncronized between the master and slave KDCs. +#. The master stash file was copied from the master to the expected + location on the slave. +#. The slave has a keytab file in the default location containing a + ``host`` principal for the slave's hostname. + +.. _prop_failed_end: + + +Add Kerberos principals to the database +--------------------------------------- + +Once your KDCs are set up and running, you are ready to use +:ref:`kadmin(1)` to load principals for your users, hosts, and other +services into the Kerberos database. This procedure is described +fully in :ref:`add_mod_del_princs`. + +You may occasionally want to use one of your slave KDCs as the master. +This might happen if you are upgrading the master KDC, or if your +master KDC has a disk crash. See the following section for the +instructions. + + +.. _switch_master_slave: + +Switching master and slave KDCs +------------------------------- + +You may occasionally want to use one of your slave KDCs as the master. +This might happen if you are upgrading the master KDC, or if your +master KDC has a disk crash. + +Assuming you have configured all of your KDCs to be able to function +as either the master KDC or a slave KDC (as this document recommends), +all you need to do to make the changeover is: + +If the master KDC is still running, do the following on the *old* +master KDC: + +#. Kill the kadmind process. +#. Disable the cron job that propagates the database. +#. Run your database propagation script manually, to ensure that the + slaves all have the latest copy of the database (see + :ref:`kprop_to_slaves`). + +On the *new* master KDC: + +#. Start the :ref:`kadmind(8)` daemon (see :ref:`start_kdc_daemons`). +#. Set up the cron job to propagate the database (see + :ref:`kprop_to_slaves`). +#. Switch the CNAMEs of the old and new master KDCs. If you can't do + this, you'll need to change the :ref:`krb5.conf(5)` file on every + client machine in your Kerberos realm. + + +Incremental database propagation +-------------------------------- + +If you expect your Kerberos database to become large, you may wish to +set up incremental propagation to slave KDCs. See :ref:`incr_db_prop` +for details. + + +Feedback +-------- + +Please, provide your feedback or suggest a new topic at +krb5-bugs@mit.edu?subject=Documentation___install_kdc diff --git a/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst b/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst deleted file mode 100644 index 219f320b9..000000000 --- a/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst +++ /dev/null @@ -1,111 +0,0 @@ -.. _admin_acl: - -Add administrators to the ACL file -================================== - -Next, you need create an Access Control List (ACL) file and put the -Kerberos principal of at least one of the administrators into it. -This file is used by the :ref:`kadmind(8)` daemon to control which -principals may view and make privileged modifications to the Kerberos -database files. The filename should match the value you have set for -**acl_file** (see :ref:`kdc_realms`) in your :ref:`kdc.conf(5)` file. -The default file name is ``/usr/local/var/krb5kdc/kadm5.acl`` (See -:ref:`mitK5defaults`). - -The format of the file is:: - - client_principal permissions [target_principal] [restrictions] - -The *client_principal* (and optional *target_principal*) can include -the ``*`` wildcard, so if you want any principal with the instance -``admin`` to have full permissions on the database, you could use the -principal ``*/admin@REALM`` where *REALM* is your Kerberos realm. -*target_principal* can also include backreferences to -*client_principal*, in which ``*number`` matches the component number -in *client_principal*. - -.. note:: A common use of an admin instance is so you can grant - separate permissions (such as administrator access to the - Kerberos database) to a separate kerberos principal. For - example, the user ``joeadmin`` might have a principal for - his administrative use, called ``joeadmin/admin``. This - way, ``joeadmin`` would obtain ``joeadmin/admin`` tickets - only when he actually needs to use those permissions. - -The permissions are represented by single letters. A lowercase -character specifies that operation can be performed by the principal, -while its uppercase counterpart indicates negative permission. The -permissions are: - - ==== ========================================================== - a [Dis]allows the addition of principals or policies in the database - c [Dis]allows the changing of passwords for principals in the database - d [Dis]allows the deletion of principals or policies in the database - i [Dis]allows inquiries to the database - l [Dis]allows the listing of principals or policies in the database - m [Dis]allows the modification of principals or policies in the database - s [Dis]allows the explicit setting of the key for a principal - \* All privileges (admcil) - x All privileges (admcil); identical to "\*" - ==== ========================================================== - -*Restrictions* are a string of flags. Allowed restrictions are: - - ====================== =============================== - [+\|-]flagname flag is forced to indicated value. The permissible flags are the same as the + and - flags for the kadmin :ref:`add_principal` and :ref:`modify_principal` commands. - -clearpolicy policy is forced to clear - -policy *pol* policy is forced to be *pol* - expire *time* associated value will be forced to MIN(*time*, requested value) - pwexpire *time* associated value will be forced to MIN(*time*, requested value) - maxlife *time* associated value will be forced to MIN(*time*, requested value) - maxrenewlife *time* associated value will be forced to MIN(*time*, requested value) - ====================== =============================== - -The above flags act as restrictions on any add or modify operation -which is allowed due to that ACL line. - -Here is an example of a kadm5.acl file. - -.. warning:: The order of lines is important; permissions are - determined by the first matching entry. - -:: - - */admin@ATHENA.MIT.EDU * - joeadmin@ATHENA.MIT.EDU ADMCIL - joeadmin/*@ATHENA.MIT.EDU il */root@ATHENA.MIT.EDU - *@ATHENA.MIT.EDU cil *1/admin@ATHENA.MIT.EDU - */*@ATHENA.MIT.EDU i - */admin@EXAMPLE.COM * -maxlife 9h -postdateable - -In the above file, any principal in the ``ATHENA.MIT.EDU`` realm with -an ``admin`` instance has all administrative privileges. - -The user ``joeadmin`` has all permissions with his ``admin`` instance, -``joeadmin/admin@ATHENA.MIT.EDU`` (matches the first line). He has no -permissions at all with his null instance, ``joeadmin@ATHENA.MIT.EDU`` -(matches the second line). His root instance has inquire and list -permissions with any other principal that has the instance root. - -Any principal in ``ATHENA.MIT.EDU`` can inquire, list, or change the -password of their ``admin`` instance, but not any other admin -instance. - -Any principal in the realm ``ATHENA.MIT.EDU`` (except for -``joeadmin@ATHENA.MIT.EDU``, as mentioned above) has inquire -privileges. - -Finally, any principal with an ``admin`` instance in ``EXAMPLE.COM`` -has all permissions, but any principal that they create or modify will -not be able to get postdateable tickets or tickets with a life of -longer than 9 hours. - -.. warning:: If the kadmind ACL file is modified, the kadmind - daemon needs to be restarted for changes to take effect. - - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___install_kdc diff --git a/doc/rst_source/krb_admins/install_kdc/admins_to_db.rst b/doc/rst_source/krb_admins/install_kdc/admins_to_db.rst deleted file mode 100644 index a0488a9ee..000000000 --- a/doc/rst_source/krb_admins/install_kdc/admins_to_db.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. _addadmin_kdb: - -Add administrators to the Kerberos database -=========================================== - -Next you need to add administrative principals (i.e. principals who -are allowed to administer Kerberos database) to the Kerberos database. -You *must* add at least one principal now to allow communication -between the Kerberos administration daemon kadmind and the kadmin -program over the network for further administration. To do this, use -the kadmin.local utility on the master KDC. kadmin.local is designed -to be run on the master KDC host without using Kerberos authentication -to its database; instead, it must have read and write access to the -Kerberos database on the local filesystem. - -The administrative principals you create should be the ones you added -to the ACL file (see :ref:`admin_acl`). - -In the following example, the administrative principal ``admin/admin`` -is created:: - - shell% /usr/local/sbin/kadmin.local - - kadmin.local: addprinc admin/admin@ATHENA.MIT.EDU - - WARNING: no policy specified for "admin/admin@ATHENA.MIT.EDU"; - assigning "default". - Enter password for principal admin/admin@ATHENA.MIT.EDU: <= Enter a password. - Re-enter password for principal admin/admin@ATHENA.MIT.EDU: <= Type it again. - Principal "admin/admin@ATHENA.MIT.EDU" created. - kadmin.local: - - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___install_kdc diff --git a/doc/rst_source/krb_admins/install_kdc/create_db.rst b/doc/rst_source/krb_admins/install_kdc/create_db.rst deleted file mode 100644 index 4d6a9da80..000000000 --- a/doc/rst_source/krb_admins/install_kdc/create_db.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. _create_db: - -Create the database -=================== - -You will use the :ref:`kdb5_util(8)` command on the master KDC to -create the Kerberos database and the optional :ref:`stash_definition`. - -.. note:: If you choose not to install a stash file, the KDC will - prompt you for the master key each time it starts up. This - means that the KDC will not be able to start automatically, - such as after a system reboot. - -:ref:`kdb5_util(8)` will prompt you for the master password for the -Kerberos database. This password can be any string. A good password -is one you can remember, but that no one else can guess. Examples of -bad passwords are words that can be found in a dictionary, any common -or popular name, especially a famous person (or cartoon character), -your username in any form (e.g., forward, backward, repeated twice, -etc.), and any of the sample passwords that appear in this manual. -One example of a password which might be good if it did not appear in -this manual is "MITiys4K5!", which represents the sentence "MIT is -your source for Kerberos 5!" (It's the first letter of each word, -substituting the numeral "4" for the word "for", and includes the -punctuation mark at the end.) - -The following is an example of how to create a Kerberos database and -stash file on the master KDC, using the :ref:`kdb5_util(8)` command. -Replace ``ATHENA.MIT.EDU`` with the name of your Kerberos realm:: - - shell% /usr/local/sbin/kdb5_util create -r ATHENA.MIT.EDU -s - - Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU', - master key name 'K/M@ATHENA.MIT.EDU' - You will be prompted for the database Master Password. - It is important that you NOT FORGET this password. - Enter KDC database master key: <= Type the master password. - Re-enter KDC database master key to verify: <= Type it again. - shell% - -This will create five files in the directory specified in your -:ref:`kdc.conf(5)` file (the default location is -``/usr/local/var/krb5kdc`` directory; see :ref:`mitK5defaults`): - -* two Kerberos database files, ``principal``, and ``principal.ok`` -* the Kerberos administrative database file, ``principal.kadm5`` -* the administrative database lock file, ``principal.kadm5.lock`` -* the stash file, in this example ``.k5.ATHENA.MIT.EDU`` (by default - it is ``.k5.`` prefix followed by the realm name of the database). - If you do not want a stash file, run the above command without the - **-s** option. - -For more information on administrating Kerberos database see -:ref:`db_operations`. - - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___install_kdc diff --git a/doc/rst_source/krb_admins/install_kdc/index.rst b/doc/rst_source/krb_admins/install_kdc/index.rst deleted file mode 100644 index 70fe3a799..000000000 --- a/doc/rst_source/krb_admins/install_kdc/index.rst +++ /dev/null @@ -1,116 +0,0 @@ -.. note:: This document was copied from **Kerberos V5 Installation - Guide** with minor changes. Currently it is under - review. Please, send your feedback, corrections and - additions to krb5-bugs@mit.edu. Your contribution is greatly - appreciated. - - -Installing KDCs -=============== - -When setting up Kerberos in a production environment, it is best to -have multiple slave KDCs alongside with a master KDC to ensure the -continued availability of the Kerberized services. Each KDC contains -a copy of the Kerberos database. The master KDC contains the writable -copy of the realm database, which it replicates to the slave KDCs at -regular intervals. All database changes (such as password changes) -are made on the master KDC. Slave KDCs provide Kerberos -ticket-granting services, but not database administration, when the -master KDC is unavailable. MIT recommends that you install all of -your KDCs to be able to function as either the master or one of the -slaves. This will enable you to easily switch your master KDC with -one of the slaves if necessary (see :ref:`switch_master_slave`). This -installation procedure is based on that recommendation. - -.. warning:: - - The Kerberos system relies on the availability of correct time - information. Ensure that the master and all slave KDCs have - properly synchronized clocks. - - - It is best to install and run KDCs on secured and dedicated - hardware with limited access. If your KDC is also a file - server, FTP server, Web server, or even just a client machine, - someone who obtained root access through a security hole in any - of those areas could potentially gain access to the Kerberos - database. - - -Install and configure the master KDC ------------------------------------- - -Install Kerberos either from the OS-provided packages or from the -source (See :ref:`do_build`). - -.. note:: For the purpose of this document we will use the following - names:: - - kerberos.mit.edu - master KDC - kerberos-1.mit.edu - slave KDC - ATHENA.MIT.EDU - realm name - .k5.ATHENA.MIT.EDU - stash file - admin/admin - admin principal - - See :ref:`mitK5defaults` for the default names and locations - of the relevant to this topic files. Adjust the names and - paths to your system environment. - -.. toctree:: - :maxdepth: 1 - - mod_conf.rst - create_db.rst - admins_to_acl.rst - admins_to_db.rst - krb_daemon.rst - - -Install the Slave KDCs ----------------------- - -You are now ready to start configuring the slave KDCs. - -.. note:: Assuming you are setting the KDCs up so that you can easily - switch the master KDC with one of the slaves, you should - perform each of these steps on the master KDC as well as the - slave KDCs, unless these instructions specify otherwise. - -.. toctree:: - :maxdepth: 1 - - slave_install.rst - kdc_prop_slave.rst - -Once your KDCs are set up and running, you are ready to use -:ref:`kadmin(1)` to load principals for your users, hosts, and other -services into the Kerberos database. This procedure is described -fully in :ref:`add_mod_del_princs`. - -You may occasionally want to use one of your slave KDCs as the master. -This might happen if you are upgrading the master KDC, or if your -master KDC has a disk crash. See the following section for the -instructions. - - -Switching Master and Slave KDCs -------------------------------- - -.. toctree:: - :maxdepth: 1 - - switch_master_slave.rst - - -Incremental database propagation --------------------------------- - -.. toctree:: - :maxdepth: 1 - - ../database/incr_db_prop.rst - - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___install_kdc diff --git a/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst b/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst deleted file mode 100644 index 0f70130ea..000000000 --- a/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst +++ /dev/null @@ -1,88 +0,0 @@ -.. _kprop_to_slaves: - -Propagate the database to each slave KDC -======================================== - -First, create a dump file of the database on the master KDC, as -follows:: - - shell% /usr/local/sbin/kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans - -Then, manually propagate the database to each slave KDC, as in the -following example:: - - shell% /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans kerberos-1.mit.edu - - Database propagation to kerberos-1.mit.edu: SUCCEEDED - -You will need a script to dump and propagate the database. The -following is an example of a Bourne shell script that will do this. - -.. note:: Remember that you need to replace ``/usr/local/var/krb5kdc`` - with the name of the KDC state directory. - -:: - - #!/bin/sh - - kdclist = "kerberos-1.mit.edu kerberos-2.mit.edu" - - /usr/local/sbin/kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans - - for kdc in $kdclist - do - /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans $kdc - done - -You will need to set up a cron job to run this script at the intervals -you decided on earlier (see :ref:`db_prop`). - -Now that the slave KDC has a copy of the Kerberos database, you can -start the krb5kdc daemon:: - - shell% /usr/local/sbin/krb5kdc - -As with the master KDC, you will probably want to add this command to -the KDCs' ``/etc/rc`` or ``/etc/inittab`` files, so they will start -the krb5kdc daemon automatically at boot time. - - -Propagation failed? -------------------- - -.. _prop_failed_start: - -.. error:: kprop: No route to host while connecting to server - -Make sure that the hostname of the slave (as given to kprop) is -correct, and that any firewalls beween the master and the slave allow -a connection on port 754. - -.. error:: kprop: Connection refused in call to connect while opening - connection - -If the slave is intended to run kpropd out of inetd, make sure that -inetd is configured to accept krb5_prop connections. inetd may need -to be restarted or sent a SIGHUP to recognize the new configuration. -If the slave is intended to run kpropd in standalone mode, make sure -that it is running. - -.. error:: kprop: Server rejected authentication while authenticating - to server - -Make sure that: - -#. The time is syncronized between the master and slave KDCs. -#. The master stash file was copied from the master to the expected - location on the slave. -#. The slave has a keytab file in the default location containing a - ``host`` principal for the slave's hostname. - -.. _prop_failed_end: - - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___install_kdc diff --git a/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst b/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst deleted file mode 100644 index 81dd08078..000000000 --- a/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. _start_kdc_daemons: - -Start the Kerberos daemons on the master KDC -============================================ - -At this point, you are ready to start the Kerberos KDC -(:ref:`krb5kdc(8)`) and administrative daemons on the Master KDC. To -do so, type:: - - shell% /usr/local/sbin/krb5kdc - shell% /usr/local/sbin/kadmind - -Each server daemon will fork and run in the background. - -.. note:: Assuming you want these daemons to start up automatically at - boot time, you can add them to the KDC's ``/etc/rc`` or - ``/etc/inittab`` file. You need to have a - :ref:`stash_definition` in order to do this. - -You can verify that they started properly by checking for their -startup messages in the logging locations you defined in -:ref:`krb5.conf(5)` (see :ref:`logging`). For example:: - - shell% tail /var/log/krb5kdc.log - Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation - shell% tail /var/log/kadmin.log - Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting - -Any errors the daemons encounter while starting will also be listed in -the logging output. - -As an additional verification, check if :ref:`kinit(1)` succeeds -against the principals that you have created on the previous step -(:ref:`addadmin_kdb`). Run:: - - shell% /usr/local/bin/kinit admin/admin@ATHENA.MIT.EDU - - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___install_kdc diff --git a/doc/rst_source/krb_admins/install_kdc/mod_conf.rst b/doc/rst_source/krb_admins/install_kdc/mod_conf.rst deleted file mode 100644 index 8bcb32ee7..000000000 --- a/doc/rst_source/krb_admins/install_kdc/mod_conf.rst +++ /dev/null @@ -1,95 +0,0 @@ -Edit the configuration files -============================ - -Modify the configuration files, :ref:`krb5.conf(5)` and -:ref:`kdc.conf(5)`, to reflect the correct information (such as -domain-realm mappings and Kerberos servers names) for your realm. -(See :ref:`mitK5defaults` for the recommended default locations for -these files). - -Most of the tags in the configuration have default values that will -work well for most sites. There are some tags in the -:ref:`krb5.conf(5)` file whose values must be specified, and this -section will explain those. - -If the locations for these configuration files differs from the -default ones, set **KRB5_CONFIG** and **KRB5_KDC_PROFILE** environment -variables to point to the krb5.conf and kdc.conf respectively. For -example:: - - export KRB5_CONFIG=/yourdir/krb5.conf - export KRB5_KDC_PROFILE=/yourdir/kdc.conf - - -krb5.conf ---------- - -If you are not using DNS TXT records (see :ref:`mapping_hostnames`), -you must specify the **default_realm** in the :ref:`libdefaults` -section. If you are not using DNS SRV records (see -:ref:`kdc_hostnames`), you must include the **kdc** tag for each -*realm* in the :ref:`realms` section. To communicate with the kadmin -server in each realm, the **admin_server** tag must be set in the -:ref:`realms` section. If your domain name and realm name are not the -same, you must provide a translation in :ref:`domain_realm`. - -An example krb5.conf file:: - - [libdefaults] - default_realm = ATHENA.MIT.EDU - - [realms] - ATHENA.MIT.EDU = { - kdc = kerberos.mit.edu - kdc = kerberos-1.mit.edu - admin_server = kerberos.mit.edu - } - - -kdc.conf --------- - -The kdc.conf file can be used to control the listening ports of the -KDC and kadmind, as well as realm-specific defaults, the database type -and location, and logging. - -An example kdc.conf file:: - - [kdcdefaults] - kdc_ports = 88,750 - - [realms] - ATHENA.MIT.EDU = { - kadmind_port = 749 - max_life = 12h 0m 0s - max_renewable_life = 7d 0h 0m 0s - master_key_type = aes256-cts - supported_enctypes = aes256-cts:normal aes128-cts:normal - # If the default location does not suit your setup, - # explicitly configure the following four values: - # database_name = /var/krb5kdc/principal - # key_stash_file = /var/krb5kdc/.k5.ATHENA.MIT.EDU - # admin_keytab = FILE:/var/krb5kdc/kadm5.keytab - # acl_file = /var/krb5kdc/kadm5.acl - } - - [logging] - # By default, the KDC and kadmind will log output using - # syslog. You can instead send log output to files like this: - kdc = FILE:/var/log/krb5kdc.log - admin_server = FILE:/var/log/kadmin.log - default = FILE:/var/log/krb5lib.log - -Replace ``ATHENA.MIT.EDU`` and ``kerberos.mit.edu`` with the name of -your Kerberos realm and server respectively. - -.. note:: You have to have write permission on the target directories - (these directories must exist) used by **database_name**, - **key_stash_file**, **admin_keytab**, and **acl_file**. - - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___install_kdc diff --git a/doc/rst_source/krb_admins/install_kdc/slave_install.rst b/doc/rst_source/krb_admins/install_kdc/slave_install.rst deleted file mode 100644 index d1d4bc1ad..000000000 --- a/doc/rst_source/krb_admins/install_kdc/slave_install.rst +++ /dev/null @@ -1,110 +0,0 @@ -.. _slave_host_key: - -Setting up slave KDCs -===================== - -Prep work on the master side ----------------------------- - -Each KDC needs a ``host`` key in the Kerberos database. These keys -are used for mutual authentication when propagating the database dump -file from the master KDC to the secondary KDC servers. - -On the master KDC, connect to administrative interface and create the -host principal for each of the KDCs' ``host`` services. For example, -if the master KDC were called ``kerberos.mit.edu``, and you had a -slave KDC named ``kerberos-1.mit.edu``, you would type the following:: - - shell% /usr/local/bin/kadmin - kadmin: addprinc -randkey host/kerberos.mit.edu - NOTICE: no policy specified for "host/kerberos.mit.edu@ATHENA.MIT.EDU"; assigning "default" - Principal "host/kerberos.mit.edu@ATHENA.MIT.EDU" created. - - kadmin: addprinc -randkey host/kerberos-1.mit.edu - NOTICE: no policy specified for "host/kerberos-1.mit.edu@ATHENA.MIT.EDU"; assigning "default" - Principal "host/kerberos-1.mit.edu@ATHENA.MIT.EDU" created. - -It is not strictly necessary to have the master KDC server in the -Kerberos database, but it can be handy if you want to be able to swap -the master KDC with one of the slaves. - -Next, extract ``host`` random keys for all participating KDCs and -store them in each host's default keytab file. Ideally, you should -extract each keytab locally on its own KDC. If this is not feasible, -you should use an encrypted session to send them across the network. -To extract a keytab on a slave KDC called ``kerberos-1.mit.edu``, you -would execute the following command:: - - kadmin: ktadd host/kerberos-1.mit.edu - Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption - type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab. - Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption - type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab. - Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption - type des3-cbc-sha1 added to keytab FILE:/etc/krb5.keytab. - Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption - type arcfour-hmac added to keytab FILE:/etc/krb5.keytab. - - -Configuring the slave ---------------------- - -Database propagation copies the contents of the master's database, but -does not propagate configuration files, stash files, or the kadm5 ACL -file. The following files must be copied by hand to each slave (see -:ref:`mitK5defaults` for the default locations for these files): - -* krb5.conf -* kdc.conf -* kadm5.acl -* master key stash file - -Move the copied files into their appropriate directories, exactly as -on the master KDC. kadm5.acl is only needed to allow a slave to swap -with the master KDC. - -The database is propagated from the master KDC to the slave KDCs via -the :ref:`kpropd(8)` daemon. You must explicitly specify the -principals which are allowed to provide Kerberos dump updates on the -slave machine with a new database. Create a file named kpropd.acl in -the KDC state directory containing the ``host`` principals for each of -the KDCs: - - host/kerberos.mit.edu@ATHENA.MIT.EDU - host/kerberos-1.mit.edu@ATHENA.MIT.EDU - -.. note:: If you expect that the master and slave KDCs will be - switched at some point of time, list the host principals - from all participating KDC servers in kpropd.acl files on - all of the KDCs. Otherwise, you only need to list the - master KDC's host principal in the kpropd.acl files of the - slave KDCs. - -Then, add the following line to ``/etc/inetd.conf`` on each KDC -(Adjust the path to kpropd):: - - krb5_prop stream tcp nowait root /usr/local/sbin/kpropd kpropd - -You also need to add the following line to ``/etc/services`` on each -KDC, if it is not already present (assuming that the default port is -used):: - - krb5_prop 754/tcp # Kerberos slave propagation - -Restart inetd daemon. - -Alternatively, start :ref:`kpropd(8)` as a stand-alone daemon with -``kpropd -S``. - -Now that the slave KDC is able to accept database propagation, you’ll -need to propagate the database from the master server. - -NOTE: Do not start the slave KDC yet; you still do not have a copy of -the master's database. - - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___install_kdc diff --git a/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst b/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst deleted file mode 100644 index 0d825c1e0..000000000 --- a/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _switch_master_slave: - -Switching Master and Slave KDCs -=============================== - -You may occasionally want to use one of your slave KDCs as the master. -This might happen if you are upgrading the master KDC, or if your -master KDC has a disk crash. - -Assuming you have configured all of your KDCs to be able to function -as either the master KDC or a slave KDC (as this document recommends), -all you need to do to make the changeover is: - -If the master KDC is still running, do the following on the *old* -master KDC: - -#. Kill the kadmind process. -#. Disable the cron job that propagates the database. -#. Run your database propagation script manually, to ensure that the - slaves all have the latest copy of the database (see - :ref:`kprop_to_slaves`). - -On the *new* master KDC: - -#. Start the :ref:`kadmind(8)` daemon (see :ref:`start_kdc_daemons`). -#. Set up the cron job to propagate the database (see - :ref:`kprop_to_slaves`). -#. Switch the CNAMEs of the old and new master KDCs. If you can't do - this, you'll need to change the :ref:`krb5.conf(5)` file on every - client machine in your Kerberos realm. - - -Feedback --------- - -Please, provide your feedback or suggest a new topic at -krb5-bugs@mit.edu?subject=Documentation___install_kdc diff --git a/doc/rst_source/krb_admins/install_kdc/stash_file_def.rst b/doc/rst_source/krb_admins/stash_file_def.rst similarity index 100% rename from doc/rst_source/krb_admins/install_kdc/stash_file_def.rst rename to doc/rst_source/krb_admins/stash_file_def.rst diff --git a/doc/rst_source/krb_admins/troubleshoot.rst b/doc/rst_source/krb_admins/troubleshoot.rst index f47dc9163..197ed0eca 100644 --- a/doc/rst_source/krb_admins/troubleshoot.rst +++ b/doc/rst_source/krb_admins/troubleshoot.rst @@ -53,7 +53,7 @@ Seen in: ssh ---- -.. include:: ./install_kdc/kdc_prop_slave.rst +.. include:: ./install_kdc.rst :start-after: _prop_failed_start: :end-before: _prop_failed_end: -- 2.26.2