Introduction to FreeS/WAN
Keywords: Linux, IPsec, VPN, security, encryption, cryptography, FreeS/WAN, FreeSWAN

# How to Configure Linux FreeS/WAN with Policy Groups

Policy groups are a new feature that we're getting ready for 2.0. Testing is appreciated, as is feedback via design@lists.freeswan.org.

## What are Policy Groups?

Policy Groups provide a new way of configuring Linux FreeS/WAN.

By defining IPsec behaviour for groups of IPs (or named domains), you can easily conceptualize an overall IPsec security policy. Linux FreeS/WAN then translates that into several connection descriptions, and establishes your connections.

Our Base Policy Groups rely on Opportunistic Encryption to do this. However, Policy Groups are a flexible tool -- they can also be used as a shorthand to configure VPNs, as in this example.

Policy Groups can be used with your existing ipsec.conf. You can have VPN connections explictly defined in ipsec.conf, and define other behaviour with policy groups.

As of 2.0-pre0, there have been significant revisions to ipsec.conf; details in our Upgrading Guide.

### Built-In Security Options

Linux FreeS/WAN offers these Base Policy Groups:

oe-or-bust (OE-based VPN)
  Attempt to negotiate opportunistically. On failure, block.
oe-or-clear
  Attempt to opportunistically negotiate a tunnel. On failure, communicate in the clear.
clear-or-oe (Opportunistic Responder)
  Communicate in the clear. If the other side negotiates opportunistically, go along with that.
clear
  Communicate with these in the clear.
block
  Block listed IP addresses from communicating with this machine.

You can also define your own groups.

All Policy Groups are bidirectional. This chart shows some technical details. FreeS/WAN does not support one-way encryption, since it can give users a false sense of security.

## Using Base Policy Groups

Base Policy Groups rely on OE. To use the following examples, you must first become OE-capable, as described here.

### Example 1: Using a base group

This is as easy as putting names, IPs or IP ranges in /etc/ipsec.d/policies/groupname (in -pre3, /etc/ipsec.d/groupname).

        cd /etc/ipsec.d/policies
        echo "193.110.157.0/24  #includes oetest.freeswan.nl" >> oe-or-clear

Now, when we try to contact oetest.freeswan.nl, FreeS/WAN will automatically bring up a connection.

To test this,

        ping oetest.freeswan.nl
        ipsec look | grep " -> "

You should see something like:

        40.40.40.40/32   -> 193.110.157.10/32  => tun0x149f@193.110.157.77 esp0xf8754dc8@193.110.157.77
        40.40.40.40/32   -> 193.110.157.14/32  => tun0x14a3@193.110.157.75 esp0xa9520f54@193.110.157.75

indicating tunnels between your node or network [here, 40.40.40.40/32] and the two targets passiveOE.freeswan.nl (193.110.157.10) and activeOE.freeswan.nl (193.110.157.14).

If the other side cannot do OE, the connection will fall back to clear. Since OEtest is properly set up for OE, if you don't see a tunnel, check your local OE capability as directed in our quickstart guide.

### Example 2: Defining IPsec Security Policy with Groups

We can indicate how we'd like traffic to any peer handled, by listing its name or IP range in the appropriate file. For example:

        cd /etc/ipsec.d/policies
        cat oe-or-bust
            40.40.38.0/27    # The finance department
            40.40.38.0/27    # HR
            40.40.40.26/32    # Barb's machine
            40.40.40.33/32    # Our IRC server

        cat oe-or-clear
            0.0.0.0/0    # My default policy: try to encrypt.

        cat clear
            66.66.66.45/32   # My POP3 server
            66.66.66.53/32   # My Web proxy

        block
            mail.spamworks.com

Notes:

- To create a default policy, use the range 0.0.0.0/0. Here, any traffic without more specific instructions will fall into the oe-or-clear group.
- Standalone IPs must be marked /32. We hope this requirement will disappear soon.
- Names are resolved at FreeS/WAN startup. Using names here (and in ipsec.conf) can give you a slow startup, since the lookup can hold up the entire startup process). If you have good DNS access, the problem may be less severe.
- In -pre3, use /etc/ipsec.d/groupname.

## Custom Policy Groups

You are now in experimental territory. This doc has not been tested, so use at your own risk.

A policy group is built using a special connection description in ipsec.conf, which:

- is generic. It uses right=[%group|%opportunisticgroup] rather than specific IPs. The connection is cloned for every name or IP range listed in its Policy Group file.
- often has a failure rule. This rule, written failureshunt=[passthrough|drop|reject], shows FreeS/WAN what to do with packets for these IPs if it fails to establish the connection. There is no default failure rule.

The connections that comprise our Base Policy Groups are hidden behind the scenes.

To create a new group:

