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:
For other distributions, you may be able to find pre-packaged RPMs and use the simple installation we describe in our quickstart document.
If either of those methods works for you, we recommend you use it. Once that is done, continue at enabling FreeS/WAN in our quickstart document.
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.
Also, if you need to add patches to the FreeS/WAN code (see this list), you need to do that and then install FreeS/WAN from the patched source.
Many people will need to install FreeS/WAN from source, including patching and rebuilding their kernel.
Information on re-installing or un-installing is provided near the end of this document.
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. You might also look at this magazine article.
The general rule is choose a current release of a production kernel -- the latest 2.2 or 2.4.
For specific information on which kernels a FreeS/WAN release supports, see the README file in that release.
Many users can continue to run kernels from the 2.2 series of Linux production kernels.
We recommend using the latest release in that series. At time of writing (Feb 2002), that is 2.2.20.
If you need to use an older 2.2.x kernel for some reason, be warned that recent versions of FreeS/WAN will not compile out-of-the-box on a kernel earlier than 2.2.19. A workaround is described in the FreeS/WAN 1.91 section of our CHANGES file. See the mailing list archives, around June 2001, for more details if needed.
2.4 has new firewalling code called nefilter. This may provide good reasons to move to 2.4, especially on for gateway machines.
Do not use 2.4.15; it has a bug that causes file system corruption.
If you must use the older 2.0.x kernel series -- for example because you need some driver that has not been ported to later kernels -- you may be in luck. When last tested, FreeS/WAN worked fine on 2.0.39.
On the other hand, you may have problems in the future. 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 -- and we are almost certain to drop 2.0 support whenever some problem crops up that would mean retaining it required significant work from our team.
Development kernels are not intended for production use . They change often and include new code which has not yet been thoroughly tested. These changes often break 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.
If you have a CD distribution of Linux, it should include everything you need.
Use your distribution's tools to load:
There are some common slips worth avoiding here:
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:
All the major distribution vendors provide kernel source. See for example:
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 Li nux 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.
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.
Note: Some recent distributions (certainly Redhat 7.2 and Mandrake 8.1, perhaps others) put kernel source code in a directory named linux-2.4 while FreeS/WAN expects to find it in linux, which is where all distributions used to put it and the kernel.org kernels still do. If your distribution uses linux-2.4, then you must create a symbolic link to linux before proceeding with your FreeS/WAN install. See the man page for ln(1) for details of how to do this if required.
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:
This will give you a directory /usr/src/freeswan<version>.
Note that these methods don't work:
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
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:
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.
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:
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.
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:
You can do the whole install with two commands (recommended in most cases) or get into as much of the detail as you like.
Go to the FreeS/WAN directory and do whichever of the following commands you prefer:
After the Makefile does the software and kernel build, it will make some RPMs and leave them in the rpms directory. The RPMs are:
Once you have the RPMs, you can install FreeS/WAN from them with rpm -i commands. For a more detailed procedure, go to our quickstart document.
This makes it much easier to build FreeS/WAN on one system for installation on another.
This facility is based on work by Paul Lahaie at Steamballoon.
With the full procedure described in the next section, you can either build the kernel parts of FreeS/WAN into your kernel or build them as a kernel module, depending on how you set the kernel configuration options.
Since 1.91, we also provide an option to build only the FreeS/WAN module, without re-compiling the rest of your kernel.
Note, however, that this requires:
To do the module install, give two commands in the FreeS/WAN directory:
You can now start FreeS/WAN with
service ipsec start
then choose what to do next.
N.B.: This is relatively new code and not yet tested on a wide range of systems. If it does not work for you, please report the problem. In the meanwhile, fall back to the older procedure described next..
There are two steps here. First you do everything else, then you install the new FreeS/WAN-enabled kernel.
To do everything except install the new kernel, cd into the freeswan directory and become root. Give any one of the following commands:
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.
There are few options in the FreeS/WAN part of kernel configuration. For most of them, we recommend that you make no changes.
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.
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.
To install the kernel the easy way, just give this command in the FreeS/WAN directory:
Using make kinstall from the FreeS/WAN directory is equivalent to giving the following sequence of commands in /usr/src/linux:
If you prefer that sequence, use it instead.
Reboot to enable your new FreeS/WAN-enabled kernel.
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.
At this point, you are finished the install. Go to the quickstart document section on testing your FreeS/WAN install and continue from there.
Alternately, you might want to look at background material on the protocols used before trying configuration.
If you have FreeS/WAN installed from source on this machine, and need to install a newer version or un-install FreeS/WAN, this section is for you.
If you have FreeS/WAN installed from RPMs, use rpm -e or rpm -u to uninstall or upgrade.
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.
In many Linux distributions, you can easily disable FreeS/WAN with the command:
chkconfig --del ipsec
This removes the symlinks in /etc/rc.d/rc?.d which cause ipsec(8) to be called at boot time or when switching run levels. If the kernel part of IPsec, KLIPS, has been compiled as a module, then this also prevents loading that module, so IPsec is completely disabled.
Other distributions may use another version of init(8), or may not provide the chkconfig(8) command. For these, you will have to use other tools, or manually edit the init scripts, to achieve the same effect.
If you installed FreeS/WAN from RPMs, then just use rpm -e to uninstall it. This section is for those who have installed from source.
To entirely remove the user-level FreeS/WAN components from your system, go to the FreeS/WAN install directory and give the command:
make uninstall_freeswan
If that doesn't work for you -- for example, if FreeS/WAN was built on another system and copied here -- then you can do it manually. First disable FreeS/WAN as described above (to avoid problems with symlinks pointing to things you are about to remove), and then use these commands:
rm -f /etc/ipsec.* /usr/local/sbin/ipsec /etc/rc.d/init.d/ipsec
rm -rf /usr/local/lib/ipsec
rm -f /usr/local/man/man?/ipsec[._]*
You may need to vary the commands slightly if you, or whoever packaged your distribution, changed the install directories when building FreeS/WAN.
If you compiled KLIPS as a module, then just disabling FreeS/WAN as described above prevents loading the module.
If KLIPS is compiled into your kernel, then you can disable it by turning off IPsec in your kernel configuration (or by making it a module) and recompiling.
You can remove the FreeS/WAN patches from your kernel source by going to the FreeS/WAN install directory and giving the command:
make unpatch
This does not remove all FreeS/WAN changes; some are not done with patch(1) and cannot be reversed in this way.
To remove all trace of IPsec in your kernel, you should revert to an unpatched version, or download fresh kernel source.