# Installing FreeS/WAN

## Who needs to perform an installation?

Some Linux distributions, listed in the introduction, ship with FreeS/WAN included. If you are using one of them, you need not perform a FreeS/WAN installation. That should all be done for you already. All you have to do is:

- include FreeS/WAN in your installation choices, or add it to your configuration later
- if you install kernel source, be sure to use a version which includes the FreeS/WAN patches. This should be available from your CDs or from the web site for your distribution.

Users of such distributions can skip ahead to our section on setting up FreeS/WAN.

Unfortunately, due to export laws restricting distribution of strong cryptography, not all distributions include FreeS/WAN. Moreover, the standard kernel does not include the kernel parts of FreeS/WAN. Many people will need to install FreeS/WAN, including patching and rebuilding their kernel.

## Re-installs

If this is the first FreeS/WAN install on this machine, skip this section.

The scripts are designed so that a re-install -- to upgrade to a later FreeS/WAN version or to a later kernel version -- can be done in exactly the same way as an original install.

The scripts know enough, for example, not to apply the same kernel patch twice and not to overwrite your ipsec.conf or ipsec.secrets files. However, they will overwrite the _updown script. If you have modified that, save your version under another name before doing the install.

Also, they may not always work exactly as designed. Check the BUGS file for any caveats in the current version.

to install a new version of FreeS/WAN, with your current kernel
  Download and untar the new FreeS/WAN. Since kernel source has already been installed and configured, you can skip a few steps in the procedure below. Go to Building FreeS/WAN, and follow normal FreeS/WAN procedures from there.
to install a new kernel, on a machine which already has FreeS/WAN installed
  Download and untar the new kernel source. Since this kernel is not yet configured, that is the next thing to do.Go to Kernel configuration, and follow normal FreeS/WAN procedures from there.
to upgrade both kernel and FreeS/WAN
  You need both new kernel source and new FreeS/WAN source. Follow the full FreeS/WAN install procedure.

## Before starting the install

Configure, compile, install, and test a Linux kernel, without FreeS/WAN.

If you have not done this before, you will need to read the Kernel HowTo.

### Choosing a kernel

#### 2.2.19 for many users

Many users can continue to run kernels from the 2.2 series of Linux production kernels.

At time of writing (June 2001), the latest version is 2.2.19. If you are going to use a 2.2 kernel, we strongly recommend 2.2.19 since:

- It has a number of small security fixes not found in earlier kernels.
- There have been changes in some kernel file formats that make it difficult to compile a current FreeS/WAN with earlier kernels.

If you really need to use an older 2.2.x kernel for some reason, see the note in the FreeS/WAN 1.91 release CHANGES file for a workaround for the compile difficulty, and the mailing list archives for more details if needed.

#### 2.4.x is possible

The new 2.4 series of kernels began in January 2001 and are currently (early June) at 2.4.5. FreeS/WAN is known to work on 2.4.5.

2.4 has new firewalling code called netfilter. This may provide good reasons to move to 2.4, especially on for gateway machines.

#### 2.0.x should still work

In the older 2.0.x kernel series, we no longer support versions earlier than 2.0.38. 2.0.38 has fixes for a number of small security-related glitches, worth having on a security gateway machine. FreeS/WAN has been tested on 2.0.39, and does work there.

Recent versions of FreeS/WAN are not heavily tested on 2.0 kernels. Most of both the development team and the user community are on 2.2, or even 2.4, by now.

We are likely to drop 2.0 support entirely if some problem crops up that would mean retaining it required significant work from our team.

#### Development kernels

Development kernels are a separate series, work-in-progress versions for use by kernel developers. By convention, production kernels have an even second digit in the version number (2.0, 2.2, 2.4) and development kernels have an odd digit there (2.1, 2.3, 2.5).

At time of writing, no more 2.3 kernels are being produced and the 2.5 series has not been started yet, so just now development kernels are not an issue. No doubt a 2.5 series will be started in the next few months.

