Initial import from FreeBSD RELENG_4:

[dragonfly.git] / 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::  
* .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{<shadow@@dementia.org>} 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.