Installing programs
*******************

You have a choise to either build the distribution from source code or to install binaries, if they are available for your machine.

We recommend building from sources, but using pre-compiled binaries might be easier.  If there are no binaries available for your machine or you want to do some specific configuration, you will have to compile from source.

Installing from source
======================

To build this software un-tar the distribution and run the configure script.

To compile successfully, you will need an ANSI C compiler, such as gcc. Other compilers might also work, but setting the ``ANSI compliance'' too high, might break in parts of the code, not to mention the standard include files.

To build in a separate build tree, run configure in the directory where the tree should reside.  You will need a Make that understands VPATH correctly.  GNU Make works fine.

After building everything (which will take anywhere from a few minutes to a long time), you can install everything in /usr/athena with make install (running as root). It is possible to install in some other place, but it isn't recommended. To do this you will have to run configure with --prefix=/my/path.

If you need to change the default behavior, configure understands the following options:

--enable-shared
     Create shared versions of the Kerberos libraries.

--with-cracklib=DIR
     Use cracklib for password quality control in kadmind. This option requires cracklib with the patch from ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch.

--with-dictpath=DICTPATH
     This is the dictionary that cracklib should use.

--with-socks=DIR
     If you have to traverse a firewall and it uses the SocksV5 protocol (RFC 1928), you can build with socks-support.  Point DIR to the directory where you have socks5 installed.  For more information about socks see http://www.socks.nec.com/.

--with-readline=DIR
     To enable history/line editing in ftp and kadmin, any present version of readline will be used.  If you have readline installed but in a place where configure does not manage to find it, you can use this option.  The code also looks for libedit.  If there is no library at all, the bundled version of editline will be used.

--with-mailspool=DIR
     The configuration process tries to determine where your machine stores its incoming mail.  This is typically /usr/spool/mail or /var/mail.  If it does not work or you store your mail in some unusual directory, this option can be used to specify where the mail spool directory is located.  This directory is only accessed by popper, and the mail check in login.

--with-hesiod=DIR
     Enable the Hesiod support in push.  With this option, it will try to use the hesiod library to locate the mail post-office for the user.

--with-mkey=FILE
     Put the master key here, the default is /.k.

--with-db-dir=DIR
     Where the kerberos database should be stored.  The default is /var/kerberos.

--without-berkeley-db
     If you have Berkeley DB installed, it is preferred over dbm. If you already are running Kerberos this option might be useful, since there currently isn't an easy way to convert a dbm database to a db one (you have to dump the old database and then load it with the new binaries).

--without-afs-support
     Do not include AFS support.

--with-afsws=DIR
     Where your AFS client installation resides.  The default is /usr/afsws.

--enable-rxkad
     Build the rxkad library.

--disable-dynamic-afs
     The AFS support in AIX consists of a shared library that is loaded at runtime. This option disables this, and links with static system calls. Doing this will make the built binaries crash on a machine that doesn't have AFS in the kernel (for instance if the AFS module fails to load at boot).

--with-mips-api=API
     This option enables creation of different types of binaries on Irix. The allowed values are 32, n32, and 64.

--enable-legacy-kdestroy
     This compile-time option creates a kdestroy that does not destroy any AFS tokens.

--disable-otp
     Do not build the OTP (see One-Time Passwords) library and programs, and do not include OTP support in the application programs.

--enable-match-subdomains
     Normally, the host host.domain will be considered to be part of the realm DOMAIN.  With this option will also enable hosts of the form host.sub.domain, host.sub1.sub2.domain, and so on to be considered part of the realm DOMAIN.

--enable-osfc2
     Enable the use of enhanced C2 security on OSF/1. See Digital SIA.

--disable-mmap
     Do not use the mmap system call.  Normally, configure detects if there is a working mmap and it is only used if there is one.  Only try this option if it fails to work anyhow.

--disable-cat-manpages
     Do not install preformatted man pages.

Installing a binary distribution
================================

The binary distribution is supposed to be installed in /usr/athena, installing in some other place may work but is not recommended.  A symlink from /usr/athena to the install directory should be fine.

Finishing the installation
==========================

The only program that needs to be installed setuid to root is su.

If rlogin and rsh are setuid to root they will fall back to non-kerberised protocols if the kerberised ones fail for some reason. The old protocols use reserved ports as security, and therefore the programs have to be setuid to root. If you don't need this functionality consider turning off the setuid bit.

login does not have to be setuid, as it is always run by root (users should use su rather than login).  It will print a helpful message when not setuid to root and run by a user.

