@node Installing programs, How to set up a realm, What is Kerberos?, Top @chapter 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. @c XXX 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. @menu * Installing from source:: * Installing a binary distribution:: * Finishing the installation:: * .klogin:: * Authentication modules:: @end menu @node Installing from source, Installing a binary distribution, Installing programs, Installing programs @comment node-name, next, previous, up @section Installing from source To build this software un-tar the distribution and run the @code{configure} script. To compile successfully, you will need an ANSI C compiler, such as @code{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 @code{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 @file{/usr/athena} with @kbd{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 @code{configure} with @samp{--prefix=/my/path}. If you need to change the default behavior, configure understands the following options: @table @asis @item @kbd{--enable-shared} Create shared versions of the Kerberos libraries. Not really recommended and might not work on all systems. @item @kbd{--with-ld-flags=}@var{flags} This allows you to specify which extra flags to pass to @code{ld}. Since this @emph{overrides} any choices made by configure, you should only use this if you know what you are doing. @item @kbd{--with-cracklib=}@var{dir} Use cracklib for password quality control in @pindex kadmind @code{kadmind}. This option requires @cindex cracklib cracklib with the patch from @url{ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch}. @item @kbd{--with-dictpath=}@var{dictpath} This is the dictionary that cracklib should use. @item @kbd{--with-socks=}@var{dir} @cindex firewall @cindex socks If you have to traverse a firewall and it uses the SocksV5 protocol (@cite{RFC 1928}), you can build with socks-support. Point @var{dir} to the directory where you have socks5 installed. For more information about socks see @url{http://www.socks.nec.com/}. @item @kbd{--with-readline=}@var{dir} @cindex readline To enable history/line editing in @code{ftp} and @code{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 @code{libedit}. If there is no library at all, the bundled version of @code{editline} will be used. @item @kbd{--with-mailspool=}@var{dir} The configuration process tries to determine where your machine stores its incoming mail. This is typically @file{/usr/spool/mail} or @file{/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 @pindex popper @code{popper}, and the mail check in @pindex login @code{login}. @item @kbd{--with-hesiod=}@var{dir} @cindex Hesiod Enable the Hesiod support in @pindex push @code{push}. With this option, it will try to use the hesiod library to locate the mail post-office for the user. @c @item @kbd{--enable-random-mkey} @c Do not use this option unless you think you know what you are doing. @item @kbd{--with-mkey=}@var{file} Put the master key here, the default is @file{/.k}. @item @kbd{--with-db-dir=}@var{dir} Where the kerberos database should be stored. The default is @file{/var/kerberos}. @item @kbd{--without-berkeley-db} If you have @cindex Berkeley DB Berkeley DB installed, it is preferred over @c XXX 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). @item @kbd{--without-afs-support} Do not include AFS support. @item @kbd{--with-afsws=}@var{dir} Where your AFS client installation resides. The default is @file{/usr/afsws}. @item @kbd{--enable-rxkad} Build the rxkad library. Normally automatically included if there is AFS. @item @kbd{--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). @item @kbd{--with-mips-api=}@var{api} This option enables creation of different types of binaries on Irix. The allowed values are @kbd{32}, @kbd{n32}, and @kbd{64}. @item @kbd{--enable-legacy-kdestroy} This compile-time option creates a @code{kdestroy} that does not destroy any AFS tokens. @item @kbd{--disable-otp} Do not build the OTP (@pxref{One-Time Passwords}) library and programs, and do not include OTP support in the application programs. @item @kbd{--enable-match-subdomains} Normally, the host @samp{host.domain} will be considered to be part of the realm @samp{DOMAIN}. With this option will also enable hosts of the form @samp{host.sub.domain}, @samp{host.sub1.sub2.domain}, and so on to be considered part of the realm @samp{DOMAIN}. @item @kbd{--enable-osfc2} Enable the use of enhanced C2 security on OSF/1. @xref{Digital SIA}. @item @kbd{--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. @item @kbd{--disable-cat-manpages} Do not install preformatted man pages. @c --with-des-quad-checksum @end table @node Installing a binary distribution, Finishing the installation, Installing from source, Installing programs @comment node-name, next, previous, up @section Installing a binary distribution The binary distribution is supposed to be installed in @file{/usr/athena}, installing in some other place may work but is not recommended. A symlink from @file{/usr/athena} to the install directory should be fine. @node Finishing the installation, .klogin, Installing a binary distribution, Installing programs @section Finishing the installation @pindex su The only program that needs to be installed setuid to root is @code{su}. If @pindex rlogin @pindex rsh @code{rlogin} and @code{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. @pindex login @code{login} does not have to be setuid, as it is always run by root (users should use @code{su} rather than @code{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 @file{/usr/athena/bin}. Inform your users to include @file{/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: @code{kauth}/@code{kinit}, @pindex kauth @pindex kinit @code{klist}, @code{kdestroy}, @code{kpasswd}, @code{ftp}, @pindex klist @pindex kdestroy @pindex kpasswd @pindex ftp @code{telnet}, @code{rcp}, @code{rsh}, @code{rlogin}, @code{su}, @pindex telnet @pindex rcp @pindex rsh @pindex rlogin @pindex su @pindex xnlock @pindex afslog @pindex pagsh @pindex rxtelnet @pindex tenletxr @pindex rxterm @code{rxtelnet}, @code{tenletxr}, @code{rxterm}, and @code{xnlock}. If you are using AFS, @code{afslog} and @code{pagsh} might also be useful. Administrators will want to use @code{kadmin} and @code{ksrvutil}, which are located in @file{/usr/athena/sbin}. @pindex kadmin @pindex ksrvutil @code{telnetd} and @code{rlogind} assume that @code{login} is located in @file{/usr/athena/bin} (or whatever path you used as @samp{--prefix}). If for some reason you want to move @code{login}, you will have to specify the new location with the @samp{-L} switch when configuring @pindex telnetd telnetd and @pindex rlogind rlogind in @file{inetd.conf}. It should be possible to replace the system's default @code{login} with the kerberised @code{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 (@pxref{Authentication modules}) supplied. The @code{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. @table @file @item /etc/fbtab @pindex fbtab @itemx /etc/logindevperm @pindex logindevperm Allows you to chown some devices when a user logs in on a certain terminal. Commonly used to change the ownership of @file{/dev/mouse}, @file{/dev/kbd}, and other devices when someone logs in on @file{/dev/console}. @file{/etc/fbtab} is the SunOS file name and it is tried first. If there is no such file then the Solaris file name @file{/etc/logindevperm} is tried. @item /etc/environment @pindex environment This file specifies what environment variables should be set when a user logs in. (AIX-style) @item /etc/default/login @pindex default/login Almost the same as @file{/etc/environment}, but the System V style. @item /etc/login.access @pindex login.access Can be used to control who is allowed to login from where and on what ttys. (From Wietse Venema) @end table @menu * .klogin:: * Authentication modules:: @end menu @node .klogin, Authentication modules, Finishing the installation, Installing programs @comment node-name, next, previous, up Each user can have an authorization file @file{~@var{user}/.klogin} @pindex .klogin that determines what principals can login as that user. It is similar to the @file{~user/.rhosts} except that it does not use IP and privileged-port based authentication. If this file does not exist, the user herself @samp{user@@LOCALREALM} will be allowed to login. Supplementary local realms (@pxref{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 @var{user}. This file is consulted by most of the daemons (@code{rlogind}, @code{rshd}, @code{ftpd}, @code{telnetd}, @code{popper}, @code{kauthd}, and @code{kxd}) @pindex rlogind @pindex rshd @pindex ftpd @pindex telnetd @pindex popper @pindex kauthd @pindex kxd to determine if the principal requesting a service is allowed to receive it. It is also used by @pindex su @code{su}, which is a good way of keeping an access control list (ACL) on who is allowed to become root. Assuming that @file{~root/.klogin} contains: @example nisse.root@@FOO.SE lisa.root@@FOO.SE @end example 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 @file{~root/.klogin}, @code{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. @code{telnet} as root provided that they have tickets for their root instance. @node Authentication modules, , .klogin, Installing programs @comment node-name, next, previous, up @section 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 @file{lib/auth}. Presently there are modules for Digital's SIA, Solaris' and Linux' PAM, and IRIX' @code{login} and @code{xdm} (in @file{lib/auth/afskauthlib}). @menu * Digital SIA:: * IRIX:: * PAM:: @end menu @node Digital SIA, IRIX, Authentication modules, Authentication modules @subsection Digital SIA To install the SIA module you will have to do the following: @itemize @bullet @item Make sure @file{libsia_krb4.so} is available in @file{/usr/athena/lib}. If @file{/usr/athena} is not on local disk, you might want to put it in @file{/usr/shlib} or someplace else. If you do, you'll have to edit @file{krb4_matrix.conf} to reflect the new location (you will also have to do this if you installed in some other directory than @file{/usr/athena}). If you built with shared libraries, you will have to copy the shared @file{libkrb.so}, @file{libdes.so}, @file{libkadm.so}, and @file{libkafs.so} to a place where the loader can find them (such as @file{/usr/shlib}). @item Copy (your possibly edited) @file{krb4_matrix.conf} to @file{/etc/sia}. @item Apply @file{security.patch} to @file{/sbin/init.d/security}. @item Turn on KRB4 security by issuing @kbd{rcmgr set SECURITY KRB4} and @kbd{rcmgr set KRB4_MATRIX_CONF krb4_matrix.conf}. @item Digital thinks you should reboot your machine, but that really shouldn't be necessary. It's usually sufficient just to run @kbd{/sbin/init.d/security start} (and restart any applications that use SIA, like @code{xdm}.) @end itemize Users with local passwords (like @samp{root}) should be able to login safely. When using Digital's xdm the @samp{KRBTKFILE} environment variable isn't passed along as it should (since xdm zaps the environment). Instead you have to set @samp{KRBTKFILE} to the correct value in @file{/usr/lib/X11/xdm/Xsession}. Add a line similar to @example KRBTKFILE=/tmp/tkt`id -u`_`ps -o ppid= -p $$`; export KRBTKFILE @end example If you use CDE, @code{dtlogin} allows you to specify which additional environment variables it should export. To add @samp{KRBTKFILE} to this list, edit @file{/usr/dt/config/Xconfig}, and look for the definition of @samp{exportList}. You want to add something like: @example Dtlogin.exportList: KRBTKFILE @end example @subsubheading Notes to users with Enhanced security Digital's @samp{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. @itemize @bullet @item Replace all occurencies of @file{krb4_matrix.conf} with @file{krb4+c2_matrix.conf} in the directions above. @item You must enable ``vouching'' in the @samp{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 @samp{edauth} to edit the default entry @kbd{/usr/tcb/bin/edauth -dd default}, and add a @samp{d_accept_alternate_vouching} capability, if not already present. @item For each user that does @emph{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 @samp{default} table. To do this use @samp{edauth} to set (or change) the @samp{u_exp} capability to @samp{u_exp#0}. @item You also need to be aware that the shipped @file{login}, @file{rcp}, and @file{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 @samp{--enable-osfc2}, these programs will, however, set the login UID. Still: use at your own risk. @end itemize At present @samp{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. @strong{Remember}, if you do these changes you will get a system that most certainly does @emph{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. @node IRIX, PAM, Digital SIA, Authentication modules @subsection IRIX The IRIX support is a module that is compatible with Transarc's @file{afskauthlib.so}. It should work with all programs that use this library, this should include @file{login} and @file{xdm}. The interface is not very documented but it seems that you have to copy @file{libkafs.so}, @file{libkrb.so}, and @file{libdes.so} to @file{/usr/lib}, or build your @file{afskauthlib.so} statically. The @file{afskauthlib.so} itself is able to reside in @file{/usr/vice/etc}, @file{/usr/afsws/lib}, or the current directory (wherever that is). IRIX 6.4 and newer seems to have all programs (including @file{xdm} and @file{login}) in the N32 object format, whereas in older versions they were O32. For it to work, the @file{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. @node PAM, , IRIX, Authentication modules @subsection PAM The PAM module was written more out of curiosity that anything else. It has not been updated for quite a while, but it seems to mostly work on both Linux and Solaris. To use this module you should: @itemize @bullet @item Make sure @file{pam_krb4.so} is available in @file{/usr/athena/lib}. You might actually want it on local disk, so @file{/lib/security} might be a better place if @file{/usr/athena} is not local. @item Look at @file{pam.conf.add} for examples of what to add to @file{/etc/pam.conf}. @end itemize There is currently no support for changing kerberos passwords. Use kpasswd instead. See also Derrick J Brashear's @code{} Kerberos PAM module at @* @url{ftp://ftp.dementia.org/pub/pam}. It has a lot more features, and it is also more in line with other PAM modules.