diff options
Diffstat (limited to 'crypto/kerberosIV/doc/install.texi')
| -rw-r--r-- | crypto/kerberosIV/doc/install.texi | 368 |
1 files changed, 368 insertions, 0 deletions
diff --git a/crypto/kerberosIV/doc/install.texi b/crypto/kerberosIV/doc/install.texi new file mode 100644 index 0000000..240c04e --- /dev/null +++ b/crypto/kerberosIV/doc/install.texi @@ -0,0 +1,368 @@ +@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{--with-shared} +Create shared versions of the Kerberos libraries. Not really +recommended and might not work on all systems. + +@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 @kbd{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). +@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 (@xref{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}). +@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}. +@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 + +There is currently no support for changing passwords. Use @file{kpasswd} +instead. + +@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 to this use @samp{edauth} to +set (or change) the @samp{u_exp} capability to @samp{u_exp#0}. +@item +You should make sure that you use Digital's login rather than the one +distributed by us. The easiest way to do this is to replace +@file{/usr/athena/bin/login} with @file{/bin/login}. +@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). + +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. |
