diff --git a/doc/heimdal.texi b/doc/heimdal.texi index 30c57defe..e47c15915 100644 --- a/doc/heimdal.texi +++ b/doc/heimdal.texi @@ -212,11 +212,26 @@ to the following restrictions: @menu * Introduction:: -* Tutorial:: +* Building and Installing:: +* Setting up a realm:: +* Kerberos 4 issues:: + + --- The Detailed Node Listing --- + +Building and Installing + +* Finishing the installation:: + +Kerberos 4 issues + +* Principal conversion issues:: +* Converting a version 4 database:: @end menu @include intro.texi -@include tut.texi +@include install.texi +@include setup.texi +@include kerberos4.texi @c @shortcontents @c @contents diff --git a/doc/install.texi b/doc/install.texi new file mode 100644 index 000000000..fedc9da2a --- /dev/null +++ b/doc/install.texi @@ -0,0 +1,61 @@ +@node Building and Installing, Setting up a realm, Introduction, Top +@comment node-name, next, previous, up +@chapter Building and Installing + +Heimdal uses GNU Autoconf to configure for specific hosts, and GNU +Automake to manage makefiles. If this is new to you, the short +instruction is to run the @code{configure} script in the top level +directory, and when that finishes @code{make}. + +You will need a compiler that supports a ``loose'' ANSI C mode, such as +@code{gcc}. To build the server side you will need either NDBM or +Berkeley DB. If you have neither, parts of the code will not build +(specifically libraries and programs that deals with databases). It +should be possible to build all clients even without a working db +library, but make will need some help (such as with the @samp{-k} flag). + +When everything is built, you can install by doing @kbd{make +install}. The default location for installation is @file{/usr/heimdal}, +but this can be changed by running @code{configure} with +@samp{--prefix=/some/other/place}. + +If you need to change the default behavior, configure understands the +following options: + +@table @asis +@item @kbd{--without-berkeley-db} +DB is preferred before NDBM, but if you for some reason want to use NDBM +instead, you can use this option. +@item @kbd{--with-krb4=@file{dir}} +Gives the location of Kerberos 4 libraries and headers. This enables +Kerberos 4 support in some programs, like telnet and the KDC. If you +keep libraries and headers in different places, you can instead give the +path to each with the @kbd{--with-krb4-lib=@file{dir}}, and +@kbd{--with-krb4-include=@file{dir}} options. +@item @kbd{--enable-kaserver} +Enables experimental kaserver support. This is the protocol used by +``KDC'' in AFS. Requires Kerberos 4 support. +@item @kbd{--with-readline=@file{dir}} +Gives the path for the GNU Readline library, which will be used in some +programs. If no readline library is found, the (simpler) editline +library will be used instead. +@end table + +@menu +* Finishing the installation:: +@end menu + +@node Finishing the installation, , Building and Installing, Building and Installing +@section Loose threads + +The +@pindex rsh +@code{rsh} program in this distribution presently isn't usable with +non-kerberised @code{rshd}s. It should not be installed set-uid to root. + +@pindex login +The @code{telnetd} daemon will try to use the @code{login} found in the +@file{/usr/athena/bin} directory. If you don't have a working login +program there (it should grok the @samp{-f} flag), you can either start +telnetd with the @samp{-L} flag, or edit the definition of @code{BINDIR} +in @file{telnetd.h}. diff --git a/doc/intro.texi b/doc/intro.texi index f66de5506..a6b3cd9dc 100644 --- a/doc/intro.texi +++ b/doc/intro.texi @@ -1,4 +1,4 @@ -@node Introduction, Tutorial, Top, Top +@node Introduction, Building and Installing, Top, Top @comment node-name, next, previous, up @chapter Introduction diff --git a/doc/kerberos4.texi b/doc/kerberos4.texi new file mode 100644 index 000000000..1ae696f97 --- /dev/null +++ b/doc/kerberos4.texi @@ -0,0 +1,74 @@ +@node Kerberos 4 issues, , Setting up a realm, Top +@comment node-name, next, previous, up +@chapter Kerberos 4 issues + +If compiled with version 4 support, the KDC can serve requests from a +Kerberos 4 client. There are a few things you must do for this to work. + +@menu +* Principal conversion issues:: +* Converting a version 4 database:: +@end menu + +@node Principal conversion issues, Converting a version 4 database, Kerberos 4 issues, Kerberos 4 issues +@section Principal conversion issues + +First, Kerberos 4 and Kerberos 5 principals are different. A version 4 +principal consists of a name, an instance, and a realm. A version 5 +principal has one or more components, and a realm @footnote{for the +common case of one and two component principals, we will refer to the +first component as the ``name'' and the second as the ``instance''}. +Also, in some cases the name of a version 4 principal differs from the +first component of the corresponding version 5 principal. One notable +example is the ``host'' type principals, where the version 4 name is +@samp{rcmd} (for ``remote command''), and the version 5 name is +@samp{host}. For the class of principals that has a hostname as +instance, there is an other major difference, Kerberos 4 uses only the +first component of the hostname, whereas Kerberos 5 uses the fully +qualified hostname. + +Because of this it can in the general case can be hard or impossible to +correctly convert a version 4 principal to a version 5 principal +@footnote{the other way is not always trivial either, but usually +easier}. The biggest problem is to know if the conversion resulted in a +valid principal. To give an example, suppose you want to convert the +principal @samp{rcmd.foo}. + +The @samp{rcmd} name suggests that the instance is a hostname (even if +there are exceptions to this rule). To correctly convert the instance +@samp{foo} to a hostame, you have to know which host it referred to. You +can to this by either guessing (from the realm) which domain name to +append, or you have to have a list of possible hostnames. In the +simplest cases you can cover most principals with the first rule. If you +have several domains sharing a single realm this will not usually +work. If the exceptions are few you can probably come by with a lookup +table for the exceptions. + +In a complex scenario you will need some kind of host lookup mechanism. +Using DNS for this is tempting, but DNS is error prone, slow and unsafe +@footnote{at least until secure DNS is comonly available}. + +Fortunately, the KDC has a trump on hand: it can easily tell if a +principal exists in the databse. The KDC will use +@code{krb5_425_conv_principal_ext} to convert principals. + +@node Converting a version 4 database, , Principal conversion issues, Kerberos 4 issues +@section Converting a version 4 database + +If you want to convert an existing version 4 database, the principal +conversion issue arises too. + +If you simply convert a database, this conversion will only take place +once. It is also possible to run a version 5 KDC as a slave. In this +case this conversion will happen every time the database is propagated. +When doing this conversion, there are a few things to look out for. If +you have stale entries in the database, these entries will not be +converted. This might be because these principals are not used anymore, +or it might be just because the principal couldn't be converted. + +You might also see problems with a many-to-one mapping of +principals. For inctance, if you are using DNS lookups and you have two +principals @samp{rcmd.foo} and @samp{rcmd.bar}, where `foo' is a CNAME +for `bar', the resulting principals will be the same. Since the +conversion function can't tell which is correct, these conflicts will +have to be resolved manually. diff --git a/doc/setup.texi b/doc/setup.texi new file mode 100644 index 000000000..21bec5156 --- /dev/null +++ b/doc/setup.texi @@ -0,0 +1,113 @@ +@node Setting up a realm, Kerberos 4 issues, Building and Installing, Top +@chapter Setting up a realm + +A +@cindex realm +realm is an administrative domain. Kerberos realms usually consists of +an Internet domain name in uppercase. Call your realm the same as your +Internet domain name if you do not have strong reasons for not doing so. +It will make life easier for you and everyone else. + +To setup a realm you will first have to create a configuration file: +@file{/etc/krb5.conf}. The @file{krb5.conf} file can contain many +configuration options, some which are described here. + +The confguration file is a hierarchial structure consisting of sections, +each containing a list of bindings (either variable assignments or +subsections). A section starts with @samp{[section-name]}. A binding +consists of a left hand side, an equal (@samp{=}) and a right hand +side. The left hand side tag must be separated from the equal with some +whitespace. Subsections has a @samp{@{} as the first non-whitespace +character after the equal. All other bindings are treated as variable +assignments. The value of a variable extends to the end of the line. + +@example +[section1] + a-subsection = @{ + var = value1 + other-var = value with @{@} + sub-sub-section = @{ + var = 123 + @} + @} + var = some other value +[section2] + var = yet another value +@end example + +To denote entries in the config file, the names of sections and bindings +will be given separated with slashes (@samp{/}). The @samp{other-var} +variable will thus be @samp{section1/a-subsection/other-var}. + +For in-depth information about the contents of the config file, refer to +the @file{krb5.conf} manual page. Some of the more important sections +are briefly described here. The @samp{libdefaults} section contains a +list of library configuration parameters, such as the default realm and +the timeout for kdc responses. The @samp{realms} section contains +information about specific realms, such as where they hide their +KDC. This section serves the same purpose as the Kerberos 4 +@file{krb.conf} file, but can contain more information. Finally the +@samp{domain_realm} section contains a list of mappings from domains to +realms, equivalent to the Kerberos 4 @file{krb.realms} file. + +To continue with the realm setup, you will have to create a config file, +with contents similar to the following. + +@example +[libdefaults] + default_realm = MY.REALM +[realms] + MY.REALM = @{ + kdc = my.kdc + @} +[domain_realm] +.my.domain = MY.REALM + +@end example + +If you use a realm name equal to your domain name, you can omit the +@samp{libdefaults}, and @samp{domain_realm}, sections. + +The database library will look for the database in @file{/var/heimdal}, +so you should probably create that directory. + +To initialise the database use the @code{kdb_edit} program. First issue +a @kbd{init MY.REALM} command. This will create the database and insert +default principals for that realm. You can have more than one realm in +one database, so @samp{init} does not destroy any old database. + +Before creating the database, @samp{init} will ask you some questions +about default and max ticket lifes. The default values should be fine. + +After creating the database you should probably add yourself. You do +this with the @samp{ank} command. It takes as argument the name of a +principal. The principal should contain a realm, so if you haven't setup +a default realm, you will need to explicitly include the realm. + +@example +# kdb_edit +kdb_edit> init MY.REALM +Realm max ticket life: [infinite] +Realm max renewable ticket life: [infinite] +Default ticket life: [1 day] +Default renewable ticket life: [7 days] +kdb_edit> ank me +Max ticket life [1 day]: +Max renewable ticket [7 days]: +Password: +Verifying password - Password: +@end example + +Now start the KDC and try getting a ticket. + +@example +# kdc & +# kinit me +me@@MY.REALMS's Password: +# klist +Credentials cache: /tmp/krb5cc_3008 + Principal: me@@MY.REALM + + Issued Expires Principal +Aug 25 07:25:55 Aug 25 17:25:55 krbtgt/MY.REALM@@MY.REALM +@end example diff --git a/doc/tut.texi b/doc/tut.texi deleted file mode 100644 index 3ebc14a89..000000000 --- a/doc/tut.texi +++ /dev/null @@ -1,88 +0,0 @@ -@node Tutorial, , Introduction, Top -@comment node-name, next, previous, up -@chapter Tutorial - -There currently isn't any documentation other than the source. To give -some example how to you might try this code, we give you a quick -`tutorial'. - -First build everything. You should be able to install it with -@samp{make install} but don't need to. Here are some simple tests to -exercise the kdc. - -You will have to create a @file{/etc/krb5.conf} with the following contents: - -@example -[realms] - MY.REALM = @{ - kdc = my.computer - @} -[domain_realm] - my.computer = MY.REALM -@end example - -And then, - -@example -$ cd kdc -$ ../admin/kdb_edit -kdb_edit> init MY.REALM -Realm max ticket life: [infinite] -Realm max renewable ticket life: [infinite] -Default ticket life: [86400] -Default renewable ticket life: [432000] -@end example - -This will create an initial database (in the current directory). - -@example -kdb_edit> add me -Max ticket life [86400]: -Max renewable ticket [432000]: -Password: -Verifying password - Password: -@end example - -This will add a principal for you. - -@example -kdb_edit> add host/my.computer -Max ticket life [86400]: -Max renewable ticket [432000]: -Password: -Verifying password - Password: -@end example - -This creates a host entry for your computer (this could be anything, but -a `host' principal is most useful). Try using the password -@samp{random}. That should generate a random key. - -Now start the KDC (press control-D to exit kdb_edit). - -@example -$ ./kdc & -@end example - -Now, try to get some credentials. - -@example -$ ../kuser/kinit me -me@@MY.REALM's Password: -$ ../kuser/klist -Credentials cache: /tmp/krb5cc_3008 - Principal: me@@MY.REALM - - Issued Expires Principal -Jul 13 07:25:55 Jul 14 07:25:55 krbtgt/MY.REALM@@MY.REALM -$ ../kuser/kfoo host/my.computer -$ ../kuser/klist -Credentials cache: /tmp/krb5cc_3008 - Principal: me@@MY.REALM - - Issued Expires Principal -Jul 13 07:25:55 Jul 14 07:25:55 krbtgt/MY.REALM@@MY.REALM -Jul 13 07:25:55 Jul 14 07:25:55 host/my.computer@@MY.REALM -@end example - -Then you should try to run the programs in `appl/test', `appl/rsh', and -`appl/telnet'. This is left as an exercise to the reader.