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.36 (note that the kernel shipped with Red Hat 5.2 is a
pre-release 2.0.36, and we recommend getting the final one).  FreeS/WAN
will work with some earlier kernels, but many of them are less stable.
FreeS/WAN does NOT work with 2.2.xx kernels yet, and fixing that is not
simple.

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 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 5.2 /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" 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, accordingly: 

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

This will attend to some preliminaries (including fitting the kernel part
of KLIPS into the kernel sources), 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 relevant to IPSEC are now set properly by
default; in particular, you should find all of the following enabled, and
you should leave them that way! 

	IP: forwarding/gatewaying
	IP: tunneling
	Kernel/User network link driver

You might possibly want to enable:

	IP: optimize as router not host

9b. You will also see a new entry for "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 other options; they are set reasonably, 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 (via "IPSEC Debugging Option") 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. The compile and kernel make 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.  If you are NOT using the "make install" (and
"make modules_install") procedures provided in the kernel makefiles,
you're on your own here -- follow whatever procedures you used in step 4. 
If you ARE using "make install", do that from the top-level directory of
the 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.84 1999/04/10 20:41:24 henry Exp $
