Contents Previous Next

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.

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)".

Configuration for a testbed network

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:

Set up and test networking

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.

Enabling packet forwarding

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:
Older Readhat
in the file /etc/sysconfig/network, set FORWARD_IPV4=yes
Redhat 6.x and 7.0
in the file /etc/sysconfig/network, set net.ipv4.ip_forward=1
Debian r2.2 systems (and most likely Debian r2.2 derived systems):
in the file /etc/network/options, set ip_forward=yes

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.

Other software

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.

RTFM (please Read The Fine Manuals)

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.

Setting up RSA authentication keys

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.

Generating an RSA key pair

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:

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.

Exchanging authentication keys

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.

Using RSA signatures for authentication

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.

The configuration file

FreeS/WAN uses a configuration file, ipsec.conf(5).

This section describes setting up the parts of that file that apply to all connections:
config setup section
describes machine configuration
conn default section
default parameters which 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:

conventional VPN
two security gateways, each with a known fixed IP address and with a network of client machines behind it
Road Warrior
one player has a dynamically-assigned address
opportunistic encryption
the two machines have no prior knowledge of each other, but are set up to secure connections whenever possible

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 setup section of ipsec.conf(5)

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:

interfaces
Tells the KLIPS IPSEC code in the Linux kernel which network interface to use. The interfaces specified here are the only ones this gateway machine will use to communicate with other IPSEC gateways. If this is not correct, nothing works.

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:

Both tell KLIPS to use eth0 as ipsec0. The second one also supports IPSEC over PPP.

Note that

If you need to discover interface names, use the command:

        ifconfig
If you have PCMCIA or other interfaces that are not available at boot time, special measures are required. See our section on that.
klipsdebug
Debugging setting for the KLIPS kernel code
plutodebug
Debugging setting for the Pluto key and connection negotiation daemon.

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
List of connections to be automatically loaded into memory when Pluto starts.
plutostart
List of connections to be automatically negotiated when Pluto starts.

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.

uniqueids
Controls whether two connections with the same subnet on the remote end are allowed. Normally this is set to yes so that when a remote system disconnects and reconnects, Pluto will automatically take the old connection down.

Connection defaults

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:

keyingtries
How persistent to be in (re)keying negotiations (0 means very).

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.

authby=rsasig
authenticate gateways using RSA signatures. This is the preferred method and is what we will use in this section's examples. An alternate method is to use shared secrets.

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.

Editing a connection description

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:

left
The gateway's external interface, the one it uses to talk to the other gateway. This can be left=%defaultroute.
leftnexthop
Where left should send packets whose destination is right, typically the first router in the appropriate direction.

This need not always be set.

However, in all other cases, you must provide nexthop information. KLIPS (Kernel IP Security) bypasses the normal routing machinery, so you must give KLIPS the information even though routing already knows it.

(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.)

leftsubnet
Addresses for the machines which left is protecting. For some applications, you may want to create two connections, one to protect traffic from the subnet behind left and another to protect traffic from the left gateway itself. This takes two connection descriptions. See below.
leftfirewall
Set to "yes" if there is a firewall in play that suppresses forwarding, for example if a subnet behind left uses non-routable addresses and left does IP masquerade for them. This will cause Pluto to invoke our default script to adjust the firewall as required.

For more detail, including ways to invoke your own customised script instead, see our FreeS/WAN and firewalls section.

auto
If the conn setup section has plutoload=%search , then all connections marked auto=add are loaded when Pluto starts.

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 is which?

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.

Example setups

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.

VPN

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.

Routable and non-routable addresses

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.

Road Warrior

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.

Opportunistic encryption

We use the term opportunistic encryption for encryption which does not rely on any pre-arranged connection, hence does not require that the administrators of the two gateways involved communicate with each other (for example, to exchange keys) before their systems can create a secure connection.

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:

history and politics
for the reasons we want to do this
IPSEC protocols
for discussion of the general principle of encrypting as much as possible

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.

Status

The team have been working on this for some time, and testing internally. As of late May, 2001 this code is ready for wider testing. We encourage everyone to try it.

The main documentation items so far are:

I am playing catch up. HTML documentation so far is neither complete nor particularly clear, and not all of it has had technical review by the developers, so it may have errors. What I have so far is below.

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.

