document admin_server and kpasswd_server for realms

document capath better


git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@9487 ec53bebd-3082-4978-b11e-865c3cabbd6b

lib/krb5/krb5.conf.5

@@ -46,7 +46,6 @@ name:
 .Li STRINGs
 consists of one or more non-white space characters.
 Currently recognised sections and bindings are:
-
 .Bl -tag -width "xxx" -offset indent
 .It Li [libdefaults]
 .Bl -tag -width "xxx" -offset indent
@@ -65,7 +64,24 @@ Maximum time to wait for a reply from the kdc, default is 3 seconds.
 These are decribed in the 
 .Xr krb5_425_conv_principal  3
 manual page.
-.It Li capath = Va realm-routing-table
+.It Li capath = {
+.Bl -tag -width "xxx" -offset indent
+.It Va destination-realm Li = Va next-hop-realm
+.It ...
+.El
+Normally, all requests to realms different from the one of the current
+client are sent to this KDC to get cross-realm tickets.
+If this KDC does not have a cross-realm key with the desired realm and
+the hierarchical path to that realm does not work, a path can be
+configured using this directive.
+The text shown above instructs the KDC to try to obtain a cross-realm
+ticket to
+.Va next-hop-realm
+when the desired realm is
+.Va destination-realm .
+This configuration should preferably be done on the KDC where it will
+help all its clients but can also be done on the client itself.
+.It Li }
 .It Li default_etypes = Va etypes...
 A list of default etypes to use.
 .It Li default_etypes_des = Va etypes...
@@ -113,10 +129,18 @@ perid.
 .It Va REALM Li = {
 .Bl -tag -width "xxx" -offset indent
 .It Li kdc = Va host[:port]
-Specifies a kdc for this realm. If the optional port is absent, the
+Specifies a list of kdcs for this realm. If the optional port is absent, the
 default value for the
 .Dq kerberos/udp
 service will be used.
+The kdcs will be used in the order that they are specified.
+.It Li admin_server = Va host[:port]
+Specifies the admin server for this realm, where all the modifications
+to the database are perfomed.
+.It Li kpasswd_server = Va host[:port]
+Points to the server where all the password changes are perfomed.
+If there is no such entry, the kpasswd port on the admin_server host
+will be tried.
 .It Li v4_instance_convert
 .It Li v4_name_convert
 .It Li default_domain
@@ -253,6 +277,19 @@ points to the configuration file to read.
 	kdc = SYSLOG:INFO
 	default = SYSLOG:INFO:USER
 .Ed
+.Sh DIAGNOSTICS
+Since
+.Nm
+is read and parsed by the krb5 library, there is not a lot of
+opportunities for programs to report parsing errors in any useful
+format.
+To help overcome this problem, there is a program
+.Nm verify_krb5_conf
+that reads
+.Nm
+and tries to emit useful diagnostics from parsing errors.  Note that
+this program does not have any way of knowing what options are
+actually used and thus cannot warn about unknown or misspelt ones.
 .Sh SEE ALSO
 .Xr verify_krb5_conf 8 ,
 .Xr krb5_openlog 3 ,