From 04288a14bb364baddb61db85591832eb67d4bd27 Mon Sep 17 00:00:00 2001 From: Zhanna Tsitkov Date: Thu, 22 Dec 2011 16:25:43 +0000 Subject: [PATCH] Updated env variable sections, formating and other corrections git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25602 dc483132-0cff-0310-8789-dd5450dbe970 --- .../krb_admins/admin_commands/kadmind.rst | 2 +- .../admin_commands/kdb5_ldap_util.rst | 2 +- .../krb_admins/admin_commands/kprop.rst | 17 +++-- .../krb_admins/admin_commands/kpropd.rst | 68 +++++++++++++------ .../krb_admins/admin_commands/kproplog.rst | 36 +++++++--- .../krb_admins/admin_commands/krb5kdc.rst | 66 ++++++++++++------ doc/rst_source/krb_admins/env_variables.rst | 5 +- .../krb_users/user_commands/kdestroy.rst | 9 +-- .../krb_users/user_commands/klist.rst | 4 +- .../krb_users/user_commands/kvno.rst | 25 +++++-- 10 files changed, 164 insertions(+), 70 deletions(-) diff --git a/doc/rst_source/krb_admins/admin_commands/kadmind.rst b/doc/rst_source/krb_admins/admin_commands/kadmind.rst index ed0ae02bb..913829492 100644 --- a/doc/rst_source/krb_admins/admin_commands/kadmind.rst +++ b/doc/rst_source/krb_admins/admin_commands/kadmind.rst @@ -40,7 +40,7 @@ After the server begins running, it puts itself in the background and disassocia *kadmind* can be configured for incremental database propagation. Incremental propagation allows slave KDC servers to receive principal and policy updates incrementally instead of receiving full dumps of the database. This facility can be enabled in the :ref:`kdc.conf` file with the *iprop_enable* option. See the :ref:`kdc.conf` documentation for other options for tuning incremental propagation parameters. -Incremental propagation requires the principal "kiprop/MASTER\@REALM" i +Incremental propagation requires the principal "kiprop/MASTER\@REALM" (where MASTER is the master KDC's canonical host name, and REALM the realm name) to be registered in the database. diff --git a/doc/rst_source/krb_admins/admin_commands/kdb5_ldap_util.rst b/doc/rst_source/krb_admins/admin_commands/kdb5_ldap_util.rst index 3b43d2758..93fe1bf55 100644 --- a/doc/rst_source/krb_admins/admin_commands/kdb5_ldap_util.rst +++ b/doc/rst_source/krb_admins/admin_commands/kdb5_ldap_util.rst @@ -493,7 +493,7 @@ create_policy (Sets the KRB5_KDB_DISALLOW_SVR flag.) *+allow_svr* clears this flag. {-\|+}allow_tgs_req - *-allow_tgs_req* specifies that a Ticket-Granting Service (TGS) request i + *-allow_tgs_req* specifies that a Ticket-Granting Service (TGS) request for a service ticket for principals is not permitted. This option is useless for most things. *+allow_tgs_req* clears this flag. The default is *+allow_tgs_req*. diff --git a/doc/rst_source/krb_admins/admin_commands/kprop.rst b/doc/rst_source/krb_admins/admin_commands/kprop.rst index 46c0e5b2c..25c86edc4 100644 --- a/doc/rst_source/krb_admins/admin_commands/kprop.rst +++ b/doc/rst_source/krb_admins/admin_commands/kprop.rst @@ -19,8 +19,10 @@ SYNOPSIS DESCRIPTION ------------- -*kprop* is used to propagate a Kerberos V5 database dump file from the master Kerberos server to a slave Kerberos server, -which is specified by *slave_host*. This is done by transmitting the dumped database file to the slave server over an encrypted, secure channel. +*kprop* is used to propagate a Kerberos V5 database dump file from the master +Kerberos server to a slave Kerberos server, which is specified by *slave_host*. +This is done by transmitting the dumped database file to the slave server over +an encrypted, secure channel. The dump file must be created by :ref:`kdb5_util(8)`. OPTIONS @@ -30,8 +32,9 @@ OPTIONS Specifies the realm of the master server. **-f** *file* - Specifies the filename where the dumped principal database file is to be found; by default the dumped database file is - normally /usr/local/var/krb5kdc/slave_datatrans. + Specifies the filename where the dumped principal database file is to be found; + by default the dumped database file is normally + */usr/local/var/krb5kdc/slave_datatrans*. **-P** *port* Specifies the port to use to contact the :ref:`kpropd(8)` server on the remote host. @@ -42,6 +45,12 @@ OPTIONS **-s** *keytab* Specifies the location of the keytab file. +ENVIRONMENT +-------------- + +*kprop* uses the following environment variable: + + - **KRB5_CONFIG** SEE ALSO ------------- diff --git a/doc/rst_source/krb_admins/admin_commands/kpropd.rst b/doc/rst_source/krb_admins/admin_commands/kpropd.rst index 90318478c..51c983ca2 100644 --- a/doc/rst_source/krb_admins/admin_commands/kpropd.rst +++ b/doc/rst_source/krb_admins/admin_commands/kpropd.rst @@ -21,25 +21,36 @@ DESCRIPTION ------------- The *kpropd* command runs on the slave KDC server. -It listens for update requests made by the :ref:`kprop(8)` program, and periodically requests incremental updates from the master KDC. +It listens for update requests made by the :ref:`kprop(8)` program, +and periodically requests incremental updates from the master KDC. -When the slave receives a *kprop* request from the master, *kpropd* accepts the dumped KDC database and places it in a file, -and then runs :ref:`kdb5_util(8)` to load the dumped database into the active database which is used by :ref:`krb5kdc(8)`. -Thus, the master Kerberos server can use :ref:`kprop(8)` to propagate its database to the slave servers. -Upon a successful download of the KDC database file, the slave Kerberos server will have an up-to-date KDC database. +When the slave receives a *kprop* request from the master, +*kpropd* accepts the dumped KDC database and places it in a file, +and then runs :ref:`kdb5_util(8)` to load the dumped database into +the active database which is used by :ref:`krb5kdc(8)`. +Thus, the master Kerberos server can use :ref:`kprop(8)` +to propagate its database to the slave servers. +Upon a successful download of the KDC database file, +the slave Kerberos server will have an up-to-date KDC database. -Normally, *kpropd* is invoked out of inetd(8). This is done by adding a line to the *inetd.conf* file which looks like this:: +Normally, *kpropd* is invoked out of inetd(8). +This is done by adding a line to the *inetd.conf* file which looks like this:: kprop stream tcp nowait root /usr/local/sbin/kpropd kpropd However, *kpropd* can also run as a standalone daemon, if the *-S* option is turned on. -This is done for debugging purposes, or if for some reason the system administrator just doesn't want to run it out of inetd(8). +This is done for debugging purposes, or if for some reason the system administrator +just doesn't want to run it out of inetd(8). -When the slave periodically requests incremental updates, *kpropd* updates its *principal.ulog* file with any updates from the master. +When the slave periodically requests incremental updates, +*kpropd* updates its *principal.ulog* file with any updates from the master. :ref:`kproplog(8)` can be used to view a summary of the update entry log on the slave KDC. -Incremental propagation is not enabled by default; it can be enabled using the *iprop_enable* and *iprop_slave_poll* settings in :ref:`kdc.conf`. -The principal "kiprop/slavehostname\@REALM" (where "slavehostname" is the name of the slave KDC host, -and "REALM" is the name of the Kerberos realm) must be present in the slave's keytab file. +Incremental propagation is not enabled by default; +it can be enabled using the *iprop_enable* and *iprop_slave_poll* settings in :ref:`kdc.conf`. +The principal "kiprop/slavehostname\@REALM" +(where "slavehostname" is the name of the slave KDC host, +and "REALM" is the name of the Kerberos realm) +must be present in the slave's keytab file. OPTIONS -------- @@ -48,33 +59,48 @@ OPTIONS Specifies the realm of the master server. **-f** *file* - Specifies the filename where the dumped principal database file is to be stored; by default the dumped database file - /usr/local/var/krb5kdc/from_master. + Specifies the filename where the dumped principal database file is to be stored; + by default the dumped database file */usr/local/var/krb5kdc/from_master*. **-p** - Allows the user to specify the pathname to the :ref:`kdb5_util(8)` program; by default the pathname used is /usr/local/sbin/kdb5_util. + Allows the user to specify the pathname to the :ref:`kdb5_util(8)` program; + by default the pathname used is /usr/local/sbin/kdb5_util. **-S** - Turn on standalone mode. Normally, *kpropd* is invoked out of inetd(8) so it expects a network connection to be passed to it from inetd(8). + Turn on standalone mode. Normally, *kpropd* is invoked out of inetd(8) + so it expects a network connection to be passed to it from inetd(8). If the *-S* option is specified, *kpropd* will put itself into the background, and wait for connections to the *krb5_prop* port specified in /etc/services. **-d** - Turn on debug mode. In this mode, if the *-S* option is selected, *kpropd* will not detach itself from the current job - and run in the background. Instead, it will run in the foreground and print out debugging messages during the database propagation. + Turn on debug mode. In this mode, if the *-S* option is selected, + *kpropd* will not detach itself from the current job and run in the background. + Instead, it will run in the foreground and print out debugging messages + during the database propagation. **-P** - Allow for an alternate port number for *kpropd* to listen on. This is only useful if the program is run in standalone mode. + Allow for an alternate port number for *kpropd* to listen on. + This is only useful if the program is run in standalone mode. **-a** *acl_file* - Allows the user to specify the path to the *kpropd.acl* file; by default the path used is /usr/local/var/krb5kdc/kpropd.acl. + Allows the user to specify the path to the *kpropd.acl* file; + by default the path used is /usr/local/var/krb5kdc/kpropd.acl. + +ENVIRONMENT +-------------- + +*kpropd* uses the following environment variables: + + - **KRB5_CONFIG** + - **KRB5_KDC_PROFILE** FILES --------- *kpropd.acl* - Access file for *kpropd*; the default location is /usr/local/var/krb5kdc/kpropd.acl. - Each entry is a line containing the principal of a *host* from which the local machine will allow Kerberos database propagation via :ref:`kprop(8)`. + Access file for *kpropd*; the default location is */usr/local/var/krb5kdc/kpropd.acl*. + Each entry is a line containing the principal of a *host* from which the local machine + will allow Kerberos database propagation via :ref:`kprop(8)`. SEE ALSO ---------- diff --git a/doc/rst_source/krb_admins/admin_commands/kproplog.rst b/doc/rst_source/krb_admins/admin_commands/kproplog.rst index 5ab72658a..afc2436af 100644 --- a/doc/rst_source/krb_admins/admin_commands/kproplog.rst +++ b/doc/rst_source/krb_admins/admin_commands/kproplog.rst @@ -12,28 +12,39 @@ SYNOPSIS DESCRIPTION ------------ -The *kproplog* command displays the contents of the Kerberos principal update log to standard output. -It can be used to keep track of the incremental updates to the principal database, when enabled. -The update log file contains the update log maintained by the *kadmind* process on the master KDC server and the *kpropd* process on the slave KDC servers. +The *kproplog* command displays the contents of the Kerberos principal +update log to standard output. +It can be used to keep track of the *incremental* updates +to the principal database, when enabled. +The update log file contains the update log maintained by the *kadmind* process +on the master KDC server and the *kpropd* process on the slave KDC servers. When updates occur, they are logged to this file. -Subsequently any KDC slave configured for incremental updates will request the current data from the master KDC and update their *principal.ulog* file with any updates returned. +Subsequently any KDC slave configured for *incremental* updates will request +the current data from the master KDC and update their *principal.ulog* file +with any updates returned. -The *kproplog* command can only be run on a KDC server by someone with privileges comparable to the superuser. +The *kproplog* command can only be run on a KDC server by someone with privileges +comparable to the superuser. It will display update entries for that server only. If no options are specified, the summary of the update log is displayed. If invoked on the master, all of the update entries are also displayed. -When invoked on a slave KDC server, only a summary of the updates are displayed, which includes the serial number of the last update received and the associated time stamp of the last update. +When invoked on a slave KDC server, only a summary of the updates are displayed, +which includes the serial number of the last update received and +the associated time stamp of the last update. OPTIONS ------------ **-h** - Display a summary of the update log. This information includes the database version number, state of the database, - the number of updates in the log, the time stamp of the first and last update, and the version number of the first and last update entry. + Display a summary of the update log. + This information includes the database version number, state of the database, + the number of updates in the log, the time stamp of the first and last update, + and the version number of the first and last update entry. **-e** *num* - Display the last *num* update entries in the log. This is useful when debugging synchronization between KDC servers. + Display the last *num* update entries in the log. + This is useful when debugging synchronization between KDC servers. **-v** Display individual attributes per update. An example of the output generated for one entry:: @@ -53,6 +64,13 @@ OPTIONS Modification time TL data +ENVIRONMENT +-------------- + +*kproplog* uses the following environment variables: + + - **KRB5_KDC_PROFILE** + SEE ALSO ------------ diff --git a/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst b/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst index beed157fc..5c6b9b1eb 100644 --- a/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst +++ b/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst @@ -37,47 +37,64 @@ The **-x** *db_args* option specifies the database specific arguments. Specifies the LDAP server to connect to by a LDAP URI. **-x** binddn= - Specifies the DN of the object used by the KDC server to bind to the LDAP server. This object should have the rights to read - the realm container, principal container and the subtree that is referenced by the realm. + Specifies the DN of the object used by the KDC server to bind to the LDAP server. + This object should have the rights to read the realm container, principal container and + the subtree that is referenced by the realm. **-x** bindpwd= - Specifies the password for the above mentioned binddn. It is recommended not to use this option. Instead, the password can be - stashed using the stashsrvpw command of kdb5_ldap_util. + Specifies the password for the above mentioned binddn. + It is recommended not to use this option. Instead, the password can be + stashed using the *stashsrvpw* command of :ref:`kdb5_ldap_util(8)` The **-r** *realm* option specifies the realm for which the server should provide service. The **-d** *dbname* option specifies the name under which the principal database can be found. This option does not apply to the LDAP database. -The **-k** *keytype* option specifies the key type of the master key to be entered manually as a password when **-m** is given; -the default is "des-cbc-crc". +The **-k** *keytype* option specifies the key type of the master key to be entered manually +as a password when **-m** is given; the default is "des-cbc-crc". -The **-M** *mkeyname* option specifies the principal name for the master key in the database (usually "K/M" in the KDC's realm). +The **-M** *mkeyname* option specifies the principal name for the master key +in the database (usually "K/M" in the KDC's realm). -The **-m** option specifies that the master database password should be fetched from the keyboard rather than from a file on disk. +The **-m** option specifies that the master database password should be fetched +from the keyboard rather than from a file on disk. -The **-n** option specifies that the KDC does not put itself in the background and does not disassociate itself from the terminal. +The **-n** option specifies that the KDC does not put itself in the background +and does not disassociate itself from the terminal. In normal operation, you should always allow the KDC to place itself in the background. -The **-P** *pid_file* option tells the KDC to write its PID (followed by a newline) into *pid_file* after it starts up. -This can be used to identify whether the KDC is still running and to allow init scripts to stop the correct process. - -The **-p** *portnum* option specifies the default UDP port number which the KDC should listen on for Kerberos version 5 requests. -This value is used when no port is specified in the KDC profile and when no port is specified in the Kerberos configuration file. +The **-P** *pid_file* option tells the KDC to write its PID (followed by a newline) +into *pid_file* after it starts up. +This can be used to identify whether the KDC is still running and to allow +init scripts to stop the correct process. + +The **-p** *portnum* option specifies the default UDP port number which the KDC +should listen on for Kerberos version 5 requests. +This value is used when no port is specified in the KDC profile and +when no port is specified in the Kerberos configuration file. If no value is available, then the value in */etc/services* for service "kerberos" is used. -The **-w** *numworkers* option tells the KDC to fork *numworkers* processes to listen to the KDC ports and process requests in parallel. -The top level KDC process (whose pid is recorded in the pid file if the **-P** option is also given) acts as a supervisor. -The supervisor will relay SIGHUP signals to the worker subprocesses, and will terminate the worker subprocess if the it is itself terminated or +The **-w** *numworkers* option tells the KDC to fork *numworkers* processes +to listen to the KDC ports and process requests in parallel. +The top level KDC process (whose pid is recorded in the pid file +if the **-P** option is also given) acts as a supervisor. +The supervisor will relay SIGHUP signals to the worker subprocesses, +and will terminate the worker subprocess if the it is itself terminated or if any other worker process exits. -.. note:: on operating systems which do not have *pktinfo* support, using worker processes will prevent the KDC from listening for UDP packets on network interfaces created after the KDC starts. +.. note:: On operating systems which do not have *pktinfo* support, + using worker processes will prevent the KDC from listening + for UDP packets on network interfaces created after the KDC starts. + EXAMPLE +---------- The KDC may service requests for multiple realms (maximum 32 realms). -The realms are listed on the command line. Per-realm options that can be specified on the command line pertain for each realm +The realms are listed on the command line. +Per-realm options that can be specified on the command line pertain for each realm that follows it and are superseded by subsequent definitions of the same option. For example:: @@ -89,8 +106,17 @@ The location of this file may be specified by the *KRB5_KDC_PROFILE* environment Parameters specified in this file take precedence over options specified on the command line. See the :ref:`kdc.conf` description for further details. +ENVIRONMENT +-------------- + +*krb5kdc* uses the following environment variables: + + - **KRB5_CONFIG** + - **KRB5_KDC_PROFILE** + + SEE ALSO ----------- -krb5(3), kdb5_util(8), kdc.conf(5), kdb5_ldap_util(8) +kdb5_util(8), kdc.conf(5), krb5.conf(5), kdb5_ldap_util(8) diff --git a/doc/rst_source/krb_admins/env_variables.rst b/doc/rst_source/krb_admins/env_variables.rst index b5bf2a272..908960b42 100644 --- a/doc/rst_source/krb_admins/env_variables.rst +++ b/doc/rst_source/krb_admins/env_variables.rst @@ -17,7 +17,10 @@ The following environment variables can be used during runtime: (See :ref:`mitK5defaults` for the default name) **KRB5CCNAME** - Default name for the credentials cache file. + Default name for the credentials cache file, in the form *type:residual*. + The type of the default cache may determine the availability of a cache collection. + For instance, a default cache of type DIR causes caches within the directory + to be present in the global cache collection. **KRB5RCACHETYPE** Default replay cache type. Defaults to "dfl". diff --git a/doc/rst_source/krb_users/user_commands/kdestroy.rst b/doc/rst_source/krb_users/user_commands/kdestroy.rst index b86137afe..4ad0a7e8c 100644 --- a/doc/rst_source/krb_users/user_commands/kdestroy.rst +++ b/doc/rst_source/krb_users/user_commands/kdestroy.rst @@ -27,7 +27,8 @@ OPTIONS available. **-q** - Run quietly. Normally *kdestroy* beeps if it fails to destroy the user's tickets. The *-q* flag suppresses this behavior. + Run quietly. Normally *kdestroy* beeps if it fails to destroy the user's tickets. + The *-q* flag suppresses this behavior. **-c** *cache_name* Use *cache_name* as the credentials (ticket) cache name and location; @@ -48,7 +49,7 @@ so that your tickets are destroyed automatically when you log out. ENVIRONMENT ~~~~~~~~~~~~~ -*kdestroy* uses the following environment variables: +*kdestroy* uses the following environment variable: **KRB5CCNAME** Location of the default Kerberos 5 credentials (ticket) @@ -63,13 +64,13 @@ ENVIRONMENT FILES ~~~~~~~~~~~~~ -/tmp/krb5cc_[uid] - Default location of Kerberos 5 credentials cache ([*uid*] is the decimal UID of the user). +/tmp/krb5cc_[uid] - Default location of Kerberos 5 credentials cache ([*uid*] is the decimal UID of the user). SEE ALSO ~~~~~~~~~ -kinit(1), klist(1), krb5(3) +kinit(1), klist(1) BUGS diff --git a/doc/rst_source/krb_users/user_commands/klist.rst b/doc/rst_source/krb_users/user_commands/klist.rst index 3886a9ff0..d75909b9b 100644 --- a/doc/rst_source/krb_users/user_commands/klist.rst +++ b/doc/rst_source/krb_users/user_commands/klist.rst @@ -85,7 +85,7 @@ OPTIONS ENVIRONMENT ~~~~~~~~~~~~~ -*klist* uses the following environment variables: +*klist* uses the following environment variable: **KRB5CCNAME** Location of the default Kerberos 5 credentials (ticket) @@ -108,6 +108,6 @@ FILES SEE ALSO ~~~~~~~~~ -kinit(1), kdestroy(1), krb5(3) +kinit(1), kdestroy(1) diff --git a/doc/rst_source/krb_users/user_commands/kvno.rst b/doc/rst_source/krb_users/user_commands/kvno.rst index d64c3d28f..ad4f9f6db 100644 --- a/doc/rst_source/krb_users/user_commands/kvno.rst +++ b/doc/rst_source/krb_users/user_commands/kvno.rst @@ -17,7 +17,8 @@ SYNOPSIS DESCRIPTION ~~~~~~~~~~~~~~~ -*kvno* acquires a service ticket for the specified Kerberos principals and prints out the key version numbers of each. +*kvno* acquires a service ticket for the specified Kerberos principals and +prints out the key version numbers of each. OPTIONS ~~~~~~~~~~~~~~~ @@ -26,7 +27,9 @@ OPTIONS Specifies the name of a credentials cache to use (if not the default) **-e** *etype* - Specifies the enctype which will be requested for the session key of all the services named on the command line. This is useful in certain backward compatibility situations. + Specifies the enctype which will be requested for the session key of all + the services named on the command line. + This is useful in certain backward compatibility situations. **-q** Suppress printing @@ -35,13 +38,21 @@ OPTIONS Prints a usage statement and exits **-P** - Specifies that the *service1 service2* ... arguments are to be treated as services for which credentials should be acquired using constrained delegation. This option is only valid when used in conjunction with protocol transition. + Specifies that the *service1 service2* ... arguments are to be treated as + services for which credentials should be acquired using constrained delegation. + This option is only valid when used in conjunction with protocol transition. **-S** *sname* - Specifies that krb5_sname_to_principal() will be used to build principal names. If this flag is specified, the *service1 service2* ... arguments are interpreted as hostnames (rather than principal names), and sname is interpreted as the service name. + Specifies that *krb5_sname_to_principal()* will be used to build principal names. + If this flag is specified, the *service1 service2* ... arguments are interpreted as + *hostnames* (rather than principal names), + and *sname* is interpreted as the service name. **-U** *for_user* - Specifies that protocol transition (S4U2Self) is to be used to acquire a ticket on behalf of for_user. If constrained delegation is not requested, the service name must match the credentials cache client principal. + Specifies that protocol transition (S4U2Self) is to be used + to acquire a ticket on behalf of *for_user*. + If constrained delegation is not requested, + the service name must match the credentials cache client principal. ENVIRONMENT ~~~~~~~~~~~~~~~ @@ -53,11 +64,11 @@ ENVIRONMENT FILES ~~~~~~~~~~~~~~~ -/tmp/krb5cc_[uid] default location of the credentials cache ([uid] is the decimal UID of the user). +/tmp/krb5cc_[uid] - Default location of the credentials cache ([uid] is the decimal UID of the user). SEE ALSO ~~~~~~~~~~~~~~~ -kinit(1), kdestroy(1), krb5(3) +kinit(1), kdestroy(1) -- 2.26.2