ipsec.conf entries for opportunism

The relevant lines in the config file might look like this:
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.

Some DNS background

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:

gateway.example.com. IN A 10.20.30.40
used to look up the name and get an IP address
40.30.20.10.in-addr.arpa. IN PTR gateway.example.com.
used for reverse lookups, looking up an address to get the associated name. Notice that the digits here are in reverse order; the actual address is 10.20.30.40 but we use 40.30.20.10 here.
Some syntactic details are: For much more detail, see: The capitalised strings after IN indicate the type of record. Possible types include: To set up for opportunistic encryption, you add some KEY and TXT records to your DNS data.

Putting IPSEC information in DNS

There are two types of DNS record to be added: ipsec_showhostkey(8) provides the key in DNS record format. You will need to put it in the appropriate place in the 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.
DNS records for client systems
You must have control of the reverse maps for your client systems, or opportunistic IPSEC cannot be made to work.

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.
DNS records for gateway systems
The gateways will be either Initiator or Responder so they need:
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...nYyUkKK8
This allows lookups on the IP address of the gateway to retrieve the key.
If you don't control the gateway's reverse map
The approach must be different if you do not have control over the reverse map for your gateway. Perhaps your ISP controls that, and provides no way for you to put data into their maps. Without that, you cannot set your gateway up to respond to incoming opportunistic requests (short of changing ISPs, which you might consider).

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...nYyUkKK8
Your 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.

Simplifying ipsec.conf files

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.

Is there a firewall in play?

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 FreeS/WAN can work. The filters must allow:

For more detail, see our IPSEC and firewalls document.

Testing the installation

This section covers testing connections once you have FreeS/WAN installed and your ipsec.conf(5) file set up.

We assume all your connection descriptions use auto=add so that ipsec_pluto(8) loads the descriptions into its internal database at startup but does not attempt to start the connections until you tell it to.

Matching numbers

It is important that the numbers in your connection descriptions match the network configuration. FreeS/WAN is almost certain to fail if they do not.

Suppose you are at the Reno office and your ipsec.conf file now has, among others, these lines:

config setup
        interfaces="ipsec0=eth0"

conn reno-van
        left=101.101.101.101
        right=202.202.202.202

When you tell FreeS/WAN to start the reno-van connection, it doesn't automagically know that it is in Reno, or that it is left in the configuration. It discovers that by comparing the IP address for ipsec0 (and, if it is set, for ipsec1) to the addresses for left and right. ipsec0 inherits its address from the underlying device, eth0 in our example.

So in our example, if eth0 has IP address 101.101.101.101 then ipsec0 inherits that address, the correct match is found, and this FreeS/WAN discovers that it is left. (If no match is found, Pluto reports "unable to orient connection".) It then sets itself up with any other left* parameters in use -- some of leftnexthop, leftsubnet, leftfirewall and leftid.

Once it has these parameters, FreeS/WAN sets things so that

All should be well.

Of course, there must also be interfaces and routes set up so that this machine can exchange IP packets both with the right gateway and with clients on leftsubnet. This is done with standard Linux utilities such as ifconfig(8) and route(8). Also, things must be correct on right in Vancouver. It takes two to tunnel.

A data mismatch anywhere in this configuration will cause FreeS/WAN to fail and to log various error messages. Depending on just how confused FreeS/WAN is and about what, the error messages may be somewhat confusing. See our troubleshooting section to get help interpreting them if required.

We recommend double-checking for consistency here before starting actual tests..

Sanity checking

Reboot both gateways to get FreeS/WAN started. No connections are actually made yet, but the stage is set.

Examine /var/log/messages for any signs of trouble.

On both gateways, the following entries should now exist in the /proc/net/ directory:

and the IPSEC interfaces should be attached on top of the specified physical interfaces. Confirm that with:

        cat /proc/net/ipsec_tncfg

You should see at least device ipsec0, and each ipsec device should point to a physical device, eg. 'ipsec0 -> eth0 mtu=16260 -> 1500'. Routing connections through this pseudo-device with our eroute(8) utility causes the data to be encrypted before being delivered to the underlying network interface.

