From: Zhanna Tsitkov Date: Fri, 4 Nov 2011 17:13:39 +0000 (+0000) Subject: Updated the documentation for the propagation X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=69d537b84f626eb2e55c5c193db5bc2afcb2be91;p=krb5.git Updated the documentation for the propagation git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25434 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 1d16bb540..64a30d88f 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 @@ -78,6 +78,8 @@ Any principal in the realm *ATHENA.MIT.EDU* (except for *joeadmin\@ATHENA.MIT.ED 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*'s ACL file is modified, the *kadmind* daemon needs to be restarted for changes to take effect. + ------------ Feedback: 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 51f652555..3e67c30ed 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 @@ -1,3 +1,5 @@ +.. _addadmin_kdb: + Add administrators to the Kerberos database =============================================== @@ -19,7 +21,7 @@ In the following example, the administrative principal *admin/admin* is created: kadmin.local: addprinc admin/admin@ATHENA.MIT.EDU - NOTICE: no policy specified for "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. diff --git a/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst b/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst index 289139650..90320dad2 100644 --- a/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst +++ b/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst @@ -11,7 +11,7 @@ You need to create the kadmin keytab with entries for the principals *kadmin/adm (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/admin.local + 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 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 8dc712ab5..84babc925 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 @@ -13,10 +13,18 @@ Finally, manually propagate the database to each slave KDC, as in the following 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 *krb5.conf* file, then + - start *krb5kdc* 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 *klist* 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. -.. note:: Remember that you need to replace */usr/local* with the name of the directory in which you installed Kerberos V5. +.. note:: Remember that you need to replace */usr/local/var* with the name of the directory in which you installed Kerberos V5. :: @@ -53,60 +61,24 @@ The keytab is generated by running kadmin and issuing the ktadd command. Propagation failed? ------------------------ - -If propagation failed with a loud: - .. _prop_failed_start: -.. error:: kprop: Connection refused in call to connect while opening connection - -it means that *kprop* did not manage to contact *kpropd* on the remote slave KDC. - -This will occur if you set restrictive access rules with a firewall, or if *kpropd* did not start upon connection. - -The propagation is done through a tcp stream on port 754. Usually, *kpropd* is not a daemon running on its own: -it is started by *inetd* (or its equivalent *xinetd*). However, many systems do not register *kpropd* as a service in their *inetd* database. - -You can launch *kpropd* by two different means: either by starting it during boot up with the **-S** argument (see :ref:`kpropd(8)` for details), -or register *kprop* as a potential services to *inetd*. - -To register *kpropd*, it depends on whether your are using inetd or its more sophisticated equivalent *xinetd*. -First, edit */etc/services*, and look for *kprop* service; the line should look like this:: - - kprop 754/tcp - -If you did not find it, please add it to the bottom of the file. Save and close. - - -Now we should edit */etc/inetd.conf* (see below for *xinetd*), and add the following line to setup the database propagation daemon :: - - kprop stream tcp nowait root /usr/local/sbin/kpropd kpropd - -Please note that the path to executable may vary from one system to another. Save and close *inetd.conf*, and restart *inetd*:: - - \# /etc/rc.d/inetd restart - - -All config file for *xinetd* resides in the */etc/xinetd.d* directory. We must add the *kprop* config file, so that *xinetd* knows its existence. -Create and edit the */etc/xinetd.d/kpropd* file :: - - service kprop - { - socket_type = stream - wait = no - user = root - server = /usr/local/sbin/kpropd - only_from = 0.0.0.0 # Allow anybody to connect to it. Restrictions may apply here. - log_on_success = PID HOST EXIT DURATION - log_on_failure = PID HOST - } +.. error:: kprop: No route to host in call to connect while opening connection -Save and close the file, and restart *xinetd*:: + kprop: Connection refused in call to connect while opening connection - \# /etc/init.d/xinetd restart + kprop: Server rejected authentication (during sendauth exchange) while authenticating to server -You should now be able to propagate the dumps from master to slave. +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 *kpropd* 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; .. _prop_failed_end: 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 c368fcf22..826d55998 100644 --- a/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst +++ b/doc/rst_source/krb_admins/install_kdc/krb_daemon.rst @@ -1,7 +1,8 @@ Start the Kerberos daemons on the master KDC =============================================== -At this point, you are ready to start the Kerberos KDC and administrative daemons on the Master KDC. To do so, type:: +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 @@ -13,6 +14,8 @@ Each server daemon will fork and run in the background. 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 */etc/krb5.conf*. (See :ref:`logging`). For example:: @@ -25,6 +28,12 @@ For example:: Any errors the daemons encounter while starting will also be listed in the logging output. +As an additional verification, check if *kinit* 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 + + 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, 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 2e0e1d20f..91affec0a 100644 --- a/doc/rst_source/krb_admins/install_kdc/mod_conf.rst +++ b/doc/rst_source/krb_admins/install_kdc/mod_conf.rst @@ -10,6 +10,14 @@ There are some tags in the *krb5.conf* file whose values must be specified, and this section will explain those. For more information on Kerberos V5 configuration files see :ref:`krb5.conf` and :ref:`kdc.conf`. +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* ------------- @@ -26,6 +34,9 @@ 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 = { @@ -53,10 +64,22 @@ An example kdc.conf file:: 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, + # 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 } -Replace *ATHENA.MIT.EDU* and *kerberos.mit.edu* with the name of your Kerberos realm and server respectively. +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* + + ------------ 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 e831d5d00..85ba4730f 100644 --- a/doc/rst_source/krb_admins/install_kdc/slave_install.rst +++ b/doc/rst_source/krb_admins/install_kdc/slave_install.rst @@ -16,7 +16,7 @@ On the master KDC connect to administrative interface and create the new princi 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:: - shell% /usr/local/sbin/kadmin + 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. @@ -73,10 +73,11 @@ Connect to the slave, *kerberos-1.mit.edu*. Move the copied files into their app You will now initialize the slave database:: - kdb5_util create + shell% /usr/local/sbin/kdb5_util create + +.. caution:: You will use :ref:`kdb5_util(8)` but without exporting the stash file (-s argument), i + thus avoiding the obliteration of the one you just copied from the master. -Caution: you will use :ref:`kdb5_util(8)` but without exporting the stash file (-s argument), i -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. @@ -96,6 +97,8 @@ Since in our case the updates should only come from *kerberos.mit.edu* server, Then, add the following line to */etc/inetd.conf* file 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):: @@ -105,11 +108,21 @@ You also need to add the following lines to */etc/services* on each KDC (assumin 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) - -.. note:: Do not start slave KDC - you still do not have a copy of the master's database. + +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 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. + ------------ diff --git a/doc/rst_source/relay/build_this.rst b/doc/rst_source/relay/build_this.rst index c8b29bc86..1207d7afe 100644 --- a/doc/rst_source/relay/build_this.rst +++ b/doc/rst_source/relay/build_this.rst @@ -96,7 +96,7 @@ Part A: Transforming Doxygen XML output into reStructuredText (rst) without 6. Rebuild Sphinx source. From the *trunk/doc/rst_source* run:: - sphinx-build . output_dir + sphinx-build . output_dir .. _Part_B: diff --git a/doc/rst_source/relay/index.rst b/doc/rst_source/relay/index.rst index 6d3ae03c5..7c91ee25e 100644 --- a/doc/rst_source/relay/index.rst +++ b/doc/rst_source/relay/index.rst @@ -1,3 +1,5 @@ +About this project +====================== .. toctree:: :maxdepth: 1