# How to Configure Linux FreeS/WAN with Policy Groups

## What are Policy Groups?

Policy Groups are an elegant general mechanism to configure FreeS/WAN. They are useful for many FreeS/WAN users.

In previous FreeS/WAN versions, you needed to configure each IPsec connection explicitly, on both local and remote hosts. This could become complex.

By contrast, Policy Groups allow you to set local IPsec policy for lists of remote hosts and networks, simply by listing the hosts and networks which you wish to have special treatment in one of several Policy Group files. FreeS/WAN then internally creates the connections needed to implement each policy.

In the next section we describe our five Base Policy Groups, which you can use to configure IPsec in many useful ways. Later, we will show you how to create an IPsec VPN using one line of configuration for each remote host or network.

### Built-In Security Options

FreeS/WAN offers these Base Policy Groups:

private
  FreeS/WAN only communicates privately with the listed CIDR blocks. If needed, FreeS/WAN attempts to create a connection opportunistically. If this fails, FreeS/WAN blocks communication. Inbound blocking is assumed to be done by the firewall. FreeS/WAN offers firewall hooks but no modern firewall rules to help with inbound blocking.
private-or-clear
  FreeS/WAN prefers private communication with the listed CIDR blocks. If needed, FreeS/WAN attempts to create a connection opportunistically. If this fails, FreeS/WAN allows traffic in the clear.
clear-or-private
  FreeS/WAN communicates cleartext with the listed CIDR blocks, but also accepts inbound OE connection requests from them. Also known as passive OE (pOE), this policy may be used to create an opportunistic responder.
clear
  FreeS/WAN only communicates cleartext with the listed CIDR blocks.
block
  FreeS/WAN blocks traffic to and from and the listed CIDR blocks. Inbound blocking is assumed to be done by the firewall. FreeS/WAN offers firewall hooks but no modern firewall rules to help with inbound blocking.

Notes:

- Base Policy Groups apply to communication with this host only.
- The most specific rule (whether policy or pre-configured connection) applies. This has several practical applications:
  - If CIDR blocks overlap, FreeS/WAN chooses the most specific applicable block.
  - This decision also takes into account any pre-configured connections you may have.
  - If the most specific connection is a pre-configured connection, the following procedure applies. If that connection is up, it will be used. If it is routed, it will be brought up. If it is added, no action will be taken.
- Base Policy Groups are created using built-in connections. Details in man ipsec.conf.
- 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 Policy Groups

The Base Policy Groups which build IPsec connections rely on Opportunistic Encryption. To use the following examples, you must first become OE-capable, as described in our quickstart guide.

### Example 1: Using a Base Policy Group

Simply place CIDR blocks (names, IPs or IP ranges) in /etc/ipsec.d/policies/[groupname], and reread the policy group files.

For example, the private-or-clear policy tells FreeS/WAN to prefer encrypted communication to the listed CIDR blocks. Failing that, it allows talk in the clear.

To make this your default policy, place fullnet in the private-or-clear policy group file:

        [root@xy root]# cat /etc/ipsec.d/policies/private-or-clear
        # This file defines the set of CIDRs (network/mask-length) to which
        # communication should be private, if possible, but in the clear otherwise.
        ....
        0.0.0.0/0

and reload your policies with

        ipsec auto --rereadgroups

Use this test to verify opportunistic connections.

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

Defining IPsec security policy with Base Policy Groups is like creating a shopping list: just put CIDR blocks in the appropriate group files. For example:

        [root@xy root]# cd /etc/ipsec.d/policies
        [root@xy policies]# cat private
            192.0.2.96/27              # The finance department
            192.0.2.192/29             # HR
    	192.0.2.12                 # HR gateway
            irc.private.example.com    # Private IRC server

        [root@xy policies]# cat private-or-clear
            0.0.0.0/0                  # My default policy: try to encrypt.

        [root@xy policies]# cat clear
            192.0.2.18/32              # My POP3 server
            192.0.2.19/32              # My Web proxy

        [root@xy policies]# cat block
            spamsource.example.com

To make these settings take effect, type:

        ipsec auto --rereadgroups

Notes:

- For opportunistic connection attempts to succeed, all participating FreeS/WAN hosts and gateways must be configured for OE.
- Examples 3 through 5 show how to implement a detailed private policy.
- Warning: Using DNS names in policy files and ipsec.conf can be tricky. If the name does not resolve, the policy will not be implemented for that name. It is therefore safer either to use IPs, or to put any critical names in /etc/hosts. We plan to implement periodic DNS retry to help with this.
  Names are resolved at FreeS/WAN startup, or when the policies are reloaded. Unfortunately, name lookup can hold up the startup process. If you have fast DNS servers, the problem may be less severe.

### Example 3: Creating a Simple IPsec VPN with the private Group

You can create an IPsec VPN between several hosts, with only one line of configuration per host, using the private policy group.

First, use our quickstart guide to set up each participating host with a FreeS/WAN install and OE.

In one host's /etc/ipsec.d/policies/private, list the peers to which you wish to protect traffic. For example:

        [root@xy root]# cd /etc/ipsec.d/policies
        [root@xy policies]# cat private
            192.0.2.9              # several hosts at example.com
            192.0.2.11
            192.0.2.12
            irc.private.example.com