Don't be surprised when you cannot find that /dev/ipsec0 or /dev/ipsec1. They do not exist. Other network pseudo-devices such as eth0 and eth1 do not have entries in /dev either. In general, network devices do not need such entries.

Starting a connection

On one gateway, start IPSEC with:

        ipsec auto --up name

replacing name with the connection name you used in ipsec.conf(5).

Note that to shut down a connection, you must do:

        ipsec auto --down name

on both gateway machines, even though you only start it from one.

If the ipsec auto --up command doesn't generate any errors, do

        ipsec look

and see if the output looks something like this:

foo.spsystems.net Wed Nov 25 22:51:45 EST 1998
-------------------------
10.0.1.0/24 -> 11.0.1.0/24 => tun0x200@11.0.0.1 esp0x202@11.0.0.1
-------------------------
tun0x200@11.0.0.1 IPv4_Encapsulation: dir=out   10.0.0.1 -> 11.0.0.1
esp0x203@10.0.0.1 3DES-MD5-96_Encryption: dir=in  iv=0xc2cbca5ba42ffbb6  seq=0  bit=0x00000000  win=0  flags=0x0<>
esp0x202@11.0.0.1 3DES-MD5-96_Encryption: dir=out  iv=0xc2cbca5ba42ffbb6  seq=0  bit=0x00000000  win=0  flags=0x0<>
Destination     Gateway         Genmask         Flags   MSS Window  irtt Iface
11.0.0.0        0.0.0.0         255.255.255.0   U      1500 0          0 eth1
11.0.1.0        11.0.0.1        255.255.255.0   UG     1404 0          0 ipsec0

If it does, you're probably in business.

This example shows:

        a tunnel              tun0x200 going to 11.0.0.1
        outgoing connection   esp0x202
        incoming connection   esp0x203

Both connections use ESP with 3DES encryption and MD5 authentication.

The routing is:

        11.0.0.0    via eth1 and the Internet
        11.0.1.0    via ipsec0 which encrypts and then sends to 11.0.0.1

This routes all traffic to the protected network 11.0.1.0/24 through an IPSEC tunnel to the gateway 11.0.0.1.

Ping tests

If that works, test whether Sunrise can ping Sunset and vice versa. Our example setup again is:

        Sunset==========West------------------East=========Sunrise
              local net       untrusted net       local net

There is no point in testing to or from the gateways themselves; the goal is to secure traffic between the subnets, not between the security gateways themselves.

In general, pings or other tests using the public interfaces of East and/or West are entirely useless. The IPSEC tunnel is for packets between the two protected subnets and the outside interfaces are not on those subnets. Depending on your routing configuration, test packets sent via those interfaces will be:

In either case, they tell you nothing about the tunnel .

Sometimes it will be inconvenient to use the client machines (Sunrise and Sunset in our example) for testing. In these cases, use a command such as:

     traceroute -i eth0 -f 20 192.168.7.1

where each of the interfaces specified (eth0 and 192.168.7.1 in the example) are on one of the protected subnets, eth0 being the local gateway's interface on that side and 192.168.7.1 the remote gateway's subnet interface. This forces the packets through the IPSEC tunnel you want to test.

For information on setting things up so that gateways can do IPSEC to each other or to remote subnets, see below .

If you have other software set up, test with it as well. Telnet from Sunrise to Sunset, browse a web server on the remote net and so on.

Testing with tcpdump

To verify that all is working, run tcpdump(8) on a machine which can listen to the traffic between the gateways.

This is most easily done from a third machine, rather than from one of the gateways. On the gateways you may see packets at intermediate stages of processing and the result may be confusing.

If the results make no sense at all, or you see "bad physical medium" error messages, you probably have an outdated version of tcpdump(8) that does not handle IPSEC at all. See our FAQ.

The packets should, except for some of the header information, be utterly unintelligible. The output of good encryption looks exactly like random noise.

You can put recognizable data in the ping packets with something like:

        ping -p feedfacedeadbeef 11.0.1.1

"feedfacedeadbeef" is a legal hexadecimal pattern that is easy to pick out of hex dumps.

For many other protocols, you need to check if you have encrypted data or ASCII text. Encrypted data has approximately equal frequencies for all 256 possible characters. ASCII text has most characters in the printable range 0x20-0x7f, a few control characters less than 0x20, and none at all in the range 0x80-0xff.

