From: Greg Hudson Date: Mon, 27 Feb 2012 23:29:09 +0000 (+0000) Subject: Edit RST install guide for clarity and accuracy X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=ba86c00741074e0c14cf8568d7e49b40ee55c62e;p=krb5.git Edit RST install guide for clarity and accuracy Notable changes include: * In the example config files, configure logging in kdc.conf rather than krb5.conf. * It is no longer necessary to create a dummy database on slaves before propagating the master DB with kprop; remove that step from the instructions. * The admin keytab file is no longer required or used. git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25717 dc483132-0cff-0310-8789-dd5450dbe970 --- 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 index a56a528ca..219f320b9 100644 --- a/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst +++ b/doc/rst_source/krb_admins/install_kdc/admins_to_acl.rst @@ -3,7 +3,7 @@ Add administrators to the ACL file ================================== -Next, you need create an Access Control List (ACL) file, and put the +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 @@ -14,15 +14,15 @@ The default file name is ``/usr/local/var/krb5kdc/kadm5.acl`` (See The format of the file is:: - kerberos_principal permissions [target_principal] [restrictions] + client_principal permissions [target_principal] [restrictions] -The *kerberos_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. +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 -*kerberos_principal*, in which "\*number" matches the component number -in the *kerberos_principal*. +*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 @@ -32,9 +32,9 @@ in the *kerberos_principal*. way, ``joeadmin`` would obtain ``joeadmin/admin`` tickets only when he actually needs to use those permissions. -The permissions are represented by single letters. The lower-case -charecter specifies that operation can be performed by the principal, -while its UPPER-CASE counterparts represent negative permissions. The +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: ==== ========================================================== @@ -49,7 +49,7 @@ permissions are: x All privileges (admcil); identical to "\*" ==== ========================================================== -The restrictions are a string of flags. Allowed restrictions are: +*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. @@ -66,8 +66,8 @@ which is allowed due to that ACL line. Here is an example of a kadm5.acl file. -.. warning:: The order is important; permissions are determined by the - first matching entry. +.. warning:: The order of lines is important; permissions are + determined by the first matching entry. :: 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 index 1200e3320..a0488a9ee 100644 --- a/doc/rst_source/krb_admins/install_kdc/admins_to_db.rst +++ b/doc/rst_source/krb_admins/install_kdc/admins_to_db.rst @@ -6,13 +6,12 @@ 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 Kerberos administration daemon kadmind and kadmin program over -the network for the further Kerberos administration. To do this, use -kadmin.local utility on the master KDC. Note, that kadmin.local is -designed to be ran on the same host as the primary KDC without using -the Kerberos authentication to its database. (However, one needs -administrative privileges on the local filesystem to access database -files for this command to succeed.) +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`). diff --git a/doc/rst_source/krb_admins/install_kdc/create_db.rst b/doc/rst_source/krb_admins/install_kdc/create_db.rst index a7e489527..4d6a9da80 100644 --- a/doc/rst_source/krb_admins/install_kdc/create_db.rst +++ b/doc/rst_source/krb_admins/install_kdc/create_db.rst @@ -11,23 +11,22 @@ create the Kerberos database and the optional :ref:`stash_definition`. means that the KDC will not be able to start automatically, such as after a system reboot. -Note that :ref:`kdb5_util(8)` will prompt you for the master key for -the Kerberos database. This key can be any string. A good key is one -you can remember, but that no one else can guess. Examples of bad -keys 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 keys that appear in this manual. One example of -a key 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.) +: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:: +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 @@ -40,13 +39,13 @@ realm:: 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`): +: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 +* 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. diff --git a/doc/rst_source/krb_admins/install_kdc/index.rst b/doc/rst_source/krb_admins/install_kdc/index.rst index 8780ec427..70fe3a799 100644 --- a/doc/rst_source/krb_admins/install_kdc/index.rst +++ b/doc/rst_source/krb_admins/install_kdc/index.rst @@ -8,32 +8,31 @@ Installing KDCs =============== -When setting up Kerberos in a production environment it is recommended -to have multiple secondary (slave) KDCs alongside with a primary -(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. This allows clients to continue to obtain tickets -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. +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 heavily relies on the timestamps, so all - Kerberos exchange participants should be rather well - synchronized. + - 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 recomended to install and run KDCs on the secured and - dedicated solely to KDC 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 gain access to the - Kerberos database. + - 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 @@ -47,7 +46,6 @@ source (See :ref:`do_build`). kerberos.mit.edu - master KDC kerberos-1.mit.edu - slave KDC - mit.edu - domain name ATHENA.MIT.EDU - realm name .k5.ATHENA.MIT.EDU - stash file admin/admin - admin principal @@ -63,13 +61,19 @@ source (See :ref:`do_build`). create_db.rst admins_to_acl.rst admins_to_db.rst - kadmind_kt.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 @@ -79,8 +83,7 @@ Install the Slave KDCs 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 the :ref:`add_mod_del_princs`. The keytab is generated by -running kadmin and issuing the :ref:`ktadd` command. +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 @@ -92,7 +95,7 @@ Switching Master and Slave KDCs ------------------------------- .. toctree:: - :maxdepth: 2 + :maxdepth: 1 switch_master_slave.rst diff --git a/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst b/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst deleted file mode 100644 index 3e2d22936..000000000 --- a/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst +++ /dev/null @@ -1,42 +0,0 @@ -Create a kadmind keytab -======================= - -.. note:: This operation is optional. - -The kadmind keytab is the key that the legacy admininstration daemons -kadmind4 and v5passwdd will use to decrypt administrators' or clients' -Kerberos tickets to determine whether or not they should have access -to the database. You need to create the kadmin keytab with entries -for the principals ``kadmin/admin`` and ``kadmin/changepw``. (These -principals are placed in the Kerberos database automatically when you -create it.) To create the kadmin keytab, run kadmin.local and use the -:ref:`ktadd` command, as in the following example:: - - shell% /usr/local/sbin/kadmin.local - - kadmin.local: ktadd -k /usr/local/var/krb5kdc/kadm5.keytab kadmin/admin kadmin/changepw - Entry for principal kadmin/admin with kvno 5, encryption - type Triple DES cbc mode with HMAC/sha1 added to keytab - WRFILE:/usr/local/var/krb5kdc/kadm5.keytab. - Entry for principal kadmin/admin with kvno 5, encryption type DES cbc mode - with CRC-32 added to keytab - WRFILE:/usr/local/var/krb5kdc/kadm5.keytab. - Entry for principal kadmin/changepw with kvno 5, encryption - type Triple DES cbc mode with HMAC/sha1 added to keytab - WRFILE:/usr/local/var/krb5kdc/kadm5.keytab. - Entry for principal kadmin/changepw with kvno 5, - encryption type DES cbc mode with CRC-32 added to keytab - WRFILE:/usr/local/var/krb5kdc/kadm5.keytab. - kadmin.local: quit - -As specified in the **-k** argument, :ref:`ktadd` will save the -extracted keytab as ``/usr/local/var/krb5kdc/kadm5.keytab`` (This is -also the default location for the admin keytab). The filename you use -must be the one specified in your :ref:`kdc.conf(5)` 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/kdc_prop_slave.rst b/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst index dc9270c7b..0f70130ea 100644 --- a/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst +++ b/doc/rst_source/krb_admins/install_kdc/kdc_prop_slave.rst @@ -1,38 +1,25 @@ -Propagate the database to each slave KDC -=========================================== +.. _kprop_to_slaves: -First, stop the kadmin service. +Propagate the database to each slave KDC +======================================== -Next, create a dump file of the database on the master KDC, as +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 -Finally, manually propagate the database to each slave KDC, as in the +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 -Just in case you need an additional confirmation of the successful -propagation, do the following on the slave: - -* make sure that only this slave's kdc is listed in the - :ref:`krb5.conf(5)` file, then -* start :ref:`krb5kdc(8)` on the slave server and -* run ``kinit admin/admin@ATHENA.MIT.EDU`` which should succeed once - the correct password (i.e. password that was entered on the master - server for this principal) is provided. -* now :ref:`klist(1)` should display the message similar to ``Default - principal: admin/admin@ATHENA.MIT.EDU`` - 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. +following is an example of a Bourne shell script that will do this. -.. note:: Remember that you need to replace ``/usr/local/var`` with - the name of the directory in which you installed Kerberos - V5. +.. note:: Remember that you need to replace ``/usr/local/var/krb5kdc`` + with the name of the KDC state directory. :: @@ -40,66 +27,60 @@ following is an example of a bourne shell script that will do this. kdclist = "kerberos-1.mit.edu kerberos-2.mit.edu" - /usr/local/sbin/kdb5_util "dump /usr/local/var/krb5kdc/slave_datatrans" + /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 + /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` and :ref:`incr_db_prop`.) -The dump can also be used as a save file. Once the operation -succeeded, connect to slaves and start thier KDCs. +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 + 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. -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 the :ref:`add_mod_del_princs`. The keytab is generated by -running kadmin and issuing the ktadd command. - Propagation failed? ------------------- .. _prop_failed_start: -.. error:: kprop: No route to host in call to connect while opening - connection +.. 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. - kprop: Connection refused in call to connect while opening +.. error:: kprop: Connection refused in call to connect while opening connection - kprop: Server rejected authentication (during sendauth - exchange) while authenticating to server +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-slaves participants; -#. master stash and keytab files (e.g. ``.k5.ATHENA.MIT.EDU`` and - ``host/kerberos-1.mit.edu@ATHENA.MIT.EDU``) are copied from the - master to the expected location on the slaves; -#. Kerberos database was created on the slaves prior the propagation - from the master. -#. if :ref:`kpropd(8)` is invoked from inetd (or its equivalent - xinetd), the inetd daemon was restarted after the configuration - files ``/etc/inetd.conf`` and ``/etc/services`` were updated; -#. kpropd is running on the slave server; -#. if the locations of the configuration/keytab files differ from the - default ones, provide the proper environment variables and/or - options to the programs; +#. 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 -------- diff --git a/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst b/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst index 97774727f..81dd08078 100644 --- a/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst +++ b/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst @@ -1,8 +1,10 @@ +.. _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 +(:ref:`krb5kdc(8)`) and administrative daemons on the Master KDC. To do so, type:: shell% /usr/local/sbin/krb5kdc @@ -29,17 +31,10 @@ 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:: +(:ref:`addadmin_kdb`). Run:: shell% /usr/local/bin/kinit admin/admin@ATHENA.MIT.EDU -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. - Feedback -------- diff --git a/doc/rst_source/krb_admins/install_kdc/mod_conf.rst b/doc/rst_source/krb_admins/install_kdc/mod_conf.rst index 2672e52b8..8bcb32ee7 100644 --- a/doc/rst_source/krb_admins/install_kdc/mod_conf.rst +++ b/doc/rst_source/krb_admins/install_kdc/mod_conf.rst @@ -31,31 +31,27 @@ section. If you are not using DNS SRV records (see *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`. It is -also higly recommeneded that you create a :ref:`logging` stanza if the -computer will be functioning as a KDC so that :ref:`krb5kdc(8)` and -:ref:`kadmind(8)` will generate logging output. +same, you must provide a translation in :ref:`domain_realm`. An example krb5.conf file:: [libdefaults] default_realm = ATHENA.MIT.EDU - # if the default location does not suit your setup, - # explicitly configure the keytab location: - # default_keytab_name = FILE:/var/krb5kdc/krb5.keytab [realms] ATHENA.MIT.EDU = { kdc = kerberos.mit.edu kdc = kerberos-1.mit.edu - kdc = kerberos-2.mit.edu admin_server = kerberos.mit.edu } - [logging] - kdc = FILE:/var/log/krb5kdc.log - admin_server = FILE:/var/log/kadmin.log - default = FILE:/var/log/krb5lib.log + +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:: @@ -67,9 +63,9 @@ An example kdc.conf file:: kadmind_port = 749 max_life = 12h 0m 0s max_renewable_life = 7d 0h 0m 0s - master_key_type = des3-hmac-sha1 - supported_enctypes = des3-hmac-sha1:normal aes128-cts-hmac-sha1-96:normal - # if the default location does not suit your setup, + 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 @@ -77,6 +73,13 @@ An example kdc.conf file:: # 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. diff --git a/doc/rst_source/krb_admins/install_kdc/slave_install.rst b/doc/rst_source/krb_admins/install_kdc/slave_install.rst index 0b1be907d..d1d4bc1ad 100644 --- a/doc/rst_source/krb_admins/install_kdc/slave_install.rst +++ b/doc/rst_source/krb_admins/install_kdc/slave_install.rst @@ -6,14 +6,14 @@ Setting up slave KDCs Prep work on the master side ---------------------------- -Each KDC needs a ``host`` keys in the Kerberos database. These keys +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 -new principals for each of the KDCs ``host`` service. For example, if -the master KDC were called ``kerberos.mit.edu``, and you had slave KDC -named ``kerberos-1.mit.edu``, you would type the following:: +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 @@ -24,119 +24,83 @@ named ``kerberos-1.mit.edu``, you would type the following:: 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 actually necessary to have the master KDC server in the -Kerberos database, but it can be handy if: - - - anyone will be logging into the machine as something other than - root - - you want to be able to swap the master KDC with one of the slaves - if necessary. +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 the default keytab file which is needed to decrypt -tickets. 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 KDC called -``kerberos.mit.edu``, you would execute the following command:: - - kadmin: ktadd host/kerberos.mit.edu - kadmin: Entry for principal host/kerberos.mit.edu@ATHENA.MIT.EDU with - kvno 1, encryption type DES-CBC-CRC added to keytab WRFILE:/etc/krb5.keytab. - - kadmin: ktadd -k /tmp/krb5.keytab host/kerberos-1.mit.edu - kadmin: Entry for principal host/kerberos-1.mit.edu@ATHENA.MIT.EDU with - kvno 1, encryption type DES-CBC-CRC added to keytab WRFILE:/tmp/krb5.keytab. - - kadmin: - -Move the file /tmp/krb5.keytab (via scp) onto the slave KDC -(``kerberos-1.mit.edu``) into exactly the same location as on the -master (default is ``/etc/krb5.keytab``). Remove the temporary copy -``/tmp/krb5.keytab`` from the master. +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 --------------------- -By default, the propagation is done on the entire content of the -master's database. That is, even special principals (like -``K/M@FOOBAR.COM``) will be dumped and copied to the slave KDCs. Pay -attention there: it means that configuration files, as also specific -files (like ACLs and :ref:`stash_definition`) must be copied to the -slave hosts too. Copying only a part of it will result in a bulky -situation. If you forget to copy the stash file for example, the KDC -daemon on the slave host will not be able to access the propagated -database because of missing master key. Before connecting to the -slave, you will copy all minimum required files from the master for -the slave system to work. Initially, it concerns (See -:ref:`mitK5defaults` for the recommended default locations for these -files): - - • krb5.conf - • kdc.conf - • kadm5.acl - • master key stash file +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): -Connect to the slave, *kerberos-1.mit.edu*. Move the copied files into -their appropriate directories (exactly like on the master KDC). +* krb5.conf +* kdc.conf +* kadm5.acl +* master key stash file -You will now initialize the slave database:: - - shell% /usr/local/sbin/kdb5_util create - -.. caution:: You will use :ref:`kdb5_util(8)` but without exporting - the stash file (-s argument), thus avoiding the - obliteration of the one you just copied from the master. - -When asking for the database Master Password, type in anything you -want. The whole dummy database will be erased upon the first -propagation from master. +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 clients -that are allowed to provide Kerberos dump updates on the slave machine -with a new database. The kpropd.acl file serves as the access control -list for the kpropd service. This file is typically resides in -krb5kdc local directory. Since in our case the updates should only -come from ``kerberos.mit.edu`` server, then the file's contents would -be:: - - host/kerberos.mit.edu@ATHENA.MIT.EDU - -.. note:: If you expect that the primary and secondary KDCs will be - switched at some point of time, it is recommended to list - the host principals from *all* participating KDC servers in - kpropd.acl files on *all* of these servers. - -Then, add the following line to ``/etc/inetd.conf`` file on each KDC +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 - eklogin stream tcp nowait root /usr/local/sbin/klogind klogind -5 -c -e -You also need to add the following lines to ``/etc/services`` on each -KDC (assuming that default ports are used):: +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):: - kerberos 88/udp kdc # Kerberos authentication (udp) - kerberos 88/tcp kdc # Kerberos authentication (tcp) krb5_prop 754/tcp # Kerberos slave propagation - kerberos-adm 749/tcp # Kerberos 5 admin/changepw (tcp) - kerberos-adm 749/udp # Kerberos 5 admin/changepw (udp) Restart inetd daemon. -Alternatively, start :ref:`kpropd(8)` as a stand-alone daemon "kpropd --S" or, if the default locations must be overridden:: - - shell% /usr/local/sbin/kpropd -S -a path-to-kpropd.acl -r ATHENA.MIT.EDU -f /var/krb5kdc/from_master - - waiting for a kprop connection +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 slave KDC - you still do not have a copy of the -master's database. +NOTE: Do not start the slave KDC yet; you still do not have a copy of +the master's database. Feedback 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 index c3239cb3a..0d825c1e0 100644 --- a/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst +++ b/doc/rst_source/krb_admins/install_kdc/switch_master_slave.rst @@ -17,24 +17,17 @@ 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 Propagate - the Database to Each Slave KDC.) If there is a need to preserve - per-principal policy information from the database, you should do a - "kdb5_util dump -ov" in order to preserve that information and - propogate that dump file securely by some means to the slave so - that its database has the correct state of the per-principal policy - information. + slaves all have the latest copy of the database (see + :ref:`kprop_to_slaves`). On the *new* master KDC: -#. Create a database keytab. (See Create a kadmind Keytab (optional).) -#. Start the :ref:`kadmind(8)` daemon. (See Start the Kerberos - Daemons.) -#. Set up the cron job to propagate the database. (See Propagate the - Database to Each Slave KDC.) -#. Switch the CNAMEs of the old and new master KDCs. (If you don't do +#. 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.) + client machine in your Kerberos realm. Feedback