Revise RST install guide client configuration
authorGreg Hudson <ghudson@mit.edu>
Fri, 16 Mar 2012 13:57:05 +0000 (13:57 +0000)
committerGreg Hudson <ghudson@mit.edu>
Fri, 16 Mar 2012 13:57:05 +0000 (13:57 +0000)
Stop recommending login.krb5.  Remove outdated OSX instructions.
Don't suggest modifying /etc/services as we don't rely on it any more
(and it's generally already done by the OS these days).  Add new
guidance for krb5.conf settings.

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25772 dc483132-0cff-0310-8789-dd5450dbe970

doc/rst_source/krb_admins/install_clients.rst

index f1aa3788f3c455ed5c5d59369a04f18c6ec352a6..4d954a246735490f5ec8b535b279acfa3b63e6db 100644 (file)
@@ -1,98 +1,57 @@
 Installing and configuring UNIX client machines
 ===============================================
 
-The Kerberized client programs are :ref:`kinit(1)`, :ref:`klist(1)`,
-:ref:`kdestroy(1)`, :ref:`kpasswd(1)`, and :ref:`ksu(1)`.  All of
-these programs are in the directory ``/usr/local/bin``.  MIT
-recommends that you use login.krb5 in place of ``/bin/login`` to give
-your users a single-sign-on system. You will need to make sure your
-users know to use their Kerberos passwords when they log in.
+The Kerberized client programs include :ref:`kinit(1)`,
+:ref:`klist(1)`, :ref:`kdestroy(1)`, and :ref:`kpasswd(1)`.  All of
+these programs are in the directory ``/usr/local/bin``.
+
+You can often integrate Kerberos with the login system on client
+machines, typically through the use of PAM.  The details vary by
+operating system, and should be covered in your operating system's
+documentation.  If you do this, you will need to make sure your users
+know to use their Kerberos passwords when they log in.
 
 You will also need to educate your users to use the ticket management
-programs kinit, klist, kdestroy, and to use the Kerberos programs ksu
-and kpasswd in place of their non-Kerberos counterparts su and passwd.
+programs kinit, klist, and kdestroy.  If you do not have Kerberos
+password changing integrated into the native password program (again,
+typically through PAM), you will need to educate users to use kpasswd
+in place of its non-Kerberos counterparts passwd.
 
 
 Client machine configuration files
 ----------------------------------
 
-Each machine running Kerberos must have a :ref:`krb5.conf(5)` file.
-
-Also, for most UNIX systems, you must add the appropriate Kerberos
-services to each client machine's ``/etc/services`` file.  If you are
-using the default configuration for Kerberos V5, you should be able to
-just insert the following code::
-
-    kerberos      88/udp    kdc    # Kerberos V5 KDC
-    kerberos      88/tcp    kdc    # Kerberos V5 KDC
-    kerberos-adm  749/tcp          # Kerberos 5 admin/changepw
-    kerberos-adm  749/udp          # Kerberos 5 admin/changepw
-    krb5_prop     754/tcp          # Kerberos slave propagation
-    krb524        4444/tcp         # Kerberos 5 to 4 ticket translator
-
-
-Mac OS X configuration
-----------------------
-
-To install Kerberos V5 on Mac OS X and Mac OS X Server, follow the
-directions for generic Unix-based OS's, except for the
-``/etc/services`` updates described above.
-
-Mac OS X and Mac OS X Server use a database called NetInfo to store
-the contents of files normally found in ``/etc``.  Instead of
-modifying ``/etc/services``, you should run the following commands to
-add the Kerberos service entries to NetInfo::
-
-    $ niutil -create . /services/kerberos
-    $ niutil -createprop . /services/kerberos name kerberos kdc
-    $ niutil -createprop . /services/kerberos port 750
-    $ niutil -createprop . /services/kerberos protocol tcp udp
-    $ niutil -create . /services/krbupdate
-    $ niutil -createprop . /services/krbupdate name krbupdate kreg
-    $ niutil -createprop . /services/krbupdate port 760
-    $ niutil -createprop . /services/krbupdate protocol tcp
-    $ niutil -create . /services/kpasswd
-    $ niutil -createprop . /services/kpasswd name kpasswd kpwd
-    $ niutil -createprop . /services/kpasswd port 761
-    $ niutil -createprop . /services/kpasswd protocol tcp
-    $ niutil -create . /services/klogin
-    $ niutil -createprop . /services/klogin port 543
-    $ niutil -createprop . /services/klogin protocol tcp
-    $ niutil -create . /services/eklogin
-    $ niutil -createprop . /services/eklogin port 2105
-    $ niutil -createprop . /services/eklogin protocol tcp
-    $ niutil -create . /services/kshell
-    $ niutil -createprop . /services/kshell name kshell krcmd
-    $ niutil -createprop . /services/kshell port 544
-    $ niutil -createprop . /services/kshell protocol tcp
-
-In addition to adding services to NetInfo, you must also modify the
-resolver configuration in NetInfo so that the machine resolves its own
-hostname as a FQDN (fully qualified domain name).  By default, Mac OS
-X and Mac OS X Server machines query NetInfo to resolve hostnames
-before falling back to DNS.  Because NetInfo has an unqualified name
-for all the machines in the NetInfo database, the machine's own
-hostname will resolve to an unqualified name.  Kerberos needs a FQDN
-to look up keys in the machine's keytab file.
-
-Fortunately, you can change the lookupd caching order to query DNS
-first.  Run the following NetInfo commands and reboot the machine::
-
-    $ niutil -create . /locations/lookupd/hosts
-    $ niutil -createprop . /locations/lookupd/hosts LookupOrder CacheAgent DNSAgent NIAgent NILAgent
-
-Once you have rebooted, you can verify that the resolver now behaves
-correctly.  Compile the Kerberos 5 distribution and run::
-
-    $ cd .../src/tests/resolve
-    $ ./resolve
-
-This will tell you whether or not your machine returns FQDNs on name
-lookups.  If the test still fails, you can also try turning off DNS
-caching.  Run the following commands and reboot::
-
-    $ niutil -create . /locations/lookupd/hosts
-    $ niutil -createprop . /locations/lookupd/hosts LookupOrder DNSAgent CacheAgent NIAgent NILAgent
-
-The remainder of the setup of a Mac OS X client machine or application
-server should be the same as for other UNIX-based systems.
+Each machine running Kerberos should have a :ref:`krb5.conf(5)` file.
+At a minimum, it should define a **default_realm** setting in
+:ref:`libdefaults`.  If you are not using DNS SRV records, it must
+also contain a :ref:`realms` section containing information for your
+realm's KDCs.
+
+Consider setting **rdns** to false in order to reduce your dependence
+on precisely correct DNS information for service hostnames.  Turning
+this flag off means that service hostnames will be canonicalized
+through forward name resolution (which adds your domain name to
+unqualified hostnames, and resolves CNAME records in DNS), but not
+through reverse address lookup.  The default value of this flag is
+true for historical reasons only.
+
+If you anticipate users frequently logging into remote hosts
+(e.g. using ssh) using forwardable credentials, consider setting
+**forwardable** to true so that users obtain forwardable tickets by
+default.  Otherwise users will need to use ``kinit -f`` to get
+forwardable tickets.
+
+Consider adjusting the **ticket_lifetime** setting to match the likely
+length of sessions for your users.  For instance, if most of your
+users will be logging in for an eight-hour workday, you could set the
+default to ten hours so that tickets obtained in the morning expire
+shortly after the end of the workday.  Users can still manually
+request longer tickets when necessary, up to the maximum allowed by
+each user's principal record on the KDC.
+
+If a client host may access services in different realms, it may be
+useful to define a :ref:`domain_realm` mapping so that clients know
+which hosts belong to which realms.  However, if your clients and KDC
+are running release 1.7 or later, it is also reasonable to leave this
+section out on client machines and just define it in the KDC's
+krb5.conf.