0x20, space, is a good character to look for. In normal English text space occurs about once in seven characters, versus about once in 256 for random or encrypted data. You can put long sequences of spaces in your data and look for 0x20202020 in output, but this is not usually necessary.

If packets look like total garbage, nothing recognizable, all is well.

Note that to shut down a connection, you must do:

        ipsec auto --down name

on both gateway machines, even though you only start it from one.

Again, you can verify with the same commands.

Repeat the ping test. Repeat the tcpdump test.

If everything succeeds, congratulations.

You now have a working Linux FreeS/WAN installation.

What next?

At this point you should have a working FreeS/WAN setup. If not, you could go back and doublecheck various things above or try:

If all is well so far, you could continue with this section to explore other ways to configure FreeS/WAN connections or branch out to:

Of course you might just go off for a beverage or meal at this point as well.

Other configuration possibilities

The rest of this section describes various less-used options for FreeS/WAN.

Choosing connection types

The first major decision you need to make before configuring additional connections is what type or types of connections you will use. There are several options, and you can use more than one concurrently.

Manual vs. automatic keying

IPSEC allows two types of connections, with manual or automatic keying. FreeS/WAN starts them with commands such as:

        ipsec manual --start name
        ipsec auto --up name

The difference is in how they are keyed.

Manually keyed connections
use keys stored in ipsec.conf .
Automatically keyed connections
use keys automatically generated by the Pluto key negotiation daemon. The key negotiation protocol, IKE , must authenticate the other system. (It is vulnerable to a man-in-the-middle attack if used without authentication.) We currently support two authentication methods:

Manually keyed connections provide weaker security than automatically keyed connections. An opponent who gets a key gets all data encrypted by it. We discuss using manual keying in production below, but this is not recommended except in special circumstances, such as needing to communicate with some implementation that offers no auto-keyed mode compatible with FreeS/WAN. Manual keying is useful for testing.

With automatically-(re)-keyed connections, the keys change often so an opponent who gets one key does not get a large amount of data. An opponent who gets a shared secret, or your private key if public key authentication is used, does not automatically gain access to any encryption keys or any data. Once your authentication mechanism has been subverted you have no way to prevent the attacker getting keys and data, but the attacker still has to work for them.

Authentication methods for auto-keying

The IKE protocol which Pluto uses to negotiate connections between gateways must use some form of authentication of peers. A gateway must know who it is talking to before it can create a secure connection. We currently support two methods for this authentication:

See our links section for information on user-contributed patches which provide a third mechanism:

As a long-term goal, FreeS/WAN plans to support distribution of public keys for authentication via secure DNS. This would allow us to support opportunistic encryption. Any two FreeS/WAN gateways could provide secure communication, without either of them having any preset information about the other.

This is not implemented in this release.

Advantages of public key methods

