Note that a machine can be both a client machine and an applicationserver.Chapter five describes procedure for updating previous installations ofKerberos V5.Chapter six describes our problem reporting system.Node:Realm Configuration Decisions,Next:Building Kerberos V5,Previous:Introduction,Up:TopRealm Configuration DecisionsBefore installing Kerberos V5, it is necessary to consider thefollowing issues:The name of your Kerberos realm (or the name of each realm, if you needmore than one).How you will map your hostnames onto Kerberos realms.Which ports your KDC and and kadmin (database access) services will use.How many slave KDCs you need and where they should be located.The hostnames of your master and slave KDCs.How frequently you will propagate the database from the master KDC tothe slave KDCs.Whether you need backward compatibility with Kerberos V4. Kerberos Realms: Mapping Hostnames onto Kerberos Realms: Ports for the KDC and Admin Services: Slave KDCs: Hostnames for the Master and Slave KDCs: Database Propagation: Node:Kerberos Realms,Next:Mapping Hostnames onto Kerberos Realms,Previous:Realm Configuration Decisions,Up:Realm Configuration DecisionsKerberos RealmsAlthough your Kerberos realm can be any ASCII string, convention is tomake it the same as your domain name, in upper-case letters. Forexample, hosts in the domain example.com would be in theKerberos realm EXAMPLE.COM.If you need multiple Kerberos realms, MIT recommends thatyou use descriptive names which end with your domain name, such asBOSTON.EXAMPLE.COM and HOUSTON.EXAMPLE.COM.Node:Mapping Hostnames onto Kerberos Realms,Next:Ports for the KDC and Admin Services,Previous:Kerberos Realms,Up:Realm Configuration DecisionsMapping Hostnames onto Kerberos RealmsMapping hostnames onto Kerberos realms is done in one of two ways.The first mechanism, which has been in use for years in MIT-basedKerberos distributions, works through a set of rules inthe krb5.conf configuration file. (See krb5.conf.) You canspecify mappings for an entire domain or subdomain, and/or on ahostname-by-hostname basis. Since greater specificity takes precedence,you would do this by specifying the mappings for a given domain orsubdomain and listing the exceptions.The second mechanism works by looking up the information in specialTXT records in the Domain Name Service. This is currently notused by default because security holes could result if the DNS TXTrecords were spoofed. If this mechanism is enabled on the client,it will try to look up a TXT record for the DNS name formed byputting the prefix _kerberos in front of the hostname in question. If that record is not found, it will try using _kerberos and thehost's domain name, then its parent domain, and so forth. So for thehostname BOSTON.ENGINEERING.FOOBAR.COM, the names looked up would be:_kerberos.boston.engineering.foobar.com_kerberos.engineering.foobar.com_kerberos.foobar.com_kerberos.comThe value of the first TXT record found is taken as the realm name. (Obviously, this doesn't work all that well if a host and a subdomainhave the same name, and different realms. For example, if all the hostsin the ENGINEERING.FOOBAR.COM domain are in the ENGINEERING.FOOBAR.COMrealm, but a host named ENGINEERING.FOOBAR.COM is for some reason inanother realm. In that case, you would set up TXT records for allhosts, rather than relying on the fallback to the domain name.)Even if you do not choose to use this mechanism within your site, youmay wish to set it up anyway, for use when interacting with other sites.Node:Ports for the KDC and Admin Services,Next:Slave KDCs,Previous:Mapping Hostnames onto Kerberos Realms,Up:Realm Configuration DecisionsPorts for the KDC and Admin ServicesThe default ports used by Kerberos are port 88 for theKDC1 andport 749 for the admin server. You can, however,choose to run on other ports, as long as they are specified in eachhost's /etc/services and krb5.conf files, and thekdc.conf file on each KDC. For a more thorough treatment ofport numbers used by the Kerberos V5 programs, refer to the"Configuring Your Firewall to Work With Kerberos V5" section ofthe Kerberos V5 System Administrator's Guide.Node:Slave KDCs,Next:Hostnames for the Master and Slave KDCs,Previous:Ports for the KDC and Admin Services,Up:Realm Configuration DecisionsSlave KDCsSlave KDCs provide an additional source of Kerberos ticket-grantingservices in the event of inaccessibility of the master KDC. The numberof slave KDCs you need and the decision of where to place them, bothphysically and logically, depends on the specifics of your network.All of the Kerberos authentication on your network requires that eachclient be able to contact a KDC. Therefore, you need to anticipate anylikely reason a KDC might be unavailable and have a slave KDC to take upthe slack.Some considerations include:Have at least one slave KDC as a backup, for when the master KDC isdown, is being upgraded, or is otherwise unavailable.If your network is split such that a network outage is likely to cause anetwork partition (some segment or segments of the network to become cutoff or isolated from other segments), have a slave KDC accessible toeach segment.If possible, have at least one slave KDC in a different building fromthe master, in case of power outages, fires, or other localizeddisasters. Node:Hostnames for the Master and Slave KDCs,Next:Database Propagation,Previous:Slave KDCs,Up:Realm Configuration DecisionsHostnames for the Master and Slave KDCsMIT recommends that your KDCs have a predefined set ofCNAME records (DNS hostname aliases), such as kerberosfor the master KDC andkerberos-1, kerberos-2, ... for theslave KDCs. This way, if you need to swap a machine, you only need tochange a DNS entry, rather than having to change hostnames.A new mechanism for locating KDCs of a realm through DNS has been addedto the MIT Kerberos V5 distribution. A relatively newrecord type called SRV has been added to DNS. Looked up by aservice name and a domain name, these records indicate the hostname andport number to contact for that service, optionally with weighting andprioritization. (See RFC 2782 if you want more information. You canfollow the example below for straightforward cases.)The use with Kerberos is fairly straightforward. The domain name usedin the SRV record name is the domain-style Kerberos realm name. (It ispossible to have Kerberos realm names that are not DNS-style names, butwe don't recommend it for Internet use, and our code does not support itwell.) Several different Kerberos-related service names are used:_kerberos._udpThis is for contacting any KDC by UDP. This entry will be used the mostoften. Normally you should list port 88 on each of your KDCs._kerberos._tcpThis is for contacting any KDC by TCP. The MIT KDC by default will notlisten on any TCP ports, so unless you've changed the configuration oryou're running another KDC implementation, you should leave thisunspecified. If you do enable TCP support, normally you should useport 88._kerberos-master._udpThis entry should refer to those KDCs, if any, that will immediately seepassword changes to the Kerberos database. This entry is used only inone case, when the user is logging in and the password appears to beincorrect; the master KDC is then contacted, and the same password usedto try to decrypt the response, in case the user's password had recentlybeen changed and the first KDC contacted hadn't been updated. Only ifthat fails is an "incorrect password" error given.If you have only one KDC, or for whatever reason there is no accessibleKDC that would get database changes faster than the others, you do notneed to define this entry._kerberos-adm._tcpThis should list port 749 on your master KDC. Support for it is not complete at this time, but it will eventually beused by the kadmin program and related utilities. For now, youwill also need the admin_server entry in krb5.conf. (See krb5.conf.)_kpasswd._udpThis should list port 464 on your master KDC. It is used when a user changes her password._kerberos-iv._udpThis should refer to your KDCs that serve Kerberos version 4 requests,if you have Kerberos v4 enabled.Be aware, however, that the DNS SRV specification requires that thehostnames listed be the canonical names, not aliases. So, for example,you might include the following records in your (BIND-style) zone file:$ORIGIN foobar.com._kerberos TXT "FOOBAR.COM"kerberos CNAME daisykerberos-1 CNAME use-the-force-lukekerberos-2 CNAME bunny-rabbit_kerberos._udp SRV 0 0 88 daisy SRV 0 0 88 use-the-force-luke SRV 0 0 88 bunny-rabbit_kerberos-master._udp SRV 0 0 88 daisy_kerberos-adm._tcp SRV 0 0 749 daisy_kpasswd._udp SRV 0 0 464 daisyAs with the DNS-based mechanism for determining the Kerberos realm of ahost, we recommend distributing the information this way for use byother sites that may want to interact with yours using Kerberos, even ifyou don't immediately make use of it within your own site. If youanticipate installing a very large number of machines on which it willbe hard to update the Kerberos configuration files, you may wish to doall of your Kerberos service lookups via DNS and not put the information(except for admin_server as noted above) in future versions ofyour krb5.conf files at all. Eventually, we hope to phase outthe listing of server hostnames in the client-side configuration files;making preparations now will make the transition easier in the future.Node:Database Propagation,Previous:Hostnames for the Master and Slave KDCs,Up:Realm Configuration DecisionsDatabase PropagationThe Kerberos database resides on the master KDC, and must be propagatedregularly (usually by a cron job) to the slave KDCs. In deciding howfrequently the propagation should happen, you will need to balance theamount of time the propagation takes against the maximum reasonableamount of time a user should have to wait for a password change to takeeffect.If the propagation time is longer than this maximum reasonable time(e.g., you have a particularly large database, you have a lot ofslaves, or you experience frequent network delays), you may wish tocut down on your propagation delay by performing the propagation inparallel. To do this, have the master KDC propagate the database to oneset of slaves, and then have each of these slaves propagate the databaseto additional slaves.Node:Building Kerberos V5,Next:Installing Kerberos V5,Previous:Realm Configuration Decisions,Up:TopBuilding Kerberos V5Kerberos V5 uses a configuration system built using the FreeSoftware Foundation's autoconf program. This system makesKerberos V5 much simpler to build and reduces the amount of effortrequired in porting Kerberos V5 to a new platform.Organization of the Source Directory: Description of the source tree. Build Requirements: How much disk space, etc. you need to build Kerberos. Unpacking the Sources: Preparing the source tree. Doing the Build: Compiling Kerberos. Installing the Binaries: Installing the compiled binaries. Testing the Build: Making sure Kerberos built correctly. Options to Configure: Command-line options to Configureosconf.h: Header file-specific configurationsShared Library Support: Building Shared Libraries for Kerberos V5OS Incompatibilities: Special cases to watch for. Using Autoconf: Modifying Kerberos V5's configuration scripts. Node:Organization of the Source Directory,Next:Build Requirements,Previous:Building Kerberos V5,Up:Building Kerberos V5Organization of the Source DirectoryBelow is a brief overview of the organization of the complete sourcedirectory. More detailed descriptions follow.applapplications with Kerberos V5 extensionsclientsKerberos V5 user programsgen-manpagesmanpages for Kerberos V5 and the Kerberos V5 login programincludeinclude fileskadminadministrative interface to the Kerberos master databasekdcthe Kerberos V5 Authentication Service and Key Distribution Centerkrb524utilities for converting between Kerberos 4 and Kerberos 5liblibraries for use with/by Kerberos V5macsource code for building Kerberos V5 on MacOSprototypetemplates for source code filesslaveutilities for propagating the database to slave KDCsteststest suiteutilvarious utilities for building/configuring the code, sending bug reports, etc. windowssource code for building Kerberos V5 on Windows (see windows/README)The appl Directory: The clients Directory: The gen-manpages Directory: The include Directory: The kadmin Directory: The kdc Directory: The krb524 Directory: The lib Directory: The prototype Directory: The slave Directory: The util Directory: Node:The appl Directory,Next:The clients Directory,Previous:Organization of the Source Directory,Up:Organization of the Source DirectoryThe appl DirectoryThe Kerberos release provides certain UNIX utilities, modified to useKerberos authentication. In the appl/bsd directory are theBerkeley utilities login, rlogin, rsh, and rcp, as well asthe associated daemons kshd and klogind. The login programobtains ticket-granting tickets for users upon login; the other utilitiesprovide authenticated Unix network services.The appl directory also contains Kerberized telnet and ftp programs,as well as sample Kerberos application client and server programs.Node:The clients Directory,Next:The gen-manpages Directory,Previous:The appl Directory,Up:Organization of the Source DirectoryThe clients DirectoryThis directory contains the code for several user-oriented programs.kdestroyThis program destroys the user's active Kerberos authorization tickets. MIT recommends that users kdestroy before logging out.kinitThis program prompts users for their Kerberos principal name and password,and attempts to get an initial ticket-granting-ticket for that principal.klistThis program lists the Kerberos principal and Kerberos tickets held ina credentials cache, or the keys held in a keytab file.kpasswdThis program changes a user's Kerberos password.ksuThis program is a Kerberized version of the su program that ismeant to securely change the real and effective user ID to that of thetarget user and to create a new security context.kvnoThis program acquires a service ticket for the specified Kerberosprincipals and prints out the key version numbers of each. Node:The gen-manpages Directory,Next:The include Directory,Previous:The clients Directory,Up:Organization of the Source DirectoryThe gen-manpages DirectoryThere are two manual pages in this directory. One is an introductionto the Kerberos system. The other describes the .k5login filewhich allows users to give access with their UID to other usersauthenticated by the Kerberos system.Node:The include Directory,Next:The kadmin Directory,Previous:The gen-manpages Directory,Up:Organization of the Source DirectoryThe include DirectoryThis directory contains the include files needed to build theKerberos system.Node:The kadmin Directory,Next:The kdc Directory,Previous:The include Directory,Up:Organization of the Source DirectoryThe kadmin DirectoryIn this directory is the code for the utilities kadmin,kadmin.local, kdb5_util, and ktutil. ktutil is the Kerberos keytab file maintenance utility fromwhich a Kerberos administrator can read, write, or edit entries in aKerberos V5 keytab or Kerberos V4 srvtab. kadmin andkadmin.local are command-line interfaces to the Kerberos V5 KADM5administration system. kadmin.local runs on the master KDC anddoes not use Kerberos to authenticate to the database, whilekadmin uses Kerberos authentication and an encrypted RPC. Thetwo provide identical functionalities, which allow administrators tomodify the database of Kerberos principals. kdb5_util allowsadministrators to perform low-level maintenance procedures on Kerberosand the KADM5 database. With this utility, databases can be created,destroyed, or dumped to and loaded from ASCII files. It can also beused to create master key stash files.Node:The kdc Directory,Next:The krb524 Directory,Previous:The kadmin Directory,Up:Organization of the Source DirectoryThe kdc DirectoryThis directory contains the code for the krb5kdc daemon, theKerberos Authentication Service and Key Distribution Center.Node:The krb524 Directory,Next:The lib Directory,Previous:The kdc Directory,Up:Organization of the Source DirectoryThe krb524 DirectoryThis directory contains the code for krb524, a service thatconverts Kerberos V5 credentials into Kerberos V4 credentials suitablefor use with applications that for whatever reason do not use V5directly.Node:The lib Directory,Next:The prototype Directory,Previous:The krb524 Directory,Up:Organization of the Source DirectoryThe lib DirectoryThe lib directory contain 10 subdirectories as well as somedefinition and glue files. The crypto subdirectory contains theKerberos V5 encryption library. The des425 subdirectory exportsthe Kerberos V4 encryption API, and translates these functions intocalls to the Kerberos V5 encryption API. The gssapi librarycontains the Generic Security Services API, which is a library ofcommands to be used in secure client-server communication. Thekadm5 directory contains the libraries for the KADM5 administrationutilities. The Kerberos 5 database libraries are contained inkdb. The directories krb4 and krb5 contain the Kerberos 4and Kerberos 5 APIs, respectively. The rpc directory contains theAPI for the Kerberos Remote Procedure Call protocol.Node:The prototype Directory,Next:The slave Directory,Previous:The lib Directory,Up:Organization of the Source DirectoryThe prototype DirectoryThis directory contains several template files. The prototype.hand prototype.c files contain the MIT copyright message and aplaceholder for the title and description of the file. prototype.h also has a short template for writing ifdefand ifndef preprocessor statements. The getopt.c fileprovides a template for writing code that will parse the options withwhich a program was called.Node:The slave Directory,Next:The util Directory,Previous:The prototype Directory,Up:Organization of the Source DirectoryThe slave DirectoryThis directory contains code which allows for the propagation of theKerberos principal database from the master KDC to slave KDCs over anencrypted, secure channel. kprop is the program which actuallypropagates the database dump file. kpropd is the Kerberos V5slave KDC update server which accepts connections from the kpropprogram. kslave_update is a script that takes the name of aslave server, and propagates the database to that server if thedatabase has been modified since the last dump or if the database hasbeen dumped since the last propagation.Node:The util Directory,Previous:The slave Directory,Up:Organization of the Source DirectoryThe util DirectoryThis directory contains several utility programs and libraries. Theprograms used to configure and build the code, such as autoconf,lndir, kbuild, reconf, and makedepend,are in this directory. The profile directory contains most of thefunctions which parse the Kerberos configuration files (krb5.confand kdc.conf). Also in this directory are the Kerberos error tablelibrary and utilities (et), the Sub-system library and utilities(ss), database utilities (db2), pseudo-terminal utilities(pty), and bug-reporting program send-pr.Node:Build Requirements,Next:Unpacking the Sources,Previous:Organization of the Source Directory,Up:Building Kerberos V5Build RequirementsIn order to build Kerberos V5, you will need approximately 60-70megabytes of disk space. The exact amount will vary depending on theplatform and whether the distribution is compiled with debugging symboltables or not.Your C compiler must conform to ANSI C (ISO/IEC 9899:1990, "c89"). Some operating systems do not have an ANSI C compiler, or theirdefault compiler requires extra command-line options to enable ANSI Cconformance.If you wish to keep a separate build tree, which contains the compiled*.o file and executables, separate from your source tree, youwill need a make program which supports VPATH, oryou will need to use a tool such as lndir to produce a symboliclink tree for your build tree.Node:Unpacking the Sources,Next:Doing the Build,Previous:Build Requirements,Up:Building Kerberos V5Unpacking the SourcesThe first step in each of these build procedures is to unpack thesource distribution. The Kerberos V5 distribution comes in a tar file,generally named krb5-1.3.tar, which contains acompressed tar file consisting of the sources for all of Kerberos(generally krb5-1.3.tar.gz) and a PGP signature forthis source tree (generally krb5-1.3.tar.gz.asc). MIT highly recommends that you verify the integrity of thesource code using this signature.Unpack the compressed tar file in some directory, such as/u1/krb5-1.3. (In the rest of this document, wewill assume that you have chosen to unpack the Kerberos V5 sourcedistribution in this directory. Note that the tarfiles will by defaultall unpack into the ./krb5-1.3 directory, so that ifyour current directory is /u1 when you unpack the tarfiles, youwill get /u1/krb5-1.3/src, etc.)Node:Doing the Build,Next:Installing the Binaries,Previous:Unpacking the Sources,Up:Building Kerberos V5Doing the BuildYou have a number of different options in how to build Kerberos. If youonly need to build Kerberos for one platform, using a single directorytree which contains both the source files and the object files is thesimplest. However, if you need to maintain Kerberos for a large numberof platforms, you will probably want to use separate build trees foreach platform. We recommend that you look at OS Incompatibilities, for notes that we have on particular operatingsystems.Building Within a Single Tree: Building with Separate Build Directories: Building using lndir: Node:Building Within a Single Tree,Next:Building with Separate Build Directories,Previous:Doing the Build,Up:Doing the BuildBuilding Within a Single TreeIf you don't want separate build trees for each architecture, thenuse the following abbreviated procedure.
Slaves of the Realm download
2ff7e9595c
Comments