From f6defacaf3e5967fb89db64f16a9148e5f09b457 Mon Sep 17 00:00:00 2001 From: Theodore Tso Date: Wed, 1 Mar 1995 03:56:35 +0000 Subject: [PATCH] More improvements made. Interim checkin... git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@5036 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/install.texi | 274 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 186 insertions(+), 88 deletions(-) diff --git a/doc/install.texi b/doc/install.texi index 80fecae9f..481b2eeb7 100644 --- a/doc/install.texi +++ b/doc/install.texi @@ -119,6 +119,7 @@ This is edition @value{EDITION}, for Kerberos V5 version @value{VERSION}. * How Kerberos Works:: * Building Kerberos:: * Installation:: +* Troubleshooting:: --- The Detailed Node Listing --- @@ -127,10 +128,15 @@ How Kerberos Works: A Schematic Description * Network Services :: * Kerberos Tickets:: * The Kerberos Database:: +* Kerberos Realms:: * The Ticket-Granting Ticket:: * Network Services and the Master Database:: * The User-Kerberos Interaction:: +Network Services and the Master Database + +* The Keytab File:: + Building Kerberos * Build Requirements:: How much disk space, etc. you need to @@ -153,6 +159,7 @@ Doing the Build Operating System Incompatibilities * Ultrix 4.2/3:: +* Alpha OSF/1 V1.3:: * Alpha OSF/1 V2.0:: * BSDI:: * Solaris versions 2.0 through 2.3:: @@ -168,6 +175,7 @@ Installation * Background:: * Installation on any Machine:: * Installing the KDC:: +* Migrating from V4 to V5 Kerberos:: * A Sample Application:: * Common Kerberos Service Names:: @@ -189,6 +197,8 @@ Installing the KDC * Storing the Master Password:: * Adding Users to the Database:: * Starting the Kerberos Server:: +* Setting up Slave Kerberos Servers:: +* Inter-realm Kerberos Operation:: * The Administration Server:: * Testing the Kerberos Server:: @@ -206,15 +216,16 @@ from the source distribution, and then to install it at a particular site. The reader is assumed to be familiar with C/UNIX development tools. -In any complex software, there will be bugs. In addition, you -may find portability problems when you try to build Kerberos V5 on a -platform on which the developers yet built. Please send bug reports or other -problems you may uncover to the e-mail address @b{krb5-bugs@@mit.edu}. -Please mention which version of the Kerberos V5 distribution you are -using, and whether you have made any private changes. Bug reports that -include proposed fixes are especially welcome. If you do include fixes, -please send them using either context diffs or unified diffs (using -@samp{diff -c} or @samp{diff -u}, respectively). +In any complex software, there will be bugs. In addition, you may +find portability problems when you try to build Kerberos V5 on a +platform on which the developers yet built. Please send bug reports +or other problems you may uncover to the e-mail address +@b{krb5-bugs@@mit.edu}. Please mention which version of the Kerberos +V5 distribution you are using, and whether you have made any private +changes. Bug reports that include proposed fixes are especially +welcome. If you do include fixes, please send them using either +context diffs or unified diffs (using @samp{diff -c} or @samp{diff +-u}, respectively). Please note that there are still a number of aspects of Kerberos V5 which will likely change before the 1.0 release. In particular, the @@ -241,6 +252,7 @@ Service for Open Network Systems}, a paper presented at Winter USENIX * Network Services :: * Kerberos Tickets:: * The Kerberos Database:: +* Kerberos Realms:: * The Ticket-Granting Ticket:: * Network Services and the Master Database:: * The User-Kerberos Interaction:: @@ -254,22 +266,24 @@ programs to request service from @dfn{server} programs that are somewhere on the network. Suppose you have logged in to a workstation and you want to @samp{rlogin} to another machine. You use the local @samp{rlogin} client program to contact the remote machine's -@samp{rlogin} service daemon. +@samp{rlogind} daemon. @node Kerberos Tickets, The Kerberos Database, Network Services , How Kerberos Works @section Kerberos Tickets -Under Kerberos, the @samp{rlogin} service program allows a client to -login to a remote machine if it can provide a Kerberos @dfn{ticket} for -the request. This ticket proves the identity of the person who has used -the client program to access the server program. +Under Kerberos, the @samp{rlogind} daemon allows you to login to a +remote machine if you can provide @samp{rlogind} a Kerberos ticket +which proves your identity. In addition to the ticket, you must also +have possession of the corresponding ticket session key. The +combination of a ticket a ticket session key is known as a credential. -In order to use a ticket, the client must also have possession of the -@dfn{ticket session key}. This combination of the ticket and the ticket -session key is known as a @dfn{credential}. +Typically, a client program automatically obtains credentials +identifiying the person using the client program. The credentials are +obtained from a Kerberos server that resides somewhere on the network. +A Kerberos server maintains a database of user, server, and password +information. - -@node The Kerberos Database, The Ticket-Granting Ticket, Kerberos Tickets, How Kerberos Works +@node The Kerberos Database, Kerberos Realms, Kerberos Tickets, How Kerberos Works @section The Kerberos Database Kerberos will give you tickets only if you have an entry in the Kerberos @@ -278,15 +292,33 @@ Kerberos @dfn{principal} (which is often just your username), and your Kerberos password. Every Kerberos user must have an entry in this database. -@node The Ticket-Granting Ticket, Network Services and the Master Database, The Kerberos Database, How Kerberos Works +@node Kerberos Realms, The Ticket-Granting Ticket, The Kerberos Database, How Kerberos Works +@section Kerberos Realms + +Each site (or administrative domain within a site) will have their own +Kerberos database, which contains information about the users and +services for that particular site or administrative domain. +A @dfn{Kerberos Realm} is used to distinguish the users and services in +one particular area of administrative control from another area of +administrative control. + +Each Kerberos realm will have at least one Kerberos server, where the +master Kerberos database for that site or administrative domain is +stored. A Kerberos realm may also have one or more @dfn{slave servers}, +which have read-only copies of the Kerberos database which are +periodically propagated from the master server. For more details on how +this is done, see @ref{Setting up Slave Kerberos Servers}. + +@node The Ticket-Granting Ticket, Network Services and the Master Database, Kerberos Realms, How Kerberos Works @section The Ticket-Granting Ticket -The @samp{kinit} command prompts for your password, and if you enter it -successfully, you will obtain a @dfn{ticket-granting ticket} and a +The @samp{kinit} command prompts for your password, and if you enter +it successfully, you will obtain a @dfn{ticket-granting ticket} and a @dfn{ticket session key} which gives you the right to use the ticket. This combination of the ticket and its associated key is also know as -your @dfn{credentials}. As illustrated below, client programs use these -credentials to get other Kerberos credentials as needed. +your @dfn{credentials}. As illustrated below, client programs use +your ticket-granting ticket credentials in order to obtain +client-specific credentials as needed. Your credentials are stored in a @dfn{credentials cache}, which is often simply just a file in @file{/tmp}. The credentials cache is also @@ -316,13 +348,26 @@ be many different machines, each offering one particular type of service, and the second component serves to give each one of these servers a different Kerberos name. -For each service, there must also be a @dfn{service key} stored in the -Kerberos database. @b{WARNING:} This service key is the equivalent of -the service's password, and must be kept secure, since data which is -meant to be read only by the service is encrypted in this key. Service -keys are stored in @dfn{key tables}, which are also commonly known as -@dfn{srvtab files}. Service keys that are meant to be used by services -which run as root are often stored in the file @file{/etc/v5srvtab}. +@menu +* The Keytab File:: +@end menu + +@node The Keytab File, , Network Services and the Master Database, Network Services and the Master Database +@subsection The Keytab File + +For each service, there must also be a @dfn{service key} known only by +Kerberos and the service. On the Kerberos server, the service key is +stored in the Kerberos database. + +On the server host, these service keys are stored in the @dfn{Key +tables}, or @dfn{keytab files}. (Keytab files were previously +referred to as @dfn{srvtab files} in the V4 literature.) The service +keys that are used by services which run as root are often stored in +the file @file{/etc/v5srvtab}. + +@b{WARNING:} This service key is the equivalent of the service's +password, and must be kept secure, since data which is meant to be +read only by the service is encrypted using this key. @node The User-Kerberos Interaction, , Network Services and the Master Database, How Kerberos Works @section The User--Kerberos Interaction @@ -348,12 +393,12 @@ entry in the Kerberos database. @item If this entry exists, the Kerberos server creates and returns a ticket-granting ticket and the key which allows you to use it, encrypted -in your password. If @samp{kinit} can decrypt the Kerberos reply using +by your password. If @samp{kinit} can decrypt the Kerberos reply using the password you provide, it stores this ticket in a credentials cache on your local machine for later use. The name of the credentials cache can be specified in the @samp{KRB5_CCNAME} environment variable. If this variable is not set, the name of the file will be -@file{/tmp/krb5cc_}, where is the UNIX user-id, represented +@file{/tmp/krb5cc_}, where is your UNIX user-id, represented in decimal format. @end enumerate @@ -361,7 +406,7 @@ in decimal format. @samp{laughter}. @example -host% @b{rlogin laughter} +host% @b{rlogin laughter} @end example @enumerate A @@ -378,11 +423,12 @@ ticket-granting service issues you a ticket for that service. That ticket is also cached in your credentials cache. @item The @samp{rlogin} client now sends that ticket to -the @samp{laughter} @samp{rlogin} service program. -The service program checks the ticket by using its own service key. -If the ticket is valid, it knows the identity of the user. If that user -is permitted to log in on @samp{laughter} (because the user's name -matches one in /etc/passwd), it lets the user log in. +the @samp{laughter} @samp{rlogind} service program. The service program +checks the ticket by using its own service key. If the ticket is valid, +it now knows your identity. If the ticket is valid and you are allowed +to login to @samp{laughter} (because the your name matches one in +/etc/passwd, or you are in the appropriate @file{.klogin} file), will +let you login. @end enumerate @end enumerate @@ -491,9 +537,9 @@ you might use the following procedure: @subsection Building Using @samp{lndir} If you wish to keep separate build directories for each platform, and -your @samp{make} program does not support @samp{VPATH}, all is not lost. -You can use the @samp{lndir} program to create symbolic link trees -in your build directory. +you do cannot use a @samp{make} program which supports @samp{VPATH}, +all is not lost. You can use the @samp{lndir} program to create +symbolic link trees in your build directory. For example, if you wish to create a build directory for solaris binaries you might use the following procedure: @@ -514,7 +560,8 @@ makes it fail for relative pathnames. The Kerberos V5 distribution comes with built-in regression tests. To run them, simply type the following command while in the top-level build -directory: +directory (i.e., the directory where you typed @samp{make} to start +building Kerberos; see @ref{Doing the Build}.): @example % @b{make check} @@ -563,6 +610,14 @@ library should be found (@file{/KRB4DIR/lib}). @end table +For example, in order to configure Kerberos on a Solaris machine using +the @samp{suncc} with the optimizer turned on, run the configure +script with the following options: + +@example +% configure --with-cc=suncc --with-ccopts=-O +@end example + @node OS Incompatibilities, Configuration .h files, Options to Configure, Building Kerberos @section Operating System Incompatibilities @@ -573,24 +628,33 @@ send a report to @b{krb5-bugs@@mit.edu}. Thanks! @menu * Ultrix 4.2/3:: +* Alpha OSF/1 V1.3:: * Alpha OSF/1 V2.0:: * BSDI:: * Solaris versions 2.0 through 2.3:: * Solaris 2.X:: @end menu -@node Ultrix 4.2/3, Alpha OSF/1 V2.0, OS Incompatibilities, OS Incompatibilities +@node Ultrix 4.2/3, Alpha OSF/1 V1.3, OS Incompatibilities, OS Incompatibilities @subsection Ultrix 4.2/3 -On the MIPS platform, @file{md4.c} and @file{md5.c} can not be compiled -with the optimizer set at level 1. (Either @samp{-O} or @samp{-g} will -work; leaving ccopts null won't.) The optimizer isn't hung; it just -takes an exponentially long time. 6 out of the 48 algorithmic steps -takes 3 seconds, 7 steps takes 9 seconds, 8 steps takes 27 seconds, and -so on. Calculations estimate it will finish in approximately 3,469 -billion years.... +On the MIPS platform, @file{md4.c} and @file{md5.c} can not be +compiled with the optimizer set at level 1. That is, you must specify +either @samp{--with-ccopts=-O} and @samp{--with-ccopts=-g} to +configure. If you don't specify either, the compile will never complete. + +The optimizer isn't hung; it just takes an exponentially long time. 6 +out of the 48 algorithmic steps takes 3 seconds, 7 steps takes 9 +seconds, 8 steps takes 27 seconds, and so on. Calculations estimate +it will finish in approximately 3,469 billion years.... + +@node Alpha OSF/1 V1.3, Alpha OSF/1 V2.0, Ultrix 4.2/3, OS Incompatibilities +@subsection Alpha OSF/1 V1.3 -@node Alpha OSF/1 V2.0, BSDI, Ultrix 4.2/3, OS Incompatibilities +There is a bug in OSF/1's fgrep which causes the @samp{configure} +script to fail. + +@node Alpha OSF/1 V2.0, BSDI, Alpha OSF/1 V1.3, OS Incompatibilities @subsection Alpha OSF/1 V2.0 @file{md4.c} can not be compiled with the optimizer on. (This could possibly @@ -786,16 +850,16 @@ To install the binaries into a binary tree, do: Currently this only works if @samp{somewhere-else} is @file{/krb5}. (It's a bug.) -@node Installation, , Building Kerberos, Top +@node Installation, Troubleshooting, Building Kerberos, Top @chapter Installation When you are installing Kerberos for the first time at a site, you must first decide on the realm name you will use for your site, and select a -machine to serve as the @dfn{Key Distribution Center}, or @dfn{KDC} for -short. The KDC must be located on a secure machine, since its database -contains the keys for the entire realm. It is extremely important that -the database be kept secure, if the realm's Kerberos service is to -remain secure. +machine to host the @dfn{Kerberos server}, which is also known as the +@dfn{KDC} (@dfn{Key Distribution Center}). The KDC must be located on a +secure machine, since its database contains the keys for the entire +realm. It is extremely important that the database be kept secure, if +the realm's Kerberos service is to remain secure. Once a KDC is installed and configured, you may then set up one or more client machines, and one or more application machines. @@ -804,6 +868,7 @@ client machines, and one or more application machines. * Background:: * Installation on any Machine:: * Installing the KDC:: +* Migrating from V4 to V5 Kerberos:: * A Sample Application:: * Common Kerberos Service Names:: @end menu @@ -832,9 +897,10 @@ have the Kerberos configuration files properly installed. If you are installing Kerberos on a machine that will act only as a Kerberos client, this section describes all that you need to do. If you -are installing a KDC, or an Kerberos Application server, please see -@ref{Installing the KDC}, or @ref{A Sample Application}, for additional -steps. +are installing a KDC, or an Kerberos Application server, you will also +need to complete the procedures detailed in @ref{Installing the KDC}, or +@ref{A Sample Application}, after you finish with the procedures found +in this section. @menu * Picking a Realm Name:: @@ -848,10 +914,11 @@ steps. Before you install Kerberos V5 at your site, you have to choose a @dfn{realm name}, the name that specifies the system's administrative domain. By convention, we suggest that you use your internet domain -name, in capital letters. For example, if your internet domain is -@code{cygnus.com} (so that you have hostnames such as -@code{ftp.cygnus.com} and @code{tweedledum.cygnus.com}), then your -Kerberos realm should be @code{CYGNUS.COM}. +name, in capital letters. (Kerberos realm names are case-sensitive, so +it's important that your realm name be in all upper case.) For example, +if your internet domain is @code{cygnus.com} (so that you have hostnames +such as @code{ftp.cygnus.com} and @code{tweedledum.cygnus.com}), then +your Kerberos realm should be @code{CYGNUS.COM}. @node Configuration files, Required Programs, Picking a Realm Name, Installation on any Machine @comment node-name, next, previous, up@section @@ -869,31 +936,35 @@ Kerberos realm should be @code{CYGNUS.COM}. @node krb.conf, krb.realms, Configuration files, Configuration files @subsubsection The @file{krb.conf} File +The @file{krb.conf} file is used to specify a system's default Kerberos +realm, and to specify the locations of the Kerberos servers. + Create a @file{[KRB5ROOT]/krb.conf} file using the following format: @example admin server @end example -Where @samp{realm_name} specifies the system's realm name, -and @samp{master_server_name} specifies the machine name on -which you will run the master server. The words @samp{admin server} must -appear next to the name of the server on which you intend to run the -administration server (which must be a machine with access to the database). +Where @samp{realm_name} specifies the default realm to be used by that +particular system, and @samp{master_server_name} specifies the machine +name on which you will run the master server. The words @samp{admin +server} must appear next to the name of the server on which you intend +to run the administration server (which must be a machine with access to +the database). -For example, -if your realm name is @samp{mit.edu} and your master server's name is -@samp{kerberos.mit.edu}, the file should have these contents: +For example, if your realm name is @samp{MIT.EDU} and your master +server's name is @samp{kerberos.mit.edu}, the file should have these +contents: @example -mit.edu -mit.edu kerberos.mit.edu admin server +MIT.EDU +MIT.EDU kerberos.mit.edu admin server @end example -See the @file{[SOURCE_DIR]/config-files/krb.conf} file for an -example @file{krb.conf} file. That file has examples of how to -provide backup servers for a given realm (additional lines with the same -leading realm name) and how to designate servers for remote realms. +See the @file{[SOURCE_DIR]/config-files/krb.conf} file for an example +@file{krb.conf} file. That file has examples of how to provide backup +servers for a given realm (additional lines with the same leading realm +name) and how to designate servers for remote realms. @node krb.realms, /etc/services, krb.conf, Configuration files @subsubsection The @file{krb.realms} File @@ -910,8 +981,8 @@ Each line of the translation file specifies either a host name or domain name, and its associated realm: @example -<.domain.name> kerberos.realm1 - kerberos.realm2 +<.domain.name> KERBEROS.REALM1 + KERBEROS.REALM2 @end example For example, to map all hosts in the domain LSC.MIT.EDU to LCS.MIT.EDU @@ -932,6 +1003,11 @@ defined in the system's @file{/etc/services} file. The file @file{[SOURCEDIR]/config-files/services.append} contains the entries which should be appened to the @file{/etc/services} file. +If you are using the Network Information Services (NIS) or Yellow +Pages (YP), you will need to add the services in the +@file{services.append} file to the services exported in the NIS or YP +server. + @node Required Programs, , Configuration files, Installation on any Machine @subsection Required Programs @@ -939,12 +1015,15 @@ The following files should be installed on all machines which are running Kerberos, either as a client, a KDC, or an application server: @itemize -@item @file{/krb5/bin/kinit} -@item @file{/krb5/bin/kdestroy} -@item @file{/krb5/bin/klist} +@item @file{/krb5/bin/kinit} --- This program allows you to obtain +Kerberos credentials. +@item @file{/krb5/bin/kdestroy} --- This program allows you to destroy +Kerberos credentials which are no longer needed. +@item @file{/krb5/bin/klist} ---- This program allows you to list the +credentials found in your credentials cache. @end itemize -@node Installing the KDC, A Sample Application, Installation on any Machine, Installation +@node Installing the KDC, Migrating from V4 to V5 Kerberos, Installation on any Machine, Installation @section Installing the KDC @menu @@ -952,6 +1031,8 @@ running Kerberos, either as a client, a KDC, or an application server: * Storing the Master Password:: * Adding Users to the Database:: * Starting the Kerberos Server:: +* Setting up Slave Kerberos Servers:: +* Inter-realm Kerberos Operation:: * The Administration Server:: * Testing the Kerberos Server:: @end menu @@ -1041,7 +1122,7 @@ The @samp{ank} command is short for "add_new_key"; this command adds a new user to the database. To see what other commands which @samp{kdb5_edit} supports, type @kbd{? @key{RET}} at the @samp{kdb5_edit} prompt. -@node Starting the Kerberos Server, The Administration Server, Adding Users to the Database, Installing the KDC +@node Starting the Kerberos Server, Setting up Slave Kerberos Servers, Adding Users to the Database, Installing the KDC @subsection Starting the Kerberos Server In order to start the Kerberos server, run it as a background process @@ -1062,7 +1143,15 @@ use the following command: The server will prompt you to enter the master password before actually starting itself. -@node The Administration Server, Testing the Kerberos Server, Starting the Kerberos Server, Installing the KDC +@node Setting up Slave Kerberos Servers, Inter-realm Kerberos Operation, Starting the Kerberos Server, Installing the KDC +@subsection Setting up Slave Kerberos Servers + +@node Inter-realm Kerberos Operation, The Administration Server, Setting up Slave Kerberos Servers, Installing the KDC +@subsection Inter-realm Kerberos Operation + +@b{To be written.} + +@node The Administration Server, Testing the Kerberos Server, Inter-realm Kerberos Operation, Installing the KDC @subsection The Administration Server There is currently an administration server in the Kerberos source tree. @@ -1110,8 +1199,12 @@ If you have any problems, you can examine the log file there was some sort of error. @end ignore +@node Migrating from V4 to V5 Kerberos, A Sample Application, Installing the KDC, Installation +@section Migrating from V4 to V5 Kerberos -@node A Sample Application, Common Kerberos Service Names, Installing the KDC, Installation +@b{To be written.} + +@node A Sample Application, Common Kerberos Service Names, Migrating from V4 to V5 Kerberos, Installation @section A Sample Application This release of Kerberos comes with a sample application server and a @@ -1304,5 +1397,10 @@ These service names are used as the first component of the server's principal name, with the second component being the server's fully qualified domain name, in lower case. +@node Troubleshooting, , Installation, Top +@chapter Troubleshooting + +@b{To be written.} + @contents @bye -- 2.26.2