Administrative Client Programs
» Table of Contents |  | | » Glossary | | | » Index | | |
| | |
| ||
| ||
This section describes the administrative utilities kadmin, kadmin_local, kdb5_util, and kprop.
The kadmin program allows the Kerberos administrator to make changes to the Kerberos database. The kadmin program provides for the maintenance of Kerberos principals, policies, and service key tables (keytabs). It exists as both a Kerberos client (kadmin), using Kerberos authentication and an RPC to operate securely from anywhere on the network, and as a local client (kadmin_local), intended to run directly on the KDC without Kerberos authentication.
SYNOPSIS
| kadmin | [-r realm] [-p principal] [-w password] [-q query][-s admin_server[:port]] [[-c credentials_cache] |[-k keytab]] | |
| kadmin_local | [-d dbname] [-e “enc:salt ...”] [-m] |
Options
| -r realm | Use realm as the default Kerberos realm for the database. | |
| -p principal | Use the Kerberos principal principal to authenticate to Kerberos. If this option is not given, kadmin will append admin to either the primary principal name or to the username of the current process. | |
| -w password | Use password as the password
instead of prompting for one. | |
| -q query | Pass the string query directly to kadmin. This is useful for writing command procedures that pass specific queries to kadmin. | |
| -s admin_server[:port] | Use admin_server as the KDC to contact. Optionally specify the TCP/IP port to use for communication. | |
| -c credentials_cache | Use credentials_cache as the credentials cache. The credentials cache should contain a service ticket for the kadmin/admin service, which can be acquired with the kinit program. If this option is not specified, kadmin requests a new service ticket from the KDC and stores it in its own temporary cache. | |
| -k keytab | Use the keytab keytab to decrypt the KDC response instead of prompting for a password on the terminal. In this case, the principal will be host/hostname. | |
| -d dbname | This option is valid for kadmin_local only. Specify the filename of the KDC database. | |
| -e “enc:salt...” | This option is valid for kadmin_local only. It sets the list of cryptosystem and salt types to be used for any new keys created. Available types include des3-cbc-sha1:normal, des-cbc-crc:normal, and des-cbc-crc:v4. | |
| -m | This option is valid for kadmin_local only. Specify the KDC database master key. |
The kdb5_util program provides a way for the Kerberos administrator to create, delete, load, or dump a Kerberos database. It also includes a command to stash a copy of the master database key in a file on a KDC, so that the KDC can authenticate itself to the kadmind and krb5kdc daemons at boot time.
SYNOPSIS
| kdb5_util | [-r realm] [-d dbname] [-k mkeytype] [-M mkeyname][-sf stashfilename] [-m] command [command_options] |
OPTIONS
| -r realm | Use realm as the default Kerberos realm for the database. | |
| -d dbname | Specify the filename of the KDC database. | |
| -k mkeytype | Specify the encryption type to use from the list of supported mtypes in KDC.CONF. | |
| -M mkeyname | Specify the master key name. | |
| -sf stashfilename | Specify the file that stores the master key. If you specify this file, you are not prompted for the master key. | |
| -m | Specify the KDC database master key. |
command
The kdb5_util command can be one of the following:
| ark [-e etype_list] principal |
| Add a random key for a Kerberos 5 database entry principal. This assumes the max key version number. As a side effect, all old keys older than the maximum key version number are deleted. |
| -e etype_list |
| Specify the key salt to use for the random key. |
| create [-s] |
| Create a new Kerberos database. If you specify the -s option, kdb5_util stashes a copy of the master key in a stash file. |
| destroy [-f] |
| Destroy the existing Kerberos database. If you do not specify the -f option, you are prompted with “are you sure?” before the database is destroyed. |
| dump [-old] [-b6] [-ov] [-verbose] [-mkey_convert] [-new_mkey_file mkey_file] [-rev] [-recurse] [filename [princs...]] |
| Dump a Kerberos database to a file. |
| -old |
| Cause the dump file to be Kerberos 5 Beta 5 and earlier dump format (kdb5_edit load_dump version 2.0). |
| -b6 |
| Cause the dump file to be Kerberos 5 Beta 6 format (“kdb5_edit load_dump version 3.0”). |
| -ov |
| Cause the dump to be in ovsec_adm_export format. |
| -verbose |
| Cause the name of each principal and policy to be printed as it is loaded. |
| -mkey_convert |
| Change master key as part of dump. |
| -new_mkey_file mkey file |
| Get master key from file mkey_file. |
| -rev |
| Dump in reverse order. |
| -recurse |
| Do recursive descent tree traversal of database instead of using previous/next pointers. |
| filename |
| File name of the dump file to be output. |
| [princs] |
| Principal name to be dumped. |
| dump_v4 filename |
| Dump a Kerberos database to a file in Kerberos V4 format. |
| filename |
| File name of the dump file to be output. |
| load [-old] [-b6] [-ov] [-verbose] [-update] filename |
| Restore a Kerberos database dump from a file, specified by filename. |
| -old |
| Requires the dump to be in the Kerberos 5 Beta 5 and earlier dump format (kdb5_edit load_dump v2.0). |
| -b6 |
| Require the dump to be in the Kerberos 5 Beta 6 format (kdb5_edit load_dump v3.0). |
| -ov |
| Require the dump to be in ovsec_adm_export format |
| -verbose |
| Cause the name of each principal and policy to be printed as it is dumped. |
| -update |
| Cause records from the dump file to be updated in or added to the existing database. |
| filename |
| File name of the dump file to load. |
| load_v4 [-t] [-n] [-v] [-K] [-s stashfile] inputfile |
| Restore a Kerberos database dump from a Kerberos V4 format dump file (specified by inputfile). |
| -t |
| Allow modification of an existing database. If you do not specify -t, the load will abort if the database exists. |
| -n |
| Read the Kerberos V4 master key from the key file. |
| -v |
| Cause the name of each principal and policy to be printed as it is loaded. |
| -K |
| Prompt for the Kerberos V5 database master password. |
| -s stashfile |
| Specify the location of the Kerberos V4 master key file. |
| inputfile |
| Filename of the V4 dump file to load. |
| stash [-f keyfile] |
| Create a stash file, which allows a KDC to authenticate itself to the database programs kadmin, kadmind, krb5kdc, and kdb5_util. If the -f option is not specified, kdb5_util stashes the key in the file specified in the KRB$ROOT:[KRB5KDC]KDC.CONF file. |
The ktutil program invokes a menu from which an administrator can read, write, or edit entries in a Kerberos V5 keytab or V4 srvtab file.
SYNOPSIS
ktutil
command
The command on the ktutil menu can be one of the following:
| clear_list, clear |
| Clear the current key list. |
| read_kt, rkt |
| Read a krb5 keytab into the current keylist. |
| read_st, rst |
| Read a krb4 srvtab into the current keylist. |
| write_kt, wkt |
| Write the current keylist to a krb5 keytab. |
| write_st, wst |
| Write the current keylist to a krb4 srvtab. |
| add_entry, addent |
| Add an entry to the current keylist. |
| delete_entry, delent |
| Delete an entry from the current keylist. |
| list, l |
| List the current keylist. |
| list_requests, lr, ? |
| List available requests. |
| quit, exit, q |
| Exit program. |
The kprop program propagates the master KDC database to slave KDCs.
The following sections describe the procedure you should use to propagate your master KDC database. This procedure involves performing steps first on the master system, then the slave system, and back and forth again until finishing with the master system.
In the following procedure, the steps are numbered M1, M2, and so on for the master KDC server, and S1, S2 and so on for the slave KDC server.
Kerberos must be installed on both the master and slave systems.
PROCEDURE
M1. On the master KDC server, enter the following command:
$ @SYS$STARTUP:KRB$CONFIGURE
M2. Set up the client.
M3. Set up the server.
M4. Exit the KRB$CONFIGURE.COM file.
M5. If you added additional USER/admin principals during your configuration (other than your first admin principal), add them to KRB$ROOT:[KRB5KDC]KADM5.ACL.
M6. Add your anticipated slave hosts to KRB$ROOT:[ETC]KRB5.CONF under the realms tag using a kdc tag as follows:
USER/admin@REALM
kdc = nodename.domain:88
M7. To create KRB$ROOT:[BIN]KRB$KPROP.DAT from the template file KRB$KPROP_DAT.TEMPLATE, copy KRB$KPROP_DAT.TEMPLATE to KRB$KPROP.DAT, and edit KRB$KPROP.DAT as follows:
Comment out the example node name lines with a # sign.
Add all of your slave node names either as just the simple node name or as fully qualified node names that include their respective domain names. Be consistent in the naming method you choose. It is safest to use the node name form that is used to define your node names in your local TCP/IP host setting. If you use DNS to manage your local host lookups, you will need to use fully qualified node and domain name strings.
If you specify local host names, know the form of the node name you use, define all propagation node names that way in the local TCP/IP host database, and enter these propagation node names in the form that they are locally defined.
Try to define all propagation nodes in your local TCP/IP hosts database, or leave them all defined in DNS and not in your local database. If you see client not found errors during propagation, review your node name definitions and the form that you have in the local TCP/IP database.
The KRB$KPROP.DAT file is simply a data file that is read by the kprop command file to see where database propagation is performed. Make sure you do not include the local server node name in this data file. The propagation server does not need its own data propagated to itself.
You need only perform step M7 on those nodes that might act as the master KDC server at some future point, and need to have master database changes propagated to them.
M8. Create the KRB$ROOT:[KRB5KDC]KPROPD.ACL file as follows. There is no template for this file. This file defines the names of the hosts that will be involved in propagation and includes the master server entity. (This step will also have to be performed on each of your slave KDCs.)
Edit KRB$ROOT:[KRB5KDC]KPROPD.ACL to add each slave KDC host/name keytab entry that will be created in Step M11.
The form depends on how your node names are defined in TCP/IP. You can use either of the following forms. The @REALM portion is required.
host/yournode@REALM
host/yournode.yourdomain@REALM
If your local TCP/IP database defines the node names, the form of your node name in Step M8a must match that of your TCP/IP database
Be sure to include the host/entry for your master KDC.
M9. Start your master server and run KADMIN.
| |
| |
| |
 | NOTE: In steps M10 and M11, it is critical that the node names are in the same form as your local TCP/IP node name. You can use either simple node names or fully qualified DNS node names, as long as you are consistent. |