Copy the private file to each host. Remove the local host, and add the initial host.

        scp2 /etc/ipsec.d/policies/private root@192.0.2.12:/etc/ipsec.d/policies/private

On each host, reread the policy groups with

        ipsec auto --rereadgroups

That's it! You're configured.

Test by pinging between two hosts. After a second or two, traffic should flow, and

        ipsec eroute

should yield something like

        192.0.2.11/32   -> 192.0.2.8/32  => tun0x149f@192.0.2.8

where your host IPs are substituted for 192.0.2.11 and 192.0.2.8.

If traffic does not flow, there may be an error in your OE setup. Revisit our quickstart guide.

Our next two examples show you how to add subnets to this IPsec VPN.

### Example 4: New Policy Groups to Protect a Subnet

To protect traffic to a subnet behind your FreeS/WAN gateway, you'll need additional DNS records, and new policy groups. To set up the DNS, see our quickstart guide. To create five new policy groups for your subnet, copy these connections to /etc/ipsec.conf. Substitute your subnet's IPs for 192.0.2.128/29.

    conn private-net
        also=private  # inherits settings (eg. auto=start) from built in conn
        leftsubnet=192.0.2.128/29  # your subnet's IPs here

    conn private-or-clear-net
        also=private-or-clear
        leftsubnet=192.0.2.128/29

    conn clear-or-private-net
        also=clear-or-private
        leftsubnet=192.0.2.128/29

    conn clear-net
        also=clear
        leftsubnet=192.0.2.128/29

    conn block-net
        also=block
        leftsubnet=192.0.2.128/29

Copy the gateway's files to serve as the initial policy group files for the new groups:

        cp -p /etc/ipsec.d/policies/private /etc/ipsec.d/policies/private-net
        cp -p /etc/ipsec.d/policies/private-or-clear /etc/ipsec.d/policies/private-or-clear-net
        cp -p /etc/ipsec.d/policies/clear-or-private /etc/ipsec.d/policies/clear-or-private-net
        cp -p /etc/ipsec.d/policies/clear /etc/ipsec.d/policies/clear-net
        cp -p /etc/ipsec.d/policies/block /etc/ipsec.d/policies/block

Tip: Since a missing policy group file is equivalent to a file with no entries, you need only create files for the connections you'll use.

To test one of your new groups, place the fullnet 0.0.0.0/0 in private-or-clear-net. Perform the subnet test in our quickstart guide. You should see a connection, and

        ipsec eroute

should include an entry which mentions the subnet node's IP and the OE test site IP, like this:

        192.0.2.131/32   -> 192.139.46.77/32  => tun0x149f@192.0.2.11

### Example 5: Adding a Subnet to the VPN

Suppose you wish to secure traffic to a subnet 192.0.2.192/29 behind a FreeS/WAN box 192.0.2.12.

First, add DNS entries to configure 192.0.2.12 as an opportunistic gateway for that subnet. Instructions are in our quickstart guide. Next, create a private-net group on 192.0.2.12 as described in Example 4.

On each other host, add the subnet 192.0.2.192/29 to private, yielding for example

        [root@xy root]# cd /etc/ipsec.d/policies
        [root@xy policies]# cat private
            192.0.2.9              # several hosts at example.com
            192.0.2.11
            192.0.2.12             # HR department gateway
            192.0.2.192/29         # HR subnet
            irc.private.example.com

and reread policy groups with

        ipsec auto --rereadgroups

That's all the configuration you need.

Test your VPN by pinging from a machine on 192.0.2.192/29 to any other host:

        [root@192.0.2.194]# ping 192.0.2.11

After a second or two, traffic should flow, and

        ipsec eroute

should yield something like

        192.0.2.11/32   -> 192.0.2.194/32  => tun0x149f@192.0.2.12

Key:

1. | 192.0.2.11/32 | Local start point of the protected traffic.
2. | 192.0.2.194/32 | Remote end point of the protected traffic.
3. | 192.0.2.12 | Remote FreeS/WAN node (gateway or host). May be the same as (2).
4. | [not shown] | Local FreeS/WAN node (gateway or host), where you've produced the output. May be the same as (1).

For additional assurance, you can verify with a packet sniffer that the traffic is being encrypted.

Note

- Because strangers may also connect via OE, this type of VPN may require a stricter firewalling policy than a conventional VPN.

## Appendix

### Our Hidden Connections

Our Base Policy Groups are created using hidden connections. These are spelled out in man ipsec.conf and defined in /usr/local/lib/ipsec/_confread.

### Custom Policy Groups

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|none], tells FreeS/WAN what to do with packets for these CIDRs if it fails to establish the connection. Default is none.

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 CIDR block in that file.
4. Reread groups with ipsec auto --rereadgroups.
5. Test: ping to activate any OE connection, and view results with ipsec eroute.

### Disabling Opportunistic Encryption

To disable OE (eg. policy groups and packetdefault), cut and paste the following lines to /etc/ipsec.conf:

    conn block
        auto=ignore

    conn private
        auto=ignore

    conn private-or-clear
        auto=ignore

    conn clear-or-private
        auto=ignore

    conn clear
        auto=ignore

    conn packetdefault
        auto=ignore

Restart FreeS/WAN so that the changes take effect:

        ipsec setup restart