This section gives an overview of:
This section is intended to cover only the essentials, things you should know before trying to use FreeS/WAN.
For more detailed background information, see the history and politics and IPSEC protocols sections.
FreeS/WAN is a Linux implementation of the IPSEC (IP security) protocols. IPSEC provides encryption and authentication services at the IP (Internet Protocol) level of the network protocol stack.
Working at this level, IPSEC can protect any traffic carried over IP, unlike other encryption which generally protects only a particular higher-level protocol -- PGP for mail, SSH for remote login, SSL for web work, and so on. This has both advantages and disadvantages, discussed in our IPSEC section
IPSEC can be used on any machine which does IP networking. Dedicated IPSEC gateway machines can be installed wherever required to protect traffic. IPSEC can also run on routers, on firewall machines, on various application servers, and on end-user desktop or laptop machines.
Three protocols are used
Our implementation has three main parts:
IPSEC is optional for the current (version 4) Internet Protocol. FreeS/WAN adds IPSEC to the Linux IPv4 network stack. Implementations of IP version 6 are required to include IPSEC. Work toward integrating FreeS/WAN into the Linux IPv6 stack has started.
For more information on IPSEC, see our IPSEC protocols section, our collection of IPSEC links or the RFCs which are the official definitions of these protocols.
IPSEC is designed to let different implementations work together. We provide:
The VPN Consortium fosters cooperation among implementers and interoperability among implementations. Their web site has much more information.
Because IPSEC operates at the network layer, it is remarkably flexible and can be used to secure nearly any type of Internet traffic. Two applications, however, are extremely widespread:
There is enough opportunity in these applications that vendors are flocking to them. IPSEC is being built into routers, into firewall products, and into major operating systems, primarily to support these applications. See our list of implementations for details.
We support both of those applications, and various less common IPSEC applications as well, but we also add one of our own:
This is an extension we are adding to the protocols. FreeS/WAN is the first prototype implementation, though we hope other IPSEC implementations will adopt the technique once we demonstrate it. See project goals below for why we think this is important.
A somewhat more detailed description of each of these applications is below. Our setup section will show you how to build each of them.
A VPN, or Virtual Private Network lets two networks communicate securely when the only connection between them is over a third network which they do not trust.
The method is to put a security gateway machine between each of the communicating networks and the untrusted network. The gateway machines encrypt packets entering the untrusted net and decrypt packets leaving it, creating a secure tunnel through it.
If the cryptography is strong, the implementation is careful, and the administration of the gateways is competent, then one can reasonably trust the security of the tunnel. The two networks then behave like a single large private network, some of whose links are encrypted tunnels through untrusted nets.
Actual VPNs are often more complex. One organisation may have fifty branch offices, plus some suppliers and clients, with whom it needs to communicate securely. Another might have 5,000 stores, or 50,000 point-of-sale devices. The untrusted network need not be the Internet. All the same issues arise on a corporate or institutional network whenever two departments want to communicate privately with each other.
Administratively, the nice thing about many VPN setups is that large parts of them are static. You know the IP addresses of most of the machines involved. More important, you know they will not change on you. This simplifies some of the admin work. For cases where the addresses do change, see the next section.
The prototypical "Road Warrior" is a traveller connecting to home base from a laptop machine. Administratively, most of the same problems arise for a telecommuter connecting from home to the office, especially if the telecommuter does not have a static IP address.
For purposes of this document:
These require somewhat different setup than VPN gateways with static addresses and with client systems behind them, but are basically not problematic.
There are some difficulties which appear for some road warrior connections:
In most situations, however, FreeS/WAN supports road warrior connections just fine.
One of the reasons we are working on FreeS/WAN is that it gives us the opportunity to add what we call opportuntistic encryption. This means that any two FreeS/WAN gateways will be able to encrypt their traffic, even if the two gateway administrators have had no prior contact and neither system has any preset information about the other . We hope this will go some distance toward creating a secure Internet, an environment where message privacy is the default. See our history and politics of cryptography section for discussion.
Both systems pick up the authentication information they need from the DNS (domain name service), the service they already use to look up IP addresses. Of course the administrators must put that information in the DNS, and must set up their gateways with opportunistic encryption enabled. Once that is done, everything is automatic. The gateways look for opportunities to encrypt, and encrypt whatever they can. Whether they also accept unencrypted communication is a policy decision the administrator can make.
A draft document giving most of the details of how we plan to implement this has been posted to the mailing list. See links below.
Only one current product we know of implements a form of opportunistic encryption. Secure sendmail will automatically encrypt server-to-server mail transfers whenever possible.
A complication, which applies to any type of connection -- VPN, Road Warrior or opportunistic -- is that a secure connection cannot be created magically. There must be some mechanism which enables the gateways to reliably identify each other. Without this, they cannot sensibly trust each other and cannot create a genuinely secure link.
Any link they do create without some form of authentication will be vulnerable to a man-in-the-middle attack. If Alice and Bob are the people creating the connection, a villian who can re-route or intercept the packets can pose as Alice while talking to Bob and pose as Bob while talking to Alice. Alice and Bob then both talk to the man in the middle, thinking they are talking to each other, and the villain gets everything sent on the bogus "secure" connection.
There are two ways to build links securely, both of which exclude the man-in-the middle:
Automatic keying is much more secure, since if an enemy gets one key only messages between the previous re-keying and the next are exposed. It is therefore the usual mode of operation for most IPSEC deployment, and the mode we use in our setup examples. FreeS/WAN does support manual keying for special circumstanes. See this section.
For automatic keying, the two systems must authenticate each other during the negotiations. There is a choice of methods for this:
Public key techniques are much preferable, for reasons discussed later, and will be used in all our setup examples. FreeS/WAN does also support auto-keying with shared secret authentication. See this section.
Our overall goal in FreeS/WAN is to make the Internet more secure and more private.
Our IPSEC implementation supports VPNs and Road Warriors of course. Those are important applications. Many users will want FreeS/WAN to build corporate VPNs or to provide secure remote access.
However, our goals in building it go beyond that. We are trying to help build security into the fabric of the Internet so that anyone who choses to communicate securely can do so, as easily as they can do anything else on the net.
More detailed objectives are:
If we can get opportunistic encryption implemented and widely deployed, then it becomes impossible for even huge well-funded agencies to monitor the net.
See also our section on history and politics of cryptography, which includes our project leader's rationale for starting the project.
People outside this core team have made substantial contributions. See
Any of those will have a list of other "munitions" mirrors.
More recently we have expanded to five lists, each with its own archive.
More information on mailing lists.
Unfortunately the export laws of some countries restrict the distribution of strong cryptography. FreeS/WAN is therefore not in the standard Linux kernel and not in all CD or web distributions.
FreeS/WAN is included in various general-purpose Linux distributions from countries (shown in brackets) with more sensible laws:
For distributions which do not include FreeS/WAN and are not Redhat (which we develop and test on), there is additional information in our compatibility section.
We would appreciate hearing of other distributions using FreeS/WAN.
There are also several sets of scripts available for managing a firewall which is also acting as a FreeS/WAN IPSEC gateway. See this list.
We would appreciate hearing of other specialised distributions using FreeS/WAN, or other script sets.
Several vendors use FreeS/WAN as the IPSEC component of a turnkey firewall or VPN product:
We would appreciate hearing of other products using FreeS/WAN.
FreeS/WAN documentation up to version 1.5 was available only in HTML. Now we ship two formats:
The Makefile assumes the htmldoc tool is available. You can
download it from Easy Software. You
may need to get source code and change some of the limits in
All formats should be available at the following websites:
The distribution tarball has only the two HTML formats.
Note: If you need the latest doc version, for example to see if anyone has managed to set up interoperation between FreeS/WAN and whatever, then you should download the current snapshot. What is on the web is documentation as of the last release. Snapshots have all changes I've checked in to date.
Text files in the main distribution directory are README, INSTALL, CREDITS, CHANGES, BUGS and COPYING.
FreeS/WAN commands and library routines are documented in standard Unix manual pages, accessible via the man(1) command. We also provide them in HTML, accessible from this index. In the event of disagreement between this HowTo and the man pages, the man pages are more likely correct since they are written by the implementers. Please report any such inconsistency on the mailing list.
The gmp (GNU multi-precision arithmetic) and Libdes (encryption) libraries which we use each have their own documentation. You can find it in those library directories.
Various user-written HowTo documents are available. The ones covering FreeS/WAN-to-FreeS/WAN connections are:
User-wriiten HowTo material may be especially helpful if you need to interoperate with another IPSEC implementation. We have neither the equipment nor the manpower to test such configurations. Users seem to be doing an admirable job of filling the gaps.
Check what version of FreeS/WAN user-written documents cover. The software is under active development and the current version may be significantly different from what an older document describes.
Two design documents show current team thinking on new developments:
A number of papers giving further background on FreeS/WAN, or exploring its future or its applications, are also available:
Several of these provoked interesting discussions on the mailing lists, worth searching for in the archives.
Interoperability test results are in our web links document.
Not all code in the distribution is ours, however. See the CREDITS file for details. In particular, note that the Libdes library has its own license.
For more detailed background information, see:
To begin working with FreeS/WAN, go to:
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:
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.
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.
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.
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:
2.4 has new firewalling code called netfilter. This may provide good reasons to move to 2.4, especially on for gateway machines.
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.
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.
If you have a CD distribution of Linux, it should include everything you need.
There are some common slips worth avoiding here:
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 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.
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.
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.
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.
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.
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.
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.
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:
You can also try the commands:
Of course any status information at this point should be uninteresting since you have not yet configured connections.
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.
This section describes setting up and testing Linux FreeS/WAN.
Before attempting this, you should:
You also need to set up and test IP networking on all the machines you plan to install FreeS/WAN on or to use in testing, before trying to set up FreeS/WAN. This is discussed in more detail after the description of our example networks.
For our examples, we assume that there are only three networks involved, two that want to talk to each other plus the Internet in the middle. The idea is to build an encrypted tunnel across the Internet so the two networks can talk securely. Once you have this working between two network gateways, extending it to three or more is straightforward.
In our examples, we'll call the two gateways East and West. We'll have only one client machine on each net: Sunrise in the East and Sunset in the West.
A diagram:
Sunset==========West------------------East=========Sunrise
local net untrusted net local net
Our goal here is to tell you how to set up the two gateways, East and West. We assume your goal is to ensure that East and West encrypt all traffic between them, or at least all that your security policies require them to encrypt.
Of course one does not always have a security gateway separate from the client machine. Especially for road warriors, a network that looks like this is common:
telecommuter's PC or
corporate LAN traveller's laptop
Sunset==========West------------------East
local net untrusted net
and this is possible:
West------------------East
untrusted net
In our configuration files, and in this discussion, we treat the two simpler setups as degenerate cases of the network-to-network link. For all the diagrams above, for example, we speak of "the subnet behind East". In two of the diagrams, of course, that "subnet" is just the machine itself.
This may take some getting used to, but we hope it is less confusing than continually having to say things like "the subnet behind East (or the East machine itself if there is no client subnet)".
Many users just want to get IPSEC installed on a few machines. They can skip this section.
Others may want to build a testbed network, for any of a number of reasons. For them, we have some suggestions.
The ideal test setup for IPSEC is something like:
Sunset==========West-----eth0 eth1-----East=========Sunrise
local net test machine local net
The test machine routes packets between the two gateways. This makes things more complicated than if you just connected the two gateway machines directly to each other, but it also makes your test setup much more like the environment you actually use IPSEC in. Those environments nearly always involve routing, and quite a few apparent IPSEC failures turn out to be problems with routing or with firewalls dropping packets. This approach lets you deal with those problems on your test setup.
Also, the test machine is in the ideal position to run diagnostic software (such as tcpdump(8)) for checking IPSEC packets. Such software is likely to misbehave if run on the gateways themselves. It is designed to look into a normal IP stack and may become confused if you ask it to display data from a stack which has IPSEC in play.
For more detailed testbed information see these mailing list messages:
Before trying to get FreeS/WAN working, you should configure and test IP networking on both gateways and on at least one client machine behind each of them. IPSEC cannot work without a working IP network beneath it. Many reported "FreeS/WAN problems" turn out to actually be problems with routing or firewalling. If any actual IPSEC problems turn up, you often cannot even recognise them (much less debug them) unless the underlying network is right.
If you need advice on this, your best sources are likely:
See also our bibliography.
Here is our network diagram again:
Sunset==========West------------------East=========Sunrise
local net untrusted net local net
The client machines, Sunrise and Sunset in our example, may have assigned routable IP addresses, or they may be using private non-routable addresses (as defined in RFC 1918) with the gateways doing IP masquerade. It doesn't matter which, as long as whatever it is works correctly.
Note, however, that the two subnets must have distinct addresses. You cannot have them both masqueraded to the same range of RFC 1918 addresses.
In any case, it is not enough to just test that East and West can communicate.
Some systems turn off packet forwarding by default, even for kernels in which it has been enabled. This is the safe default. You don't want systems forwarding packets in uncontrolled ways.
To turn forwarding on temporarily, use the following command as root:
echo "1" > /proc/sys/net/ipv4/ip_forward
Turning it on permanently is also possible. The exact method varies
from distribution to distribution:
A gateway machine needs forwarding enabled or it will not route packets between the two networks it is attached to. The simplest way to ensure this is to enable forwarding using whatever method your distribution provides. See list above.
A more conservative approach is to disable forwarding in your system configuration, then enable from your boot scripts after appropriate firewall scripts are in place.
Configure and test any other software you will want to use for testing once IPSEC is up. For example, you might put an HTTP daemon on Sunset and a browser on Sunrise. Make sure these work without IPSEC.
If these tests fail, figure out why and fix it. Do not proceed until it works.
As with most things on any Unix-like system, most parts of Linux FreeS/WAN are documented in online manual pages. We provide a list of FreeS/WAN man pages, with links to HTML versions of them.
The man pages describing configuration files are:
Man pages for commands used in this document include:
You can read these either in HTML using the links above or with the man(1) command.
RSA keys come in matched pairs. Each pair includes:
For FreeS/WAN, both keys for your system are in the ipsec.secrets(5) file. Maintaining security of this file is essential since it holds your private key.
Public keys for systems you communicate with are placed in ipsec.conf(5). Security here is less vital (unless you are using manual keying as well, in which case the file may have secret keys). It does not matter if an enemy knows the public keys, as long as the private keys are protected.
If you installed FreeS/WAN yourself, then the installation process has already generated an RSA key pair for you and placed it in the ipsec.secrets(5) file.
If not, you need to:
: RSA {
<stuff generated by rsasigkey>
}
Note that:
This means "always use this as my private RSA key". For other options, for example if you want to use different keys with different partners, see the man pages.
The RSA keys we generate are suitable only for authentication, not for encryption. IPSEC uses them only for authentication. See our IPSEC section for details.
It is also possible to use keys in other formats, not generated by FreeS/WAN. This may be necessary for interoperation with other IPSEC implementations. See our links to patches which add support for keys generated by PGP or embedded in X.509 certificates.
The next step is to send your public key to everyone you need to set up connections with, and collect their public keys. The public key is the line in the output of rsasigkey starting "#pubkey=0x".
Public keys need not be protected as fanatically as private keys. They are intended to be made public; the system is designed to work even if an enemy knows all the public keys used.
Note, however, that authentication of public keys is critical. It does not matter if an enemy knows your public keys, but if you can be tricked into trusting a public key supplied by an enemy, you are in deep trouble.
For example, consider the fellow who wants to communicate with his mistress, keeping messages secret from his wife.
You must authenticate any public keys received before using them. For remote sites, the simplest method is to exchange them using PGP-signed email (taking appropriate steps to authenticate the signing keys). For nearby machines, a floppy disk or trusted network is fine.
For each system you will communicate with, you need an RSA public key and an identifier associated with it. The identifiers go in the leftid= and rightid= lines of connection descriptions in ipsec.conf(5). They are the names the systems use to identify themselves during connection negotiation.
There are four possible forms for these identifiers:
We recommend that only the @FQDN form be used in most applications. IP addresses make remarkably uninteresting names. Resolving a name to an IP address is not interesting in this context, and attempting to resolve it may cause problems if DNS is down or if someone subverts a DNS server which you rely on.
If your domain is example.com, the names you use should be of three types:
In order to facilitate distributing keys through DNS, we recommend avoiding
For example, if you have a server alice.example.com, then you should not use "@alice.example.com" to identify Alice's laptop for IPSEC.
FreeS/WAN uses a configuration file, ipsec.conf(5).
This section describes setting up the parts of that file that apply to all connections:and gives an introduction to the parts of the file that specify the actual connections. The following section covers setting up three common types of connection, all using automatic keying with RSA authentication of the gateways:
Setup is quite similar for each of these, but details differ.
Other types of connections are covered in later sections.
The easiest way to create a connection is by editing one of our examples. Here we will use the one in the installation ipsec.conf file. You could also start with one from our doc/examples file if one of those is closer to what you need to do.
The first section of ipsec.conf(5) contains overall setup parameters for IPSEC, which apply to all connections. In our example file, it is:
# basic configuration
config setup
# THIS SETTING MUST BE CORRECT or almost nothing will work;
# %defaultroute is okay for most simple cases.
interfaces=%defaultroute
# Debug-logging controls: "none" for (almost) none, "all" for lots.
klipsdebug=none
plutodebug=none
# Use auto= parameters in conn descriptions to control startup actions.
plutoload=%search
plutostart=%search
# Close down old connection when new one using same ID shows up.
uniqueids=yes
The variables set here are:
In many cases, the appropriate interface is just your default connection to the world (the Internet, or your corporate network). In these cases, you can use the default setting:
To check what FreeS/WAN sees as the default route, you can use the command ipsec showdefaults. You may need to compare this with the output from route -n to get a more complete picture.
In other cases, you can name one or more specific interfaces to be used by FreeS/WAN. For example:
Note that
If you need to discover interface names, use the command:
ifconfigIf you have PCMCIA or other interfaces that are not available at boot time, special measures are required. See our section on that.
klipsdebug and plutodebug can each be set to "none" or to "all" in most circumstances. There are other options; see the relevant man pages.
plutoload and plutostart can be quoted lists of connection names, but are often set to %search as in our example. Any connection with auto=add in its connection definition is then loaded, and any connection with auto=start is started.
In most cases, you want plutostart=%search here and auto=start in your connection descriptions. That way when a connection is broken, for example if one machine crashes or is taken down for some reason, it will be reliably rebuilt. If only one end is told to start the connection, then if the other end crashes, you may lose the connection for a long time. The end that could rebuild does not know it needs to.
The exception to the above is when you have many road warriors connecting to a single gateway. Having the gateway trying to rebuild tunnels to systems which are offline can waste considerable resources. In this case, the gateway should have auto=add for all connections, and let the remote systems start negotiations.
There is a special name %default that lets you define things that apply to all connections. e.g. our example file has:
# defaults for subsequent connection descriptions
conn %default
# How persistent to be in (re)keying negotiations (0 means very).
keyingtries=0
# How to authenticate gateways
authby=rsasig
Variables set here are:
For testing, you might wish to set this to some small number, perhaps even to 1, to avoid wasting resources on incorrectly set up connections. In production, it is often set to zero (retry forever). Keeping the connection up is what machine resources are for, so if a connection is down you night as well waste resources retrying as waste them by sitting idle. Of course some caution should be exercised with this, since it can waste network resources as well.
Once you are finished testing, you can edit these defaults, adding anything that is standard for all gateways in your organisation.
Previous versions of this document said:
Note, however, that setting the auto= parameter in the default connection description does not work. You cannot use auto=start here to get all connections started automatically or auto=add to get them all loaded. You must set that in the individual connection descriptions.This restriction has been removed in FreeS/WAN 1.9. However, if the other end of the tunnel is an older version, the restriction will still apply there, so some caution is still required.
Edit our example connection to match what you want to do. Rename it appropriately for the connection you would like to build: "fred-susan", "reno-van" or whatever. The name is the second string in the line that begins with "conn", for example in:
conn snt
The connection name is "snt" (subn et tunnel) and to define another connection you make a copy with a new name such as:
conn reno-van
A sample connection description is:
# sample tunnel
# The network here looks like:
# leftsubnet====left----leftnexthop......rightnexthop----right====rightsubnet
# If left and right are on the same Ethernet, omit leftnexthop and rightnexthop.
conn sample
# left security gateway (public-network address)
left=10.0.0.1
# next hop to reach right
leftnexthop=10.44.55.66
# subnet behind left (omit if there is no subnet)
leftsubnet=172.16.0.0/24
# right s.g., subnet behind it, and next hop to reach left
right=10.12.12.1
rightnexthop=10.88.77.66
rightsubnet=192.168.0.0/24
auto=start
We omit here the variables we have shown as set in the default
connection above. All of them could also be set here. If they are set
in both places, settings here take precedence. Defaults are used only
if the specific connection description has no value set.
The network described above looks like this:
subnet 172.16.0.0/24 =leftsubnet
|
interface 172.16.0.something
left gateway machine
interface 10.0.0.1 =left
|
interface 10.44.55.66 =leftnexthop
router
interface we don't know
|
INTERNET
|
interface we don't know
router
interface 10.88.77.66 =rightnexthop
|
interface 10.12.12.1 =right
right gateway machine
interface 192.168.0.something
|
subnet 192.168.0.0/24 =rightsubnet
You need to edit the connection description, inserting appropriate IP
addresses and subnet descriptions so that it describes your network.
In most cases, you should use numeric IP addresses, not names, here. The file syntax allows names to be used, but this creates an additional risk. If someone can subvert the DNS service, then they can redirect packets whose addresses are looked up via that service.
Many of the variables in this file come in pairs such as "leftsubnet: and "rightsubnet", one for each end of the connection. The variables on the left side are:
This need not always be set.
(Yes, we know that design is not ideal, and we plan to change it. See extensive discussions on the mailing list, mostly with "routing" or "KLIPS 2" in the subject lines.)
For more detail, including ways to invoke your own customised script instead, see our FreeS/WAN and firewalls section.
If the conn setup section has plutostart=%search , then all connections marked auto=start are started when Pluto starts.
Initially, we suggest using auto=add on all connections. This lets you start them manually during testing. Once they are tested, you can change many of them to auto=start.
For each left* parameter, there is a corresponding right* parameter.
Note that a connection to a subnet behind left does not include left itself. The tunnel described above protects packets going from one subnet to the other. It does not apply to packets which either begin or end their journey on one of the gateways. If you need to protect those packets, you must build separate tunnel descriptions for them.
It is a common error to attempt testing a subnet-to-subnet connection by pinging from one of the gateways to the far end or vice versa. This does not work, even if the connection is functioning perfectly, because traffic to or from the gateway itself is not sent on that connection. If you want to protect traffic originating or terminating on the gateway, then you need a separate tunnel for that in addition to the subnet's tunnel. See the section on multiple tunnels below.
Which security gateway is "left" and which is "right" is arbitrary.
We suggest that you name connections by their ends. For example, name the link between Fred and Susan's machines "fred-susan" or the link between your Reno and Vancouver offices "reno-van". You can then let "left" refer to the left half of the name, "fred" or "reno" in our examples, and "right" to the other half.
To simplify administration, we recommend that you use the same names in the ipsec.conf files on both ends. The name "reno", for example, should refer to the machine in Reno, no matter which city the file is in, and if "reno" is "left" in the reno-van description in Reno, then "reno" should be "left" in that description on the Vancouver machine as well.
Then when you copy the file from one machine to the other, the only change you should make on the second machine is changing the interfaces= line to match the interface that machine uses for IPSEC.
Of course the software does not actually require this. The names are just arbitrary strings to it. If your administrator in Reno wants to refer to the machines as "Phobos" and "Demios" while the Vancouver admin calls them "George" and "Gracie", things should still work.
In this section we show examples of three common setups:
We use a, b, c ... to indicate components of IP addresses. Each letter is some number in the range 0 to 255, inclusive.
For additional examples, see our examples file.
In this example, the network looks like this:
subnet a.b.c.0/24 =leftsubnet
| (head office has routable IP addresses)
interface a.b.c.d
left gateway machine
interface e.f.g.h =left
| (external address outside a.b.c.0 subnet)
interface e.f.g.i =leftnexthop
router
interface we don't know
|
INTERNET
|
interface we don't know
router
interface j.k.l.m =rightnexthop
|
interface j.k.l.n =right
right gateway machine
interface 192.168.0.something
| (branch office uses private IP addresses)
subnet 192.168.0.0/24 =rightsubnet
The ipsec.conf(5) file might look like this (with RSA keys shortened for easy display):
# basic configuration
config setup
interfaces=eth0
klipsdebug=none
plutodebug=none
plutoload=%search
plutostart=%search
# defaults that apply to all connection descriptions
conn %default
# How persistent to be in (re)keying negotiations (0 means very).
keyingtries=0
# How to authenticate gatways
authby=rsasig
# VPN connection for head office and branch office
conn head-branch
# identity we use in authentication exchanges
leftid=@head.example.com
leftrsasigkey=0x175cffc641f...
# left security gateway (public-network address)
left=e.f.g.h
# next hop to reach right
leftnexthop=e.f.g.i
# subnet behind left (omit if there is no subnet)
leftsubnet=a.b.c.0/24
# right s.g., subnet behind it, and next hop to reach left
rightid=@branch.example.com
rightrsasigkey=0xfc641fd6d9a24...
right=j.k.l.n
rightnexthop=j.k.l.m
rightsubnet=192.168.0.0/24
# right is masquerading
rightfirewall=yes
auto=start
The versions of this file at the two ends should be identical, except that each must have an interfaces= line appropriate for the local machine.
RFC 1918 reserves three groups of addresses for use on private networks:
Addresses in these ranges will never be assigned to anything on the Internet. Many routers automatically drop any packet with one of these addresses as either source or destination.
You can use FreeS/WAN to route between two such networks, using for example leftsubnet=192.168.47.0/24 and rightsubnet=192.168.48.0/24. These addresses still do not appear on the Internet; they are encapsulated inside IPSEC packets which have the gateways' external addresses (from the left and right parameters of the connection description) in their headers.
For our purposes, a "road warrior" is any machine that does not have a fixed IP address where it can normally be expected to be on line. This includes:
The configuration for road warrior support looks slightly different from a VPN configuration. We cannot use the road warrior's IP address in the configuration file since we don't know it, and we don't want to have our server retrying connections to road warriors that are no longer online.
In this example, the network looks like this:
subnet a.b.c.0/24 =leftsubnet
| (head office has routable IP addresses)
interface a.b.c.d
left gateway machine
interface e.f.g.h =left
| (external address outside a.b.c.0 subnet)
interface e.f.g.i =leftnexthop
router
|
INTERNET
|
interface with dynamic IP address
road warrior machine
Here the ipsec.conf(5) files on the two ends are slightly different. The one at the office might have exactly the same config setuo and conn %default sections as in the VPN example.
# basic configuration
config setup
interfaces=eth0
klipsdebug=none
plutodebug=none
plutoload=%search
plutostart=%search
# defaults that apply to all connection descriptions
conn %default
# How persistent to be in (re)keying negotiations (0 means very).
keyingtries=0
# How to authenticate gatways
authby=rsasig
Then add a description for the road warrior connection:
# Connection for road warrior Fred
conn head-fred
# identity we use in authentication exchanges
leftid=@head.example.com
leftrsasigkey=0x175cffc641f...
# left security gateway (public-network address)
left=e.f.g.h
# next hop to reach right
leftnexthop=e.f.g.i
# subnet behind left (omit if there is no subnet)
leftsubnet=a.b.c.0/24
# accept any address for right
right=%any
# any address, provided authentication works
rightid=@fred.example.com
rightrsasigkey=0xd9a24765fe...
# no subnet for a typical road warrior
# it is possible, but usually not needed
# let the road warrior start the connection
auto=add
# override the default retry for road warriors
# we don't want to retry if IP connectivity is gone
keyingtries=1
On the gateway end we use
The file on the road warrior end is nearly identical, except that it has:
Additional road warriors can be added as required. Each should have his or her own connection description with unique settings for rightid and rightrsasigkey.
Jean-Francois Nadeau's Practical Configurations document also has an example of using RSA authentication for road warriors.
The idea is that each gateway check the destinations of outgoing packets, see if an encrypted connection is possible and, if so, take the opportuntity to encrypt. The opportunity will exist whenever the admins on both ends have set their systems up for opportunistic encryption.
This makes encryption the default behaviour, and could greatly increase the overall security of the Internet if it were widely enough adopted. See our documents:
The gateways must be able to authenticate each other for IPSEC to be secure. For opportunistic encryption, we rely on the domain name system, DNS, to provide the RSA keys needed for this authentication. Note, that currently this is not entirely secure because the DNS mechanism it relies on is not fully secure. Eventually, as secure DNS becomes widely deployed, this will change.
The main documentation items so far are:
Note that both software and documentation for this are changing quickly. You may want the latest snapshot for opportunism experiments.
We do not yet recommend this code for production use . You should still protect your critical data with explicitly configured IPSEC tunnels, rather than relying on opportunistic for everything at this stage.
conn subnet-to-anyone # for our client subnet
leftsubnet=10.42.42.0/24 # any single client in our subnet
left=%defaultroute # our SG (defaults leftnexthop too)
right=%opportunistic
The public key, in our format, must be in a KEY record of the appropriate DNS entry for this to work.
Each opportunistic connection supports a single source/destination pair of IP addresses. There is no way to build an opportunistic connection for a larger subnet. Specifying a subnet in the connection description, as in the example above, just means that any host in that subnet may have opportunistic connections.
Opportunism requires that the gateway systems be able to fetch public keys, and other IPSEC-related information, from each other's DNS (domain name service) records.
DNS is a distributed database that maps names to IP addresses and vice versa. A system named gateway.example.com with IP address 10.20.30.40 should have at least two DNS records:
To be more precise, quoting the Opportunism Design document:
For reference, the minimum set of DNS records needed to make
this all work is either:
1. TXT in Destination reverse map, identifying Responder
and providing public key.
2. KEY in Initiator reverse map, providing public key.
3. TXT in Source reverse map, verifying relationship to
Initiator.
or:
1. TXT in Destination reverse map, identifying Responder.
2. KEY in Responder reverse map, providing public key.
3. KEY in Initiator reverse map, providing public key.
4. TXT in Source reverse map, verifying relationship to
Initiator.
Slight complications ensue for dynamic addresses, lack of
control over reverse maps, etc.
The client systems will be either Source or Destination, so they must have:
1. TXT in Destination reverse map, identifying Responder
and providing public key.
2. ...
3. TXT in Source reverse map, verifying relationship to
Initiator.
or:
1. TXT in Destination reverse map, identifying Responder.
2. ...
3. ...
4. TXT in Source reverse map, verifying relationship to
Initiator.
If you control the gateway's reverse map, example client records would
look like this:
42.42.42.10.in-addr.arpa. IN PTR deepthought.example.com. 42.42.42.10.in-addr.arpa. IN TXT "X-IPsec-Server(10)=10.20.30.40 AQNJjkKlIk9...nYyUkKK8"which can also be written as just:
42.42.42.10.in-addr.arpa. IN PTR deepthought.example.com.
IN TXT "X-IPsec-Server(10)=10.20.30.40 AQNJjkKlIk9...nYyUkKK8"
This provides the IP address of the security gateway and the public
key which the gateway will use to authenticate itself. This is the
preferred method.
1. ... 2. KEY in Initiator reverse map, providing public key. 3. ... or: 1. ... 2. KEY in Responder reverse map, providing public key. 3. KEY in Initiator reverse map, providing public key. 4. ...
If you control the gateway's reverse map, you just add a KEY record there. That is all the gateway reverse map needs, whether it is working as Initiator or Responder.
Here is an example, with many characters of the key itself left out:
40.30.20.10.in-addr.arpa. IN KEY 0x4200 4 1 AQNJjkKlIk9...nYyUkKK8This allows lookups on the IP address of the gateway to retrieve the key.
However, suppose a friend over at example.org will let you put things in their maps. That will allow you to set your gateway up to handle opportunistic connections for which it is the initiator.
You still need to be able to put data in the reverse map for your clients. However, that data is slightly different:
42.42.42.10.in-addr.arpa. IN PTR deepthought.example.com.
IN TXT "X-IPsec-Server(10)=something.example.org"
Over at example.org, your friend puts these lines in the DNS data
files:
something.example.org. IN A 10.20.30.40 something.example.org. IN KEY 0x4200 4 1 AQNJjkKlIk9...nYyUkKK8Your gateway must identify itself in IKE as something.example.org, not as gateway.example.com. You set that up via leftid= or rightid= entries in ipsec.conf(5).
With this arrangement, the remote gateway receives an ID payload early in IKE with your (bogus) gateway name "something.example.org". Then it looks up that name to get the IP address and key for the gateway.
We provide several features in the syntax of the ipsec.conf(5) file that are intended to simplify the work of managing complex multi-connection setups:
These can be combined in whatever way suits your application. One example is this ipsec.conf file for a gateway supporting multiple road warriors, all using RSA authentication:
conn %default
type=tunnel
pfs=yes
keylife=2h
authby=rsasig # all connections use RSA authentication
keyingtries=1 # road warrior can retry, we shouldn't
# some parameters are common to all remote systems
right=%any # accept from any address
# pick up all remote system descriptions
# uses shell wildcards
include /etc/ipsec/remote.*.conn
# left side of all connections is the same
# define it after the descriptions which use it
conn leftstuff
left=101.101.101.101
leftnexthop=101.101.101.1
leftsubnet=202.202.202.0/24
leftid=@gateway.example.org
On the left gateway, we can omit leftrsasig. That gateway uses the private key stored in ipsec.secrets(5) and has no need for its own public key. Similarly, the road warriors need not have their own public keys in ipsec.conf(5), only the gateway's public key.
The remote connection descriptions in /etc/ipsec/remote.*.conn need then have only a few lines each:
conn myname
# pick up common info for all connections
also=leftstuff
# identify the remote machine
rightid=@myname.example.org
rightrsasigkey=0xfc641fd6d9a24...
# we cannot use auto= in default or an also= section
# so do it here
auto=add # load, but don't start
Note that if auto=add or auto=start parameters are used, they must be in the actual connection descriptions. Neither putting them in the conn default section nor including them via an also= line will work.
Also, be careful with the order of sections in this file. The parser used requires that a definition comes after the also= line which uses it. In our example, the include inserts the files with the also=leftstuff lines before the definition of conn leftstuff so things are parsed in the correct order.
If firewall packet filtering is being done on either of the FreeS/WAN gateway machines, or on any machine on the path between them, then you will probably need to adjust the filters before Free