| |
| |
| |
M10. Add the host/principals with the following commands:
|
|
|
|
|
|
M11. Add/export the host/keytabs with the following commands:
|
|
|
|
|
|
| |
| |
| |
| NOTE: The @REALM part of this file name is important and must match the REALM entered into KPROPD.ACL in step M8. |
| |
| |
| |
M12. Restart your master KDC server using the latest configuration.
After you configure the master server, perform the following steps to configure each slave KDC server.
S1. To configure your slave KDC client, enter the master KDC server name when asked where the master KDC server resides. Do not use your local node name.
S2. Set up your slave KDC server by entering the following command:
|
|
|
Note the following:
Your KDC node name is your local node, not the master KDC node name.
Specify SLAVE_KDC, if it is not the default.
Add a local admin principal. (This will not be used.)
Accept the defaults for the remaining questions.
S3. Exit the configuration file and perform step M7 from the previous section only if, in the future, you may use this slave KDC as a master KDC server. Otherwise, go to step S4.
S4. Perform Step 1, M8 on your slave KDC node. You can copy the file from the server or edit a new file using the same host/entry information. This step is required for propagation.
S5. Export the master server's host/keytabs to the local KDC slave server keytab file. Because the slave server is configured as a client in the master KDC, you can kinit as the master KDC server's admin and run kadmin to extract the server's keytabs as shown in Step 1, M11. This will create your local keytab file with the MASTER KDC server keytab information. Issue a listprincs command and then ktadd the host principals.
S6. Edit KRB$ROOT:[KRB5KDC]KRB$ROLE.DAT. Change the second data line from a zero to a one (0 to 1), and save the file. This tells KRB$CONFIGURE that the KRB$KPROPD.EXE daemon must be started when the slave server is started.
S7. Edit KRB$ROOT:[ETC]KRB5.CONF and add the slave and master KDC nodes under the realms tag, if they do not exist. Here, you can safely specify fully qualified node names with their domain names as follows:
|
|
|
|
|
|
Make sure the record format for KRB5.CONF and KPROPD.ACL is STREAM_LF.
| |
| |
| |
 | CAUTION: Do not start the slave server yet. |
