Added kpropd and kproplog man pages to Sphinx doc tree
authorZhanna Tsitkov <tsitkova@mit.edu>
Thu, 4 Aug 2011 15:01:51 +0000 (15:01 +0000)
committerZhanna Tsitkov <tsitkova@mit.edu>
Thu, 4 Aug 2011 15:01:51 +0000 (15:01 +0000)
git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25071 dc483132-0cff-0310-8789-dd5450dbe970

doc/rst_source/conf.py
doc/rst_source/krb_admins/admin_commands/index.rst
doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
doc/rst_source/krb_admins/admin_commands/kprop.rst
doc/rst_source/krb_admins/admin_commands/kpropd.rst [new file with mode: 0644]
doc/rst_source/krb_admins/admin_commands/kproplog.rst [new file with mode: 0644]
doc/rst_source/krb_admins/admin_commands/krb5kdc.rst

index 65e76f7180d163303bda5b02c4be9b091e4dd84f..8f0af99c3c736d52ec346a16a9761fee816e570e 100644 (file)
@@ -226,6 +226,8 @@ man_pages = [
     ('krb_users/user_commands/ksu', 'ksu', u'Kerberized super-user', [u'MIT'], 1),
     ('krb_admins/admin_commands/krb5kdc', 'krb5kdc', u'Kerberos V5 KDC', [u'MIT'], 8),
     ('krb_admins/admin_commands/kadmin_local', 'kadmin.local', u'Kerberos V5 database administration program', [u'MIT'], 8),
-    ('krb_admins/admin_commands/kadmin', 'kadmin', u'Kerberos V5 database administration program', [u'MIT'], 1),
+    ('krb_admins/admin_commands/kadmin_local', 'kadmin', u'Kerberos V5 database administration program', [u'MIT'], 1),
     ('krb_admins/admin_commands/kprop', 'kprop', u'propagate a Kerberos V5 principal database to a slave server', [u'MIT'], 8),
+    ('krb_admins/admin_commands/kproplog', 'kproplog', u'display the contents of the Kerberos principal update log', [u'MIT'], 8),
+    ('krb_admins/admin_commands/kpropd', 'kpropd', u'Kerberos V5 slave KDC update server', [u'MIT'], 8),
 ]
index 8a8ae0fb0ba327f8a770963d6c095e1e4033c0a8..e38217801ff988ac28f421f7ff3c4b132722c55e 100644 (file)
@@ -10,6 +10,8 @@ Administration  programs
    krb5kdc.rst
    kadmin_local.rst
    kprop.rst
+   kpropd.rst
+   kproplog.rst
 
 
 ------------
index c725ff6672c3c52116877d61907c2cb4ec0b6e9f..c06afcf0169dbe6b84fdc322408d766b4e92c94d 100644 (file)
@@ -1,5 +1,6 @@
-kadmin - Kerberos V5 database administration program
-============================================================
+kadmin(1), kadmin.local(8)
+===========================
+
 
 SYNOPSYS
 --------------
index 532634593f38bfe5586d646198659010de224978..a810d8dca77780f5dec89829024b62fa40e68ca2 100644 (file)
@@ -1,16 +1,20 @@
-kprop - propagate a Kerberos V5 principal database to a slave server
-=====================================================================
+.. _kprop:
+
+kprop(8)
+=========
+
 
 SYNOPSIS
 -------------
 
 **kprop**
-         [**-r** *realm*] 
-         [**-f** *file*] 
-         [**-d**] 
-         [**-P** *port*] 
-         [**-s** *keytab*] 
-         *slave_host*
+          [**-r** *realm*] 
+          [**-f** *file*] 
+          [**-d**] 
+          [**-P** *port*] 
+          [**-s** *keytab*] 
+          *slave_host*
+
 
 DESCRIPTION
 -------------
@@ -30,7 +34,7 @@ OPTIONS
               *KPROP_DEFAULT_FILE* (normally /usr/local/var/krb5kdc/slave_datatrans).
 
        **-P** *port*
-              Specifies the port to use to contact the kpropd server on the remote host.
+              Specifies the port to use to contact the :ref:`kpropd` server on the remote host.
 
        **-d**     
               Prints debugging information.
