diff options
Diffstat (limited to 'crypto/kerberosIV/doc/setup.texi')
-rw-r--r-- | crypto/kerberosIV/doc/setup.texi | 905 |
1 files changed, 905 insertions, 0 deletions
diff --git a/crypto/kerberosIV/doc/setup.texi b/crypto/kerberosIV/doc/setup.texi new file mode 100644 index 0000000..24a955d --- /dev/null +++ b/crypto/kerberosIV/doc/setup.texi @@ -0,0 +1,905 @@ +@node How to set up a realm, One-Time Passwords, Installing programs, Top +@chapter How to set up a realm + +@quotation +@flushleft + Who willed you? or whose will stands but mine? + There's none protector of the realm but I. + Break up the gates, I'll be your warrantize. + Shall I be flouted thus by dunghill grooms? + --- King Henry VI, 6.1 +@end flushleft +@end quotation + +@menu +* How to set up the kerberos server:: +* Install the client programs:: +* Install the kerberised services:: +* Install a slave kerberos server:: +* Cross-realm functionality :: +@end menu + +@node How to set up the kerberos server, Install the client programs, How to set up a realm, How to set up a realm +@section How to set up the kerberos server + +@menu +* Choose a realm name:: +* Choose a kerberos server:: +* Install the configuration files:: +* Install the /etc/services:: +* Install the kerberos server:: +* Set up the server:: +* Add a few important principals:: +* Start the server:: +* Try to get tickets:: +* Create initial ACL for the admin server:: +* Start the admin server:: +* Add users to the database:: +* Automate the startup of the servers:: +@end menu + +@node Choose a realm name, Choose a kerberos server, How to set up the kerberos server, How to set up the kerberos server +@subsection Choose a realm name + +A +@cindex realm +realm is an administrative domain. Kerberos realms are usually +written in uppercase and consist of a Internet domain +name@footnote{Using lowercase characters in the realm name might break +in mysterious ways. This really should have been fixed, but has not.}. +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. + +@node Choose a kerberos server, Install the configuration files, Choose a realm name, How to set up the kerberos server +@subsection Choose a kerberos server + +You need to choose a machine to run the +@pindex kerberos +kerberos server program. If the kerberos database residing on this host +is compromised, your entire realm will be compromised. Therefore, this +machine must be as secure as possible. Preferably it should not run any +services other than Kerberos. The secure-minded administrator might +only allow logins on the console. + +This machine has also to be reliable. If it is down, you will not be +able to use any kerberised services unless you have also configured a +slave server (@pxref{Install a slave kerberos server}). + +Running the kerberos server requires very little CPU power and a small +amount of disk. An old PC with some hundreds of megabytes of free disk +space should do fine. Most of the disk space will be used for various +logs. + +@node Install the configuration files, Install the /etc/services, Choose a kerberos server, How to set up the kerberos server +@subsection Install the configuration files + +There are two important configuration files: @file{/etc/krb.conf} and +@file{/etc/krb.realms}. +@pindex krb.conf +@pindex krb.realms + +The @file{krb.conf} file determines which machines are servers for +different realms. The format of this file is: + +@example +THIS.REALM +SUPP.LOCAL.REALM +THIS.REALM kerberos.this.realm admin server +THIS.REALM kerberos-1.this.realm +SUPP.LOCAL.REALM kerberos.supp.local.realm admin server +ANOTHER.REALM kerberos.another.realm +@end example + +The first line defines the name of the local realm. The next few lines +optionally defines supplementary local realms. +@cindex supplementary local realms +The rest of the file +defines the names of the kerberos servers and the database +administration servers for all known realms. You can define any number +of kerberos slave servers similar to the one defined on line +four. Clients will try to contact servers in listed order. + +The @samp{admin server} clause at the first entry states that this is +the master server +@cindex master server +(the one to contact when modifying the database, such as changing +passwords). There should be only one such entry for each realm. + +In the original MIT Kerberos 4 (as in most others), the server +specification could only take the form of a host-name. To facilitate +having kerberos servers in odd places (such as behind a firewall), +support has been added for ports other than the default (750), and +protocols other than UDP. + +The formal syntax for an entry is now +@samp{[@var{proto}/]@var{host}[:@var{port}]}. @var{proto} is either +@samp{UDP}, @samp{TCP}, or @samp{HTTP}, and @var{port} is the port to +talk to. Default value for @var{proto} is @samp{UDP} and for @var{port} +whatever @samp{kerberos-iv} is defined to be in @file{/etc/services} or +750 if undefined. If @var{proto} is @samp{HTTP}, the default port is +80. An @samp{http} entry may also be specified in URL format. + +If the information about a realm is missing from the @file{krb.conf} +file, or if the information is wrong, the following methods will be +tried in order. + +@enumerate +@item +If you have an SRV-record (@cite{RFC 2052}) for your realm it will be +used. This record should be of the form +@samp{kerberos-iv.@var{protocol}.@var{REALM}}, where @var{proto} is +either @samp{UDP}, @samp{TCP}, or @samp{HTTP}. (Note: the current +implementation does not look at priority or weight when deciding which +server to talk to.) +@item +If there isn't any SRV-record, it tries to find a TXT-record for the +same domain. The contents of the record should have the same format as the +host specification in @file{krb.conf}. (Note: this is a temporary +solution if your name server doesn't support SRV records. The clients +should work fine with SRV records, so if your name server supports them, +they are very much preferred.) +@item +If no valid kerberos server is found, it will try to talk UDP to the +service @samp{kerberos-iv} with fall-back to port 750 with +@samp{kerberos.@var{REALM}} (which is also assumed to be the master +server), and then @samp{kerberos-1.@var{REALM}}, +@samp{kerberos-2.@var{REALM}}, and so on. +@end enumerate + +SRV records have been supported in BIND since 4.9.5T2A. An example +would look like the following in the zone file: + +@example +kerberos-iv.udp.foo.se. 1M IN SRV 1 0 750 kerberos-1.foo.se. +kerberos-iv.udp.foo.se. 1M IN SRV 0 0 750 kerberos.foo.se. +@end example + +We strongly recommend that you add a CNAME @samp{kerberos.@var{REALM}} +pointing to your kerberos master server. + +The @file{krb.realms} file is used to find out what realm a particular +host belongs to. An example of this file could look like: + +@example +this.realm THIS.REALM +.this.realm THIS.REALM +foo.com SOME.OTHER.REALM +www.foo.com A.STRANGE.REALM +.foo.com FOO.REALM +@end example + +Entries starting with a dot are taken as the name of a domain. Entries +not starting with a dot are taken as a host-name. The first entry matched +is used. The entry for @samp{this.realm} is only necessary if there is a +host named @samp{this.realm}. + +If no matching realm is found in @file{krb.realms}, DNS is searched for +the correct realm. For example, if we are looking for host @samp{a.b.c}, +@samp{krb4-realm.a.b.c} is first tried and then @samp{krb4-realm.b.c} +and so on. The entry should be a TXT record containing the name of the +realm, such as: + +@example +krb4-realm.pdc.kth.se. 7200 TXT "NADA.KTH.SE" +@end example + +If this didn't help the domain name sans the first part in uppercase is +tried. + +The plain vanilla version of Kerberos doesn't have any fancy methods of +getting realms and servers so it is generally a good idea to keep +@file{krb.conf} and @file{krb.realms} up to date. + +In addition to these commonly used files, @file{/etc/krb.extra} +@pindex krb.extra +holds some things that are not normally used. It consists of a number of +@samp{@var{variable} = @var{value}} pairs, blank lines and lines +beginning with a hash (#) are ignored. + +The currently defined variables are: + +@table @samp +@item kdc_timeout +@cindex kdc_timeout +The time in seconds to wait for an answer from the KDC (the default is 4 +seconds). +@item kdc_timesync +@cindex kdc_timesync +This flag enables storing of the time differential to the KDC when +getting an initial ticket. This differential is used later on to compute +the correct time. This can help if your machine doesn't have a working +clock. +@item firewall_address +@cindex firewall_address +The IP address that hosts outside the firewall see when connecting from +within the firewall. If this is specified, the code will try to compute +the value for @samp{reverse_lsb_test}. +@item krb4_proxy +@cindex krb4_proxy +When getting tickets via HTTP, this specifies the proxy to use. The +default is to speak directly to the KDC. +@item krb_default_tkt_root +@cindex krb_default_tkt_root +The default prefix for ticket files. The default is @file{/tmp/tkt}. +Normally the uid or tty is appended to this prefix. +@item krb_default_keyfile +@cindex krb_default_keyfile +The file where the server keys are stored, the default is @file{/etc/srvtab}. +@item nat_in_use +@cindex nat_in_use +If the client is behind a Network Address Translator (NAT). +@cindex Network Address Translator +@cindex NAT +@item reverse_lsb_test +@cindex reverse_lsb_test +Reverses the test used by @code{krb_mk_safe}, @code{krb_rd_safe}, +@code{krb_mk_priv}, and @code{krb_rd_priv} to compute the ordering of +the communicating hosts. This test can cause truble when using +firewalls. +@end table + +@node Install the /etc/services, Install the kerberos server, Install the configuration files, How to set up the kerberos server +@subsection Updating /etc/services + +You should append or merge the contents of @file{services.append} to +your @file{/etc/services} files or NIS-map. Remove any unused factory +installed kerberos port definitions to avoid possible conflicts. +@pindex services + +Most of the programs will fall back to the default ports if the port +numbers are not found in @file{/etc/services}, but it is convenient to +have them there anyway. + +@node Install the kerberos server, Set up the server, Install the /etc/services, How to set up the kerberos server +@subsection Install the kerberos server + +You should have already chosen the machine where you want to run the +kerberos server and the realm name. The machine should also be as +secure as possible (@pxref{Choose a kerberos server}) before installing +the kerberos server. In this example, we will install a kerberos server +for the realm @samp{FOO.SE} on a machine called @samp{hemlig.foo.se}. + +@node Set up the server, Add a few important principals, Install the kerberos server, How to set up the kerberos server +@subsection Setup the server + +Login as root on the console of the kerberos server. Add +@file{/usr/athena/bin} and @file{/usr/athena/sbin} to your path. Create +the directory @file{/var/kerberos} (@kbd{mkdir /var/kerberos}), which is +where the database will be stored. Then, to create the database, run +@kbd{kdb_init}: +@pindex kdb_init + +@example +@cartouche +hemlig# mkdir /var/kerberos +hemlig# kdb_init +Realm name [default FOO.SE ]: +You will be prompted for the database Master Password. +It is important that you NOT FORGET this password. + +Enter Kerberos master password: +Verifying password +Enter Kerberos master password: +@end cartouche +@end example + +If you have set up the configuration files correctly, @kbd{kdb_init} +should choose the correct realm as the default, otherwise a (good) guess +is made. Enter the master password. + +This password will only be used for encrypting the kerberos database on +disk and for generating new random keys. You will not have to remember +it, only to type it again when you run @kbd{kstash}. Choose something +long and random. Now run @kbd{kstash} using the same password: +@pindex kstash + +@example +@cartouche +hemlig# kstash + +Enter Kerberos master password: + +Current Kerberos master key version is 1. + +Master key entered. BEWARE! +Wrote master key to /.k +@end cartouche +@end example + +After entering the same master password it will be saved in the file +@file{/.k} and the kerberos server will read it when needed. Write down +the master password and put it in a sealed envelope in a safe, you might +need it if your disk crashes or should you want to set up a slave +server. + +@code{kdb_init} initializes the database with a few entries: + +@table @samp +@item krbtgt.@var{REALM} +The key used for authenticating to the kerberos server. + +@item changepw.kerberos +The key used for authenticating to the administrative server, i.e. when +adding users, changing passwords, and so on. + +@item default +This entry is copied to new items when these are added. Enter here the +values you want new entries to have, particularly the expiry date. + +@item K.M +This is the master key and it is only used to verify that the master key +that is saved un-encrypted in @file{/.k} is correct and corresponds to +this database. + +@end table + +@code{kstash} only reads the master password and writes it to +@file{/.k}. This enables the kerberos server to start without you +having to enter the master password. This file (@file{/.k}) is only +readable by root and resides on a ``secure'' machine. + +@node Add a few important principals, Start the server, Set up the server, How to set up the kerberos server +@subsection Add a few important principals + +Now the kerberos database has been created, containing only a few +principals. The next step is to add a few more so that you can test +that it works properly and so that you can administer your realm without +having to use the console on the kerberos server. Use @kbd{kdb_edit} +to edit the kerberos database directly on the server. +@pindex kdb_edit + +@code{kdb_edit} is intended as a bootstrapping and fall-back mechanism +for editing the database. For normal purposes, use the @code{kadmin} +program (@pxref{Add users to the database}). + +The following example shows the adding of the principal +@samp{nisse.admin} into the kerberos database. This principal is used +by @samp{nisse} when administrating the kerberos database. Later on the +normal principal for @samp{nisse} will be created. Replace @samp{nisse} +and @samp{password} with your own username and password. + +@example +@cartouche +hemlig# kdb_edit -n +Opening database... +Current Kerberos master key version is 1. + +Master key entered. BEWARE! +Previous or default values are in [brackets] , +enter return to leave the same, or new value. + +Principal name: <nisse> +Instance: <admin> + +<Not found>, Create [y] ? <> + +Principal: nisse, Instance: admin, kdc_key_ver: 1 +New Password: <password> +Verifying password +New Password: <password> + +Principal's new key version = 1 +Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? <> +Max ticket lifetime (*5 minutes) [ 255 ] ? <> +Attributes [ 0 ] ? <> +Edit O.K. +Principal name: <> +@end cartouche +@end example + +@code{kdb_edit} will loop until you hit the @kbd{return} key at the +``Principal name'' prompt. Now you have added nisse as an administrator. + +@page + +@node Start the server, Try to get tickets, Add a few important principals, How to set up the kerberos server +@subsection Start the server + +@pindex kerberos +@example +@cartouche +hemlig# /usr/athena/libexec/kerberos & +Kerberos server starting +Sleep forever on error +Log file is /var/log/kerberos.log +Current Kerberos master key version is 1. + +Master key entered. BEWARE! + +Current Kerberos master key version is 1 +Local realm: FOO.SE +@end cartouche +@end example + +@node Try to get tickets, Create initial ACL for the admin server, Start the server, How to set up the kerberos server +@subsection Try to get tickets + +You can now verify that these principals have been added and that the +server is working correctly. + +@pindex kinit +@example +@cartouche +hemlig# kinit +eBones International (hemlig.foo.se) +Kerberos Initialization +Kerberos name: <nisse.admin> +Password: <password> +@end cartouche +@end example + +If you do not get any error message from @code{kinit}, then everything +is working (otherwise, see @ref{Common error messages}). Use +@code{klist} to verify the tickets you acquired with @code{kinit}: + +@pindex klist +@example +@cartouche +hemlig# klist +Ticket file: /tmp/tkt0 +Principal: nisse.admin@@FOO.SE + +Issued Expires Principal +May 24 21:06:03 May 25 07:06:03 krbtgt.FOO.SE@@FOO.SE +@end cartouche +@end example + +@node Create initial ACL for the admin server, Start the admin server, Try to get tickets, How to set up the kerberos server +@subsection Create initial ACL for the admin server + +The admin server, @code{kadmind}, uses a series of files to determine who has +@pindex kadmind +the right to perform certain operations. The files are: +@file{admin_acl.add}, @file{admin_acl.get}, @file{admin_acl.del}, and +@file{admin_acl.mod}. Create these with @samp{nisse.admin@@FOO.SE} as +the contents. +@pindex admin_acl.add +@pindex admin_acl.get +@pindex admin_acl.del +@pindex admin_acl.mod + +@example +@cartouche +hemlig# echo "nisse.admin@@FOO.SE" >> /var/kerberos/admin_acl.add +hemlig# echo "nisse.admin@@FOO.SE" >> /var/kerberos/admin_acl.get +hemlig# echo "nisse.admin@@FOO.SE" >> /var/kerberos/admin_acl.mod +hemlig# echo "nisse.admin@@FOO.SE" >> /var/kerberos/admin_acl.del +@end cartouche +@end example + +Later on you may wish to add more users with administration +privileges. Make sure that you create both the administration principals +and add them to the admin server ACL. + +@node Start the admin server, Add users to the database, Create initial ACL for the admin server, How to set up the kerberos server +@subsection Start the admin server + +@pindex kadmind +@example +@cartouche +hemlig# /usr/athena/libexec/kadmind & +KADM Server KADM0.0A initializing +Please do not use 'kill -9' to kill this job, use a +regular kill instead + +Current Kerberos master key version is 1. + +Master key entered. BEWARE! +@end cartouche +@end example + +@node Add users to the database, Automate the startup of the servers, Start the admin server, How to set up the kerberos server +@subsection Add users to the database + +Use the @code{kadmin} client to add users to the database: +@pindex kadmin + +@example +@cartouche +hemlig# kadmin -p nisse.admin -m +Welcome to the Kerberos Administration Program, version 2 +Type "help" if you need it. +admin: <add nisse> +Admin password: <nisse.admin's password> +Maximum ticket lifetime? (255) [Forever] +Attributes? [0x00] +Expiration date (enter yyyy-mm-dd) ? [Sat Jan 1 05:59:00 2000] +Password for nisse: +Verifying password Password for nisse: +nisse added to database. +@end cartouche +@end example + +Add whatever other users you want to have in the same way. Verify that +a user is in the database and check the database entry for that user: + +@example +@cartouche +admin: <get nisse> +Info in Database for nisse.: +Max Life: 255 (Forever) Exp Date: Sat Jan 1 05:59:59 2000 + +Attribs: 00 key: 0 0 +admin: <^D> +Cleaning up and exiting. +@end cartouche +@end example + +@node Automate the startup of the servers, , Add users to the database, How to set up the kerberos server +@subsection Automate the startup of the servers + +Add the lines that were used to start the kerberos server and the +admin server to your startup scripts (@file{/etc/rc} or similar). +@pindex rc + +@node Install the client programs, Install the kerberised services, How to set up the kerberos server, How to set up a realm +@section Install the client programs + +Making a machine a kerberos client only requires a few steps. First you +might need to change the configuration files as with the kerberos +server. (@pxref{Install the configuration files} and @pxref{Install the +/etc/services}.) Also you need to make the programs in +@file{/usr/athena/bin} available. This can be done by adding the +@file{/usr/athena/bin} directory to the users' paths, by making symbolic +links, or even by copying the programs. + +You should also verify that the local time on the client is synchronised +with the time on the kerberos server by some means. The maximum allowed +time difference between the participating servers and a client is 5 +minutes. +@cindex NTP. +One good way to synchronize the time is NTP (Network Time Protocol), see +@url{http://www.eecis.udel.edu/~ntp/}. + +If you need to run the client programs on a machine where you do not +have root-access, you can hopefully just use the binaries and no +configuration will be needed. The heuristics used are mentioned above +(see @ref{Install the configuration files}). If this is not the case +and you need to have @file{krb.conf} and/or @file{krb.realms}, you can +copy them into a directory of your choice and +@pindex krb.conf +@pindex krb.realms +set the environment variable @var{KRBCONFDIR} to point at this +@cindex KRBCONFDIR +directory. + +To test the client functionality, run the @code{kinit} program: + +@example +@cartouche +foo$ kinit +eBones International (foo.foo.se) +Kerberos Initialization +Kerberos name: <nisse> +Password: <password> + +foo$ klist +Ticket file: /tmp/tkt4711 +Principal: nisse@@FOO.SE + +Issued Expires Principal +May 24 21:06:03 May 25 07:06:03 krbtgt.FOO.SE@@FOO.SE +@end cartouche +@end example + +@node Install the kerberised services, Install a slave kerberos server, Install the client programs, How to set up a realm +@section Install the kerberised services + +These includes @code{rsh}, @code{rlogin}, @code{telnet}, @code{ftp}, +@code{rxtelnet}, and so on. +@pindex rsh +@pindex rlogin +@pindex telnet +@pindex ftp +@pindex rxtelnet + +First follow the steps mentioned in the prior section to make it a +client and verify its operation. Change @file{inetd.conf} next to use +the new daemons. Look at the file +@pindex inetd.conf +@file{etc/inetd.conf.changes} to see the changes that we recommend you +perform on @file{inetd.conf}. + +You should at this point decide what services you want to run on +each machine. + +@subsection rsh, rlogin, and rcp +@pindex rsh +@pindex rlogin +@pindex rcp + +These exist in kerberised versions and ``old-style'' versions. The +different versions use different port numbers, so you can choose none, +one, or both. If you do not want to use ``old-style'' r* services, you +can let the programs output the text ``Remote host requires Kerberos +authentication'' instead of just refusing connections to that port. +This is enabled with the @samp{-v} option. The kerberised services +exist in encrypted and non-encrypted versions. The encrypted services +have an ``e'' prepended to the name and the programs take @samp{-x} as an +option indicating encryption. + +Our recommendation is to only use the kerberised services and give +explanation messages for the old ports. + +@subsection telnet +@pindex telnet + +The telnet service always uses the same port and negotiates as to which +authentication method should be used. The @code{telnetd} program has +@pindex telnetd +an option ``-a user'' that only allows kerberised and authenticated +connections. If this is not included, it falls back to using clear text +passwords. For obvious reasons, we recommend that you enable this +option. If you want to use one-time passwords (@pxref{One-Time +Passwords}) you can use the ``-a otp'' option which will allow OTPs or +kerberised connections. + +@subsection ftp +@pindex ftp + +The ftp service works as telnet does, with just one port being used. By +default only kerberos authenticated connections are allowed. You can +specify additional levels that are thus allowed with these options: + +@table @asis +@item @kbd{-a otp} +Allow one-time passwords (@pxref{One-Time Passwords}). +@item @kbd{-a ftp} +Allow anonymous login (as user ``ftp'' or ``anonymous''). +@item @kbd{-a safe} +The same as @kbd{-a ftp}, for backwards compatibility. +@item @kbd{-a plain} +Allow clear-text passwords. +@item @kbd{-a none} +The same as @kbd{-a ftp -a plain}. +@item @kbd{-a user} +A no-op, also there for backwards compatibility reasons. +@end table + +When running anonymous ftp you should read the man page on @code{ftpd} +which explains how to set it up. + +@subsection pop +@pindex popper + +The Post Office Protocol (POP) is used to retrieve mail from the mail +hub. The @code{popper} program implements the standard POP3 protocol +and the kerberised KPOP. Use the @samp{-k} option to run the kerberos +version of the protocol. This service should only be run on your mail +hub. + +@subsection kx +@pindex kx + +@code{kx} allows you to run X over a kerberos-authenticated and +encrypted connection. This program is used by @code{rxtelnet}, +@code{tenletxr}, and @code{rxterm}. + +If you have some strange kind of operating system with X libraries that +do not allow you to use unix-sockets, you need to specify the @samp{-t} +@pindex kxd +option to @code{kxd}. Otherwise it should be sufficient by adding the +daemon in @file{inetd.conf}. + +@subsection kauth +@pindex kauth + +This service allows you to create tickets on a remote host. To +enable it just insert the corresponding line in @file{inetd.conf}. + +@section srvtabs +@pindex srvtab + +In the same way every user needs to have a password registered with +the kerberos server, every service needs to have a shared key with the +kerberos server. The service keys are stored in a file, usually called +@file{/etc/srvtab}. This file should not be readable to anyone but +root, in order to keep the key from being divulged. The name of this principal +in the kerberos database is usually the service name and the hostname. Examples +of such principals are @samp{pop.@var{hostname}} and +@samp{rcmd.@var{hostname}}. (rcmd comes from ``remote command''.) Here +is a list of the most commonly used srvtab types and what programs use them. + +@table @asis +@item rcmd.@var{hostname} +rsh, rcp, rlogin, telnet, kauth, su, kx +@item rcmd.kerberos +kprop +@item pop.@var{hostname} +popper, movemail, push +@item sample.@var{hostname} +sample_server, simple_server +@item changepw.kerberos +kadmin, kpasswd +@item krbtgt.@var{realm} +kerberos (not stored in any srvtab) +@item ftp.@var{hostname} +ftp (also tries with rcmd.@var{hostname}) +@item zephyr.zephyr +Zephyr +@item afs or afs.@var{cellname} +Andrew File System +@end table + +To create these keys you will use the the @code{ksrvutil} program. +Perform the +@pindex ksrvutil +following: + +@example +@cartouche +bar# ksrvutil -p nisse.admin get +Name [rcmd]: <> +Instance [bar]: <> +Realm [FOO.SE]: <> +Is this correct? (y,n) [y] <> +Add more keys? (y,n) [n] <> +Password for nisse.admin@@FOO.SE: <nisse.admin's password> +Written rcmd.bar +rcmd.bar@@FOO.SE +Old keyfile in /etc/srvtab.old. +@end cartouche +@end example + +@subsection Complete test of the kerberised services + +Obtain a ticket on one machine (@samp{foo}) and use it to login with a +kerberised service to a second machine (@samp{bar}). The test should +look like this if successful: + +@example +@cartouche +foo$ kinit nisse +eBones International (foo.foo.se) +Kerberos Initialization for "nisse" +Password: <nisse's password> +foo$ klist +Ticket file: /tmp/tkt4711 +Principal: nisse@@FOO.SE + +Issued Expires Principal +May 30 13:48:03 May 30 23:48:03 krbtgt.FOO.SE@@FOO.SE +foo$ telnet bar +Trying 17.17.17.17... +Connected to bar.foo.se +Escape character is '^]'. +[ Trying mutual KERBEROS4 ... ] +[ Kerberos V4 accepts you ] +[ Kerberos V4 challenge successful ] +bar$ +@end cartouche +@end example + +You can also try with @code{rsh}, @code{rcp}, @code{rlogin}, +@code{rlogin -x}, and some other commands to see that everything is +working all right. + +@node Install a slave kerberos server, Cross-realm functionality , Install the kerberised services, How to set up a realm +@section Install a slave kerberos server + +It is desirable to have at least one backup (slave) server in case the +master server fails. It is possible to have any number of such slave +servers but more than three usually doesn't buy much more redundancy. + +First select a good server machine. (@pxref{Choose a kerberos +server}). + +On the master, add a @samp{rcmd.kerberos} (note, it should be literally +``kerberos'') principal (using @samp{ksrvutil get}). The +@pindex kprop +@code{kprop} program, running on the master, will use this when +authenticating to the +@pindex kpropd +@code{kpropd} daemons running on the slave servers. The @code{kpropd} +on the slave will use its @samp{rcmd.hostname} key for authenticating +the connection from the master. Therefore, the slave needs to have this +key in its srvtab, and it of course also needs to have enough of the +configuration files to act as a server. See @ref{Install the kerberised +services} for information on how to do this. + +To summarize, the master should have a key for @samp{rcmd.kerberos} and +the slave one for @samp{rcmd.hostname}. + +The slave will need the same master key as you used at the master. + +On your master server, create a file, e.g. @file{/var/kerberos/slaves}, +that contains the hostnames of your kerberos slave servers. + +Start @code{kpropd} with @samp{kpropd -i} on your slave servers. + +On your master server, create a dump of the database and then propagate +it. + +@example +foo# kdb_util slave_dump /var/kerberos/slave_dump +foo# kprop +@end example + +You should now have copies of the database on your slave servers. You +can verify this by issuing @samp{kdb_util dump @var{file}} on your +slave servers, and comparing with the original file on the master +server. Note that the entries will not be in the same order. + +This procedure should be automated with a script run regularly by cron, +for instance once an hour. + +Since the master and slave servers will use copies of the same +database, they need to use the same master key. Add the master key on +the slave with @code{kstash}. (@pxref{Set up the server}) + +To start the kerberos server on slaves, you first have to copy the +master key from the master server. You can do this either by remembering +the master password and issuing @samp{kstash}, or you can just copy the +keyfile. Remember that if you copy the file, do so on a safe media, not +over the network. Good means include floppy or paper. Paper is better, +since it is easier to swallow afterwards. + +The kerberos server should be started with @samp{-s} on the slave +servers. This enables sanity checks, for example checking the time since +the last update from the master. + +All changes to the database are made by @code{kadmind} at the master, +and then propagated to the slaves, so you should @strong{not} run +@code{kadmind} on the slaves. + +Finally add the slave servers to +@file{/etc/krb.conf}. The clients will ask the servers in the order +specified by that file. + +Consider adding CNAMEs to your slave servers, see @ref{Install the +configuration files}. + +@node Cross-realm functionality , , Install a slave kerberos server, How to set up a realm +@section Cross-realm functionality + +Suppose you are residing in the realm @samp{MY.REALM}, how do you +authenticate to a server in @samp{OTHER.REALM}? Having valid tickets in +@samp{MY.REALM} allows you to communicate with kerberised services in that +realm. However, the computer in the other realm does not have a secret +key shared with the kerberos server in your realm. + +It is possible to add a shared key between two realms that trust each +other. When a client program, such as @code{telnet}, finds that the +other computer is in a different realm, it will try to get a ticket +granting ticket for that other realm, but from the local kerberos +server. With that ticket granting ticket, it will then obtain service +tickets from the kerberos server in the other realm. + +To add this functionality you have to add a principal to each realm. The +principals should be @samp{krbtgt.OTHER.REALM} in @samp{MY.REALM}, and +@samp{krbtgt.MY.REALM} in @samp{OTHER.REALM}. The two different +principals should have the same key (and key version number). Remember +to transfer this key in a safe manner. This is all that is required. + +@page + +@example +@cartouche +blubb$ klist +Ticket file: /tmp/tkt3008 +Principal: joda@@NADA.KTH.SE + + Issued Expires Principal +Jun 7 02:26:23 Jun 7 12:26:23 krbtgt.NADA.KTH.SE@@NADA.KTH.SE +blubb$ telnet agat.e.kth.se +Trying 130.237.48.12... +Connected to agat.e.kth.se. +Escape character is '^]'. +[ Trying mutual KERBEROS4 ... ] +[ Kerberos V4 accepts you ] +[ Kerberos V4 challenge successful ] +Last login: Sun Jun 2 20:51:50 from emma.pdc.kth.se + +agat$ exit +Connection closed by foreign host. +blubb$ klist +Ticket file: /tmp/tkt3008 +Principal: joda@@NADA.KTH.SE + + Issued Expires Principal +Jun 7 02:26:23 Jun 7 12:26:23 krbtgt.NADA.KTH.SE@@NADA.KTH.SE +Jun 7 02:26:50 Jun 7 12:26:50 krbtgt.E.KTH.SE@@NADA.KTH.SE +Jun 7 02:26:51 Jun 7 12:26:51 rcmd.agat@@E.KTH.SE +@end cartouche +@end example |