| |
| |
| |
Perform the following steps on the master server.
M13. Run kadmin and re-export only the master's host/keytab as in Step 1, M11. Because this keytab was exported on one or more slaves, the key version number is now greater than when this keytab was originally exported, and the slave KDCs will not be able to authenticate to the master KDC with a lower key version number.
M14. In kadmin, enter the following command:
|
|
|
| |
| |
| |
| NOTE: You may have to remove the host keytabs and principals and re-add them if the slave and master cannot agree on the key version numbers. This is an issue only with the master KDC keytab after keys are added to the slaves. This step does correct certain authentication problems. |
| |
| |
| |
M15. Restart the master server.
Perform the following steps on the slave server.
S8. Use kinit to get to your master server's admin account. This will refresh the master’s host keytab on the local system and start the slave server in preparation for its first propagation from the master.
Perform the following steps to complete the propagation procedure.
M16. Enter the following command:
|
|
|
The kprop command procedure causes the following to occur:
The master server is stopped, the database dumped, the servers restarted, and a connection to each slave kpropd daemon is made in order to transfer the master database to the slave servers listed in KRB$ROOT:[BIN]KRB$KPROP.DAT.
The slave servers are stopped, the master KDC database is loaded, the slave servers are restarted, and a signal is sent to the master server that the propagation has successfully completed.
The master server produces a file called SLAVE_DATATRANS_DAT_YOURSLAVENODE.LAST_PROP that indicates that the propagation to the individual slave node has completed.
When propagation to each slave server completes, the kpropd.exe daemon exits. The next propagation can be done only after starting the kpropd daemon on each of the KDC slave servers. This is why kpropd should be a TCP/IP service. The TCP/IP system automatically starts the kpropd daemon for each slave server requested by the master server.