svn rev #22223: branches/krb5-1-7/doc/
tlyu@MIT.EDU
tlyu at MIT.EDU
Tue Apr 14 17:07:29 EDT 2009
http://src.mit.edu/fisheye/changelog/krb5/?cs=22223
Commit By: tlyu
Log Message:
ticket: 6418
version_fixed: 1.7
pull up r22088 from trunk
------------------------------------------------------------------------
r22088 | ghudson | 2009-03-14 01:46:18 -0400 (Sat, 14 Mar 2009) | 15 lines
Changed paths:
M /trunk/doc/admin.texinfo
ticket: 6418
subject: Improve LDAP admin documentation
target_version: 1.7
tags: pullup
Use dc=example,dc=com as the example base DN instead of more archaic
forms. Provide a little more cross-referencing of concepts and
mechanisms. Add additional steps in the OpenLDAP setup instructions
for choosing DNs for the Kerberos container, KDC service, and kadmin
service. Explain a little bit about what the Kerberos container and
realm container are. Be clearer that using separate subtrees from the
realm container for principals is an option, not a necessity, and
don't use the base DN as an example of a separate subtree (it's
confusing).
Changed Files:
U branches/krb5-1-7/doc/admin.texinfo
Modified: branches/krb5-1-7/doc/admin.texinfo
===================================================================
--- branches/krb5-1-7/doc/admin.texinfo 2009-04-14 21:07:26 UTC (rev 22222)
+++ branches/krb5-1-7/doc/admin.texinfo 2009-04-14 21:07:28 UTC (rev 22223)
@@ -1013,7 +1013,7 @@
@itemx ldap_service_password_file
-This LDAP specific tag indicates the file containing the stashed passwords for the objects used by the Kerberos servers to bind to the LDAP server. This file must be kept secure. This value is used if no service password file is mentioned in the configuration section under [dbmodules].
+This LDAP specific tag indicates the file containing the stashed passwords (created by @code{kdb5_ldap_util stashsrvpw}) for the objects used by the Kerberos servers to bind to the LDAP server. This file must be kept secure. This value is used if no service password file is mentioned in the configuration section under [dbmodules].
@itemx ldap_server
@@ -1044,7 +1044,7 @@
This LDAP specific tag indicates the default bind DN for the Administration server. The administration server does a login to the directory as this object. This object should have the rights to read and write the Kerberos data in the LDAP database.
@itemx ldap_service_password_file
-This LDAP specific tag indicates the file containing the stashed passwords for the objects used by the Kerberos servers to bind to the LDAP server. This file must be kept secure.
+This LDAP specific tag indicates the file containing the stashed passwords (created by @code{kdb5_ldap_util stashsrvpw}) for the objects used by the Kerberos servers to bind to the LDAP server. This file must be kept secure.
@itemx ldap_server
This LDAP specific tag indicates the list of LDAP servers that the Kerberos servers can connect to. The list of LDAP servers is whitespace-separated. The LDAP server is specified by a LDAP URI. It is recommended to use ldapi:// or ldaps:// interface to connect to the LDAP server.
@@ -1379,20 +1379,20 @@
kdc = SYSLOG:INFO
admin_server = FILE=/var/kadm5.log
[dbdefaults]
- ldap_kerberos_container_dn = cn=krbcontainer,o=mit
+ ldap_kerberos_container_dn = cn=krbcontainer,dc=example,dc=com
[dbmodules]
openldap_ldapconf = @{
- db_library = kldap
- ldap_kerberos_container_dn = cn=krbcontainer,o=mit
- ldap_kdc_dn = "cn=krbadmin,o=mit"
- # this object needs to have read rights on
- # the realm container, principal container and realm sub-trees
- ldap_kadmind_dn = "cn=krbadmin,o=mit"
- # this object needs to have read and write rights on
- # the realm container, principal container and realm sub-trees
- ldap_service_password_file = /etc/kerberos/service.keyfile
- ldap_servers = ldaps://kerberos.mit.edu
- ldap_conns_per_server = 5
+ db_library = kldap
+ ldap_kerberos_container_dn = cn=krbcontainer,dc=example,dc=com
+ ldap_kdc_dn = "cn=krbadmin,dc=example,dc=com"
+ # this object needs to have read rights on
+ # the realm container and principal subtrees
+ ldap_kadmind_dn = "cn=krbadmin,dc=example,dc=com"
+ # this object needs to have read and write rights on
+ # the realm container and principal subtrees
+ ldap_service_password_file = /etc/kerberos/service.keyfile
+ ldap_servers = ldaps://kerberos.mit.edu
+ ldap_conns_per_server = 5
@}
@@ -2310,7 +2310,7 @@
@smallexample
@group
- at b{kadmin:} addprinc -x dn=cn=@value{RANDOMUSER1},o=mit @value{RANDOMUSER1}
+ at b{kadmin:} addprinc -x dn=cn=@value{RANDOMUSER1},dc=example,dc=com @value{RANDOMUSER1}
@b{WARNING: no policy specified for "@value{RANDOMUSER1}@@@value{PRIMARYREALM}";
defaulting to no policy.}
@iftex
@@ -2334,7 +2334,7 @@
@smallexample
@group
- at b{kadmin:} addprinc -x containerdn=o=mit -x linkdn=cn=@value{RANDOMUSER2},o=mit @value{RANDOMUSER2}
+ at b{kadmin:} addprinc -x containerdn=dc=example,dc=com -x linkdn=cn=@value{RANDOMUSER2},dc=example,dc=com @value{RANDOMUSER2}
@b{WARNING: no policy specified for "@value{RANDOMUSER2}@@@value{PRIMARYREALM}";
defaulting to no policy.}
@iftex
@@ -3131,9 +3131,9 @@
@smallexample
@group
-shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu create -sscope
--subtree ou=users,o=org -r ATHENA.MIT.EDU
- at b{Password for "cn=admin,o=org":}
+shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu create -sscope 2
+-subtree ou=users,dc=example,dc=com -r ATHENA.MIT.EDU
+ at b{Password for "cn=admin,dc=example,dc=com":}
@b{Initializing database for realm 'ATHENA.MIT.EDU'}
@b{You will be prompted for the database Master Password.}
@b{It is important that you NOT FORGET this password.}
@@ -3159,9 +3159,9 @@
@smallexample
@group
-shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu create -sscope
--subtree ou=users,o=org -kdcdn cn=krbkdc,o=org -admindn cn=krbadmin,o=org -r ATHENA.MIT.EDU
- at b{Password for "cn=admin,o=org":}
+shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu create -sscope 2
+-subtree ou=users,dc=example,dc=com -kdcdn cn=krbkdc,dc=example,dc=com -admindn cn=krbadmin,dc=example,dc=com -r ATHENA.MIT.EDU
+ at b{Password for "cn=admin,dc=example,dc=com":}
@b{Initializing database for realm 'ATHENA.MIT.EDU'}
@b{You will be prompted for the database Master Password.}
@b{It is important that you NOT FORGET this password.}
@@ -3256,9 +3256,9 @@
For example:
@smallexample
@group
-shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu
+shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu
modify -r ATHENA.MIT.EDU +requires_preauth
- at b{Password for "cn=admin,o=org":}
+ at b{Password for "cn=admin,dc=example,dc=com":}
shell%
@end group
@end smallexample
@@ -3306,11 +3306,11 @@
For example:
@smallexample
@group
-shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu view -r ATHENA.MIT.EDU
- at b{Password for "cn=admin,o=org":}
+shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu view -r ATHENA.MIT.EDU
+ at b{Password for "cn=admin,dc=example,dc=com":}
@b{Realm Name: ATHENA.MIT.EDU}
- at b{Subtree: ou=users,o=org}
- at b{Subtree: ou=servers,o=org}
+ at b{Subtree: ou=users,dc=example,dc=com}
+ at b{Subtree: ou=servers,dc=example,dc=com}
@b{SearchScope: ONE}
@b{Maximum ticket life: 0 days 01:00:00}
@b{Maximum renewable life: 0 days 10:00:00}
@@ -3339,8 +3339,8 @@
For example:
@smallexample
@group
-shell% kdb5_ldap_util -D cn=admin,o=org -H ldap-server1.mit.edu destroy -r ATHENA.MIT.EDU
- at b{Password for "cn=admin,o=org":}
+shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldap-server1.mit.edu destroy -r ATHENA.MIT.EDU
+ at b{Password for "cn=admin,dc=example,dc=com":}
@b{Deleting KDC database of 'ATHENA.MIT.EDU', are you sure?}
@b{type 'yes' to confirm)? Yes}
@b{OK, deleting database of 'ATHENA.MIT.EDU'...}
@@ -3359,8 +3359,8 @@
For example:
@smallexample
@group
-shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu list
- at b{Password for "cn=admin,o=org":}
+shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu list
+ at b{Password for "cn=admin,dc=example,dc=com":}
@b{ATHENA.MIT.EDU}
@b{OPENLDAP.MIT.EDU}
@b{MEDIA-LAB.MIT.EDU}
@@ -3387,9 +3387,9 @@
For example:
@smallexample
@group
-shell% kdb5_ldap_util stashsrvpw -f /home/andrew/conf_keyle cn=service-kdc,o=org
- at b{Password for "cn=service-kdc,o=org"}:
- at b{Re-enter password for "cn=service-kdc,o=org"}:
+shell% kdb5_ldap_util stashsrvpw -f /home/andrew/conf_keyle cn=service-kdc,dc=example,dc=com
+ at b{Password for "cn=service-kdc,dc=example,dc=com"}:
+ at b{Re-enter password for "cn=service-kdc,dc=example,dc=com"}:
shell%
@end group
@end smallexample
@@ -3488,9 +3488,9 @@
For example:
@smallexample
@group
-shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu create_policy
+shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu create_policy
-r ATHENA.MIT.EDU -maxtktlife "1 day" -maxrenewlife "1 week" -allow_forwardable usertktpolicy
- at b{Password for "cn=admin,o=org":}
+ at b{Password for "cn=admin,dc=example,dc=com":}
shell%
@end group
@end smallexample
@@ -3513,9 +3513,9 @@
For example:
@smallexample
@group
-shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu view_policy
+shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu view_policy
-r ATHENA.MIT.EDU usertktpolicy
- at b{Password for "cn=admin,o=org":}
+ at b{Password for "cn=admin,dc=example,dc=com":}
@b{Ticket policy: usertktpolicy}
@b{Maxmum ticket life: 0 days 01:00:00}
@b{Maxmum renewable life: 0 days 10:00:00}
@@ -3548,9 +3548,9 @@
For example:
@smallexample
@group
-shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu
+shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu
destroy_policy -r ATHENA.MIT.EDU usertktpolicy
- at b{Password for "cn=admin,o=org":}
+ at b{Password for "cn=admin,dc=example,dc=com":}
@b{This will delete the policy object 'usertktpolicy', are you sure?}
@b{(type 'yes' to confirm)? Yes}
@b{** policy object 'usertktpolicy' deleted.}
@@ -3577,8 +3577,8 @@
For example:
@smallexample
@group
-shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu list_policy -r ATHENA.MIT.EDU
- at b{Password for "cn=admin,o=org":}
+shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu list_policy -r ATHENA.MIT.EDU
+ at b{Password for "cn=admin,dc=example,dc=com":}
@b{usertktpolicy}
@b{tempusertktpolicy}
@b{krbtktpolicy}
@@ -3628,9 +3628,9 @@
For example:
@smallexample
@group
-shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu
-create_service -kdc -randpw -f /home/andrew/service_passwd cn=service-kdc,o=org
- at b{Password for "cn=admin,o=org":}
+shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu
+create_service -kdc -randpw -f /home/andrew/service_passwd cn=service-kdc,dc=example,dc=com
+ at b{Password for "cn=admin,dc=example,dc=com":}
@b{File does not exist. Creating the file /home/andrew/service_passwd...}
shell%
@end group
@@ -3674,9 +3674,9 @@
@smallexample
@group
-shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu
-modify_service -realm ATHENA.MIT.EDU cn=service-kdc,o=org
- at b{Password for "cn=admin,o=org":}
+shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu
+modify_service -realm ATHENA.MIT.EDU cn=service-kdc,dc=example,dc=com
+ at b{Password for "cn=admin,dc=example,dc=com":}
@b{Changing rights for the service object. Please wait ... done}
shell%
@end group
@@ -3695,13 +3695,13 @@
For example:
@smallexample
@group
-shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu
-view_service cn=service-kdc,o=org
- at b{Password for "cn=admin,o=org":}
- at b{Service dn: cn=service-kdc,o=org}
+shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu
+view_service cn=service-kdc,dc=example,dc=com
+ at b{Password for "cn=admin,dc=example,dc=com":}
+ at b{Service dn: cn=service-kdc,dc=example,dc=com}
@b{Service type: kdc}
@b{Service host list:}
- at b{Realm DN list: cn=ATHENA.MIT.EDU,cn=Kerberos,o=org}
+ at b{Realm DN list: cn=ATHENA.MIT.EDU,cn=Kerberos,dc=example,dc=com}
shell%
@end group
@end smallexample
@@ -3726,12 +3726,12 @@
For example:
@smallexample
@group
-shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu
-destroy_service cn=service-kdc,o=org
- at b{Password for "cn=admin,o=org":}
- at b{This will delete the service object 'cn=service-kdc,o=org', are you sure?}
+shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu
+destroy_service cn=service-kdc,dc=example,dc=com
+ at b{Password for "cn=admin,dc=example,dc=com":}
+ at b{This will delete the service object 'cn=service-kdc,dc=example,dc=com', are you sure?}
@b{(type 'yes' to confirm)? Yes}
- at b{** service object 'cn=service-kdc,o=org' deleted.}
+ at b{** service object 'cn=service-kdc,dc=example,dc=com' deleted.}
shell%
@end group
@end smallexample
@@ -3751,11 +3751,11 @@
For example:
@smallexample
@group
-shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu list_service
- at b{Password for "cn=admin,o=org":}
- at b{cn=service-kdc,o=org}
- at b{cn=service-adm,o=org}
- at b{cn=service-pwd,o=org}
+shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu list_service
+ at b{Password for "cn=admin,dc=example,dc=com":}
+ at b{cn=service-kdc,dc=example,dc=com}
+ at b{cn=service-adm,dc=example,dc=com}
+ at b{cn=service-pwd,dc=example,dc=com}
shell%
@end group
@end smallexample
@@ -3786,11 +3786,11 @@
@smallexample
@group
-shell% kdb5_ldap_util setsrvpw -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu
-setsrvpw -f /home/andrew/conf_keyfile cn=service-kdc,o=org
- at b{Password for "cn=admin,o=org":}
- at b{Password for "cn=service-kdc,o=org":}
- at b{Re-enter password for "cn=service-kdc,o=org":}
+shell% kdb5_ldap_util setsrvpw -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu
+setsrvpw -f /home/andrew/conf_keyfile cn=service-kdc,dc=example,dc=com
+ at b{Password for "cn=admin,dc=example,dc=com":}
+ at b{Password for "cn=service-kdc,dc=example,dc=com":}
+ at b{Re-enter password for "cn=service-kdc,dc=example,dc=com":}
shell%
@end group
@end smallexample
@@ -3924,9 +3924,25 @@
@end smallexample
@item
-Configure the LDAP server ACLs to enable the KDC and Admin server to
-read and write the Kerberos data.
+Choose DNs for the KDC and kadmin servers to bind to the LDAP server,
+and create them if necessary. These DNs will be specified with the
+ at code{ldap_kdc_dn} and @code{ldap_kadmind_dn} directives in krb5.conf;
+their passwords can be stashed with @code{kdb5_ldap_util stashsrvpw}
+and the resulting file specified with the
+ at code{ldap_service_password_file} directive.
+ at item
+Choose a DN for the global Kerberos container entry (but do not create
+the entry at this time). This DN will be specified with the
+ at code{ldap_kerberos_container_dn} directive in krb5.conf. Realm
+container entries will be created underneath this DN. Principal
+entries may exist either underneath the realm container (the default)
+or in separate trees referenced from the realm container.
+
+ at item
+Configure the LDAP server ACLs to enable the KDC and kadmin server DNs
+to read and write the Kerberos data.
+
@subheading
Sample access control information
@@ -3945,16 +3961,16 @@
by self write
by * read
-# Providing access to realm subtree
-access to @code{dn.subtree}= @i{"o=mit"}
- by @code{dn.exact}=@i{"cn=kdc-service,o=mit"} read
- by @code{dn.exact}=@i{"cn=adm-service,o=mit"} write
+# Providing access to realm container
+access to @code{dn.subtree}= @i{"cn=EXAMPLE.COM,cn=krbcontainer,dc=example,dc=com"}
+ by @code{dn.exact}=@i{"cn=kdc-service,dc=example,dc=com"} read
+ by @code{dn.exact}=@i{"cn=adm-service,dc=example,dc=com"} write
by * none
-# Providing access to realm container
-access to @code{dn.subtree}= @i{"cn=MIT.EDU,cn=Kerberos,o=mit"}
- by @code{dn.exact}=@i{"cn=kdc-service,o=mit"} read
- by @code{dn.exact}=@i{"cn=adm-service,o=mit"} write
+# Providing access to principals, if not underneath realm container
+access to @code{dn.subtree}= @i{"ou=users,dc=example,dc=com"}
+ by @code{dn.exact}=@i{"cn=kdc-service,dc=example,dc=com"} read
+ by @code{dn.exact}=@i{"cn=adm-service,dc=example,dc=com"} write
by * none
access to *
@@ -3962,10 +3978,9 @@
@end smallexample
@noindent
-The above list provides the access control information for the KDC and
-Admin service object for the realm container and the realm
-subtree. Thus if the realm subtree or the service objects for a realm
-are changed then this information should be updated.
+If the locations of the container and principals or the DNs of the
+service objects for a realm are changed then this information should
+be updated.
@item
Start the LDAP server as follows:
@@ -3998,11 +4013,11 @@
Create the realm using @samp{kdb5_ldap_util}.
@smallexample
- at b{kdb5_ldap_util} @b{-D} @i{ cn=admin,o=mit} create @b{-subtrees} @i{ o=mit} @b{-r} @i{MIT.EDU} @b{-s}
+ at b{kdb5_ldap_util} @b{-D} @i{cn=admin,dc=example,dc=com} create @b{-subtrees} @i{ou=users,dc=example,dc=com} @b{-r} @i{EXAMPLE.COM} @b{-s}
@end smallexample
@noindent
-Before executing the command, make sure that the subtree mentioned above @samp{(o=mit)} exists.
+Use the @code{-subtrees} option if the principals are to exist in a separate subtree from the realm container. Before executing the command, make sure that the subtree mentioned above @samp{(ou=users,dc=example,dc=com)} exists. If the principals will exist underneath the realm container, omit the @code{-subtrees} option and do not worry about creating the principal subtree.
For more information, refer to the section @dfn{Global Operations on the Kerberos LDAP Database}.
@@ -4017,7 +4032,7 @@
file.
@smallexample
- at b{kdb5_ldap_util} @b{-D} @i{ cn=admin,o=mit} @i{stashsrvpw} @b{-f} @code{/etc/kerberos/service.keyfile} @i{cn=krbadmin,o=mit}
+ at b{kdb5_ldap_util} @b{-D} @i{cn=admin,dc=example,dc=com} @i{stashsrvpw} @b{-f} @code{/etc/kerberos/service.keyfile} @i{cn=krbadmin,dc=example,dc=com}
@end smallexample
@item
More information about the cvs-krb5
mailing list