From: Tom Yu Date: Tue, 24 Dec 1996 10:18:06 +0000 (+0000) Subject: merge from V1_0_RELEASE X-Git-Tag: krb5-1.1-beta1~1396 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=1c3559d6f74f042ed190090fc0bc858e5f9c68e0;p=krb5.git merge from V1_0_RELEASE git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@9686 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/doc/.cvsignore b/doc/.cvsignore index b2c6b121c..47cc49736 100644 --- a/doc/.cvsignore +++ b/doc/.cvsignore @@ -1,80 +1,15 @@ -admin_toc.html -admin.html -admin_foot.html -admin.log -admin.dvi -admin.aux -admin.toc -admin.cp -admin.fn -admin.vr -admin.tp -admin.ky -admin.pg -admin-guide.ps -kerberos-admin.info -kerberos-admin.info-1 -kerberos-admin.info-2 -install_toc.html -install.html -install_foot.html -install.log -install.dvi -install.aux -install.toc -install.cp -install.fn -install.vr -install.tp -install.ky -install.pg -install-guide.ps -krb5-install.info -krb5-install.info-1 -krb5-install.info-2 -user-guide_toc.html -user-guide.html -user-guide_foot.html -user-guide.log -user-guide.dvi -user-guide.aux -user-guide.toc -user-guide.cp -user-guide.fn -user-guide.vr -user-guide.tp -user-guide.ky -user-guide.pg -user-guide.ps -krb5-user.info -kdestroy1.ps -klist1.ps -kinit1.ps -kinit2.ps -rcp1.ps -ftp1.ps -ftp2.ps -ftp3.ps -ftp4.ps -ftp5.ps -ftp6.ps -ftp7.ps -ftp8.ps -rlogin1.ps -ksu1.ps -ksu2.ps -ksu3.ps -ksu4.ps -ksu5.ps -rlogin2.ps -rsh1.ps -rsh2.ps -telnet1.ps -telnet2.ps -telnet3.ps -telnet4.ps -telnet5.ps -telnet6.ps -telnet7.ps -telnet8.ps -telnet9.ps +*.html +*.info +*.info-* +*.log +*.dvi +*.aux +*.toc +*.cp +*.fn +*.vf +*.tp +*.ky +*.pg +*.vr +*.ps diff --git a/doc/ChangeLog b/doc/ChangeLog index 7b3a8bbd2..49002f24f 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,167 @@ +Fri Dec 13 15:10:44 1996 Tom Yu + + * admin.texinfo (The User--Kerberos Interaction): The environment + variable is KRB5CCNAME, not KRB5_CCNAME. + (Getting DNS Information Correct): It's Domain Name System, not + Distributed Name Service. + +Thu Dec 12 18:36:20 1996 Tom Yu + + * user-guide.texinfo: Bump edition to 1.0. Nuke gratuitous + vfills. Change @value{PRODUCT} to explicit reference, to avoid + makeinfo bug that introduces a nul character. + + * krb425.texinfo: Bump edition to 1.0. + + * build.texinfo (OS Incompatibilities): Refer to krb5-send-pr + instead of mail to krb5-bugs. + (Options to Configure): Change options to indicate meta-names, + e.g. "--prefix=PREFIX"; also nuke leading slash on some + descriptions of options. + + * admin.texinfo: Add more explicit linebreaks to prevent overruns; + also break up a few long lines in example program output. + +Fri Dec 6 13:58:19 1996 Tom Yu + + * .cvsignore: Ignore by suffix rather than by file. + + * Makefile (admin-guide-info): + (admin-guide-info): Update to reflect new info file name. + + * admin.texinfo: Change info file name to krb5-admin.info for + consistency. + (Administrating Kerberos Database Entries): "-c credentials_cache" + -> "-c ccache" to avoid overrun. + (Privileges): Null instance example is joeuser@REALM, not + joeuser/null@REALM. + + * install.texinfo (Kerberos Realms): SAN_FRANCISCO.FUBAR.ORG -> + HOUSTON.FUBAR.ORG to prevent margin overrun. + (Create a kadmind Keytab): Add explicit linebreak to prevent + margin overrun. + (Overview of This Guide): + (Installing Kerberos V5): Remove references to windows and mac + client machines for now. + + * krb425.texinfo: Use krb425.info instead of + Kerberos-V4-to-V5.info in the interest of shorter filenames. + + * user-guide.texinfo (Introduction): Eliminate "Kerberos V5 is + based on Kerberos V5". + (Ticket Management): Fix ref to "/rsh". + (rsh): Add explicit linebreak to avoid margin overrun. + + * krb425.texinfo (Upgrading KDCs): Use ROOTDIR rather than + INSTALLDIR to get the proper pathname. + + * send-pr.texinfo: Fix some misspellings, also remove references + to things that are only really applicable for Cygnus. + +Wed Dec 4 23:47:28 1996 Tom Yu + + * krb425.texinfo (Upgrading Application Servers): v5srvtab -> + krb5.keytab + +Mon Dec 2 13:00:26 1996 Barry Jaspan + + * build.texinfo (The DejaGnu Tests): info about .k5login for + krb-root tests [krb5-doc/261] + + * install.texinfo (Add Administrators to the Kerberos Database): + note relationship between acl file and admin principals + [krb5-doc/251] + (Edit the Configuration Files): mention the logging stanza here, + too, and tell people to check it when they start the daemons + [krb5-doc/253] + + * build.texinfo (The KADM5 Tests): add section for the kadm5 tests + [krb5-doc/247] + +Fri Nov 29 19:47:38 1996 Tom Yu + + * build.texinfo (Unpacking the Sources): Mention that ./krb5-1.0 + is the default directory that the tarballs will unpack into. + Also, "/u1/krb5" -> "/u1/krb5-1.0". + (osconf.h): Remove reference to DEFAULT_LNAME_FILENAME, as we're + no longer using the aname database code. + (Options to Configure): Add mention of --localstatedir + (Shared Library Support): It's Solaris 2.4/SunOS 5.4, not Solaris + 5.4. + (Solaris 2.X): Shared libs work with gcc. + + * install.texinfo (Mapping Hostnames onto Kerberos Realms): Fix + spacing error. + + * admin.texinfo: Fix up old references to "/krb5". + + * send-pr.texinfo: krb5-send-pr is in PREFIX/sbin, not PREFIX/bin. + + * admin.texinfo: "/lib/krb5kdc" -> "/var/krb5kdc" + + * krb425.texinfo (Upgrading Application Servers): Change flag + "cygnus" to "CYGNUS". + + * install.texinfo (Please Read the Documentation): Change flag + "cygnus" to "CYGNUS". + + * admin.texinfo (domain_realm): Change flag "cygnus" to "CYGNUS". + + * definitions.texinfo: Change /usr/@value{LCPRODUCT} to /usr/local + to sync with default paths. + + * admin.texinfo (domain_realm): Conditionalize "COM" vs "EDU" in + example. + + * install.texinfo (Create Host Keys for the Slave KDCs): Change + -randpass to -randkey. [244] + +Thu Nov 28 18:54:02 1996 Tom Yu + + * krb425.texinfo: Change to use "@chapternewpage odd", also frob + copyright page as per other docs. Also, remove footnote claiming + that "Kerberos V5 is based on the MIT beta7 release". + + * admin.texinfo (capaths): Fix unquoted braces. + (appdefaults): Fix unquoted braces. + +Wed Nov 27 18:27:18 1996 Jeffrey C. G. Bigler + + * Makefile: Added send-pr.texinfo to ADMIN_INCLUDES and + INSTALL_INCLUDES. + + * admin.texinfo: Added chapter on config files. Changed bug + reporting section to include send-pr file. + + * install.texinfo: Changed bug reporting section to include + send-pr file. Added reference to Sysadmin Guide chapter on config + files. + + * send-pr.texinfo: Fixed this up to match our version of + krb5-send-pr. + +Tue Nov 26 18:34:11 1996 Tom Yu + + * install.texinfo: Fix a couple of references to "@value{COMPANY}" + so they don't commit MIT to doing user support; also fixed some + punctuation errors. + +Mon Nov 25 23:39:53 1996 Theodore Y. Ts'o + + * copyright.texinfo: Change lib/kadm to lib/kadm5, and add the + kadmin/passwd to the list of directories containing OV + code. + +Sun Nov 24 23:55:52 1996 Ezra Peisach (epeisach@mit.edu) + + * build.texinfo: Remove --with-kdb-db section as it does not + exist. Add --with-tcl info. + +Tue Nov 19 13:42:00 1996 Barry Jaspan + + * install.texinfo, build.texinfo: misc suggestions from jhawk + [krb5-doc/55] + Fri Nov 15 17:52:39 1996 Jeff Bigler * Makefile (krb425-guide): added section to make krb425 guide. diff --git a/doc/Makefile b/doc/Makefile index 92a3477a9..f8c29969b 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -9,11 +9,11 @@ GZIP=gzip -9 MANPS=./man2ps ADMIN_INCLUDES=definitions.texinfo copyright.texinfo document-list.texinfo \ - glossary.texinfo + glossary.texinfo send-pr.texinfo ADMIN_DEPS=admin.texinfo $(ADMIN_INCLUDES) INSTALL_INCLUDES=definitions.texinfo copyright.texinfo document-list.texinfo \ - build.texinfo bug-report.texinfo + build.texinfo bug-report.texinfo send-pr.texinfo INSTALL_DEPS=install.texinfo $(INSTALL_INCLUDES) USER_GUIDE_INCLUDES=definitions.texinfo copyright.texinfo glossary.texinfo @@ -42,9 +42,9 @@ admin.html: $(ADMIN_DEPS) $(HTML) admin.texinfo .PHONY: admin-guide-info -admin-guide-info:: kerberos-admin.info +admin-guide-info:: krb5-admin.info -kerberos-admin.info: $(ADMIN_DEPS) +krb5-admin.info: $(ADMIN_DEPS) $(INFO) admin.texinfo .PHONY: install-guide-full diff --git a/doc/admin.texinfo b/doc/admin.texinfo index cca3e321e..7e70d28c7 100644 --- a/doc/admin.texinfo +++ b/doc/admin.texinfo @@ -3,7 +3,7 @@ \input texinfo @c -*-texinfo-*- @c %**start of header @c guide -@setfilename kerberos-admin.info +@setfilename krb5-admin.info @settitle Kerberos V5 System Administrator's Guide @setchapternewpage odd @c chapter begins on next odd page @c @setchapternewpage on @c chapter begins on next page @@ -15,7 +15,8 @@ @end iftex @include definitions.texinfo -@set EDITION b7-1 +@set EDITION 1.0 +@set UPDATED November 27, 1996 @finalout @c don't print black warning boxes @@ -58,6 +59,7 @@ installation. * Copyright:: * Introduction:: * How Kerberos Works:: +* Configuration Files:: * Administrating Kerberos Database Entries:: * Application Servers:: * Backups of Secure Hosts:: @@ -116,7 +118,7 @@ The appendices include sample configuration files, the list of Kerberos error messages, and a complete list of the time zones understood by @code{kadmin}. -@node How Kerberos Works, Administrating Kerberos Database Entries, Introduction, Top +@node How Kerberos Works, Configuration Files, Introduction, Top @chapter How Kerberos Works This section provides a simplified description of a general user's @@ -282,8 +284,8 @@ ticket-granting ticket and the key which allows you to use it, encrypted 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 +can be specified in the @samp{KRB5CCNAME} environment variable. If this +variable is not set, the name of the file will be @file{/tmp/krb5cc_}, where is your UNIX user-id, represented in decimal format. @end enumerate @@ -329,7 +331,582 @@ Following are definitions of some of the Kerberos terminology. @include glossary.texinfo -@node Administrating Kerberos Database Entries, Application Servers, How Kerberos Works, Top +@node Configuration Files, Administrating Kerberos Database Entries, How Kerberos Works, Top +@chapter Configuration Files + +@menu +* krb5.conf:: +* kdc.conf:: +@end menu + +@node krb5.conf, kdc.conf, Configuration Files, Configuration Files +@section krb5.conf + +The @code{krb5.conf} file contains Kerberos configuration information, +including the locations of KDCs and admin servers for the Kerberos +realms of interest, defaults for the current realm and for Kerberos +applications, and mappings of hostnames onto Kerberos realms. Normally, +you should install your @code{krb5.conf} file in the directory +@code{/etc}. You can override the default location by setting the +environment variable @samp{KRB5_CONFIG}. + +The @code{krb5.conf} file is set up in the style of a Windows INI file. +Sections are headed by the section name, in square brackets. Each +section may contain zero or more relations, of the form: + +@smallexample +foo = bar +@end smallexample + +@noindent +or + +@smallexample +@group +fubar = @{ + foo = bar + baz = quux +@} +@end group +@end smallexample + +The @code{krb5.conf} file may contain any or all of the following seven +sections: + +@table @b +@itemx libdefaults +Contains default values used by the Kerberos V5 library. + +@itemx appdefaults +Contains default values used by Kerberos V5 applications. + +@itemx realms +Contains subsections keyed by Kerberos realm names. Each subsection +describes realm-specific information, including where to find the +Kerberos servers for that realm. + +@itemx domain_realm +Contains relations which map domain names and subdomains onto Kerberos +realm names. This is used by programs to determine what realm a host +should be in, given its fully qualified domain name. + +@itemx logging +Contains relations which determine how Kerberos programs are to perform +logging. + +@itemx capaths +Contains the authentication paths used with direct (nonhierarchical) +cross-realm authentication. Entries in this section are used by the +client to determine the intermediate realms which may be used in +cross-realm authentication. It is also used by the end-service when +checking the transited field for trusted intermediate realms. + +@itemx kdc +For a KDC, may contain the location of the kdc.conf file. +@end table + +@menu +* libdefaults:: +* appdefaults:: +* realms (krb5.conf):: +* domain_realm:: +* logging:: +* capaths:: +* Sample krb5.conf File:: +@end menu + +@node libdefaults, appdefaults, krb5.conf, krb5.conf +@subsection [libdefaults] + +The @code{libdefaults} section may contain any of the following +relations: + +@table @b +@itemx default_realm +Identifies the default Kerberos realm for the client. Set its value to +your Kerberos realm. + +@itemx default_tgs_enctypes +Identifies the supported list of session key encryption types that +should be returned by the KDC. The list may be delimited with commas or +whitespace. Currently, the only supported encryption type is +"des-cbc-crc". Support for other encryption types is planned in the +future. + +@itemx default_tkt_enctypes +Identifies the supported list of session key encryption +types that should be requested by the client. The format is the same as +for @emph{default_tkt_enctypes}. Again, the only supported encryption +type is "des-cbc-crc". + +@itemx clockskew +Sets the maximum allowable amount of clockskew in seconds that the +library will tolerate before assuming that a Kerberos message is +invalid. The default value is 300 seconds, or five minutes. + +@itemx checksum_type +Used for compatability with DCE security servers which do not support +the default CKSUMTYPE_RSA_MD5 used by this version of Kerberos. A value +of 1 indicates the default checksum type. Use a value of 2 to use the +CKSUMTYPE_RSA_MD4 instead. This applies to DCE 1.1 and earlier. + +@itemx ccache_type +Use this parameter on systems which are DCE clients, to specify the type +of cache to be created by kinit, or when forwarded tickets are received. +DCE and Kerberos can share the cache, but some versions of DCE do not +support the default cache as created by this version of Kerberos. Use a +value of 1 on DCE 1.0.3a systems, and a value of 2 on DCE 1.1 systems. +@end table + +@node appdefaults, realms (krb5.conf), libdefaults, krb5.conf +@subsection [appdefaults] + +Each tag in the [appdefaults] section names a Kerberos V5 application. +The value of the tag is a subsection with relations that define the +default behaviors for that application. + +For example: + +@smallexample +@group +[appdefaults] + kinit = @{ + forwardable = true + @} + telnet = @{ + forward = true + encrypt = true + autologin = true + @} +@end group +@end smallexample + +The list of specifiable options for each application may be found in +that application's man pages. The application defaults specified here +are overridden by those specified in the [realms] section. + +@node realms (krb5.conf), domain_realm, appdefaults, krb5.conf +@subsection [realms] + +Each tag in the [realms] section of the file is the name of a Kerberos +realm. The value of the tag is a subsection with relations that define +the properties of that particular realm. For each realm, the following +tags may be specified in the realm's subsection: + +@table @b +@itemx kdc +The name of a host running a KDC for that realm. An optional port +number (separated from the hostname by a colon) may be included. + +@itemx admin_server +Identifies the host where the administration server is running. +Typically, this is the master Kerberos server. + +@itemx application defaults +Application defaults that are specific to a particular realm may be +specified within that realm's tag. Realm-specific application defaults +override the global defaults specified in the [appdefaults] section. +@end table + +@node domain_realm, logging, realms (krb5.conf), krb5.conf +@subsection [domain_realm] + +The [domain_realm] section provides a translation from a domain name or +hostname to a Kerberos realm name. The tag name can be a host name, or +a domain name, where domain names are indicated by a prefix of a period +(@samp{.}). The value of the relation is the Kerberos realm name for +that particular host or domain. Host names and domain names should be +in lower case. + +If no translation entry applies, the host's realm is considered to be +the hostname's domain portion converted to upper case. For example, the +following [domain_realm] section: + +@smallexample +@group +[domain_realm] +@ifset MIT + .mit.edu = ATHENA.MIT.EDU +@end ifset + @value{PRIMARYDOMAIN} = @value{PRIMARYREALM} + crash.@value{PRIMARYDOMAIN} = TEST.@value{PRIMARYREALM} + @value{SECONDDOMAIN} = @value{SECONDREALM} +@end group +@end smallexample + +@noindent +maps crash.@value{PRIMARYDOMAIN} into the TEST.@value{PRIMARYREALM} +realm. All other hosts in the @value{PRIMARYDOMAIN} domain will map by +default to the @value{PRIMARYREALM} realm, and all hosts in the +@value{SECONDDOMAIN} domain will map by default into the +@value{SECONDREALM} realm. Note the entries for the hosts +@value{PRIMARYDOMAIN} and @value{SECONDDOMAIN}. Without these entries, +@ifset CYGNUS +these hosts would be mapped into the Kerberos realms @samp{COM} and +@end ifset +@ifclear CYGNUS +these hosts would be mapped into the Kerberos realms @samp{EDU} and +@end ifclear +@samp{ORG}, respectively. + +@node logging, capaths, domain_realm, krb5.conf +@subsection [logging] +The [logging] section indicates how a particular entity is to perform +its logging. The relations in this section assign one or more values to +the entity name. Currently, the following entities are used: + +@table @b +@itemx admin_server +These entries specify how the administrative server +is to perform its logging. + +@itemx default +These entries specify how to perform logging in the +absence of explicit specifications otherwise. +@end table + +Values are of the following forms: + +@table @b +@itemx FILE= + +@itemx FILE: +This value causes the entity's logging messages to go to the specified +file. If the @samp{=} form is used, the file is overwritten. If the +@samp{:} form is used, the file is appended to. + +@itemx STDERR +This value causes the entity's logging messages to go to its standard +error stream. + +@itemx CONSOLE +This value causes the entity's logging messages to go to the console, if +the system supports it. + +@itemx DEVICE= +This causes the entity's logging messages to go to the specified device. + +@itemx SYSLOG[:[:]] +This causes the entity's logging messages to go to the system log. + +The @dfn{severity} argument specifies the default severity of system log +messages. This may be any of the following severities supported by the +@code{syslog(3)} call, minus the LOG_ prefix: LOG_EMERG, LOG_ALERT, +LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, and LOG_DEBUG. +For example, a value of @samp{CRIT} would specify LOG_CRIT severity. + +The facility argument specifies the facility under which the messages +are logged. This may be any of the following facilities supported by +the syslog(3) call minus the LOG_ prefix: LOG_KERN, LOG_USER, LOG_MAIL, +LOG_DAEMON, LOG_AUTH, LOG_LPR, LOG_NEWS, LOG_UUCP, LOG_CRON, and +LOG_LOCAL0 through LOG_LOCAL7. + +If no severity is specified, the default is ERR. If no facility is +specified, the default is AUTH. +@end table + +In the following example, the logging messages from the KDC will go to +the console and to the system log under the facility LOG_DAEMON with +default severity of LOG_INFO; and the logging messages from the +administrative server will be appended to the file /var/adm/kadmin.log +and sent to the device /dev/tty04. + +@smallexample +@group +[logging] + kdc = CONSOLE + kdc = SYSLOG:INFO:DAEMON + admin_server = FILE:/var/adm/kadmin.log + admin_server = DEVICE=/dev/tty04 +@end group +@end smallexample + +@node capaths, Sample krb5.conf File, logging, krb5.conf +@subsection [capaths] + +In order to perform direct (non-hierarchical) cross-realm +authentication, a database is needed to construct the authentication +paths between the realms. This section defines that database. + +A client will use this section to find the authentication path between +its realm and the realm of the server. The server will use this section +to verify the authentication path used be the client, by checking the +transited field of the received ticket. + +There is a tag for each participating realm, and each tag has subtags +for each of the realms. The value of the subtags is an intermediate +realm which may participate in the cross-realm authentication. The +subtags may be repeated if there is more then one intermediate realm. A +value of "." means that the two realms share keys directly, and no +intermediate realms should be allowd to participate. + +There are n**2 possible entries in this table, but only those entries +which will be needed on the client or the server need to be present. +The client needs a tag for its local realm, with subtags for all the +realms of servers it will need to authenticate with. A server needs a +tag for each realm of the clients it will serve. + +For example, ANL.GOV, PNL.GOV, and NERSC.GOV all wish to use the ES.NET +realm as an intermediate realm. ANL has a sub realm of TEST.ANL.GOV +which will authenticate with NERSC.GOV but not PNL.GOV. The [capath] +section for ANL.GOV systems would look like this: + +@smallexample +@group +[capaths] + ANL.GOV = @{ + TEST.ANL.GOV = . + PNL.GOV = ES.NET + NERSC.GOV = ES.NET + ES.NET = . + @} + TEST.ANL.GOV = @{ + ANL.GOV = . + @} + PNL.GOV = @{ + ANL.GOV = ES.NET + @} + NERSC.GOV = @{ + ANL.GOV = ES.NET + @} + ES.NET = @{ + ANL.GOV = . + @} +@end group +@end smallexample + +The [capath] section of the configuration file used on NERSC.GOV systems +would look like this: + +@smallexample +@group +[capaths] + NERSC.GOV = @{ + ANL.GOV = ES.NET + TEST.ANL.GOV = ES.NET + TEST.ANL.GOV = ANL.GOV + PNL.GOV = ES.NET + ES.NET = . + @} + ANL.GOV = @{ + NERSC.GOV = ES.NET + @} + PNL.GOV = @{ + NERSC.GOV = ES.NET + @} + ES.NET = @{ + NERSC.GOV = . + @} + TEST.ANL.GOV = @{ + NERSC.GOV = ANL.GOV + NERSC.GOV = ES.NET + @} +@end group +@end smallexample + +In the above examples, the ordering is not important, except when the +same subtag name is used more then once. The client will use this to +determing the path. (It is not important to the server, since the +transited field is not sorted.) + +This feature is not currently supported by DCE. DCE security servers +can be used with Kerberized clients and servers, but versions prior to +DCE 1.1 did not fill in the transited field, and should be used with +caution. + +@node Sample krb5.conf File, , capaths, krb5.conf +@subsection Sample krb5.conf File + +Here is an example of a generic @code{krb5.conf} file: + +@smallexample +@group +[libdefaults] + ticket_lifetime = 600 + default_realm = @value{PRIMARYREALM} + default_tkt_enctypes = des-cbc-crc + default_tgs_enctypes = des-cbc-crc + +[realms] + @value{PRIMARYREALM} = @{ + kdc = @value{KDCSERVER}.@value{PRIMARYDOMAIN} + kdc = @value{KDCSLAVE1}.@value{PRIMARYDOMAIN} + kdc = @value{KDCSLAVE2}.@value{PRIMARYDOMAIN} + admin_server = @value{KDCSERVER}.@value{PRIMARYDOMAIN} + default_domain = @value{PRIMARYDOMAIN} + @} + @value{SECONDREALM} = @{ + kdc = @value{KDCSERVER}.@value{SECONDDOMAIN} + kdc = @value{KDCSLAVE1}.@value{SECONDDOMAIN} + admin_server = @value{KDCSERVER}.@value{SECONDDOMAIN} + @} + +[domain_realm] +@ifset MIT + .mit.edu = ATHENA.MIT.EDU +@end ifset + @value{PRIMARYDOMAIN} = @value{PRIMARYREALM} + +@end group +@end smallexample + +@iftex +@vfill +@end iftex + +@node kdc.conf, , krb5.conf, Configuration Files +@section kdc.conf + +The @code{kdc.conf} file contains KDC configuration information, +including defaults used when issuing Kerberos tickets. Normally, you +should install your @code{kdc.conf} file in the directory +@code{@value{ROOTDIR}/var/krb5kdc}. You can override the default +location by setting the environment variable @samp{KRB5_KDC_PROFILE}. + +The @code{kdc.conf} file is set up in the same format as the +@code{krb5.conf} file. (@xref{krb5.conf}.) The @code{kdc.conf} file +may contain any or all of the following three sections: + +@table @b +@itemx kdcdefaults +Contains default values for overall behavior of the KDC. + +@itemx realms +Contains subsections keyed by Kerberos realm names. Each subsection +describes realm-specific information, including where to find the +Kerberos servers for that realm. + +@itemx logging +Contains relations which determine how Kerberos programs are to perform +logging. +@end table + +@menu +* kdcdefaults:: +* realms (kdc.conf):: +* Sample kdc.conf File:: +@end menu + +@node kdcdefaults, realms (kdc.conf), kdc.conf, kdc.conf +@subsection [kdcdefaults] + +The following relation is defined in the [kdcdefaults] section: + +@table @b +@itemx kdc_ports +This relation lists the ports on which the Kerberos server should listen +by default. This list is a comma separated list of integers. If this +relation is not specified, the compiled-in default is usually port 88 +(the assigned Kerberos port) and port 750 (the port used by Kerberos +V4). +@end table + +@node realms (kdc.conf), Sample kdc.conf File, kdcdefaults, kdc.conf +@subsection [realms] + +Each tag in the [realms] section of the file names a Kerberos realm. +The value of the tag is a subsection where the relations in that +subsection define KDC parameters for that particular realm. + +For each realm, the following tags may be specified in the [realms] +subsection: + +@table @b +@itemx acl_file +(String.) Location of the access control list (acl) file that kadmin +uses to determine which principals are allowed which permissions on the +database. The default is @code{@value{ROOTDIR}/var/krb5kdc/kadm5.acl}. + +@itemx admin_keytab +(String.) Location of the keytab file that kadmin uses to authenticate +to the database. The default is +@code{@value{ROOTDIR}/var/krb5kdc/kadm5.keytab}. + +@itemx database_name +(String.) Location of the Kerberos database for this realm. The +default is @* @code{@value{ROOTDIR}/var/krb5kdc/principal}. + +@itemx default_principal_expiration +(Absolute time string.) Specifies the default expiration date of +principals created in this realm. + +@itemx default_principal_flags +(Flag string.) Specifies the default attributes of principals created +in this realm. + +@itemx dict_file +(String.) Location of the dictionary file containing strings that are +not allowed as passwords. The default is +@code{@value{ROOTDIR}/var/krb5kdc/kadm5.dict}. + +@itemx encryption_type +(Encryption type string.) Specifies the encryption type used for this +realm. Only "des-cbc-crc" is supported at this time. + +@itemx kadmind_port +(Port number.) Specifies the port that the kadmind daemon is to listen +for this realm. The assigned port for kadmind is 749. + +@itemx key_stash_file +(String.) Specifies the location where the master key has been stored +(via @code{kdb5_util stash}). The default is +@code{@value{ROOTDIR}/var/krb5kdc/.k5.@i{REALM}}, where @i{REALM} is the +Kerberos realm. + +@itemx kdc_ports +(String.) Specifies the list of ports that the KDC is to listen to for +this realm. By default, the value of kdc_ports as specified in the +[kdcdefaults] section is used. + +@itemx master_key_name +(String.) Specifies the name of the master key. + +@itemx master_key_type +(Key type string.) Specifies the master key's key type. Only +"des-cbc-crc" is supported at this time. + +@itemx max_life +(Delta time string.) Specifes the maximum time period for which a +ticket may be valid in this realm. + +@itemx max_renewable_life +(Delta time string.) Specifies the maximum time period during which a +valid ticket may be renewed in this realm. + +@itemx supported_enctypes +List of key:salt strings. Specifies the default key/salt combinations +of principals for this realm. Since only the encryption type +"des-cbc-crc" is supported, you should set this tag to +@samp{des-cbc-crc:normal}. +@end table + +@node Sample kdc.conf File, , realms (kdc.conf), kdc.conf +@subsection Sample kdc.conf File + +Here's an example of a @code{kdc.conf} file: + +@smallexample +@group +[kdcdefaults] + kdc_ports = 88 + +[realms] + @value{PRIMARYREALM} = @{ + kadmind_port = 749 + max_life = 10h 0m 0s + max_renewable_life = 7d 0h 0m 0s + master_key_type = des-cbc-crc + supported_enctypes = des-cbc-crc:normal + @} + +[logging] + kdc = FILE:@value{ROOTDIR}/var/krb5kdc/kdc.log + admin_server = FILE:@value{ROOTDIR}/var/krb5kdc/kadmin.log + +@end group +@end smallexample + +@node Administrating Kerberos Database Entries, Application Servers, Configuration Files, Top @chapter Administrating the Kerberos Database Your Kerberos database contains all of your realm's Kerberos principals, @@ -361,13 +938,13 @@ database dump and load, which are provided by @code{kdb5_util}). The remote version authenticates to the KADM5 server using the service principal @code{kadmin/admin}. If the credentials cache contains a -ticket for the @code{kadmin/admin} principal, and the @samp{-c -credentials_cache} option is specified, that ticket is used to -authenticate to KADM5. Otherwise, the @samp{-p} and @samp{-k} options -are used to specify the client Kerberos principal name used to -authenticate. Once kadmin has determined the principal name, it -requests a @code{kadmin/admin} Kerberos service ticket from the KDC, and -uses that service ticket to authenticate to KADM5. +ticket for the @code{kadmin/admin} principal, and the @samp{-c ccache} +option is specified, that ticket is used to authenticate to KADM5. +Otherwise, the @samp{-p} and @samp{-k} options are used to specify the +client Kerberos principal name used to authenticate. Once kadmin has +determined the principal name, it requests a @code{kadmin/admin} +Kerberos service ticket from the KDC, and uses that service ticket to +authenticate to KADM5. @menu * Kadmin Options:: @@ -514,7 +1091,7 @@ requires the ``inquire'' administrative privilege. The syntax is: @noindent The @code{get_principal} command has the alias @code{getprinc}. For example, suppose you wanted to view the attributes of the principals -@code{@value{RANDOMUSER1}/root@@@value{PRIMARYREALM}} and +@* @code{@value{RANDOMUSER1}/root@@@value{PRIMARYREALM}} and @code{systest@@@value{PRIMARYREALM}}. You would type: @smallexample @@ -629,7 +1206,7 @@ permissions are determined by the first matching entry. @smallexample @group */admin@@@value{PRIMARYREALM} * -@value{ADMINUSER}/null@@@value{PRIMARYREALM} ADMCIL +@value{ADMINUSER}@@@value{PRIMARYREALM} ADMCIL @value{ADMINUSER}/*@@@value{PRIMARYREALM} il @value{RANDOMUSER1}/root@@@value{PRIMARYREALM} cil */root@@@value{PRIMARYREALM} */*@@@value{PRIMARYREALM} i @@ -641,7 +1218,7 @@ has all administrative privileges. The user @code{@value{ADMINUSER}} has all permissions with his @code{admin} instance, @code{@value{ADMINUSER}/admin@@@value{PRIMARYREALM}} (matches the first line). He has no permissions at all with his @code{null} instance, -@code{@value{ADMINUSER}/null@@@value{PRIMARYREALM}} (matches the second +@code{@value{ADMINUSER}@@@value{PRIMARYREALM}} (matches the second line). He has @i{inquire} and @i{list} permissions with any other instance (matches the third line). When @code{@value{RANDOMUSER1}} is using her @code{root} @@ -649,7 +1226,7 @@ instance, @code{@value{RANDOMUSER1}/root@@@value{PRIMARYREALM}}, she has @i{change password}, @i{inquire}, and @i{list} privileges for any other principal that has the instance @code{root}. Finally, any principal in the realm @code{@value{PRIMARYREALM}} (except for -@code{@value{ADMINUSER}/null@@@value{PRIMARYREALM}}, as mentioned above) +@code{@value{ADMINUSER}@@@value{PRIMARYREALM}}, as mentioned above) has @i{inquire} privileges. @node Adding or Modifying Principals, Deleting Principals, Privileges, Principals @@ -741,14 +1318,14 @@ principal in the database. @item @{-|+@}allow_proxiable The ``-allow_proxiable'' option prohibits this principal from obtaining proxiable tickets. ``+allow_proxiable'' clears this flag. In effect, -``-allow_proxiable'' sets the KRB5_KDB_DISALLOW_PROXIABLE flag. on the -principal in the database. +``-allow_proxiable'' sets the @* KRB5_KDB_DISALLOW_PROXIABLE flag. on +the principal in the database. @item @{-|+@}allow_dup_skey The ``-allow_dup_skey'' option disables user-to-user authentication for this principal by prohibiting this principal from obtaining a session key for another user. ``+allow_dup_skey'' clears this flag. In effect, -``-allow_dup_skey'' sets the KRB5_KDB_DISALLOW_DUP_SKEY flag on the +``-allow_dup_skey'' sets the @* KRB5_KDB_DISALLOW_DUP_SKEY flag on the principal in the database. @item @{-|+@}requires_preauth @@ -767,8 +1344,8 @@ database. @item @{-|+@}allow_svr The ``-allow_svr'' flag prohibits the issuance of service tickets for this principal. ``+allow_svr'' clears this flag. In effect, -``-allow_svr'' sets the KRB5_KDB_DISALLOW_SVR flag on the principal in -the database. +``-allow_svr'' sets the @* KRB5_KDB_DISALLOW_SVR flag on the principal +in the database. @item @{-|+@}allow_tgs_req The ``-allow_tgs_req'' option specifies that a Ticket-Granting Service @@ -781,7 +1358,7 @@ principal in the database. @item @{-|+@}allow_tix The ``-allow_tix'' option forbids the issuance of any tickets for this principal. ``+allow_tix'' clears this flag. The default is -``+allow_tix''. In effect, ``-allow_tix'' sets the +``+allow_tix''. In effect, ``-allow_tix'' sets the @* KRB5_KDB_DISALLOW_ALL_TIX flag on the principal in the database. @item @{-|+@}needchange @@ -863,7 +1440,7 @@ kadmin:} If you will need cross-realm authentication, you need to add principals for the other realm's TGT to each realm. For example, if you need to do cross-realm authentication between the realms @value{PRIMARYREALM} and -@value{SECONDREALM}, you would need to add the principals +@value{SECONDREALM}, you would need to add the principals @* @samp{krbtgt/@value{SECONDREALM}@@@value{PRIMARYREALM}} and @samp{krbtgt/@value{PRIMARYREALM}@@@value{SECONDREALM}} to both databases. You need to be sure the passwords and the key version @@ -1312,8 +1889,9 @@ example: @smallexample @group @b{shell%} @value{ROOTDIR}/sbin/kdb5_util -r @value{PRIMARYREALM} create -s -@b{kdb5_util: No such file or directory while setting active database to '/krb5/principal' -Initializing database '@value{ROOTDIR}/lib/krb5kdc/principal' for +@b{kdb5_util: No such file or directory while setting active database to +@result{} '@value{ROOTDIR}/var/krb5kdc/principal' +Initializing database '@value{ROOTDIR}/var/krb5kdc/principal' for @result{} realm '@value{PRIMARYREALM}', master key name 'K/M@@@value{PRIMARYREALM}' You will be prompted for the database Master Password. @@ -1404,7 +1982,8 @@ for the kadmin @code{list_principals} (@pxref{Retrieving a List of Principals}) command. @end table -For example: +For example (The line beginning with @result{} is a continuation of the +previous line.): @smallexample @group @@ -1418,10 +1997,11 @@ kadmin:} @smallexample @group -@b{kadmin:} ktadd -k /krb5/kadmind.keytab kadmin/admin kadmin/changepw +@b{kadmin:} ktadd -k @value{ROOTDIR}/var/krb5kdc/kadmind.keytab +@result{} kadmin/admin kadmin/changepw @b{kadmin: Entry for principal kadmin/admin@@@value{PRIMARYREALM} with kvno 3, encryption type DES-CBC-CRC added to keytab - WRFILE:/krb5/kadmind.keytab. + WRFILE:@value{ROOTDIR}/var/krb5kdc/kadmind.keytab. kadmin:} @end group @end smallexample @@ -1466,9 +2046,9 @@ For example: @smallexample @group -@b{kadmin:} ktremove -k /krb5/kadmind.keytab kadmin/admin +@b{kadmin:} ktremove -k @value{ROOTDIR}/var/krb5kdc/kadmind.keytab kadmin/admin @b{kadmin: Entry for principal kadmin/admin with kvno 3 removed - from keytab WRFILE:/krb5/kadmind.keytab. + from keytab WRFILE:@value{ROOTDIR}/var/krb5kdc/kadmind.keytab. kadmin:} @end group @end smallexample @@ -1503,7 +2083,7 @@ to set up a cron job that adjusts the time on a regular basis. Several aspects of Kerberos rely on name service. In order for Kerberos to provide its high level of security, it is less forgiving of name service problems than some other parts of your network. It is important -that your Distributed Name Service (DNS) entries and your hosts have the +that your Domain Name System (DNS) entries and your hosts have the correct information. Each host's canonical name must be the fully-qualified host name @@ -1528,8 +2108,8 @@ Here is a sample @code{/etc/hosts} file: @end smallexample Additionally, on Solaris machines, you need to be sure the ``hosts'' -entry in the file @code{/etc/nsswitch.conf} includes the source ``dns'' -as well as ``file''. +entry in the file @* @code{/etc/nsswitch.conf} includes the source +``dns'' as well as ``file''. Finally, each host's keytab file must include a host/key pair for the host's canonical name. You can list the keys in a keytab file by @@ -1627,7 +2207,7 @@ suggests that you have rules that specifically name these applications and, if possible, list the allowed hosts. A reasonably good cookbook for configuring firewalls is available by FTP -from @code{ftp.livingston.com}, in the location: +from @* @code{ftp.livingston.com}, in the location: @code{/pub/firewall/firewall-1.1.ps.Z}. The book @cite{UNIX System Security}, by David Curry, is also a good starting point. @@ -1677,174 +2257,17 @@ Database from a Dump File}.) @node Bug Reporting, Appendix, Backups of Secure Hosts, Top @chapter Bug Reporting -In any complex software, there will be bugs. 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). +@include send-pr.texinfo @node Appendix, , Bug Reporting, Top @appendix Appendix @menu -* Files:: -* krb5.conf:: -* kdc.conf:: * Errors:: * kadmin Time Zones:: @end menu -@node Files, krb5.conf, Appendix, Appendix -@appendixsec Files - -@node krb5.conf, kdc.conf, Files, Appendix -@appendixsec krb5.conf - -Normally, you should install your @code{krb5.conf} file in the directory -@code{/etc}. However, note that you can override this default through -the environment variable @samp{KRB5_CONFIG}. - -Here is an example of a generic @code{krb5.conf} file: - -@smallexample -@group -[libdefaults] - ticket_lifetime = 600 - default_realm = @value{PRIMARYREALM} - default_tkt_enctypes = des-cbc-crc - default_tgs_enctypes = des-cbc-crc - -[realms] - @value{PRIMARYREALM} = @{ - kdc = @value{KDCSERVER}.@value{PRIMARYDOMAIN}:88 - kdc = @value{KDCSLAVE1}.@value{PRIMARYDOMAIN}:88 - kdc = @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}:88 - admin_server = @value{KDCSERVER}.@value{PRIMARYDOMAIN}:749 - default_domain = @value{PRIMARYDOMAIN} - @} - @} - -[domain_realm] - .@value{PRIMARYDOMAIN} = @value{PRIMARYREALM} - @value{PRIMARYDOMAIN} = @value{PRIMARYREALM} - -[logging] - kdc = FILE:/dev/ttyp9 - admin_server = FILE:/dev/ttyp9 - default = FILE:/dev/ttyp9 -@end group -@end smallexample - -@iftex -@vfill -@end iftex -@page - -Here is an example of a more extensive @code{krb5.conf} file, which -includes a second Kerberos realm and authentication to Kerberos V4 as -well as V5 KDCs in the realm @code{@value{PRIMARYREALM}}: - -@smallexample -@group -[libdefaults] - ticket_lifetime = 600 - default_realm = @value{PRIMARYREALM} - default_tkt_enctypes = des-cbc-crc - default_tgs_enctypes = des-cbc-crc - krb4_srvtab = /etc/srvtab - krb4_config = /usr/krb4/lib/krb.conf - krb4_realms = /usr/krb4/lib/krb.realms - -[realms] - @value{PRIMARYREALM} = @{ - kdc = @value{KDCSERVER}.@value{PRIMARYDOMAIN}:88 - kdc = @value{KDCSLAVE1}.@value{PRIMARYDOMAIN}:88 - kdc = @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}:88 - admin_server = @value{KDCSERVER}.@value{PRIMARYDOMAIN}:749 - default_domain = @value{PRIMARYDOMAIN} - v4_instance_convert = @{ - bleep = @value{PRIMARYDOMAIN} - @} - @} - @value{SECONDREALM} = @{ - kdc = @value{KDCSERVER}.@value{SECONDDOMAIN} - kdc = @value{KDCSLAVE1}.@value{SECONDDOMAIN} - admin_server = @value{KDCSERVER}.@value{SECONDDOMAIN} - @} - -[domain_realm] - .@value{PRIMARYDOMAIN} = @value{PRIMARYREALM} - @value{PRIMARYDOMAIN} = @value{PRIMARYREALM} - .@value{SECONDDOMAIN} = @value{SECONDREALM} - @value{SECONDDOMAIN} = @value{SECONDREALM} -@end group -@end smallexample - -For the KDCs, add a section onto the end of the @code{krb5.conf} file -telling where the @code{kdc.conf} file is located, as in the following -example: - -@smallexample -@group -[kdc] - profile = @value{ROOTDIR}/lib/krb5kdc/kdc.conf - -[logging] - admin_server = FILE:@value{ROOTDIR}/lib/krb5kdc/kadmind.log - kdc = FILE:@value{ROOTDIR}/lib/krb5kdc/kdc.log - default = CONSOLE -@end group -@end smallexample - -@iftex -@vfill -@end iftex -@page - -@node kdc.conf, Errors, krb5.conf, Appendix -@appendixsec kdc.conf - -Normally, you should install your @code{kdc.conf} file in the directory -@code{@value{ROOTDIR}/lib/krb5kdc}. However, note that you can override -this default by a pointer in the KDC's @code{krb5.conf} file, or through -the environment variable @samp{KRB5_KDC_PROFILE}. - -Here's an example of a @code{kdc.conf} file: - -@smallexample -@group -[kdcdefaults] - kdc_ports = 88,750 - -[realms] - @value{PRIMARYREALM} = @{ - profile = /etc/krb5.conf - database_name = @value{ROOTDIR}/lib/krb5kdc/principal - admin_database_name = @value{ROOTDIR}/lib/krb5kdc/principal.kadm5 - admin_database_lockfile = @value{ROOTDIR}/lib/krb5kdc/principal.kadm5.lock - admin_keytab = @value{ROOTDIR}/lib/krb5kdc/kadm5.keytab - acl_file = @value{ROOTDIR}/lib/krb5kdc/kadm5.acl - dict_file = @value{ROOTDIR}/lib/krb5kdc/kadm5.dict - key_stash_file = @value{ROOTDIR}/lib/krb5kdc/.k5.@value{PRIMARYREALM} - kadmind_port = 749 - max_life = 10h 0m 0s - max_renewable_life = 7d 0h 0m 0s - master_key_type = des-cbc-crc - supported_enctypes = des-cbc-crc:normal - @} -@end group -@end smallexample - -To add Kerberos V4 support, change the @code{supported_enctypes} line to: - -@smallexample - supported_enctypes = des-cbc-crc:normal des-cbc-crc:v4 -@end smallexample - -@node Errors, kadmin Time Zones, kdc.conf, Appendix +@node Errors, kadmin Time Zones, Appendix, Appendix @appendixsec Kerberos Error Messages @menu @@ -1859,8 +2282,8 @@ To add Kerberos V4 support, change the @code{supported_enctypes} line to: @appendixsubsec Kerberos V5 Library Error Codes This is the Kerberos v5 library error code table. Protocol error codes -are ERROR_TABLE_BASE_krb5 + the protocol error code number; other error -codes start at ERROR_TABLE_BASE_krb5 + 128. +are @* ERROR_TABLE_BASE_krb5 + the protocol error code number; other +error codes start at ERROR_TABLE_BASE_krb5 + 128. @c error table numbering starts at 0 @enumerate 0 diff --git a/doc/build.texinfo b/doc/build.texinfo index 5852c06d0..bee77fe88 100644 --- a/doc/build.texinfo +++ b/doc/build.texinfo @@ -37,14 +37,18 @@ link tree for your build tree. The first step in each of these build procedures is to unpack the source distribution. The Kerberos V5 distribution comes in two compressed tar -files. The first file, which is generally named @file{krb5.src.tar.gz}, -contains the sources for all of Kerberos except for the crypto library, -which is found in the file @file{krb5.crypto.tar.gz}. +files. The first file, which is generally named +@file{krb5-1.0.src.tar.gz}, contains the sources for all of Kerberos +except for the crypto library, which is found in the file +@file{krb5-1.0.crypto.tar.gz}. Both files should be unpacked in the same directory, such as -@file{/u1/krb5}. (In the rest of this document, we will assume that you -have chosen to unpack the Kerberos V5 source distribution in this -directory.) +@file{/u1/krb5-1.0}. (In the rest of this document, we will assume that +you have chosen to unpack the Kerberos V5 source distribution in this +directory. Note that the tarfiles will by default all unpack into the +@file{./krb5-1.0} directory, so that if your current directory is +@file{/u1} when you unpack the tarfiles, you will get +@file{/u1/krb5-1.0/src}, etc.) @node Doing the Build, Testing the Build, Unpacking the Sources, Building Kerberos V5 @@ -73,7 +77,7 @@ use the following abbreviated procedure. @enumerate @item - @code{cd /u1/krb5/src} + @code{cd /u1/krb5-1.0/src} @item @code{./configure} @item @@ -96,9 +100,9 @@ you might use the following procedure: @enumerate @item -@code{mkdir /u1/krb5/pmax} +@code{mkdir /u1/krb5-1.0/pmax} @item - @code{cd /u1/krb5/pmax} + @code{cd /u1/krb5-1.0/pmax} @item @code{../src/configure} @item @@ -118,11 +122,11 @@ you might use the following procedure: @enumerate @item - @code{mkdir /u1/krb5/solaris} + @code{mkdir /u1/krb5-1.0/solaris} @item - @code{cd /u1/krb5/solaris} + @code{cd /u1/krb5-1.0/solaris} @item - @code{/u1/krb5/src/util/lndir `pwd`/../src} + @code{/u1/krb5-1.0/src/util/lndir `pwd`/../src} @item @code{./configure} @item @@ -148,9 +152,10 @@ building Kerberos; see @ref{Doing the Build}.): @menu * The DejaGnu Tests:: +* The KADM5 Tests:: @end menu -@node The DejaGnu Tests, , Testing the Build, Testing the Build +@node The DejaGnu Tests, The KADM5 Tests, Testing the Build, Testing the Build @subsection The DejaGnu Tests Some of the built-in regression tests are setup to use the DejaGnu @@ -158,24 +163,52 @@ framework for running tests. These tests tend to be more comprehensive than the normal built-in tests as they setup test servers and test client/server activities. -DejaGnu may be found wherever GNU software is archived. +DejaGnu may be found wherever GNU software is archived. -Most of the tests are setup to run as a non-privledged user. There are -two series of tests (@samp{rlogind} and @samp{telnetd}) which require -the ability to @samp{rlogin} as root to the local machine. Admittedly, -this does require the use of a @file{.rhosts} file or some other -authenticated means. @footnote{If you are fortunate enough to have a -previous version of Kerberos V5 or V4 installed, and the Kerberos rlogin -is first in your path, you can setup @file{.k5login} or @file{.klogin} -respectively to allow you access.} +Most of the tests are setup to run as a non-privledged user. For some +of the krb-root tests to work properly, either (a) the user running the +tests must not have a .k5login file in the home directory or (b) the +.k5login file must contain an entry for @code{@@KRBTEST.COM}. +There are two series of tests (@samp{rlogind} and @samp{telnetd}) which +require the ability to @samp{rlogin} as root to the local +machine. Admittedly, this does require the use of a @file{.rhosts} file +or some authenticated means. @footnote{If you are fortunate enough to +have a previous version of Kerberos V5 or V4 installed, and the Kerberos +rlogin is first in your path, you can setup @file{.k5login} or +@file{.klogin} respectively to allow you access.} If you cannot obtain root access to your machine, all the other tests will still run. Note however, with DejaGnu 1.2, the "untested testcases" will cause the testsuite to exit with a non-zero exit status which @samp{make} will consider a failure of the testing process. Do not worry about this, as these tests are the last run when @samp{make check} is -executed from the top level of the build tree. - +executed from the top level of the build tree. This problem does not +exist with DejaGnu 1.3. + +@node The KADM5 Tests, , The DejaGnu Tests, Testing the Build +@subsection The KADM5 Tests + +Regression tests for the KADM5 system, including the GSS-RPC, KADM5 +client and server libraries, and kpasswd, are also included in this +release. Each set of KADM5 tests is contained in a sub-directory called +@code{unit-test} directly below the system being tested. For example, +lib/rpc/unit-test contains the tests for GSS-RPC. The tests are all +based on DejaGnu (but they are not actually called part of "The DejaGnu +tests," whose naming predates the inclusion of the KADM5 system). In +addition, they require the Tool Command Language (TCL) header files and +libraries to be available during compilation and some of the tests also +require Perl in order to operate. If all of these resources are not +available during configuration, the KADM5 tests will not run. The TCL +installation directory can be specified with the @code{--with-tcl} +configure option (see @xref{Options to Configure}). The runtest and +perl programs must be in the current execution path. + +If you install DejaGnu, TCL, or Perl after configuring and building +Kerberos and then want to run the KADM5 tests, you will need to +re-configure the tree and run @code{make} at the top level again to make +sure all the proper programs are built. To save time, you actually only +need to reconfigure and build in the directories src/kadmin/testing, +src/lib/rpc, src/lib/kadm5, and src/kpasswd. @node Options to Configure, osconf.h, Testing the Build, Building Kerberos V5 @section Options to Configure @@ -192,17 +225,25 @@ program. Provides help to configure. This will list the set of commonly used options for building Kerberos. -@item --prefix=DIR +@item --prefix=PREFIX By default, Kerberos will install the package's files rooted at `/usr/local' as in `/usr/local/bin', `/usr/local/sbin', etc. If you -desire a different location use this option. +desire a different location, use this option. -@item --exec-prefix=DIR +@item --exec-prefix=EXECPREFIX This option allows one to separate the architecture independent programs from the configuration files and manual pages. +@item --localstatedir=LOCALSTATEDIR + +This option sets the directory for locally modifiable single-machine +data. In Kerberos, this mostly is useful for setting a location for the +KDC data files, as they will be installed in +@code{LOCALSTATEDIR/krb5kdc}, which is by default +@code{PREFIX/var/krb5kdc}. + @item --with-cc=COMPILER Use @code{COMPILER} as the C compiler. @@ -239,10 +280,11 @@ builtin Kerberos V4 library. @item --with-krb4=KRB4DIR -This option enables Kerberos V4 backwards compatibility. The directory -specified by @code{KRB4DIR} specifies where the V4 header files should -be found (@file{/KRB4DIR/include}) as well as where the V4 Kerberos -library should be found (@file{/KRB4DIR/lib}). +This option enables Kerberos V4 backwards compatibility using a +pre-existing Kerberos V4 installation. The directory specified by +@code{KRB4DIR} specifies where the V4 header files should be found +(@file{KRB4DIR/include}) as well as where the V4 Kerberos library should +be found (@file{KRB4DIR/lib}). @item --without-krb4 @@ -280,22 +322,12 @@ you're using slave servers!!! It also causes the database to be modified (and thus needing to be locked) frequently. Please note that the implementors do not regularly test this feature. -@item --with-kdb-db=database - -The configuration process will try to determine a working set of -libraries required to implement the Kerberos database. Configure will -look for interfaces that use or emulate a @samp{ndbm} or @samp{dbm} -library. Failing that, a build in copy of the Berkeley DB code will be -used. You may decide to compile a different interface than the default -by specifying one of "ndbm", "dbm", or "db". +@item --with-tcl=TCLPATH -An important note on platforms where the @samp{ndbm} implementation is -based on @sc{GDBM} (such as the Linux Slackware distribution). @sc{GDBM} -has its own built in file locking which prevents simultaneous access to -the database from two separate processes in which one wants to modify -the database while the otherone only wants to read. (i.e. the KDC and -administrative servers). In this case, you will need to specify the use -of the Berkeley DB. +Some of the unit-tests in the build tree rely upon using a program in +Tcl. The directory specified by @code{TCLPATH} specifies where the Tcl +header file (@file{TCLPATH/include/tcl.h} as well as where the Tcl +library should be found (@file{TCLPATH/lib}). @end table @@ -330,11 +362,6 @@ realms, their KDCs, etc. The profile file format is no longer the same format as Kerberos V4's @file{krb.conf} file. -@item DEFAULT_LNAME_FILENAME - -The pathname to the database that maps authentication names to local -account names. See kdb5_anadd(8). - @item DEFAULT_KEYTAB_NAME The type and pathname to the default server keytab file (the equivalent @@ -371,7 +398,7 @@ of the libraries may be installed on the same system and continue to work. Currently the supported platforms are: NetBSD 1.0A, AIX 3.2.5, AIX 4.1, -Solaris 5.3, Alpha OSF/1 >= 2.1, HP-UX >= 9.X. +Solaris 2.4 (aka SunOS 5.4), Alpha OSF/1 >= 2.1, HP-UX >= 9.X. To enable shared libraries on the above platforms, run the configure script with the option @samp{--enable-shared}. @@ -390,9 +417,10 @@ one in the tree or you will be missing references. @section Operating System Incompatibilities This section details operating system incompatibilities with Kerberos V5 -which have been reported to the developers at MIT. If you find additional -incompatibilities, and/or discover work arounds to such problems, please -send a report to @b{krb5-bugs@@mit.edu}. Thanks! +which have been reported to the developers at MIT. If you find +additional incompatibilities, and/or discover work arounds to such +problems, please send a report via the @code{krb5-send-pr} program. +Thanks! @menu * AIX:: @@ -503,10 +531,6 @@ LD_LIBRARY_PATH environment variable when you compile it. Alternatively you can use the @code{-i} option to @samp{cc}, by using the specifying @code{--with-ccopts=-i} option to @samp{configure}. -Shared library support only works when using the Sunsoft C compiler. We -are currently using version 3.0.1. (The latest GCC may work; this -needs to be tested.) - @node SGI Irix 5.X, Ultrix 4.2/3, Solaris 2.X, OS Incompatibilities @subsection SGI Irix 5.X @@ -581,7 +605,7 @@ that you have made a change that will require that all the @code{--force} option: @example -% cd /u1/krb5/src +% cd /u1/krb5-1.0/src % ./util/reconf --force @end example @@ -601,7 +625,7 @@ Then follow the instructions for building packaged source trees (above). To install the binaries into a binary tree, do: @example -% cd /u1/krb5/src +% cd /u1/krb5-1.0/src % make all % make install DESTDIR=somewhere-else @end example diff --git a/doc/copyright.texinfo b/doc/copyright.texinfo index a91a9ad6e..04601e203 100644 --- a/doc/copyright.texinfo +++ b/doc/copyright.texinfo @@ -23,9 +23,9 @@ It is provided ``as is'' without express or implied warranty. @vskip 12pt @end iftex -The following copyright and permission notice applies to the -OpenVision Kerberos Administration system located in kadmin/create, -kadmin/dbutil, kadmin/server, lib/kadm, and portions of lib/rpc: +The following copyright and permission notice applies to the OpenVision +Kerberos Administration system located in kadmin/create, kadmin/dbutil, +kadmin/passwd, kadmin/server, lib/kadm5, and portions of lib/rpc: @quotation Copyright, OpenVision Technologies, Inc., 1996, All Rights Reserved @@ -36,20 +36,22 @@ terms. If you do not agree to the following terms, do not retrieve the OpenVision Kerberos administration system. You may freely use and distribute the Source Code and Object Code -compiled from it, but this Source Code is provided to you "AS IS" -EXCLUSIVE OF ANY WARRANTY, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES -OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, OR ANY OTHER -WARRANTY, WHETHER EXPRESS OR IMPLIED. IN NO EVENT WILL OPENVISION HAVE -ANY LIABILITY FOR ANY LOST PROFITS, LOSS OF DATA OR COSTS OF PROCUREMENT -OF SUBSTITUTE GOODS OR SERVICES, OR FOR ANY SPECIAL, INDIRECT, OR -CONSEQUENTIAL DAMAGES ARISING OUT OF THIS AGREEMENT, INCLUDING, WITHOUT -LIMITATION, THOSE RESULTING FROM THE USE OF THE SOURCE CODE, OR THE -FAILURE OF THE SOURCE CODE TO PERFORM, OR FOR ANY OTHER REASON. +compiled from it, with or without modification, but this Source Code is +provided to you "AS IS" EXCLUSIVE OF ANY WARRANTY, INCLUDING, WITHOUT +LIMITATION, ANY WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A +PARTICULAR PURPOSE, OR ANY OTHER WARRANTY, WHETHER EXPRESS OR IMPLIED. +IN NO EVENT WILL OPENVISION HAVE ANY LIABILITY FOR ANY LOST PROFITS, +LOSS OF DATA OR COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR +FOR ANY SPECIAL, INDIRECT, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THIS +AGREEMENT, INCLUDING, WITHOUT LIMITATION, THOSE RESULTING FROM THE USE +OF THE SOURCE CODE, OR THE FAILURE OF THE SOURCE CODE TO PERFORM, OR FOR +ANY OTHER REASON. -OpenVision retains all rights, title, and interest in the donated Source -Code. With respect to OpenVision's copyrights in the donated Source -Code, OpenVision also retains rights to derivative works of the Source -Code whether created by OpenVision or a third party. +OpenVision retains all copyrights in the donated Source Code. OpenVision +also retains copyright to derivative works of the Source Code, whether +created by OpenVision or by a third party. The OpenVision copyright +notice must be preserved if derivative works are made based on the +donated Source Code. OpenVision Technologies, Inc. has donated this Kerberos Administration system to MIT for inclusion in the standard Kerberos 5 distribution. diff --git a/doc/definitions.texinfo b/doc/definitions.texinfo index 93cc3b9a1..19b2b0f55 100644 --- a/doc/definitions.texinfo +++ b/doc/definitions.texinfo @@ -23,8 +23,8 @@ @set PREVRELEASE beta 7 @set INSTALLDIR /usr/@value{LCPRODUCT} @set PREVINSTALLDIR @value{INSTALLDIR} -@set ROOTDIR /usr/@value{LCPRODUCT} -@set BINDIR /usr/@value{LCPRODUCT}/bin +@set ROOTDIR /usr/local +@set BINDIR /usr/local/bin @set SECONDDOMAIN fubar.org @set SECONDREALM FUBAR.ORG @set UPDATED @today diff --git a/doc/install.texinfo b/doc/install.texinfo index 216abf974..f5c4396a8 100644 --- a/doc/install.texinfo +++ b/doc/install.texinfo @@ -16,7 +16,7 @@ @end iftex @include definitions.texinfo -@set EDITION b7-1 +@set EDITION 1.0 @finalout @c don't print black warning boxes @@ -123,10 +123,17 @@ installation procedure is somewhat involved, and requires forethought and planning. @value{COMPANY} has attempted to make this @value{PRODUCT} Installation Guide as concise as possible, rather than making it an exhaustive description of the details of Kerberos. +@ifset CYGNUS Consequently, everything in this guide appears because @value{COMPANY} believes that it is important. Please read and follow these instructions carefully, and if there is anything you do not understand or are not sure of, please don't hesitate to call us. +@end ifset +@ifset MIT +Consequently, everything in this guide appears because @value{COMPANY} +believes that it is important. Please read and follow these +instructions carefully. +@end ifset @node Overview of This Guide, , Please Read the Documentation, Introduction @section Overview of This Guide @@ -134,7 +141,7 @@ or are not sure of, please don't hesitate to call us. The next chapter describes the decisions you need to make before installing @value{PRODUCT}. -Chapter three describes installation procedures for each class of +Chapter four describes installation procedures for each class of Kerberos machines: @enumerate @@ -150,28 +157,20 @@ Slave KDCs. @end enumerate @item -Client machines (user machines): - -@enumerate A -@item -UNIX client machines. - -@item -Windows machines. - -@item -Macintoshes. -@end enumerate +UNIX client machines @item -application server machines +UNIX application server machines @end enumerate @noindent Note that a machine can be both a client machine and an application server. -Chapter four describes our problem reporting system. +Chapter five describes procedure for updating previous installations of +@value{PRODUCT}. + +Chapter six describes our problem reporting system. The appendices give sample configuration files. @@ -225,7 +224,7 @@ Kerberos realm @value{SECONDREALM}. If you need multiple Kerberos realms, @value{COMPANY} recommends that you use descriptive names which end with your domain name, such as -BOSTON.@value{SECONDREALM} and SAN_FRANCISCO.@value{SECONDREALM}. +BOSTON.@value{SECONDREALM} and HOUSTON.@value{SECONDREALM}. @node Mapping Hostnames onto Kerberos Realms, Ports for the KDC and Admin Services, Kerberos Realms, Realm Configuration Decisions @section Mapping Hostnames onto Kerberos Realms @@ -237,6 +236,12 @@ hostname-by-hostname basis. Since greater specificity takes precedence, you would do this by specifying the mappings for a given domain or subdomain and listing the exceptions. +The @value{PRODUCT} System Administrator's Guide contains a thorough +description of the parts of the @code{krb5.conf} file and what may be +specified in each. A sample @code{krb5.conf} file appears in +@ref{krb5.conf}. You should be able to use this file, substituting the +relevant information for your Kerberos instllation for the samples. + @node Ports for the KDC and Admin Services, Slave KDCs, Mapping Hostnames onto Kerberos Realms, Realm Configuration Decisions @section Ports for the KDC and Admin Services @@ -271,9 +276,10 @@ Have at least one slave KDC as a backup, for when the master KDC is down, is being upgraded, or is otherwise unavailable. @item -If your network is split such that a network outage is likely to cause -some segment or segments of the network to become cut off or isolated, -have a slave KDC accessible to each segment. +If your network is split such that a network outage is likely to cause a +network partition (some segment or segments of the network to become cut +off or isolated from other segments), have a slave KDC accessible to +each segment. @item If possible, have at least one slave KDC in a different building from @@ -304,7 +310,7 @@ effect. If the propagation time is longer than this maximum reasonable time (@i{e.g.,} you have a particularly large database, you have a lot of -slaves, and/or you experience frequent network delays), you may wish to +slaves, or you experience frequent network delays), you may wish to cut down on your propagation delay by performing the propagation in parallel. To do this, have the master KDC propagate the database to one set of slaves, and then have each of these slaves propagate the database @@ -325,20 +331,9 @@ The sections of this chapter describe procedures for installing @item The KDCs -@item -Client machines - -@enumerate A @item UNIX client machines -@item -Windows machines - -@item -Macintoshes -@end enumerate - @item UNIX Application Servers @end enumerate @@ -359,12 +354,12 @@ regular intervals. All database changes (such as password changes) are made on the master KDC. Slave KDCs provide Kerberos ticket-granting services, but not database -access. This allows clients to continue to obtain tickets when the -master KDC is unavailable. +administration. This allows clients to continue to obtain tickets when +the master KDC is unavailable. -@value{COMPANY}'s recommends that you install all of your KDCs to be -able to function as either the master or one of the slaves. This will -enable you to easily switch your master KDC with one of the slaves if +@value{COMPANY} recommends that you install all of your KDCs to be able +to function as either the master or one of the slaves. This will enable +you to easily switch your master KDC with one of the slaves if necessary. (@xref{Switching Master and Slave KDCs}.) This installation procedure is based on that recommendation. @@ -401,9 +396,20 @@ Modify the configuration files, @code{/etc/krb5.conf} (@pxref{krb5.conf}) and @code{@value{ROOTDIR}/var/krb5kdc/kdc.conf} (@pxref{kdc.conf}) to reflect the correct information (such as the hostnames and realm name) for your realm. @value{COMPANY} recommends -that you keep @code{krb5.conf} in @code{/etc}. The @code{krb5.conf} -file may contain a pointer to @code{kdc.conf}, which you need to change -if you want to move @code{kdc.conf} to another location. +that you keep @code{krb5.conf} in @code{/etc}. + +Among the settings in your @code{/etc/krb5.conf} file, be sure to create +a @code{[logging]} stanza so that the KDC and kadmind will generate +logging output. For example: + +@smallexample +@group +[logging] + kdc = FILE:/var/log/krb5kdc.log + admin_server = FILE:/var/log/kadmin.log + default = FILE:/var/log/krb5lib.log +@end group +@end smallexample @node Create the Database, Add Administrators to the Acl File, Edit the Configuration Files, Install the Master KDC @subsubsection Create the Database @@ -430,11 +436,10 @@ words that can be found in a dictionary, any common or popular name, especially a famous person (or cartoon character), your username in any form (@i{e.g.}, forward, backward, repeated twice, @i{etc.}), and any of the sample keys that appear in this manual. One example of a key which -would be good if it did not appear in this manual is ``MITiys4K5!'', -which represents the sentence ``@value{COMPANY} is your source for -Kerberos 5!'' (It's the first letter of each word, substituting the -numeral ``4'' for the word ``for'', and includes the punctuation mark at -the end.) +might be good if it did not appear in this manual is ``MITiys4K5!'', +which represents the sentence ``MIT is your source for Kerberos 5!'' +(It's the first letter of each word, substituting the numeral ``4'' for +the word ``for'', and includes the punctuation mark at the end.) The following is an example of how to create a Kerberos database and stash file on the master KDC, using the @code{kdb5_util} command. (The @@ -554,7 +559,10 @@ instance ``root'', you would add the following line to the acl file: Next you need to add administrative principals to the Kerberos database. (You must add at least one now.) To do this, use @code{kadmin.local} -@emph{on the master KDC}, as in the following example: +@emph{on the master KDC}. The administrative principals you create +should be the ones you added to the ACL file (see @xref{Add +Administrators to the Acl File}). In the following example, the +administration principal @code{admin/admin} is created: @smallexample @group @@ -575,6 +583,8 @@ kadmin.local:} @end group @end smallexample + + @node Create a kadmind Keytab, Start the Kerberos Daemons, Add Administrators to the Kerberos Database, Install the Master KDC @subsubsection Create a kadmind Keytab @@ -606,7 +616,7 @@ kadmin.local:} quit @noindent As specified in the @samp{-k} argument, @code{ktadd} will save the -extracted keytab as @code{@value{ROOTDIR}/var/krb5kdc/kadm5.keytab}. +extracted keytab as @* @code{@value{ROOTDIR}/var/krb5kdc/kadm5.keytab}. The filename you use must be the one specified in your @code{kdc.conf} file. @@ -628,6 +638,21 @@ these daemons to start up automatically at boot time, you can add them to the KDC's @code{/etc/rc} or @code{/etc/inittab} file. You need to have a stash file in order to do this. +You can verify that they started properly by checking for their startup +messages in the logging locations you defined in @code{/etc/krb5.conf} +(see @xref{Edit the Configuration Files}). For example: + +@smallexample +@b{shell%} tail /var/log/krb5kdc.log +Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation +@b{shell%} tail /var/log/kadmin.log +Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting +@end smallexample + +Any errors the daemons encounter while starting will also be listed in +the logging output. + + @node Install the Slave KDCs, Back on the Master KDC, Install the Master KDC, Installing KDCs @subsection Install the Slave KDCs @@ -657,15 +682,15 @@ named @value{KDCSLAVE1}.@value{PRIMARYDOMAIN} and @smallexample @group @b{shell%} @value{ROOTDIR}/sbin/kadmin -@b{kadmin:} addprinc -randpass host/@value{KDCSERVER}.@value{PRIMARYDOMAIN} +@b{kadmin:} addprinc -randkey host/@value{KDCSERVER}.@value{PRIMARYDOMAIN} @b{WARNING: no policy specified for "host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}"; defaulting to no policy. Principal "host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created. -kadmin:} addprinc -randpass host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN} +kadmin:} addprinc -randkey host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN} @b{WARNING: no policy specified for "host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}"; defaulting to no policy. Principal "host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created.} -@b{kadmin:} addprinc -randpass host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN} +@b{kadmin:} addprinc -randkey host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN} @b{WARNING: no policy specified for "host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}"; defaulting to no policy. Principal "host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created. @@ -758,8 +783,8 @@ KDC: kerberos 88/udp kdc # Kerberos authentication (udp) kerberos 88/tcp kdc # Kerberos authentication (tcp) krb5_prop 754/tcp # Kerberos slave propagation -kerberos-adm 749/tcp # Kerberos 5 admin/changepw (tcp) -kerberos-adm 749/udp # Kerberos 5 admin/changepw (udp) +kerberos-adm 749/tcp # Kerberos 5 admin/changepw (tcp) +kerberos-adm 749/udp # Kerberos 5 admin/changepw (udp) eklogin 2105/tcp # Kerberos encrypted rlogin @end group @end smallexample @@ -1350,7 +1375,8 @@ terminology. @node Bug Reports for Kerberos V5, Files, Upgrading Existing Kerberos V5 Installations, Top @chapter Bug Reports for @value{PRODUCT} -@include bug-report.texinfo + +@include send-pr.texinfo @node Files, , Bug Reports for Kerberos V5, Top @appendix Files diff --git a/doc/krb425.texinfo b/doc/krb425.texinfo index 2ff2b3ec8..e78d4e6ac 100644 --- a/doc/krb425.texinfo +++ b/doc/krb425.texinfo @@ -3,11 +3,11 @@ @c definitions added by jcb. @c %**start of header @c guide -@setfilename Kerberos-V4-to-V5.info +@setfilename krb425.info @settitle Upgrading to Kerberos V5 from Kerberos V4 -@c @setchapternewpage odd @c chapter begins on next odd page -@setchapternewpage on @c chapter begins on next page -@smallbook @c Format for 7" X 9.25" paper +@setchapternewpage odd @c chapter begins on next odd page +@c @setchapternewpage on @c chapter begins on next page +@c @smallbook @c Format for 7" X 9.25" paper @c %**end of header @paragraphindent 0 @@ -16,7 +16,7 @@ @end iftex @include definitions.texinfo -@set EDITION 0.1 alpha +@set EDITION 1.0 @set UPDATED October 8, 1996 @finalout @c don't print black warning boxes @@ -34,15 +34,13 @@ @include copyright.texinfo @end titlepage -@node Top, Introduction, (dir), (dir) +@node Top, Copyright, (dir), (dir) @ifinfo This document describes how to convert to @value{PRODUCT} from Kerberos V4. -@include copyright.texinfo -@end ifinfo - @menu +* Copyright:: * Introduction:: * Configuration Files:: * Upgrading KDCs:: @@ -51,7 +49,13 @@ This document describes how to convert to @value{PRODUCT} from Kerberos V4. * Firewall Considerations:: @end menu -@node Introduction, Configuration Files, Top, Top +@node Copyright, Introduction, Top, Top +@unnumbered Copyright +@include copyright.texinfo + +@end ifinfo + +@node Introduction, Configuration Files, Copyright, Top @chapter Introduction As with most software upgrades, @value{PRODUCT} is generally backward @@ -173,7 +177,7 @@ Create a dump of the V4 database in the directory where your V5 database will reside by issuing the command: @smallexample -% kdb_util dump @value{INSTALLDIR}/lib/krb5kdc/v4-dump +% kdb_util dump @value{ROOTDIR}/var/krb5kdc/v4-dump @end smallexample @item @@ -266,6 +270,7 @@ telnet stream tcp nowait root @end group @end smallexample +@ifset CYGNUS @strong{N.B.}: As noted in the @value{PRODUCT} Installation Guide, if you have some clients running older versions of Kerberos V5 (beta 6@footnote{@value{PRODUCT} is based on the MIT beta 7 release.} or @@ -273,6 +278,15 @@ earlier), checksums were done differently in those versions, which will cause authentication to fail. To get around this problem, have the @code{klogind} and @code{kshd} daemons ignore checksums, by replacing each @code{-c} flag above with @code{-i}. +@end ifset +@ifclear CYGNUS +@strong{N.B.}: As noted in the @value{PRODUCT} Installation Guide, if +you have some clients running older versions of Kerberos V5 (beta 6 or +earlier), checksums were done differently in those versions, which will +cause authentication to fail. To get around this problem, have the +@code{klogind} and @code{kshd} daemons ignore checksums, by replacing +each @code{-c} flag above with @code{-i}. +@end ifclear For an @emph{insecure} server, make the changes described in the @value{PRODUCT} Installation Guide. @@ -288,7 +302,7 @@ follows: @group @b{#} @value{ROOTDIR}/sbin/ktutil @b{ktutil:} rst /etc/krb-srvtab -@b{ktutil:} wkt /etc/v5srvtab +@b{ktutil:} wkt /etc/krb5.keytab @b{ktutil:} q @b{#} @end group diff --git a/doc/krb5-protocol/krb5.constants b/doc/krb5-protocol/krb5.constants index ed70559fa..e7cc5b80e 100644 --- a/doc/krb5-protocol/krb5.constants +++ b/doc/krb5-protocol/krb5.constants @@ -13,6 +13,8 @@ des-cbc-md4 2 8 0 8 des-cbc-md5 3 8 0 8 4 des3-cbc-md5 5 8 0 8 + 6 +des3-cbc-sha1 7 8 0 8 0x8003 -------------------------------+-------------------+------------- @@ -26,7 +28,10 @@ des-mac-k 5 8 rsa-md4-des-k 6 16 rsa-md5 7 16 rsa-md5-des 8 24 -rsa-md5-des3 9 24 + 9 + 10 +nist-sha1 11 20 +hmac-sha1-des3 12 20 -------------------------------+----------------- padata type |padata-type value @@ -42,6 +47,8 @@ PA-OSF-DCE 8 PA-CYBERSAFE-SECUREID 9 PA-AFS3-SALT 10 PA-ETYPE-INFO 11 +PAM-SAM-CHALLENGE 12 +PAM-SAM-RESPONSE 13 -------------------------------+------------- authorization data type |ad-type value @@ -120,6 +127,7 @@ KDC_ERR_KEY_EXPIRED 23 Password has expired - change to reset KDC_ERR_PREAUTH_FAILED 24 Pre-authentication information was invalid KDC_ERR_PREAUTH_REQUIRED 25 Additional pre-authentication required* KDC_ERR_SERVER_NOMATCH 26 Requested server and ticket don't match +KDC_ERR_MUST_USE_USER2USER 27 Server principal valid for user2user only KRB_AP_ERR_BAD_INTEGRITY 31 Integrity check on decrypted field failed KRB_AP_ERR_TKT_EXPIRED 32 Ticket expired KRB_AP_ERR_TKT_NYV 33 Ticket not yet valid diff --git a/doc/send-pr.texinfo b/doc/send-pr.texinfo index 628b14192..9209ffd56 100644 --- a/doc/send-pr.texinfo +++ b/doc/send-pr.texinfo @@ -1,88 +1,75 @@ -If you have problems installing @value{PRODUCT}, please use the -@code{send-pr} program to fill out a Problem Report. +In any complex software, there will be bugs. If you have successfully +built and installed @value{PRODUCT}, please use the +@code{krb5-send-pr} program to fill out a Problem Report. -The @code{send-pr} program is installed in the directory -@code{@value{ROOTDIR}/bin}. - -@need 1100 -Before using @code{send-pr} for the first time, you need to install your -customer support ID into the program, by typing the command: - -@smallexample -@b{shell%} install-sid @i{customerID} -@end smallexample +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). -@noindent replacing @i{customerID} with your customer ID, which your -sales representative will supply. +The @code{krb5-send-pr} program is installed in the directory +@code{@value{ROOTDIR}/sbin}. -The @code{send-pr} program enters the problem report into our Problem -Report Management System (PRMS), which automatically assigns it to the -engineer best able to help you with problems in the assigned category. +The @code{krb5-send-pr} program enters the problem report into our +Problem Report Management System (PRMS), which automatically assigns it +to the engineer best able to help you with problems in the assigned +category. +@ifset CYGNUS The engineer will work with you via email, telephone, or both, and all email related to this Problem Report will be tracked by PRMS for future -reference. If the engineer does not reply to you after a certain time, -a reminder is automatically generated. If you need to talk to someone -else in our organization about the problem (@i{e.g.}, if the engineer -gets hit by a truck), we can find out what the current state is through -the PR number. @value{COMPANY} uses PRMS for almost all of the real -problems we handle. - -The @code{send-pr} program will try to intelligently fill in as many -fields as it can. You need to choose the @dfn{category}, @dfn{class}, -@dfn{severity}, and @dfn{priority} of the problem, as well as giving us -as much information as you can about its exact nature. +reference. If you need to talk to someone else in our organization +about the problem (@i{e.g.}, if the engineer gets hit by a truck), we +can find out what the current state is through the PR number. +@end ifset + +The @code{krb5-send-pr} program will try to intelligently fill in as +many fields as it can. You need to choose the @dfn{category}, +@dfn{class}, @dfn{severity}, and @dfn{priority} of the problem, as well +as giving us as much information as you can about its exact nature. @need 1000 The PR @b{category} will be one of: @smallexample @group -kerberos kerbnet doc help-request -info-request install query-pr id-request -send-pr +krb5-admin krb5-appl krb5-build krb5-clients +krb5-doc krb5-kdc krb5-libs krb5-misc +pty telnet test @end group @end smallexample -In general, if specific knowledge about Kerberos is requried to answer a -PR, use the @i{kerberos} or @i{doc} categories. The @i{install} -category is for problems retrieving the code off the media (@i{e.g.}, -the data on a tape seems to be corrupted.) Questions about the -installation procedures described in this document would fall under the -category @i{kerberos}. The @i{help-request} and @i{info-request} -categories are for general questions about your contract, or other -issues not necessarily related to @value{PRODUCT}. Use @i{query-pr} to -receive a current copy of your Problem Report, @i{id-request} if you -need a customer ID, and @i{send-pr} if you're having trouble using -send-pr. If your question is related to @value{PRODUCT} and you're not -sure what the most appropriate category should be, use @i{kerberos}. -The engineer can change the category if necessary. +@noindent +Choose the category that best describes the area under which your +problem falls. The @b{class} can be @dfn{sw-bug}, @dfn{doc-bug}, @dfn{change-request}, -or @dfn{support}. The first two are exactly as their names imply. The -@i{change-request} class is to inform us of changes, such as new email -addresses or new contact information. The @i{support} class is intended -for general questions about using the @value{PRODUCT} clients or -libraries. +or @dfn{support}. The first two are exactly as their names imply. Use +@i{change-request} when the software is behaving according to +specifications, but you want to request changes in some feature or +behavior. The @i{support} class is intended for more general questions +about building or using @value{PRODUCT}. The @b{severity} of the problem indicates the problem's impact on the -usability of the @value{PRODUCT} software package. If a problem is -@dfn{critical}, that means the product, component or concept is -completely non-operational, or some essential functionality is missing, -and no workaround is known. A @dfn{serious} problem is one in which the -product, component or concept is not working properly or significant -functionality is missing. Problems that would otherwise be considered -@i{critical} are rated @i{serious} when a workaround is known. A -@dfn{non-critical} problem is one that is indeed a problem, but one that -is having a minimal affect on your ability to use @value{PRODUCT}. -@i{E.g.}, The product, component or concept is working in general, but -lacks features, has irritating behavior, does something wrong, or -doesn't match its documentation. The default severity is @i{serious}. +usability of @value{PRODUCT}. If a problem is @dfn{critical}, that +means the product, component or concept is completely non-operational, +or some essential functionality is missing, and no workaround is known. +A @dfn{serious} problem is one in which the product, component or +concept is not working properly or significant functionality is missing. +Problems that would otherwise be considered @i{critical} are rated +@i{serious} when a workaround is known. A @dfn{non-critical} problem is +one that is indeed a problem, but one that is having a minimal effect on +your ability to use @value{PRODUCT}. @i{E.g.}, The product, component +or concept is working in general, but lacks features, has irritating +behavior, does something wrong, or doesn't match its documentation. The +default severity is @i{serious}. The @b{priority} indicates how urgent this particular problem is in relation to your work. Note that low priority does not imply low -importance. @value{COMPANY} considers all problems important, and -encourages its customers to be realistic about priority ratings. A -priority of @dfn{high} means a solution is needed as soon as possible. +importance. +@ifset CYGNUS +@value{COMPANY} considers all problems important, and +encourages its customers to be realistic about priority ratings. +@end ifset +A priority of @dfn{high} means a solution is needed as soon as possible. A priority of @dfn{medium} means the problem should be solved no later than the next release. A priority of @dfn{low} means the problem should be solved in a future release, but it is not important to your work how @@ -94,10 +81,8 @@ you are faced with a hard deadline. Conversely, a serious problem might have a low priority if the feature it is disabling is one that you do not need. -The @b{release} is as labeled on the software that was shipped. -@i{e.g.}, @code{kerbnet-@value{RELEASE}}. It is important that you tell -us which release you are using, and whether or not you have made any -private changes. +It is important that you fill in the @i{release} field and tell us +what changes you have made, if any. Bug reports that include proposed fixes are especially welcome. If you include proposed fixes, please send them using either context diffs @@ -113,50 +98,35 @@ look like this: @smallexample @group -To: bugs@@cygnus.com -Subject: "KDC reply did not match expectations" error -From: joe.smith@@toasters.com -Reply-To: joe.smith@@toasters.com -X-send-pr-version: 3.97-96q1 - ->Submitter-Id: toastersinc ->Confidential: yes ->Originator: Joe Smith (+1 415 903 1400) ->Organization: ------ -Joe Smith joe.smith@@toasters.com -Toasters, Inc. - ``The best UI in the world'' +To: krb5-bugs@@mit.edu +Subject: misspelled "Kerberos" in title of installation guide +From: jcb +Reply-To: jcb +Cc: +X-send-pr-version: 3.99 ->Synopsis: "KDC reply did not match expectations" error message + +>Submitter-Id: mit +>Originator: Jeffrey C. Gilman Bigler +>Organization: +mit +>Confidential: no +>Synopsis: Misspelled "Kerberos" in title of installation guide >Severity: non-critical >Priority: low ->Category: kerberos ->Class: sw-bug ->Release: kerbnet-1.0 +>Category: krb5-doc +>Class: doc-bug +>Release: 1.0-development >Environment: -NetBSD viola 1.1 NetBSD 1.1 (ATHENAADP) #0: Tue May 21 00:31:42 EDT 1996 -i386 -System: Intel P166 -Architecture: NetBSD - + +System: ULTRIX imbrium 4.2 0 RISC +Machine: mips >Description: - - Getting "KDC reply did not match expectations" message. This - does not seem to be affecting anything else. - + Misspelled "Kerberos" in title of "Kerboros V5 Installation Guide" >How-To-Repeat: - - - - - - It happens when I type kinit. - + N/A >Fix: - - - None. Sorry. + Correct the spelling. @end group @end smallexample @@ -164,40 +134,7 @@ Architecture: NetBSD @vfill @end iftex -@page -If the @code{send-pr} program does not work for you, you can use the -following template instead: - -@smallexample -@group -To: bugs@@cygnus.com -Subject: -From: -Reply-To: -X-send-pr-version: none (typed manually) - ->Submitter-Id: ->Originator: ->Organization: - ->Confidential: <[ yes | no ] (one line)> ->Synopsis: ->Severity: <[ non-critical | serious | critical ] (one line)> ->Priority: <[ low | medium | high ] (one line)> ->Category: ->Class: <[ sw-bug | doc-bug | change-request | support ] (one line)> ->Release: cns-9?q? ->Environment: - -System: -Architecture: - - ->Description: - ->How-To-Repeat: - ->Fix: - -@end group -@end smallexample +If the @code{krb5-send-pr} program does not work for you, or if you did +not get far enough in the process to have an installed and working +@code{krb5-send-pr}, you can generate your own form, using the above as +an example. diff --git a/doc/user-guide.texinfo b/doc/user-guide.texinfo index d068396c3..c60be114b 100644 --- a/doc/user-guide.texinfo +++ b/doc/user-guide.texinfo @@ -14,7 +14,7 @@ @end iftex @include definitions.texinfo -@set EDITION b7-1 +@set EDITION 1.0 @finalout @c don't print black warning boxes @@ -67,9 +67,15 @@ This file describes how to use the @value{PRODUCT} client programs. @node Introduction, Kerberos V5 Tutorial, Copyright, Top @chapter Introduction +@ifset CYGNUS @value{PRODUCT} is based on the Kerberos V5 authentication system -developed at MIT. Kerberos is named for the three-headed watchdog from -Greek mythology, who guarded the entrance to the underworld. +developed at MIT. +@end ifset +@ifset MIT +Kerberos V5 is an authentication system developed at MIT. +@end ifset +Kerberos is named for the three-headed watchdog from Greek mythology, +who guarded the entrance to the underworld. Under Kerberos, a client (generally either a user or a service) sends a request for a ticket to the @i{Key Distribution Center} (KDC). The KDC @@ -98,10 +104,6 @@ used to. @value{PRODUCT} is a @dfn{single-sign-on} system, which means that you have to type your password only once per session, and Kerberos does the authenticating and encrypting transparently. -@iftex -@vfil -@end iftex -@need 2000 @menu * What is a Ticket?:: * What is a Kerberos Principal?:: @@ -130,10 +132,6 @@ new resort. The difference is that the @value{PRODUCT} programs notice that you have the weekend ski pass, and get the lift ticket for you, so you don't have to perform the transactions yourself. -@iftex -@vfil -@end iftex -@need 2000 @node What is a Kerberos Principal?, , What is a Ticket?, Introduction @section What is a Kerberos Principal? @@ -166,7 +164,7 @@ the realm @code{@value{PRIMARYREALM}}. @end itemize @node Kerberos V5 Tutorial, Kerberos V5 Reference, Introduction, Top -@chapter @value{PRODUCT} Tutorial +@chapter Kerberos V5 Tutorial This tutorial is intended to familiarize you with the @value{PRODUCT} client programs. We will represent your prompt as ``@code{shell%}''. @@ -215,7 +213,7 @@ versions, when you type their command names. On many systems, Kerberos is built into the login program, and you get tickets automatically when you log in. Other programs, such as -/@code{rsh}, @code{rcp}, @code{telnet}, and @code{rlogin}, can forward +@code{rsh}, @code{rcp}, @code{telnet}, and @code{rlogin}, can forward copies of your tickets to the remote host. Most of these programs also automatically destroy your tickets when they exit. However, @value{COMPANY} recommends that you explicitly destroy your Kerberos @@ -336,10 +334,6 @@ in an error. Note also that most systems specify a maximum ticket lifetime. If you request a longer ticket lifetime, it will be automatically truncated to the maximum lifetime. -@iftex -@vfil -@end iftex -@need 3000 @node Viewing Your Tickets with klist, Destroying Your Tickets with kdestroy, Obtaining Tickets with kinit, Ticket Management @subsection Viewing Your Tickets with klist @@ -397,9 +391,6 @@ host ticket for the host ticket, which telnet then presented to the host @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}, and she was allowed to log in without typing her password. -@iftex -@vfil -@end iftex @need 3000 Suppose your Kerberos tickets allow you to log into a host in another @@ -488,10 +479,6 @@ shell%} @end group @end smallexample -@iftex -@vfil -@end iftex -@need 2000 @node Destroying Your Tickets with kdestroy, , Viewing Your Tickets with klist, Ticket Management @subsection Destroying Your Tickets with kdestroy @@ -524,10 +511,6 @@ shell%} @end group @end smallexample -@iftex -@vfil -@end iftex -@need 2000 @node Password Management, Kerberos V5 Applications, Ticket Management, Kerberos V5 Tutorial @section Password Management @@ -544,10 +527,6 @@ administrator, for any reason. You should change your password frequently, particularly any time you think someone may have found out what it is. -@iftex -@vfil -@end iftex -@need 2000 @menu * Changing Your Password:: * Password Advice:: @@ -613,11 +592,7 @@ this might be anywhere from a few minutes to an hour or more. If you need to get new Kerberos tickets shortly after changing your password, try the new password. If the new password doesn't work, try again using the old one. -@iftex -@vfil -@end iftex -@need 2000 @node Password Advice, Granting Access to Your Account, Changing Your Password, Password Management @subsection Password Advice @@ -650,9 +625,6 @@ listed in this manual include: @noindent Note: don't actually use any of the above passwords. They're only meant to show you how to make up a good password. Passwords that appear in a manual are the first ones intruders will try. -@iftex -@vfil -@end iftex @need 3800 @value{PRODUCT} allows your system administrators to automatically @@ -683,10 +655,6 @@ shell%} displayed if you choose a bad password, so the message you see may be different from the above example. -@iftex -@vfil -@end iftex -@need 2000 @node Granting Access to Your Account, , Password Advice, Password Management @subsection Granting Access to Your Account @@ -736,13 +704,8 @@ users to become root locally, or to log in remotely as @code{root}, without their having to give out the root password, and without anyone having to type the root password over the network. -@iftex -@vfil -@end iftex -@need 2000 - @node Kerberos V5 Applications, , Password Management, Kerberos V5 Tutorial -@section @value{PRODUCT} Applications +@section Kerberos V5 Applications @value{PRODUCT} is a @dfn{single-sign-on} system. This means that you only have to type your password once, and the @value{PRODUCT} programs @@ -758,10 +721,6 @@ space of a few seconds. The @value{PRODUCT} applications are versions of existing UNIX network programs with the Kerberos features added. -@iftex -@vfil -@end iftex -@need 2000 @menu * Overview of Additional Features:: * telnet:: @@ -795,10 +754,6 @@ This section of the tutorial assumes you are familiar with the non-Kerberos versions of these programs, and highlights the Kerberos functions added in the @value{PRODUCT} package. -@iftex -@vfil -@end iftex -@need 2000 @node telnet, rlogin, Overview of Additional Features, Kerberos V5 Applications @subsection telnet @@ -841,10 +796,6 @@ turns on encryption. turns off encryption. @end table -@iftex -@vfil -@end iftex - @need 4000 For example, if @code{@value{RANDOMUSER2}} wanted to use the standard UNIX telnet to connect to the machine @@ -879,9 +830,6 @@ was sent over the network unencrypted. If an intruder were watching network traffic at the time, that intruder would know @code{@value{RANDOMUSER2}}'s password. -@iftex -@vfil -@end iftex @need 4000 If, on the other hand, @code{@value{RANDOMUSER1}} wanted to use the @value{PRODUCT} telnet to connect to the machine @@ -915,9 +863,6 @@ destroys them when it exits. The full set of options to @value{PRODUCT} @code{telnet} are discussed in the Reference section of this manual. (@pxref{telnet Reference}) -@iftex -@vfil -@end iftex @need 2000 @node rlogin, FTP, telnet, Kerberos V5 Applications @subsection rlogin @@ -981,9 +926,6 @@ was sent over the network unencrypted. If an intruder were watching network traffic at the time, that intruder would know @code{@value{RANDOMUSER2}}'s password. -@iftex -@vfil -@end iftex @need 4000 If, on the other hand, @code{@value{RANDOMUSER1}} wanted to use @value{PRODUCT} rlogin to connect to the machine @@ -1013,10 +955,6 @@ destroys them when it exits. The full set of options to @value{PRODUCT} @code{rlogin} are discussed in the Reference section of this manual. (@pxref{rlogin Reference}) -@iftex -@vfil -@end iftex -@need 2000 @node FTP, rsh, rlogin, Kerberos V5 Applications @subsection FTP @@ -1077,14 +1015,9 @@ ftp> quit The full set of options to @value{PRODUCT} @code{FTP} are discussed in the Reference section of this manual. (@pxref{FTP Reference}) -@iftex -@vfil -@end iftex -@need 2000 @node rsh, rcp, FTP, Kerberos V5 Applications @subsection rsh -@need 1000 The @value{PRODUCT} @code{rsh} program works exactly like the standard UNIX rlogin program, with the following Kerberos features added: @@ -1118,7 +1051,7 @@ turns off encryption. @need 1800 For example, if your Kerberos tickets allowed you to run programs on the -host @code{@value{RANDOMHOST2}@@@value{SECONDDOMAIN}} as root, you could +host @* @code{@value{RANDOMHOST2}@@@value{SECONDDOMAIN}} as root, you could run the @samp{date} program as follows: @smallexample @@ -1135,10 +1068,6 @@ destroys them when it exits. The full set of options to @value{PRODUCT} @code{rsh} are discussed in the Reference section of this manual. (@pxref{rsh Reference}) -@iftex -@vfil -@end iftex -@need 2000 @node rcp, ksu, rsh, Kerberos V5 Applications @subsection rcp @@ -1170,10 +1099,6 @@ transparently. The full set of options to @value{PRODUCT} @code{rcp} are discussed in the Reference section of this manual. (@pxref{rcp Reference}) -@iftex -@vfil -@end iftex -@need 2000 @node ksu, , rcp, Kerberos V5 Applications @subsection ksu @@ -1353,7 +1278,7 @@ The full set of options to @value{PRODUCT} @code{ksu} are discussed in the Reference section of this manual. (@pxref{ksu Reference}) @node Kerberos V5 Reference, Kerberos Glossary, Kerberos V5 Tutorial, Top -@chapter @value{PRODUCT} Reference +@chapter Kerberos V5 Reference This section will include copies of the manual pages for the @value{PRODUCT} client programs. You can read the manual entry for any