Development kernels are not intended for production use. They change often and include new code which has not yet been thoroughly tested. This regularly breaks things, including FreeS/WAN. The FreeS/WAN team does not have the resources to chase the moving target; our priority is developing FreeS/WAN on stable kernels. If you encounter a problem on a development kernel, please solve it (you are a developer, aren't you?) and send us a patch. Of course, we will happily discuss problems and solutions on the mailing list, but we are unlikely to do much work on actually implementing a solution.

Fortunately we have a user who regularly fixes problems with FreeS/WAN on development kernels (merci, Marc), and we do fix some ourselves. FreeS/WAN often works just fine on a development kernel; it's just that there's no guarantee.

If you are going to test FreeS/WAN with a development kernel, we recommend you use our latest snapshot. This is the FreeS/WAN version most likely to have the patches required to work on a recent development kernel. The released version of FreeS/WAN is likely to be out of date for your purposes.

### Things you must have installed

If you have a CD distribution of Linux, it should include everything you need.

#### Tools and libraries

Use your distribution's tools to load:

- tools
  - a GNU C compiler (gcc or egcs)
  - assembler and linker for your architecture (the bin86 package on PCs)
  - miscellaneous development tools such as make(1) and patch(1)
- libraries, both headers and object modules
  - standard compiler libraries such as glibc
  - the GMP (GNU Multi-Precision) library, required for Pluto's public key calculations.
  - ncurses library if you want to use menuconfig (recommended)

There are some common slips worth avoiding here:

- not installing the GMP library. Pluto will not compile without it. See the FreeS/WAN FAQ for more detail if required.
- not installing patch(1). Our scripts need it to apply our patches to the kernel.

#### Kernel source code

You need the source code for the kernel because you must patch and re-compile it to install FreeS/WAN. There are several places you can get this:

- off your distribution CDs
- from your ditribution vendor's website
- from kernel.org

##### Kernel from CD

You can install the kernel from your distribution CD. It may be in two packages.

- kernel source
- kernel headers

However, if your CD is not recent, it may have an older kernel, in which case we suggest getting more recent kernel source from the net.

##### Vendor kernels

All the major distribution vendors provide kernel source. See for example:

- Red Hat's list of mirror sites
- SuSE's download page

Using a kernel from your distribution vendor may save you some annoyance later.

Different distributions put the kernel in different places (/vmlinuz, /boot/vmlinuz, /boot/vmlinuz-2.2.15 ...) and set lilo (the Linux loader) up differently. With a kernel from your distribution vendor, everything should work right. With other combinations, a newly compiled kernel may be installed in one place while lilo is looking in another. You can of course adjust the kernel Makefile and/or /etc/lilo.conf to solve this problem, but we suggest just avoiding it.

Also, distributions vendors may include patches or drivers which are not part of the standard kernel. If you install a standard kernel, you must either do without those features or download those patches and add them yourself.

##### Kernels from kernel.org

For kernels direct from Linus, without any distribution vendor's modifications, see the kernel.org mirror list, or go directly to ftp.<country>.kernel.org, with the appropriate two-letter country code inserted.

#### Once you've found a kernel

Once you have found suitable kernel source, choose a mirror that is close to you and bookmark it.

Kernel source normally resides in /usr/src/linux, whether you load it from a distribution CD or download a tar file into /usr/src and untar it there. Unless you both have unusual requirements and know exactly what you're doing, we recommend you put it there.

### Getting FreeS/WAN

You can download FreeS/WAN from our primary site or one of our mirrors.

Put the tarfile under /usr/src and untar it there. The command to use is:

- tar -xzf freeswan*.gz

This will give you a directory /usr/src/freeswan<version>.

Note that these methods don't work:

- putting freeswan under /usr/src/linux. The links become confused.
- untarring in one place, then using cp -R to move it where you want it. Some necessary symbolic links are not copied.

### Kernel configuration

The gateway kernel must be configured before FreeS/WAN is added because some of our utilities rely on the results of configuration.

Note for Redhat 7.1 users: If you are using the Redhat-supplied kernel, then you must do a make mrproper command before starting the kernel configuration. This prevents some unpleasant interactions between Redhat's config and our patches.

On some distributions, you can get the configuration files for the vendor's standard kernel(s) off the CD, and use that. This allows you to skip this step; you need not configure the kernel if the vendor has and you have the vendor's config file installed. Here is a mailing list message describing the procedure for Redhat:

    Subject: Re: [Users] Do I need to recompile kernel 2.2.17-14?
       Date: Wed, 6 Jun 2001 08:38:38 -0500
       From: "Corey J. Steele" <csteele@mtron.com>

    if you install the corresponding kernel-source-*.rpm, you can actually find
    the config file used to build that kernel in /usr/src/linux/Configs, just
    copy the one you want to use (based solely on architecture) to
    /usr/src/linux/.config, and proceed!  It should work.

If you have ever configured the kernel yourself on this machine, you can also skip this step.

If the kernel has not been configured, do that now. This is done by giving one of the following commands in /usr/src/linux:

make config
  command-line interface
make menuconfig
  text menus (requires curses(3) libraries)
make xconfig
  using the X window system (requires X, not recommended for gateways)

Any of these wiil do the job. If you have no established preference, we suggest trying menuconfig.

For more information on configuring your kernel, see our section on that topic.

### Install and test a kernel before adding FreeS/WAN

You should compile, install and test the kernels as you have configured them, so that you have a known stable starting point. The series of commands involved is usually something like:

make menuconfig
  choose kernel options, set up a kernel for your machine
make dep
  find dependencies between files
make bzImage
  build a loadable kernel image, compressed with bzip(1)
make install
  install it
make modules
  build modules which can be added to a running kernel
make modules_install
  install them
lilo
  ensure that the boot loader sees your changes

Doing this first means that if there is a problem after you add FreeS/WAN, tracking it down is much simpler.

If you need advice on this process, or general Linux background information, try our Linux web references. The most directly relevant document is the Kernel HowTo.

## Building and installing the software

There are several ways to build and install the software. All require that you have kernel source, correctly configured for your machine, as a starting point. If you don't have that yet, see the previous section

Whatever method you choose, it will do all of the following:

- add FreeS/WAN code to the kernel
  - insert patches into standard kernel code to provide an interface
  - add additional files which use that interface
- re-configure and re-compile the kernel to activate that code
- install the new kernel
- build the non-kernel FreeS/WAN programs and install them
  - ipsec(8) in /usr/local/sbin
  - others in /usr/local/lib/ipsec
- install FreeS/WAN man pages under /usr/local/man
- create the configuration file ipsec.conf(5). Editing this file to configure your IPSEC gateway is described in the next section.
- create an RSA public/private key pair for your system and place it in ipsec.secrets(5)
- install the initialisation script /etc/rc.d/init.d/ipsec
- create links to that script from the /etc/rc.d/rc[0-6].d directories so that each run level starts or stops IPSEC. (If the previous sentence makes no sense to you, try the From Power-up to Bash Prompt HowTo).

You can do the whole install with two commands (recommended in most cases) or get into as much of the detail as you like.

### Everything but kernel installation

To do everything except install the new kernel, cd into the freeswan directory and become root. Give any one of the following commands:

make oldgo
  Uses FreeS/WAN's default settings for some kernel configuration options. Leaves all other options unchanged from your last kernel configuration.
make ogo
  Invokes config so you can configure the kernel from the command line.
make menugo
  Invokes menuconfig so you can configure the kernel with text-mode menus.
make xgo
  Invokes xconfig so you can configure the kernel in an X window.

You must save the new configuration even if you make no changes. This ensures that the FreeS/WAN changes are actually seen by the system.

Our scripts save the output of make commands they call in files with names like out.kbuild or out.kinstall. The last command of each script checks the appropriate out.* file for error messages.

- If the last output you see is make saying it is calling our errcheck script, then all is well. There were no errors.
- If not, an error has occurred. Check the appropriate out.* file for details.

For the above commands, the error files are out.kpatch and out.kbuild.

These scripts automatically build an RSA authentication key pair (a public key and the matching private key) for you, and put the result in /etc/ipsec.secrets. For information on using RSA authentication, see our configuration section. Here, we need only note that generating the key uses random(4) quite heavily and if random(4) runs out of randomness, it will block until it has enough input. You may need to provide input by moving the mouse around a lot, or going to another window and typing random characters, or using some command such as du -s /usr to generate disk activity.

### Installing the new kernel

To install the kernel the easy way, just give this command in the FreeS/WAN directory:

make kinstall
  Installs the new kernel and, if required, the modules to go with it. Errors, if any, are reported in out.kinstall

Using make kinstall from the FreeS/WAN directory is equivalent to giving the following sequence of commands in /usr/src/linux:

- make
- make install
- make modules
- make modules_install

If you prefer that sequence, use it instead.

If you have some unusual setup such that the above sequence of commands won't work on your system, then our make kinstall will not work either. Use whatever method does work on your system. See our implementation notes file for additional information that may help in such situations.

### Make sure Lilo knows about the new kernel

Check your lilo.conf(5) file to ensure it points to the right kernel, then run lilo(8) to read lilo.conf(5) and set up the bootloader.

## Testing to see if install succeeded

To check that you have a sucessful install, you can reboot and check (by watching messages during boot or by looking at them later with dmesg(8)) that:

- the kernel reports the right version. If not, you are likely still running your old kernel. Check your lilo.conf(5) file and the installation directory (defined in the kernel make file, often /boot but the default is /), then rerun lilo(8).
- KLIPS initialisation messages appear
- Pluto reports that it is starting

You can also try the commands:

- ipsec --version, to test whether /usr/local/bin is in your path so you can use IPSEC administration commands
- ipsec whack --status, using ipsec_whack(8) to ask Pluto for status information

Of course any status information at this point should be uninteresting since you have not yet configured connections.

## Where to go from here

See the following section for information on configuring connections.

Alternately, you might want to look at background material on the protocols used before trying configuration.