diff --git a/doc/rst_source/krb_admins/admin_commands/kpropd.rst b/doc/rst_source/krb_admins/admin_commands/kpropd.rst
new file mode 100644 (file)
index 0000000..78746ef
--- /dev/null
@@ -0,0 +1,85 @@
+.. _kpropd:
+
+kpropd(8)
+===========
+
+
+SYNOPSIS
+----------
+
+***kpropd***
+          [ **-r** *realm* ] 
+          [ **-f** *slave_dumpfile* ] 
+          [ **-F** *principal_database* ] 
+          [ **-p** *kdb5_util_prog* ] 
+          [ **-d** ] 
+          [ **-S** ] 
+          [ **-P** *port* ]
+
+DESCRIPTION
+-------------
+
+The *kpropd* command runs on the slave KDC server.  
+It listens for update requests made by the :ref:`kprop` 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 kdb5_util(8) to load the dumped database into the active database which is used by :ref:`krb5kdc`.  
+Thus, the master Kerberos server can use :ref:`kprop` to propagate its database to the slave slavers.  
+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::
+
+       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).
+
+When the slave periodically requests incremental updates, *kpropd* updates its *principal.ulog* file with any updates from the master.  
+:ref:`kproplog` 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.
+
+OPTIONS
+--------
+
+       **-r** *realm*
+              Specifies the realm of the master server; by default the realm returned by krb5_default_local_realm(3) is used.
+
+       **-f** *file*
+              Specifies the filename where the dumped principal database file is to be stored; by default the dumped database file is *KPROPD_DEFAULT_FILE*
+              (normally /usr/local/var/krb5kdc/from_master).
+
+       **-p**
+              Allows the user to specify the pathname to the kdb5_util(8) program; by default the pathname used is *KPROPD_DEFAULT_KDB5_UTIL*
+              (normally /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).
+              If the *-S* option is specified, *kpropd* will put itself into the background, and wait for connections to the  *KPROP_SERVICE* port  
+              (normally *krb5_prop*).
+
+       **-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.
+
+       **-P**     
+               Allow for an alternate port number for *kpropd* to listen on. This is only useful if the program is run in standalone mode.
+
+       **-a**     
+              Allows the user to specify the path to the *kpropd.acl* file; by default the path used is *KPROPD_ACL_FILE*   
+              (normally /usr/local/var/krb5kdc/kpropd.acl).
+
+FILES
+---------
+
+*kpropd.acl*  
+            Access file for *kpropd*; the default location is KPROPD_ACL_FILE (normally /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`.
+
+SEE ALSO
+----------
+
+kprop(8), kdb5_util(8), krb5kdc(8), inetd(8)
+
+
diff --git a/doc/rst_source/krb_admins/admin_commands/kproplog.rst b/doc/rst_source/krb_admins/admin_commands/kproplog.rst
new file mode 100644 (file)
index 0000000..dc5c4e0
--- /dev/null
@@ -0,0 +1,60 @@
+.. _kproplog:
+
+kproplog(8)
+===========
+
+
+SYNOPSIS
+------------
+
+**kproplog** [**-h**] [**-e** *num*]
+
+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.  
+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.
+
+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.
+
+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.
+
+       **-e** *num*
+             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::
+
+               Update Entry
+                  Update serial # : 4
+                  Update operation : Add
+                  Update principal : test@EXAMPLE.COM
+                  Update size : 424
+                  Update committed : True
+                  Update time stamp : Fri Feb 20 23:37:42 2004
+                  Attributes changed : 6
+                        Principal
+                        Key data
+                        Password last changed
+                        Modifying principal
+                        Modification time
+                        TL data
+
+SEE ALSO
+------------
+
+kpropd(8)
+
index e1bd34638feb7ca94a9fcf171b0e0e5d4c861fe9..91f10204d606f70aa3470996824ab563cff0e762 100644 (file)
@@ -1,4 +1,6 @@
-krb5kdc - Kerberos V5 KDC
+.. _krb5kdc:
+
+krb5kdc(8)
 ===========================
 
 SYNOPSIS