Introduction

This document is some quick notes to sophisticated implementors, on topics
which are a bit too arcane to be mentioned in the install instructions.
Beware that it is not updated very often, and may be behind the times.
This file is RCSID $Id: impl.notes,v 1.15 2001/06/08 16:22:16 henry Exp $



Where are things?

If your kernel sources are not located in /usr/src/linux, or local manual
pages are not in /usr/local/man/man[1-8], you've got a problem.  You may
be able to get around it to some extent just by modifying the top-level
Makefile, but we don't promise.  For a different manpage location, that
will probably suffice; for a different kernel location, probably not. 
We'd welcome reports of what needs to be fixed for this. 



Cross-compiling

At the moment, this distribution makes no attempt to support building
the software on one machine for use on another.  That's hard, especially
since the Linux kernel sources are not set up for it at all.



One thing at a time

(CAUTION:  This is somewhat outdated.  It's retained because it may be a
useful guide for experts.  Consult the Makefile for current details.)

If you want to do the build and install one step at a time, instead of
using the prepackaged make commands like "make menugo", do the following
instead.  (We do things in a slightly different order here, to avoid
unnecessary directory changing.)

To fit the kernel part of KLIPS into the kernel sources, do:

	make insert

(This makes a symbolic link /usr/src/linux/net/ipsec, pointing to the
KLIPS source directory.  It patches some kernel files, where necessary, to
know about KLIPS and/or to fix bugs.  It adds a default configuration to
the kernel configuration file.  Finally, it makes the KLIPS communication
file, /dev/ipsec, if it's not already there.)

Build the libraries, Pluto, and various user-level utilities: 

	make programs

Install the Pluto daemon and user-level utilities, and set things up for
boot-time startup:

	make install

Configure the kernel:

	cd /usr/src/linux
	make menuconfig          # (or xconfig, or whatever)

See the configuration step of INSTALL for details of what to do within
the configuration program.  Don't forget to save the results.

Go through the usual kernel make process (still in /usr/src/linux):

	make dep clean zImage

Caution:  the Linux kernel Makefiles are not always careful about checking
for errors.  We recommend capturing the output of this step and searching
it for any occurrence of "error", "Error", etc.  The details of how to do
so are unfortunately somewhat shell-dependent, although if you are using
the standard shell (rather than csh, tcsh, etc.), this would do:

	make dep clean zImage 2>&1 | tee junk
	egrep -i error junk		# no output is good output

(One glitch here is that the word "error" can sometimes occur legitimately
in the make output.  For example, the kernel math emulation package has a
source file "errors.c".  Some judgement is required to ignore such false
alarms.)  The prepackaged make commands do all this for you.

If your kernel is using loadable modules, you'll also need to do:

	make modules

Now you need to install the resulting kernel.  If you're not using the
kernel's "make install" -- many people aren't -- then you need to do your
usual install procedure.  You might want to read doc/kernel.notes, which
recounts some of our experiences with RedHat 5.2 kernel installation in
particular.

If "make install" is good enough for you, then: 

	make install

(Same comments on error checking as in previous step.)  If your kernel is
using loadable modules, you'll also need to do: 

	make modules_install

Finally, go back to INSTALL for the remaining steps.



Klips as a module

It is possible to run Klips as a kernel module, meaning that it does not
have to be loaded until needed.  Formerly this was necessary, in fact,
because Klips wouldn't run any other way.  Now it will, and we recommend
static linking ("y", not "m", to the configuration question) for security.
Klips is not terribly large (tens of KB, not hundreds) and should not
cause size problems unless your kernel is already pushing the limits.

However, Klips does still run as a module, if you want (although beware
that we don't test this option very often).  "ipsec setup start" and
"ipsec setup stop" load and unload it as appropriate, and you should not
need to do anything about that yourself.



Old Red Hats

Our development is currently on a mix of Red Hat 6.2 and 7.1, with 6.2
fading fast.  Our older Red Hats have been retired, and although FreeS/WAN
should still work on them, we no longer make any attempt to ensure that.