This file is part of the documentation for the Linux FreeS/WAN project.
See the documentation index or project home page for more information.

Linux FreeS/WAN Configuration

This document describes configuration options for Linux FreeS/WAN.

Our Setup document covers installation and setting up a simple VPN using IPSEC. If you have not yet read that, you should probably go there first.

The Setup document should get you to the point where you have a working FreeS/WAN installation. Of course, a working installation is not all you need for a production system. You still have to configure it for your requirements and circumstances. That is covered here.


You will of course need to refer to the online manual pages for various things. We provide an HTML list of man pages with links to HTML versions of the pages themselves. The pages are of course also available via the man command.

For configuration, the critical pages are ipsec(8) and ipsec.conf(5).

Do you need multiple tunnels?

Consider a pair of subnets, each with a security gateway, connected via the Internet:
         North Gateway
         South gateway
              | subnet
A tunnel specification such as:
conn northnet-southnet
will allow machines on the two subnets to talk to each other. You might test this by pinging from polarbear ( to penguin (

However, this does not cover other traffic you might want to secure. To handle all the possibilities, you might also want these connection descriptions:

conn northgate-southnet
conn northnet-southgate
Without these, neither gateway can do IPSEC to the remote subnet. There is no IPSEC tunnel or eroute set up for the traffic.

In our example, with the non-routable 192.168.* addresses used, packets would simply be discarded. In a different configuration, with routable addresses for the remote subnet, they would be sent unencrypted since there would be no IPSEC eroute and there would be a normal IP route.

You might also want:

conn northgate-southgate
This is required if you want the two gateways to speak IPSEC to each other.

Setting up connections at boot time

You can tell the system to set up connections automatically at boot time by putting suitable stuff in /etc/ipsec.conf on both systems. The relevant section of the file is labelled by a line reading config setup.

Details can be found in the ipsec.conf(5) man page. We also provide a file of example comfigurations, doc/examples.

The most likely options are something like:

interfaces="ipsec0=eth0 ipsec1=ppp1"
Tells KLIPS which interfaces to use. Up to four interfaces numbered ipsec[0-3] are supported.
Alternative setting, useful in simple cases. KLIPS will pick up both its interface and the next hop information from the settings of the Linux default route.
Normally "no". Set to "yes" if the IP forwarding option is disabled in your network configuration. (This can be set as a kernel configuration option or later. e.g. on Redhat, it's in /etc/sysconfig/network and on SuSE you can adjust it with Yast.) Linux FreeS/WAN will then enable forwarding when starting up and turn it off when going down. This is used to ensure that no packets will be forwarded before IPSEC comes up and takes control.
Used in messages to the system logging daemon (syslogd) to specify what type of software is sending the messages. If the settings are "daemon.error" as in our example, then syslogd treats the messages as error messages from a daemon.

Note that Pluto does not currently pay attention to this variable. The variable controls setup messages only.

Debug settings for KLIPS.
Debug settings for Pluto.
... for both the above DEBUG settings
Normally, leave empty as shown above for no debugging output.
Use "all" for maximum information.
See ipsec_klipsdebug(8) and ipsec_pluto(8) man page for other options. Beware that if you set /etc/ipsec.conf to enable debug output, your system's log files may get large quickly.
Are programs started by ipsec setup allowed to core dump? This parameter is optional and defaults to "no" if not present. There is a security risk in setting it to "yes" since dumps will contain highly sensitive information. It should be used only in special situations such as debugging Linux FreeS/WAN on an unusual processor type.
List of manually keyed connections to be automatically started at boot time. Useful for testing, but not for long term use. Connections which are automatically started should also be automatically re-keyed.
Whether to start Pluto when ipsec startup is done.
This parameter is optional and defaults to "yes" if not present.

"yes" is strongly recommended for production use so that the keying daemon (Pluto) will automatically re-key the connections regularly. The ipsec-auto parameters ikelifetime, ipseclifetime and reykeywindow give you control over frequency of rekeying.

plutoload="reno-van reno-adam reno-nyc"
List of tunnels (by name, e.g. fred-susan or reno-van in our examples) to be loaded into Pluto's internal database at startup. In this example, Pluto loads three tunnels into its database when it is started.

If plutoadd is "%search", Pluto will load any connections whose description includes "auto=add" or "auto=start".

plutostart="reno-van reno-adam reno-nyc"
List of tunnels to attempt to negotiate when Pluto is started.

If plutostart is "%search", Pluto will start any connections whose description includes "auto=start".

Controls whether Pluto waits for one tunnel to be established before starting to negotiate the next. You might set this to "yes" if your gateway is a limited machine and you need to conserve resources. For a busy and resource-laden production gateway, you likely want "no" so that connections are brought up in parallel and the whole process takes less time.

The example assumes you are at the Reno office and will use IPSEC to Vancouver, New York City and Amsterdam.

Using manual keying in production

Generally, automatic keying is preferred over manual keying for production use because it is more secure. Automatic keying can provide perfect forward secrecy.

However, it is possible to use manual keying in production if that is what you want to do. This might be necessary, for example, in order to interoperate with some device that either does not provide automatic keying or provides it in some version we cannot talk to.

Note that with manual keying all security rests with the keys. If an adversary acquires your keys, you've had it. He or she can read everything ever sent with those keys, including old messages he or she may have archived. You need to be really paranoid about keys if you're going to rely on manual keying for anything important.

Linux FreeS/WAN provides some facilities to help with this. In particular, it is good policy to keep keys in separate files so you can edit configuration information in /etc/ipsec.conf without exposing keys to "shoulder surfers" or network snoops. We support this with the "also=" and "include" syntax in ipseconf(5).

See the last example in our examples file. In the /etc/ipsec.conf "conn samplesep" section, it has the line:

which tells the "ipsec manual" script to insert the configuration description labelled "samplesec-keys" if it can find it. The /etc/ipsec.conf file must also have a line such as:
include ipsec.*.conf
which tells it to read other files. One of those other files then contains the required additional data:
conn samplesep-keys
        espenckey=[192 bits]
        espauthkey=[128 bits]
The first line matches the label in the "also=" line, so the two indented lines are inserted. The net effect is exactly as if the two lines providing keys had occurred in the original file in place of the "also=" line.

Of course, any files containing keys must have 600 permissions and be owned by root.

If you connect in this way to multiple sites, we recommend that you keep keys for each site in a separate file and adopt some naming convention that lets you pick them all up with a single "include" line. This minimizes the risk of losing several keys to one error or attack and of accidentally giving another site admin keys which he or she has no business knowing.

Variations on IPSEC
Using FreeS/WAN in different ways

This section of the document covers Linux FreeS/WAN configuration for situations other than the straightforward subnet-to-subnet VPN described in our Setup document.

It is incomplete. If you must deal with some situation not covered here, please post to the mailing list.

Extruded Subnets

What we call extruded subnets are a special case of VPNs. For basic VPN setup information, see the Setup document. You should almost certainly read that and try the techniques in it before attempting an extruded subnet.

If your buddy has some unused IP addresses, in his subnet far off at the other side of the Internet, he can loan them to you... provided that the connection between you and him is fast enough to carry all the traffic between your machines and the rest of the Internet. In effect, he "extrudes" a part of his address space over the network to you, with your Internet traffic appearing to originate from behind his Internet gateway.

The extruded addresses have to be a complete subnet. Your friend's security gateway needs to be also his Internet gateway, so that all traffic from the Internet to his addresses passes through the SG.

First, configure your subnet using the extruded addresses. Your security gateway's interface to your subnet needs to have an extruded address (possibly using a Linux virtual interface, if it also has to have a different address). Your gateway needs to have a route to the extruded subnet, pointing to that interface. The other machines at your site need to have addresses in that subnet, and default routes pointing to your gateway.

If any of your friend's machines need to talk to the extruded subnet, they need to have a route for the extruded subnet, pointing at his gateway.

Then set up an IPSEC subnet-to-subnet tunnel between your gateway and his, with your subnet specified as the extruded subnet, and his subnet specified as "". Do it with manual keying first for testing, and then with automatic keying for production use.

If either side was doing firewalling for the extruded subnet before the IPSEC connection is set up, ipsec_manual and ipsec_auto need to know about that (via the {left|right}firewall parameters) so that it can be overridden for the duration of the connection.

And it all just works. Your SG routes traffic for -- that is, the whole Internet -- through the tunnel to his SG, which then sends it onward as if it came from his subnet. When traffic for the extruded subnet arrives at his SG, it gets sent through the tunnel to your SG, which passes it to the right machine.

Remember that when ipsec_manual or ipsec_auto takes a connection down, it does not undo the route it made for that connection. This lets you take a connection down and bring up a new one, or a modified version of the old one, without having to rebuild the route it uses and without any risk of packets which should use IPSEC accidentally going out in the clear. Because the route always points into KLIPS, the packets will always go there. Because KLIPS temporarily has no idea what to do with them (no eroute for them), they will be discarded.

If you do want to take the route down, this is what the "unroute" operation in manual and auto is for. Just do an unroute after doing the down.

Note that the route for a connection may have replaced an existing non-IPSEC route. Nothing in Linux FreeS/WAN will put that pre-IPSEC route back. If you need it back, you have to create it with the route command.

Road Warrior support

"Road Warrior" is our term for the laptop user who needs to call home base and wants a secure connection. The problem is that Linux FreeS/WAN configuration files define connections by the IP addresses involved and a Road Warrior's IP address is not known in advance.

Our current solution is a temporary expedient, likely to be replaced by something better in the long run.

One connection may be defined for the IP address On getting a connection request from an address it does not recognise, the server tries to authenticate it using the secret for If this succeeds, a connection is created to the unrecognised address. For details, see ipsec_pluto(8).

This implies that all Road Warriors connecting to a server must share the same connection description and the same secret. On the client side, the Road Warrior must set up the /etc/ipsec.conf file with the current IP address before connecting.

Road Warrior example

Here is an example of Road Warrior configuration files.
Server end
On the server, one connection is set up for all Road Warriors:

conn whatever
You do not set rightnexthop here: the server (left) neither knows nor needs to know that.

Nor do you set rightsubnet. When is used as "right", and an incoming connection request matches this connection, then the actual values used for both gateway and subnet on that end are set up from the IP address on the incoming packets.

You also need to create a secret for those warriors. For example, /etc/ipsec.secrtets might have the line: "ffhffkfyuurdsdfdsrehj98753207865v"
Road Warrior end
On the Road warrior end, you need a similar setup, but with the current IP address and next hop for your end of the connection filled in.

conn whatever

Note that these right* values must be changed whenever your connection changes.

On this end, the secret appears as: "ffhffkfyuurdsdfdsrehj98753207865v"
Again, the IP address in the file must be changed whenever the connection changes.

Road Warrior with virtual IP address

Here is a mailing list message about another way to configure for road warrior support:

Subject: Re: linux-ipsec: understanding the vpn
   Date: Thu, 28 Oct 1999 10:43:22 -0400
   From: Irving Reid <>

>  local-------linux------internet------mobile
>  LAN        box                         user
>  ...
>  now when the mobile user connects to the linux box
>  it is given a virtual IP address, i have configured it to
>  be in the 10.x.x.x range. mobile user and linux box 
>  have a tunnel between them with these IP addreses.
>   Uptil this all is fine.

If it is possible to configure your mobile client software *not* to
use a virtual IP address, that will make your life easier. It is easier
to configure FreeS/WAN to use the actual address the mobile user gets
from its ISP.

Unfortunately, some Windows clients don't let you choose.

>  what i would like to know is that how does the mobile
>  user communciate with other computers on the local
>  LAN , ofcourse with the vpn ?
>   what IP address should the local LAN 
>  computers have ? I guess their default gateway 
>  should be the linux box ? and does the linux box need
>  to be a 2 NIC card box or one is fine.

As someone else stated, yes, the Linux box would usually be the default
IP gateway for the local lan.


If you mobile user has software that *must* use a virtual IP address,
the whole picture changes. Nobody has put much effort into getting
FreeS/WAN to play well in this environment, but here's a sketch of one

Local Lan
    +- Linux FreeS/WAN
Mobile User
      Virtual Address:

Note that the Local Lan network (1.0.0.x) can be registered, routable

Now, the Mobile User sets up an IPSec security association with the
Linux box (; it should ESP encapsulate all traffic to the
network 1.0.0.x **EXCEPT** UDP port 500. 500/udp is required for the key
negotiation, which needs to work outside of the IPSec tunnel.

On the Linux side, there's a bunch of stuff you need to do by hand (for
now). FreeS/WAN should correctly handle setting up the IPSec SA and
routes, but I haven't tested it so this may not work...

The FreeS/WAN conn should look like:

conn mobile

        left=  # The infamous "road warrior"

Note that the left subnet contains *only* the remote host's virtual

Hopefully the routing table on the FreeS/WAN box ends up looking like

% netstat -rn
Kernel IP routing table
Destination     Gateway      Genmask         Flags   MSS Window  irtt Iface   U      1500 0          0 eth0       U      3584 0          0 lo         UG     1500 0          0 eth0 UG     1433 0          0 ipsec0

So, if anybody sends a packet for to the Linux box, it should
get bundled up and sent through the tunnel. To get the packets for to the Linux box in the first place, you need to use "proxy

How this works is: when a host or router on the local Ethernet segment
wants to send a packet to, it sends out an Ethernet level
broadcast "ARP request". If was on the local LAN, it would
reply, saying "send IP packets for to my Ethernet address".

Instead, you need to set up the Linux box so that _it_ answers ARP
requests for, even though that isn't its IP address. That
convinces everyone else on the lan to send packets to the Linux
box, where the usual FreeS/WAN processing and routing take over.

% arp -i eth0 -s -D eth0 pub

This says, if you see an ARP request on interface eth0 asking for, respond with the Ethernet address of interface eth0.

Now, as I said at the very beginning, if it is *at all* possible to
configure your client *not* to use the virtual IP address, you can avoid
this whole mess.

Dynamic Network Interfaces

Sometimes you have to cope with a situation where the network interface(s) aren't all there at boot. The common example is notebooks with PCMCIA.


The key issue here is that the config setup section of the /etc/ipsec.conf configuration file lists the connection between ipsecN and hardware interfaces, in the interfaces= variable. At any time when ipsec setup start or ipsec setup restart is run this variable must correspond to the current real situation. More precisely, it must not mention any hardware interfaces which don't currently exist. The difficulty is that an ipsec setup start command is normally run at boot time so interfaces that are not up then are mis-handled.

Boot Time

Normally, an ipsec setup start is run at boot time. However, if the hardware situation at boot time is uncertain, one of two things must be done.

Change Time

When the hardware *is* in place, IPSEC has to be made aware of it. Someday there may be a nice way to do this.

Right now, the way to do it is to fix the /etc/ipsec.conf file appropriately, so interfaces reflects the new situation, and then restart the IPSEC subsystem. This does break any existing IPSEC connections.

If IPSEC wasn't brought up at boot time, do

	ipsec setup start
while if it was, do
	ipsec setup restart
which won't be as quick.

If some of the hardware is to be taken out, before doing that, amend the configuration file so interfaces no longer includes it, and do

	ipsec setup restart
Again, this breaks any existing connections.

Unencrypted tunnels

Sometimes you will want to create a tunnel without encryption. The IPSEC protocols provide two ways to do this, either using
AH without ESP or using ESP with null encryption. With Linux FreeS/WAN, these are currently supported for manually keyed connections, but not with automatic keying, so we'll look at other solutions here.

One situation in which this comes up is when otherwise some data would be encrypted twice. Alice wants a secure tunnel from her machine to Bob's. Since she's behind one security gateway and he's behind another, part of the tunnel that they build passes through the tunnel that their site admins have built between the gateways. All of Alice and Bob's messages are encrypted twice.

There are several ways to handle this.

Click below to go to: