From 3c391d2e67de83afbee8db2ab578ba2dcd83fe59 Mon Sep 17 00:00:00 2001 From: Zhanna Tsitkov Date: Fri, 7 Oct 2011 16:33:25 +0000 Subject: [PATCH] Minor updates and correction of the RST documents git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25321 dc483132-0cff-0310-8789-dd5450dbe970 --- .../krb_admins/conf_files/krb5_conf.rst | 5 +- .../database/db_princs/modify_princ.rst | 5 +- .../krb_admins/install_appl_srv.rst | 8 +- .../krb_admins/install_kdc/create_db.rst | 14 +-- .../krb_admins/install_kdc/kadmind_kt.rst | 9 +- .../krb_admins/install_kdc/kdc_prop_slave.rst | 93 +++++++++++++++++-- 6 files changed, 104 insertions(+), 30 deletions(-) diff --git a/doc/rst_source/krb_admins/conf_files/krb5_conf.rst b/doc/rst_source/krb_admins/conf_files/krb5_conf.rst index 010fca696..09fa12f20 100644 --- a/doc/rst_source/krb_admins/conf_files/krb5_conf.rst +++ b/doc/rst_source/krb_admins/conf_files/krb5_conf.rst @@ -282,13 +282,14 @@ The [domain_realm] section provides a translation from a domain name or hostname If no translation entry applies, the host's realm is considered to be the hostname's domain portion converted to upper case. For example, the following [domain_realm] section:: [domain_realm] + crash.mit.edu = TEST.ATHENA.MIT.EDU .mit.edu = ATHENA.MIT.EDU mit.edu = ATHENA.MIT.EDU - crash.mit.edu = TEST.ATHENA.MIT.EDU example.com = EXAMPLE.COM -maps *crash.mit.edu* into the *TEST.ATHENA.MIT.EDU* realm. All other hosts in the *mit.edu* domain will map by default to the *ATHENA.MIT.EDU* realm, and all hosts in the example.com domain will map by default into the *EXAMPLE.COM* realm. Note the entries for the hosts *mit.edu* and *example.com*. Without these entries, these hosts would be mapped into the Kerberos realms EDU and ORG, respectively. +maps the host with the *exact* name *crash.mit.edu* into the TEST.ATHENA.MIT.EDU realm. The period prefix in *.mit.edu* denotes that *all* systems in the *mit.edu* domain belong to ATHENA.MIT.EDU realm. +Note the entries for the hosts *mit.edu* and *example.com*. Without these entries, these hosts would be mapped into the Kerberos realms EDU and COM, respectively. .. _logging: diff --git a/doc/rst_source/krb_admins/database/db_princs/modify_princ.rst b/doc/rst_source/krb_admins/database/db_princs/modify_princ.rst index 3a9f1aa62..3a1ec0903 100644 --- a/doc/rst_source/krb_admins/database/db_princs/modify_princ.rst +++ b/doc/rst_source/krb_admins/database/db_princs/modify_princ.rst @@ -51,11 +51,10 @@ If you want to associate a ticket policy to a principal, all you need to do is:: Principal "david@ATHENA.MIT.EDU" modified. kadmin: -If, on the other hand, you want to set up an account that expires on January 1, 2000, that uses a policy called "stduser", with a temporary password (which you want the user to change immediately), you would type the following. (Note: each line beginning with => is a continuation of the previous line.):: +If, on the other hand, you want to set up an account that expires on January 1, 2000, that uses a policy called "stduser", with a temporary password (which you want the user to change immediately), you would type the following:: - kadmin: addprinc david -expire "1/1/2000 12:01am EST" -policy stduser - => +needchange + kadmin: addprinc david -expire "1/1/2000 12:01am EST" -policy stduser +needchange Enter password for principal david@ATHENA.MIT.EDU: <= Type the password. Re-enter password for principal david@ATHENA.MIT.EDU: <= Type it again. diff --git a/doc/rst_source/krb_admins/install_appl_srv.rst b/doc/rst_source/krb_admins/install_appl_srv.rst index 1f051b573..b24762fc6 100644 --- a/doc/rst_source/krb_admins/install_appl_srv.rst +++ b/doc/rst_source/krb_admins/install_appl_srv.rst @@ -11,15 +11,15 @@ If you have Kerberos V5 installed on all of your client machines, MIT recommends The keytab file ---------------------- -All Kerberos server machines need a *keytab* file, called */etc/krb5.keytab*, to authenticate to the KDC. The keytab file is an encrypted, local, on-disk copy of the host's key. The keytab file, like the stash file (See :ref:`create_db_label`) is a potential point-of-entry for a break-in, and if compromised, would allow unrestricted access to its host. The *keytab* file should be readable only by root, and should exist only on the machine's local disk. The file should not be part of any backup of the machine, unless access to the backup data is secured as tightly as access to the machine's root password itself. +All Kerberos server machines need a *keytab* file to authenticate to the KDC. By default on UNIX-like systems this file is named */etc/krb5.keytab*. The keytab file is an encrypted, local, on-disk copy of the host's key. The keytab file, like the stash file (See :ref:`create_db_label`) is a potential point-of-entry for a break-in, and if compromised, would allow unrestricted access to its host. The *keytab* file should be readable only by root, and should exist only on the machine's local disk. The file should not be part of any backup of the machine, unless access to the backup data is secured as tightly as access to the machine's root password itself. -In order to generate a *keytab* for a host, the host must have a principal in the Kerberos database. The procedure for adding hosts to the database is described fully in :ref:`add_mod_del_princs_label`. (See :ref:`slave_host_key_label` for a brief description.) The *keytab* is generated by running kadmin and issuing the *ktadd* command. + +In order to generate a *keytab* for a host, the host must have a principal in the Kerberos database. The procedure for adding hosts to the database is described fully in :ref:`add_mod_del_princs_label`. (See :ref:`slave_host_key_label` for a brief description.) The *keytab* is generated by running *kadmin* and issuing the :ref:`ktadd` command. For example, to generate a *keytab* file to allow the host *trillium.mit.edu* to authenticate for the services host, ftp, and pop, the administrator *joeadmin* would issue the command (on *trillium.mit.edu*):: trillium% /usr/local/sbin/kadmin - kadmin5: ktadd host/trillium.mit.edu ftp/trillium.mit.edu - => pop/trillium.mit.edu + kadmin5: ktadd host/trillium.mit.edu ftp/trillium.mit.edu pop/trillium.mit.edu kadmin: Entry for principal host/trillium.mit.edu@ATHENA.MIT.EDU with kvno 3, encryption type DES-CBC-CRC added to keytab WRFILE:/etc/krb5.keytab. 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 fa7afa3dc..31932f469 100644 --- a/doc/rst_source/krb_admins/install_kdc/create_db.rst +++ b/doc/rst_source/krb_admins/install_kdc/create_db.rst @@ -3,17 +3,17 @@ Create the database ========================= -You will use the *kdb5_util* command on the Master KDC to create the Kerberos database and the optional stash file. The stash file is a local copy of the master key that resides in encrypted form on the KDC's local disk. The stash file is used to authenticate the KDC to itself automatically before starting the *kadmind* and *krb5kdc* daemons (e.g., as part of the machine's boot sequence). The stash file, like the keytab file (see :ref:`kt_file_label` for more information) is a potential point-of-entry for a break-in, and if compromised, would allow unrestricted access to the Kerberos database. If you choose to install a stash file, it should be readable only by root, and should exist only on the KDC's local disk. The file should not be part of any backup of the machine, unless access to the backup data is secured as tightly as access to the master password itself. +You will use the :ref:`kdb5_util(8)` command on the master KDC to create the Kerberos database and the optional stash file. +The stash file is a local copy of the master key that resides in encrypted form on the KDC's local disk. The stash file is used to authenticate the KDC to itself automatically before starting the *kadmind* and *krb5kdc* daemons (e.g., as part of the machine's boot sequence). The stash file, like the keytab file (see :ref:`kt_file_label` for more information) is a potential point-of-entry for a break-in, and if compromised, would allow unrestricted access to the Kerberos database. If you choose to install a stash file, it should be readable only by root, and should exist only on the KDC's local disk. The file should not be part of any backup of the machine, unless access to the backup data is secured as tightly as access to the master password itself. .. 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. Note that kdb5_util 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.) -The following is an example of how to create a Kerberos database and stash file on the master KDC, using the kdb5_util command. (The line that begins with => is a continuation of the previous line.) Replace *ATHENA.MIT.EDU* with the name of your Kerberos realm:: +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', + 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. @@ -22,12 +22,12 @@ The following is an example of how to create a Kerberos database and stash file shell% -This will create five files in the directory specified in your *kdc.conf* file: +This will create five files in the directory specified in your *kdc.conf* file (The default location is */usr/local/var/krb5kdc* directory): -- two Kerberos database files, *principal.db*, and *principal.ok*; +- 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, *.k5stash*. (The default directory is */usr/local/var/krb5kdc*.) If you do not want a stash file, run the above command without the *-s* option. +- 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_label`. 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 7b33e63ba..4f98baac9 100644 --- a/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst +++ b/doc/rst_source/krb_admins/install_kdc/kadmind_kt.rst @@ -1,14 +1,13 @@ -Create a kadmind Keytab +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 *ktadd* command, as in the following example. (The line beginning with => is a continuation of the previous line.):: +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 + 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. @@ -25,7 +24,7 @@ The kadmind keytab is the key that the legacy admininstration daemons *kadmind4* shell% -As specified in the *-k* argument, *ktadd* will save the extracted keytab as */usr/local/var/krb5kdc/kadm5.keytab*. The filename you use must be the one specified in your *kdc.conf* file. +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 *kdc.conf* file. ------------ 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 e5bdd7a5a..aaf9441b3 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,4 +1,4 @@ -Propagate the database to each Slave KDC +Propagate the database to each slave KDC =========================================== First, create a dump of the database on the master KDC, as follows:: @@ -7,15 +7,16 @@ First, create a dump of the database on the master KDC, as follows:: shell% -Next, you need to manually propagate the database to each slave KDC, as in the following example. (The lines beginning with => are continuations of the previous line.):: +Next, you need to manually propagate the database to each slave KDC, as in the following example:: - /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans - => kerberos-1.mit.edu - /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans - => kerberos-2.mit.edu + shell% /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans kerberos-1.mit.edu + Database propagation to kerberos-1.mit.edu: SUCCEEDED + + shell% /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans kerberos-2.mit.edu + Database propagation to kerberos-2.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 that the line that begins with => is a continuation of the previous line.) +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. @@ -25,8 +26,7 @@ You will need a script to dump and propagate the database. The following is an e 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 @@ -35,6 +35,81 @@ You will need a script to dump and propagate the database. The following is an e You will need to set up a cron job to run this script at the intervals you decided on earlier (See :ref:`db_prop_label` and :ref:`incr_db_prop_label`.) +The dump can also be used as a save file. +Once the operation succeeded, connect to slaves and start thier KDCs. + + + +Propagation failed? +------------------------ + + +If propagation failed with a loud:: + + 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:: + + /etc/services + + kprop 754/tcp + +If you did not find it, please add it to the bottom of the file. Save and close. + + +inetd.conf +~~~~~~~~~~~~~~~ + +Now we should edit *inetd.conf* (see below for *xinetd*), and add this line:: + + /etc/inetd.conf + + kprop stream tcp nowait root /usr/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 + +xinetd.conf +~~~~~~~~~~~~~~~~~ + +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 *kpropd* file */etc/xinetd.d/kpropd* :: + + /etc/xinetd.d/kpropd + + service kprop + { + socket_type = stream + wait = no + user = root + server = /usr/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 + } + +Save and close the file, and restart *xinetd*:: + + # /etc/init.d/xinetd restart + +You should now be able to propagate the dumps from master to slave. + + + ------------ -- 2.26.2