To install FreeS/WAN (KLIPS and Pluto, and associated auxiliaries):

0. If you have not already taken a look at the HTML documentation,
starting either from doc/setup.html or doc/index.html, you should do
so now.  (If you prefer text rather than HTML, see doc/README for methods
of generating text files.)  In particular, for installing this software
for the first time, you should be reading doc/setup.html, which will
refer you back to this file as appropriate.

Also, if you have used an earlier version but have not read the CHANGES
and BUGS files in this distribution, read them now.

We have skipped some expert-level topics, which are discussed in the
doc/impl.notes file. 

1. We assume you have unpacked the distribution into a suitable place,
e.g. a subdirectory of /usr/src.  We will also assume that your kernel
sources are in /usr/src/linux and that local manual pages are in
/usr/local/man/man[1-8] (see doc/impl.notes if not).

2. First, check that you have suitable kernel source.  We now recommend
version 2.0.38 (note that the kernel shipped with Red Hat 5.2 is now badly
obsolete, and we strongly recommend updating).  FreeS/WAN will work with
some earlier kernels, but many of them are less stable.  FreeS/WAN now
also works with 2.2.xx kernels. 

If you are using a kernel in which you have installed a pre-1.00 version
of FreeS/WAN, you will need to start over from the original kernel
distribution -- some of our kernel patches have changed, and there is no
good way for us to update files that have been patched by the old versions
(the patching now takes care to save enough information to do such updates
automatically in future). 

3. If you have Red Hat 5.1 or earlier, uncomment the line
"INSTALL_PATH=/boot" in /usr/src/linux/Makefile (edit the file and take
the "#" off the beginning of the line). 

4. If you have not actually configured, built, and booted your own Linux
kernel, do that first.  See the documentation for your Linux distribution
on how to do it -- it's too complex to describe here.  (Some of our
experiences on this in Red Hat 5.2 are recorded in doc/kernel.notes.  The
Linux kernel FAQ at <http://www.tux.org/lkml/> may also be of help.)  Make
sure you can boot both the new kernel and the original one. 

One particular boobytrap:  the Red Hat /etc/lilo.conf refers to the kernel
image by a name like "/boot/vmlinuz-2.0.36-0.7", which is very specific to
the particular version of the kernel you are compiling.  Changing that to
"/boot/vmlinuz" (which is a symlink pointing to the most recently-installed
kernel) may simplify your life. 