Authentication with a public key method such as RSA has some important advantages over using shared secrets.

  • does not require fixed IP addresses
  • There is also a disadvantage:

    This is partly counterbalanced by the fact that the key is never transmitted and remains under your control at all times. It is likely necessary, however, to take account of this in setting security policy. For example, you should change gateway keys when an administrator leaves the company, and should change them periodically in any case.

    Overall, public key methods are more secure, more easily managed and more flexible. We recommend that they be used for all connections, unless there is a compelling reason to do otherwise.

    Using shared secrets in production

    Generally, public key methods are preferred for reasons given above, but shared secrets can be used with no loss of security, just more work and perhaps more need to take precautions.

    Putting secrets in ipsec.secrets(5)

    If shared secrets are to be used to authenticate communication for the Diffie-Hellman key exchange in the IKE protocol, then those secrets must be stored in /etc/ipsec.secrets . For details, see the ipsec.secrets(5) man page.

    A few considerations are vital:

    Each line has the IP addresses of the two gateways plus the secret. It should look something like this:

            10.0.0.1 11.0.0.1 : PSK "jxTR1lnmSjuj33n4W51uW3kTR55luUmSmnlRUuWnkjRj3UuTV4T3USSu23Uk55nWu5TkTUnjT"
    

    PSK indicates the use of a pre-s hared key. The quotes and the whitespace shown are required.

    You can use any character string as your secret. For security, it should be both long and extremely hard to guess. We provide a utility to generate such strings, ipsec_ranbits(8).

    You want the same secret on the two gateways used, so you create a line with that secret and the two gateway IP addresses. The installation process supplies an example secret, useful only for testing. You must change it for production use.

    File security

    You must deliver this file, or the relevant part of it, to the other gateway machine by some secure means. Don't just FTP or mail the file! It is vital that the secrets in it remain secret. An attacker who knew those could easily have all the data on your "secure" connection.

    This file must be owned by root and should have permissions rw-------.

    Shared secrets for road warriors

    You can use a shared secret to support a single road warrior connecting to your gateway, and this is a reasonable thing to do in some circumstances. Public key methods have advantages, discussed above, but they are not critical in this case.

    To do this, the line in ipsec.secrets(5) is something like:

            10.0.0.1 0.0.0.0 : PSK "jxTR1lnmSjuj33n4W51uW3kTR55luUmSmnlRUuWnkjRj3UuTV4T3USSu23Uk55nWu5TkTUnjT"
    
    where the 0.0.0.0 means that any IP address is acceptable.

    For more than one road warrior, shared secrets are not recommended. If shared secrets are used, then when the responder needs to look up the secret, all it knows about the sender is an IP address. This is fine if the sender is at a fixed IP address specified in the config file. It is also fine if only one road warrior uses the wildcard 0.0.0.0 address. However, if you have more than one road warrior using shared secret authentication, then they must all use that wildcard and therefore all road warriors using PSK autentication must use the same secret. Obviously, this is insecure.

    For multiple road warriors, use public key authentication. Each roadwarrior can then have its own identity (our leftid= or rightid= parameters), its own public/private key pair, and its own secure connection.

    Using manual keying in production

    Generally, automatic keying is preferred over manual keying for production use because it is both easier to manage and more secure. Automatic keying frees the admin from much of the burden of managing keys securely, and 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 ipsec.conf(5).

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

            also=samplesep-keys
    

    which tells the "ipsec manual" script to insert the configuration description labelled "samplesep-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 might contain the additional data:

    conn samplesep-keys
      spi=0x200
      esp=3des-md5-96
      espenckey=0x01234567_89abcdef_02468ace_13579bdf_12345678_9abcdef0
      espauthkey=0x12345678_9abcdef0_2468ace0_13579bdf
    

    The first line matches the label in the "also=" line, so the indented lines are inserted. The net effect is exactly as if the inserted lines had occurred in the original file in place of the "also=" line.

    Variables set here are:

    spi
    A number needed by the manual keying code. Any 3-digit hex number will do, but if you have more than one manual connection then spi must be different for each connection.
    esp
    Options for ESP (Encapsulated Security Payload), the usual IPSEC encryption mode. Settings here are for encryption using triple DES and authentication using MD5. Note that encryption without authentication should not be used; it is insecure.
    espenkey
    Key for ESP encryption. Here, a 192-bit hex number for triple DES.
    espauthkey
    Key for ESP authentication. Here, a 128-bit hex number for MD5.

    Note that the example keys we supply are intended only for testing. For real use, you should go to automatic keying. If that is not possible, create your own keys for manual mode and keep them secret

    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.

    Also note that if you have multiple manually keyed connections on a single machine, then the spi parameter must be different for each one. Any 3-digit hex number is OK, provided they are different for each connection. We reserve the range 0x100 to 0xfff for manual connections. Pluto assigns SPIs from 0x1000 up for automatically keyed connections.

    If ipsec.conf(5) contains keys for manual mode connections, then it too must have permissions rw-------. We recommend instead that, if you must manual keying in production, you keep the keys in separate files.

    Note also that ipsec.conf is installed with permissions rw-r--r--. If you plan to use manually keyed connections for anything more than initial testing, you must:

    We recommend the latter method for all but the simplest configurations.

    Creating keys with ranbits

    You can create new random keys with the ranbits(8) utility. For example, the commands:

          umask 177
          ipsec ranbits 192  > temp
          ipsec ranbits 128 >> temp

    create keys in the sizes needed for our default algorithms:

    If you want to use SHA instead of MD5, that requires a 160-bit key

    Note that any temporary files used must be kept secure since they contain keys. That is the reason for the umask command above. The temporary file should be deleted as soon as you are done with it. You may also want to change the umask back to its default value after you are finished working on keys.

    The ranbits utility may pause for a few seconds if not enough entropy is available immediately. See ipsec_ranbits(8) and random(4) for details. You may wish to provide some activity to feed entropy into the system. For example, you might move the mouse around, type random characters, or do du /usr > /dev/null in the background.

    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 configurations.

    The most likely options are something like:

    interfaces="ipsec0=eth0 ipsec1=ppp0"
    Tells KLIPS which interfaces to use. Up to four interfaces numbered ipsec[0-3] are supported. Each interface can support an arbitrary number of tunnels.

    Note that for PPP, you give the ppp[0-9] device name here, not the underlying device such as modem (or eth1 if you are using PPPoE).

    interfaces=%defaultroute
    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.
    forwardcontrol=no
    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.
    syslog=daemon.error
    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.

    klipsdebug=
    Debug settings for KLIPS.
    plutodebug=
    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.
    dumpdir=/safe/directory
    Normally, programs started by ipsec setup don't crash. If they do, by default, no core dump will be produced because such dumps would contain secrets. If you find you need to debug such crashes, you can set dumpdir to the name of a directory in which to collect the core file.
    manualstart=
    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.
    pluto=yes
    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 plutoload 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".

    Note that, for a connection intended to be permanent, both gateways should be set try to start the tunnel. This allows quick recovery if either gateway is rebooted or has its IPSEC restarted. If only one gateway is set to start the tunnel and the other gateway restarts, the tunnel may not be rebuilt.

    plutowait=no
    Controls whether Pluto waits for one tunnel to be established before starting to negotiate the next. You might set this to "yes" 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.

    Multiple tunnels between the same two gateways

    Consider a pair of subnets, each with a security gateway, connected via the Internet:

             192.168.100.0/24           left subnet
                  |
             192.168.100.1
             North Gateway
             101.101.101.101            left
                  |
             101.101.101.1              left next hop
             [Internet]
             202.202.202.1              right next hop
                  |
             202.202.202.202            right
             South gateway
             192.168.200.1
                  |
             192.168.200.0/24           right subnet
    

    A tunnel specification such as:

    conn northnet-southnet
          left=101.101.101.101
          leftnexthop=101.101.101.1
          leftsubnet=192.168.100.0/24
          leftfirewall=yes
          right=202.202.202.202
          rightnexthop=202.202.202.1
          rightsubnet=192.168.200.0/24
          rightfirewall=yes
    
    will allow machines on the two subnets to talk to each other. You might test this by pinging from polarbear (192.168.100.7) to penguin (192.168.200.5).

    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
          left=101.101.101.101
          leftnexthop=101.101.101.1
          right=202.202.202.202
          rightnexthop=202.202.202.1
          rightsubnet=192.168.200.0/24
          rightfirewall=yes
    
    conn northnet-southgate
          left=101.101.101.101
          leftnexthop=101.101.101.1
          leftsubnet=192.168.100.0/24
          leftfirewall=yes
          right=202.202.202.202
          rightnexthop=202.202.202.1
    

    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
          left=101.101.101.101
          leftnexthop=101.101.101.1
          right=202.202.202.202
          rightnexthop=202.202.202.1
    

    This is required if you want the two gateways to speak IPSEC to each other.

    This requires a lot of duplication of details. Judicious use of also= and include can reduce this problem.

    Note that, while FreeS/WAN supports all four tunnel types, not all implementations do. In particular, some versions of Windows 2000 and the freely downloadable version of PGP provide only "client" functionality. You cannot use them as gateways with a subnet behind them. To get that functionality, you must upgrade to Windows 2000 server or the commercially available PGP products.

    One tunnel plus advanced routing

    It is also possible to use the new routing features in 2.2 and later kernels to avoid most needs for multple tunnels. Here is one mailing list message on the topic:
    Subject: Re: linux-ipsec: IPSec packets not entering tunnel?
       Date: Mon, 20 Nov 2000
       From: Justin Guyett <jfg@sonicity.com>
    
    On Mon, 20 Nov 2000, Claudia Schmeing wrote:
    
    > Right                                                         Left
    >                      "home"                "office"
    > 10.92.10.0/24 ---- 24.93.85.110 ========= 216.175.164.91 ---- 10.91.10.24/24
    >
    > I've created all four tunnels, and can ping to test each of them,
    > *except* homegate-officenet.
    
    I keep wondering why people create all four tunnels.  Why not route
    traffic generated from home to 10.91.10.24/24 out ipsec0 with iproute2?
    And 99% of the time you don't need to access "office" directly, which
    means you can eliminate all but the subnet<->subnet connection.
    
    and FreeS/WAN technical lead Henry Spencer's comment:
    > I keep wondering why people create all four tunnels.  Why not route
    > traffic generated from home to 10.91.10.24/24 out ipsec0 with iproute2?
    
    This is feasible, given some iproute2 attention to source addresses, but
    it isn't something we've documented yet... (partly because we're still
    making some attempt to support 2.0.xx kernels, which can't do this, but
    mostly because we haven't caught up with it yet).
    
    > And 99% of the time you don't need to access "office" directly, which
    > means you can eliminate all but the subnet<->subnet connection.
    
    Correct in principle, but people will keep trying to ping to or from the
    gateways during testing, and sometimes they want to run services on the
    gateway machines too.
    
    

    Many tunnels from a single gateway

    FreeS/WAN allows a single gateway machine to build tunnels to many others. There may, however, be some problems for large numbers as indicated in this message from the mailing list:

    Subject: Re: Maximum number of ipsec tunnels?
       Date: Tue, 18 Apr 2000
       From: "John S. Denker" <jsd@research.att.com>
    
    Christopher Ferris wrote:
    
    >> What are the maximum number ipsec tunnels FreeS/WAN can handle??
    
    Henry Spencer wrote:
    
    >There is no particular limit.  Some of the setup procedures currently
    >scale poorly to large numbers of connections, but there are (clumsy)
    >workarounds for that now, and proper fixes are coming.
    
    1) "Large" numbers means anything over 50 or so.  I routinely run boxes
    with about 200 tunnels.  Once you get more than 50 or so, you need to worry
    about several scalability issues:
    
    a) You need to put a "-" sign in syslogd.conf, and rotate the logs daily
    not weekly.
    
    b) Processor load per tunnel is small unless the tunnel is not up, in which
    case a new half-key gets generated every 90 seconds, which can add up if
    you've got a lot of down tunnels.
    
    c) There's other bits of lore you need when running a large number of
    tunnels.  For instance, systematically keeping the .conf file free of
    conflicts requires tools that aren't shipped with the standard freeswan
    package.
    
    d) The pluto startup behavior is quadratic.  With 200 tunnels, this eats up
    several minutes at every restart.   I'm told fixes are coming soon.
    
    2) Other than item (1b), the CPU load depends mainly on the size of the
    pipe attached, not on the number of tunnels.
    

    It is worth noting that item (1b) applies only to repeated attempts to re-key a data connection (IPSEC SA, Phase 2) over an established keying connection (ISAKMP SA, Phase 1). There are two ways to reduce this overhead using settings in ipsec.conf(5):

    The overheads for establishing keying connections (ISAKMP SAs, Phase 1) are lower because for these Pluto does not perform expensive operations before receiving a reply from the peer.

    Extruded Subnets

    What we call extruded subnets are a special case of VPNs.

    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.

    Suppose your friend has a.b.c.0/24 and wants to give you a.b.c.240/28. The initial situation is:

        subnet           gateway          Internet
      a.b.c.0/24    a.b.c.1    p.q.r.s
    where anything from the Internet destined for any machine in a.b.c.0/24 is routed via p.q.r.s and that gateway knows what to do from there.

    Of course it is quite normal for various smaller subnets to exist behind your friend's gateway. For example, your friend's company might have a.b.c.16/28=development, a.b.c.32/28=marketing and so on. The Internet neither knows not cares about this; it just delivers packets to the p.q.r.s and lets the gateway do whatever needs to be done from there.

    What we want to do is take a subnet, perhaps a.b.c.240/28, out of your friend's physical location while still having your friend's gateway route to it. As far as the Internet is concerned, you remain behind that gateway.

        subnet           gateway          Internet       your gate  extruded
    
      a.b.c.0/24   a.b.c.1     p.q.r.s              d.e.f.g         a.b.c.240/28                
    
                               ========== tunnel ==========

    The extruded addresses have to be a complete subnet.

    In our example, the friend's security gateway is also his Internet gateway, but this is not necessary. As long as all traffic from the Internet to his addresses passes through the Internet gate, the security gate could be a machine behind that. The IG would need to route all traffic for the extruded subnet to the SG, and the SG could handle the rest.

    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 "0.0.0.0/0". Do it with manual keying first for testing, and then with automatic keying for production use.

    The tunnel description should be:

    conn extruded
            left=p.q.r.s
            leftsubnet=0.0.0.0/0
            right=d.e.f.g
            rightsubnet=a.b.c.0/28
    

    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 0.0.0.0/0 -- 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 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 <irving@nevex.com>
    
    >  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 addresses.
    
    >   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 communicate with other computers on the local
    >  LAN , of course 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.
    
    However...
    
    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
    approach:
    
    Local Lan 1.0.0.0/24
        |
        +- Linux FreeS/WAN 1.0.0.2
        |
        | 1.0.0.1
     Router
        | 2.0.0.1
        |
    Internet
        |
        | 3.0.0.1
    Mobile User
          Virtual Address: 1.0.0.3
    
    Note that the Local Lan network (1.0.0.x) can be registered, routable
    addresses.
    
    Now, the Mobile User sets up an IPSec security association with the
    Linux box (1.0.0.2); 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
            right=1.0.0.2
            rightsubnet=1.0.0.0/24
            rightnexthop=1.0.0.1
            left=0.0.0.0  # The infamous "road warrior"
            leftsubnet=1.0.0.3/32
    
    Note that the left subnet contains *only* the remote host's virtual
    address.
    
    Hopefully the routing table on the FreeS/WAN box ends up looking like
    this:
    
    % netstat -rn
    Kernel IP routing table
    Destination     Gateway      Genmask         Flags   MSS Window  irtt Iface
    1.0.0.0         0.0.0.0      255.255.255.0   U      1500 0          0 eth0
    127.0.0.0       0.0.0.0      255.0.0.0       U      3584 0          0 lo
    0.0.0.0         1.0.0.1      0.0.0.0         UG     1500 0          0 eth0
    1.0.0.3         1.0.0.1      255.255.255.255 UG     1433 0          0 ipsec0
    
    So, if anybody sends a packet for 1.0.0.3 to the Linux box, it should
    get bundled up and sent through the tunnel. To get the packets for
    1.0.0.3 to the Linux box in the first place, you need to use "proxy
    ARP".
    
    How this works is: when a host or router on the local Ethernet segment
    wants to send a packet to 1.0.0.3, it sends out an Ethernet level
    broadcast "ARP request". If 1.0.0.3 was on the local LAN, it would
    reply, saying "send IP packets for 1.0.0.3 to my Ethernet address".
    
    Instead, you need to set up the Linux box so that _it_ answers ARP
    requests for 1.0.0.3, even though that isn't its IP address. That
    convinces everyone else on the lan to send 1.0.0.3 packets to the Linux
    box, where the usual FreeS/WAN processing and routing take over.
    
    % arp -i eth0 -s 1.0.0.3 -D eth0 pub
    
    This says, if you see an ARP request on interface eth0 asking for
    1.0.0.3, 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.

    Basics

    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 might want to create a tunnel without encryption. Often this is a bad idea, even if you have some data which need not be private. See this discussion.

    The IPSEC protocols provide two ways to do build such tunnels:

    using ESP with null encryption
    not supported by FreeS/WAN
    using AH without ESP
    supported for manually keyed connections
    possible with explicit commands via ipsec_whack(8) (see this list message)
    not supported in the ipsec_auto(8) scripts.
    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.

    Note that if Alice and Bob want end-to-end security, they must build a tunnel end-to-end between their machines or use some other end-to-end tool such as PGP or SSL that suits their data. The only question is whether the admins build some special unencrypted tunnel for those already-encrypted packets.


    Contents Previous Next