The programs intended to be run by users are located in /usr/athena/bin.  Inform your users to include /usr/athena/bin in their paths, or copy or symlink the binaries to some good place.  The programs that you will want to use are: kauth/kinit, klist, kdestroy, kpasswd, ftp, telnet, rcp, rsh, rlogin, su, rxtelnet, tenletxr, rxterm, and xnlock. If you are using AFS, afslog and pagsh might also be useful.  Administrators will want to use kadmin and ksrvutil, which are located in /usr/athena/sbin.

telnetd and rlogind assume that login is located in /usr/athena/bin (or whatever path you used as --prefix). If for some reason you want to move login, you will have to specify the new location with the -L switch when configuring telnetd and rlogind in inetd.conf.

It should be possible to replace the system's default login with the kerberised login.  However some systems assume that login performs some serious amount of magic that our login might not do (although we've tried to do our best). So before replacing it on every machine, try and see what happens.  Another thing to try is to use one of the authentication modules (see Authentication modules) supplied.

The login program that we use was in an earlier life the standard login program from NetBSD. In order to use it with a lot of weird systems, it has been ``enhanced'' with features from many other logins (Solaris, SunOS, IRIX, AIX, and others).  Some of these features are actually useful and you might want to use them even on other systems.

/etc/fbtab
/etc/logindevperm
     Allows you to chown some devices when a user logs in on a certain terminal.  Commonly used to change the ownership of /dev/mouse, /dev/kbd, and other devices when someone logs in on /dev/console.

     /etc/fbtab is the SunOS file name and it is tried first.  If there is no such file then the Solaris file name /etc/logindevperm is tried.

/etc/environment
     This file specifies what environment variables should be set when a user logs in. (AIX-style)

/etc/default/login
     Almost the same as /etc/environment, but the System V style.

/etc/login.access
     Can be used to control who is allowed to login from where and on what ttys. (From Wietse Venema)

Each user can have an authorization file ~USER/.klogin that determines what principals can login as that user.  It is similar to the ~user/.rhosts except that it does not use IP and privileged-port based authentication.  If this file does not exist, the user herself user@LOCALREALM will be allowed to login.  Supplementary local realms (see Install the configuration files) also apply here.  If the file exists, it should contain the additional principals that are to be allowed to login as the local user USER.

This file is consulted by most of the daemons (rlogind, rshd, ftpd, telnetd, popper, kauthd, and kxd) to determine if the principal requesting a service is allowed to receive it.  It is also used by su, which is a good way of keeping an access control list (ACL) on who is allowed to become root.  Assuming that ~root/.klogin contains:

     nisse.root@FOO.SE
     lisa.root@FOO.SE

both nisse and lisa will be able to su to root by entering the password of their root instance.  If that fails or if the user is not listed in ~root/.klogin, su falls back to the normal policy of who is permitted to su.  Also note that that nisse and lisa can login with e.g. telnet as root provided that they have tickets for their root instance.

Authentication modules
======================

The problem of having different authentication mechanisms has been recognised by several vendors, and several solutions has appeared. In most cases these solutions involve some kind of shared modules that are loaded at run-time.  Modules for some of these systems can be found in lib/auth.  Presently there are modules for Digital's SIA, Solaris' and Linux' PAM, and IRIX' login and xdm (in lib/auth/afskauthlib).

Digital SIA
-----------

How to install the SIA module depends on which OS version you're running. Tru64 5.0 have a new command, siacfg, which makes this process quite simple. If you have this program, you should just be able to run:

     siacfg -a KRB4 /usr/athena/lib/libsia_krb4.so

On older versions, or if you want to do it by hand, you have to do the following (not tested by us on Tru64 5.0):

  * Make sure libsia_krb4.so is available in /usr/athena/lib. If /usr/athena is not on local disk, you might want to put it in /usr/shlib or someplace else. If you do, you'll have to edit krb4_matrix.conf to reflect the new location (you will also have to do this if you installed in some other directory than /usr/athena). If you built with shared libraries, you will have to copy the shared libkrb.so, libdes.so, libkadm.so, and libkafs.so to a place where the loader can find them (such as /usr/shlib).

  * Copy (your possibly edited) krb4_matrix.conf to /etc/sia.

  * Apply security.patch to /sbin/init.d/security.

  * Turn on KRB4 security by issuing rcmgr set SECURITY KRB4 and rcmgr set KRB4_MATRIX_CONF krb4_matrix.conf.

  * Digital thinks you should reboot your machine, but that really shouldn't be necessary.  It's usually sufficient just to run /sbin/init.d/security start (and restart any applications that use SIA, like xdm.)