5. If possible, configure and test your system and network(s) without
FreeS/WAN, to make sure it can get packets from one end to the other. 
(If you don't do this, troubleshooting will be much more difficult.)
You may need to adjust both the kernel configuration and the files in
/etc/sysconfig; notably, on modern Red Hat Linuxes, /etc/sysconfig/network
starts out including a "FORWARD_IPV4=false" line, which will prevent any
packet forwarding from one network to another at all. 

6. If you are not already running as root, you need to become root at this
point.  Most of the remaining steps require root's authority.

7. cd to the top-level directory of the FreeS/WAN distribution (where this
INSTALL file is), if you are not already there.

8. You need to decide which form of the Linux kernel configuration program
you want to use:  menuconfig, xconfig, or the original config.  In the
top-level directory of the distribution, run ONE of the following "make"
commands.  (You may want to arrange for the output to be saved in some way,
in case there are problems; the "script" command is one way to do that.)

	# run only one of these
	make menugo		# use menuconfig
	make xgo		# use xconfig
	make ogo		# use config
	make oldgo		# use oldconfig

This will attend to some preliminaries (including fitting the kernel part
of KLIPS into the kernel sources; a report on some details of this is left
in the file out.kpatch), run the chosen configuration program (see step 9
for what to do within it), compile the software, install it, and build a
kernel with it (but NOT install the kernel).  Proper error checking is
done at every step; the make WILL STOP if something goes wrong (even in
the Linux kernel makefiles, which are careless about this themselves --
their output is caught and checked). 

9. Whichever configuration program you are using, you should pay careful
attention to a few issues:

9a. Most "Networking options" items relevant to IPSEC are now set properly
by default; in particular, do NOT disable any of the following:

	IP: forwarding/gatewaying		(2.0.xx kernels only)
	Kernel/User network link driver		(2.0.xx kernels only)
	Kernel/User netlink socket		(2.2.xx kernels only)

You might possibly want to enable:

	IP: optimize as router not host

In 2.2.xx, it may look tempting to enable:

	IP: advanced router

but beware that its "rp_filter" subsystem must be turned off for IPSEC
to work properly (see the Help button for details); unless you know what
you're doing, it's probably better to leave the advanced router disabled.

9b. In "Networking options", you will see "IP Security Protocol (IPSEC)",
which should already be enabled (as a part of the basic kernel ["y"]; see
doc/impl.notes for enabling it as a module ["m"]).  Under it are a number
of details; the defaults are intended to be reasonable, but you may want
to change some.

By default, the IPSEC transforms which do only authentication, without
encryption, are disabled.  There is no problem with enabling these
transforms, except that data sent using them is not very secure. 

The standard configuration enables "IPSEC Debugging Option", the KLIPS
debugging facilities, which are switched on and off via the "klipsdebug"
utility (see the ipsec_klipsdebug(8) manual page).  At the current stage
of development, we *strongly* suggest leaving this option enabled.

9c. Complete the configuration process and save the new configuration
settings.  You MUST do this even if you have made no changes; KLIPS will
not be part of your kernel configuration until such a save is done.  The
makefile attempts to check to make sure this has been done.

10. Wait.  The compile and kernel build may take a while, depending on the
speed of your machine.  A 200MHz PCI machine with 32MB and good disks will
take perhaps 5 minutes, while a 386 with limited resources may need more
than a day (!).  No interaction is needed after the configuration save. 

11. Inspect the very last line of make's output.  It should be:

	utils/errcheck out.kbuild

If not, then something didn't work, and you need to investigate that
before proceeding.  If the problem happened during kernel build, the
kernel-build make output is in out.kbuild.  doc/debugging.html may help. 

If all went well, then almost everything is ready.

Most of the user-level utilities are in /usr/local/lib/ipsec, with the
"ipsec" command in /usr/local/sbin to provide easy access to the rest. 
(In general, we assume that /usr/local/sbin is in your shell's search path
for testing, so that you can run "ipsec" by typing just "ipsec" not
"/usr/local/sbin/ipsec".)

The manual pages are installed, mostly under names starting with "ipsec_"
to avoid name conflicts. 

The new kernel is built but not yet installed.

At boot time, KLIPS and Pluto will start automatically.  If you are
running a pre-5.0 Red Hat or other system with no chkconfig command, the
Makefile has tried to set up the necessary symbolic links under /etc/rc.d
itself.  Either way, the link setup it uses is right in simple cases but
might have to be hand-tuned on complicated systems.

12. Install the new kernel, as you did in step 4.  If kernel install on
your system does NOT use the kernel's own "make install" (and "make
modules_install") procedures, you're on your own here. Do whatever it
takes to install the kernel and modules on your system.

If you ARE using the kernel "make install", then you can cd to
/usr/src/linux and do "make install" and "make modules_install".
Or, as a convenience, you can do both from the top-level directory
of the FreeS/WAN distribution by saying: 

	make kinstall		# only if using kernel "make install" etc.

This does "make modules_install" too, if it appears to be required. 
Again, this is properly error-checked; the last output line should be: 

	utils/errcheck out.kinstall

If not, something is wrong.  The make output is in out.kinstall if you
need to examine it.

13. Edit the /etc/ipsec.conf configuration file.  Most of it can be left
alone for the moment, but the interface names near the top -- that is, the
contents of "interfaces" under "config setup" -- must be right or there
will be trouble when you try running FreeS/WAN.  The Makefile is careful
not to overwrite changed configuration files when run again. 

14. Go back to doc/setup.html (see step 0) for instructions on how to make
the software run. 

This file is RCSID $Id: INSTALL,v 1.97 2000/01/07 02:48:48 henry Exp $
