freebsd-dev/crypto/kerberosIV/doc/install.texi

@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::  
* 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
@code{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 managed 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}.

@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{--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{--disable-shared-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=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.
@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, Authentication modules, 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
* Authentication modules::      
@end menu

@node  Authentication modules,  , Finishing the installation, 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, Linux'
PAM (might also work on Solaris, when PAM gets supported), 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, since none of us are using
Linux, and Solaris does not support PAM yet.  We've had positive reports
from at least one person using the module, though.

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{<shadow@@dementia.org>} Kerberos PAM
module at @kbd{ftp://ftp.dementia.org/pub/pam}. It has a lot more
features, and it is also more in line with other PAM modules.