Users with local passwords (like root) should be able to login safely.

When using Digital's xdm the KRBTKFILE environment variable isn't passed along as it should (since xdm zaps the environment). Instead you have to set KRBTKFILE to the correct value in /usr/lib/X11/xdm/Xsession. Add a line similar to

     KRBTKFILE=/tmp/tkt`id -u`_`ps -o ppid= -p $$`; export KRBTKFILE

If you use CDE, dtlogin allows you to specify which additional environment variables it should export. To add KRBTKFILE to this list, edit /usr/dt/config/Xconfig, and look for the definition of exportList. You want to add something like:

     Dtlogin.exportList:     KRBTKFILE

Notes to users with Enhanced security
.....................................

Digital's ENHANCED (C2) security, and Kerberos solves two different problems. C2 deals with local security, adds better control of who can do what, auditing, and similar things. Kerberos deals with network security.

To make C2 security work with Kerberos you will have to do the following.

  * Replace all occurencies of krb4_matrix.conf with krb4+c2_matrix.conf in the directions above.

  * You must enable ``vouching'' in the default database.  This will make the OSFC2 module trust other SIA modules, so you can login without giving your C2 password. To do this use edauth to edit the default entry /usr/tcb/bin/edauth -dd default, and add a d_accept_alternate_vouching capability, if not already present.

  * For each user that does not have a local C2 password, you should set the password expiration field to zero. You can do this for each user, or in the default table. To do this use edauth to set (or change) the u_exp capability to u_exp#0.

  * You also need to be aware that the shipped login, rcp, and rshd, doesn't do any particular C2 magic (such as checking to various forms of disabled accounts), so if you rely on those features, you shouldn't use those programs. If you configure with --enable-osfc2, these programs will, however, set the login UID. Still: use at your own risk.

At present su does not accept the vouching flag, so it will not work as expected.

Also, kerberised ftp will not work with C2 passwords. You can solve this by using both Digital's ftpd and our on different ports.

Remember, if you do these changes you will get a system that most certainly does not fulfill the requirements of a C2 system. If C2 is what you want, for instance if someone else is forcing you to use it, you're out of luck.  If you use enhanced security because you want a system that is more secure than it would otherwise be, you probably got an even more secure system. Passwords will not be sent in the clear, for instance.

IRIX
----

The IRIX support is a module that is compatible with Transarc's afskauthlib.so.  It should work with all programs that use this library, this should include login and xdm.

The interface is not very documented but it seems that you have to copy libkafs.so, libkrb.so, and libdes.so to /usr/lib, or build your afskauthlib.so statically.

The afskauthlib.so itself is able to reside in /usr/vice/etc, /usr/afsws/lib, or the current directory (wherever that is).

IRIX 6.4 and newer seems to have all programs (including xdm and login) in the N32 object format, whereas in older versions they were O32. For it to work, the afskauthlib.so library has to be in the same object format as the program that tries to load it. This might require that you have to configure and build for O32 in addition to the default N32.

Appart from this it should ``just work'', there are no configuration files.

PAM
---

Currently the PAM module has only been tested under Linux and SunOS5 (aka Solaris). Probably it will also work on other systems but that has not yet been tried by us.

To build the module the argument --enable-shared must be passed to configure. This is necessary because PAM modules are loaded as shared libraries. Note that the shared libraries must also be available during runtime for the PAM module to operate correctly. You may pass the argument debug to the PAM module to trace configuration errors.

As an alternative to building shared libraries it is possible to build a stand-alone PAM module, i.e a module that does not depend on any of the Kerberos shared-libraries. To do this archive (.a) libraries containing position independent code are required. The following steps can be used to build a stand-alone PAM module:

     datan$ env CFLAGS=-fpic ./configure
     datan$ make
     datan$ cd lib/auth/pam
     datan$ make
     datan$ make install

Note that --enable-shared should not be passed to configure, setting CFLAGS takes care of that. The module will be functional even if the Kerberos libraries can not be loaded.

To use the module you should:

  * Make sure that pam_krb4.so is available in /usr/athena/lib. You might want to keep the module locally instead, /lib/security can be a better alternative if /usr/athena is not on local disk.

  * Look at krb4-1.0.2/lib/auth/pam/pam.conf.add for examples of what to add to /etc/pam.conf (or the files in /etc/pam.d).

The PAM module currently has no support for changing kerberos passwords. Use kpasswd instead.

The PAM module was greatly influenced by Derrick J Brashear's <shadow@dementia.org> Kerberos PAM module that can be found at

 ftp://ftp.dementia.org/pub/pam.