1. Create its connection definition in ipsec.conf.
2. Create a Policy Group file in /etc/ipsec.d/policies with the same name as your connection.
3. Put a name or IP range in that file.
4. Test.

### Example 3: Variation on a Base Policy Group

Suppose we'd like to create a group which would make opportunistic connections and, if successful, try to keep them open forever.

Copy this connection into your ipsec.conf. It is similar to our hidden connection OEself, with one small change.

        conn OEpersistent
            left=%defaultroute
            leftrsasigkey=%dnsondemand
            right=%opportunistic
            rightrsasigkey=%dnsondemand
            keyingtries=3
            ikelifetime=1h
            keylife=1h
            rekey=yes                  # rekeys persistently, unlike OEself
            failureshunt=passthrough   # fails to clear
            auto=route

Next, create the group file, and place in it a sample entry:

        echo "oetest.freeswan.nl" > /etc/ipsec.d/policies/OEpersistent

(In -pre3, use /etc/ipsec.d/OEpersistent.)

If you've stepped through Example 1 you may also need to remove oetest from another group file.

Load the new configs with

        ipsec setup restart

Is there an easier way? Test.

        ping oetest.freeswan.nl
        ipsec look | grep " -> "

You should see something like:

        40.40.40.40/32   -> 193.110.157.10/32  => tun0x149f@193.110.157.77 esp0xf8754dc8@193.110.157.77
        40.40.40.40/32   -> 193.110.157.14/32  => tun0x14a3@193.110.157.75 esp0xa9520f54@193.110.157.75

indicating tunnels between your node or network [here, 40.40.40.40/32] and the two targets passiveOE.freeswan.nl (193.110.157.10) and activeOE.freeswan.nl (193.110.157.14).

If the other side cannot do OE, the connection will fall back to clear. Since OEtest is properly set up for OE, if you don't see a tunnel, check your local OE capability as directed in our quickstart guide.

Do some other tasks. After an hour and ten minutes, again run

        ipsec look | grep " -> "

Even if you have not attempted to contact oetest in the interim, you should still see tunnels to its IPs, as above.

For more immediate results, do the above procedure with keylifetime=5m, and check for your rekeyed tunnels after ten minutes.

That's it. Your OEpersistent connection works.

Now, add any other IPs with which you'd like to have an OEpersistent connection, to /etc/ipsec.d/policies/OEpersistent. To make this your default policy, put 0.0.0.0/0 in this file:

        echo "0.0.0.0/0" > /etc/ipsec.d/policies/OEpersistent

Restart to make the changes effective:

        ipsec setup restart

When do the group files get read?

### Example 4: Policy Group as shorthand for several VPNs

We can create a Custom Policy Group to link several friends' computers to a network behind an IPsec gateway.

        conn friends
            left=%defaultroute             # Local vitals
            leftsubnet=42.42.42.0/24       #
            leftnexthop=%defaultroute      # correct in many situations
            right=%group
            authby=secret
            auto=add

Does this get started on ping? Do we need to explicitly start if auto!=start. Then: error in intro to this doc.

On her computer, each friend must also configure a return conn. Barbara at 40.40.52.1/32 might have in ipsec.conf:

        version 2
        conn back_at_you
            left=42.42.42.1                # Your IP
            leftsubnet=42.42.42.0/24       #
            right=40.40.52.1/32             # Friend's IP
            rightnexthop=%defaultroute      # correct in many situations
            authby=secret
            auto=start

All the friends will also need to share a secret by some secure means, and put it in ipsec.secrets. Barbara's ipsec.secrets looks like this:

        42.42.42.1 : PSK "verysecretsecret"

Is there some way to co-ordinate ipsec.secrets with my group file? Otherwise I have a problem.

Back at my machine, I make a Policy Group file titled friends

        cd /etc/ipsec.d/policies
        vi friends

(In -pre3, use /etc/ipsec.d/friends.) I add the friends' names and/or IP ranges:

        44.44.44.61/32
        40.40.52.1/32
        mattspc.org

And I edit my own ipsec.secrets: (shouldn't there be some shorthand for this?)

To start a connection, I ping a friend. To see the results, I type:

       ipsec look

I should now see a connection, for example:

       snip tunnel text here

If you hit a snag, see our FAQ.

### Appendix: Our hidden connections

Our standard oe-or-clear connection is created using this hidden connection:

        conn OEgroup  #check this conn's specifics
            rightsubnet=%opportunisticgroup
            also=OEself

        conn OEself
            left=%defaultroute
            leftrsasigkey=%dnsondemand
            right=%opportunistic
            rightrsasigkey=%dnsondemand
            keyingtries=3
            ikelifetime=1h
            keylife=1h
            rekey=no
            failureshunt=passthrough   # fail to clear
            auto=route

See man ipsec.conf for explanations of these settings.