Contents Previous Next

FreeS/WAN quick start guide

This is a quick guide to and then setting up some common configurations: This should cover everything you need to set up

More complex requirements are covered elsewhere:

However, please read this quick start section first , before tackling the others.

Easy installation

There are two easy ways to install FreeS/WAN:

If your distribution does not include FreeS/WAN and no RPMs are available, see our installation from source document.

Enabling FreeS/WAN

Once you have FreeS/WAN on the system, ensure that it is enabled:
Set your boot loader to get the system booting with the new kernel.
On many systems, you do this by editing lilo.conf(5) and running lilo(8). If this is unfamilar territory, see the LILO mini-HowTo.
Enable ipsec in your boot scripts.
Typically, this is done with chkconfig(8). If this is unfamilar territory, see the Power-up to Bash Prompt HowTo.

That's it. FreeS/WAN is installed.

Creating an RSA key

The next step is to generate an RSA key for use in authenticating IPsec negotiations.

RSA is a public key cryptographic technique. Keys are created as 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.

To generate your key pair, give these commands as root:

        ipsec newhostkey > /etc/ipsec.secrets
        chmod 600 /etc/ipsec.secrets

Key generation may take some time, even on a fast system. Also, it needs a lot of random numbers so you may need to switch consoles and do something like typing a lot of text or running du / > /dev/null. These give random(4) some inputs to work with.

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.

Setting up opportunistic encryption

Opportunistic encryption makes setup and adminstration of IPsec simple.

For opportunistic encryption, you do not need to communicate with the administrator of a site before establishing secure communications to that site. In particular, you do not have to send them your keys or collect and authenticate theirs. All you have to do is set up your end correctly and from there on, everything is automatic.

Opportunistic client

In the general case, an IPsec connection involves two gateways securing communication between two client subnets, and either end may initiate an IPsec connection.

In this section, we treat the simplest case:

The next section covers opportunistic gateways, where these restrictions do not apply.

There are two steps:

Once this is done, your system will automatically encrypt whenever it can.

ipsec.conf(5) for opportunistic client

The ipsec.conf(5) file for this setup is just:
# general IPsec setup
config setup
        # Use the default interface
        interfaces=%defaultroute
        # Use auto= parameters in conn descriptions to control startup actions.
        plutoload=%search
        plutostart=%search

# defaults for subsequent connection descriptions
conn %default
        # How to authenticate gateways
        authby=rsasig
        # Try to start all connections by default
        auto=start

# description for opportunistic connections
conn us-to-anyone
        also=our_stuff             # our system details, stored below
        left=%opportunistic        # anyone we can authenticate via DNS
        rekey=no                   # let unused connections die

# description of our system
# included in other connection descriptions via also= lines
# must come after the lines that use it
conn our_stuff
        # all connections should use our default route
        # also controls the source address on IPsec packets
        right=%defaultroute
        # our identity for IPsec negotiations
        # must match what is in DNS and ipsec.secrets(5)
        rightid=xy.example.com

The last line above is the only one that you need to edit for your system. All the rest is identical for any standalone machine doing opportunistic encryption.

There is no need to provide any keys in this file. Your private key is in ipsec.secrets(5) and, for opportunistic encryption, the public keys for remote gateways are all looked up in DNS.

Client DNS key

You need to put your system's RSA public key in a DNS record so that systems you communicate with can find it.

What follows here is a simple technique suitable for systems which always initiate any opportunistic encryption they are involved in. If you need to let others inititiate -- for example, if you run services on your machine and want remote clients to be able to acess them securely -- then you need the more complex techniques described in the gateways section.

Find a helpful DNS administrator
You need the co-operation of a DNS administrator somewhere for this, to place a KEY record so that you can use a name in some domain he or she controls. This need not be either the domain you get your IP address from or the domain that points to your system.

For example, a reverse lookup on the IP address for a home gateway might give 123.adsl.kalamazoo.example.net, and a forward lookup for example.dyndns.org might point to that gateway. You could use either of these names as your ID for IPsec purposes, if the admins at either example.net or dyndns.org co-operate.

If not, you can use any domain whose DNS adminstrator is willing to help out. You do not need an A record (address record, associating your chosen name with an address) in that domain, only a KEY record.

Generate a KEY record

You can generate a DNS KEY record containing your system's public key with the command:

     ipsec showhostkey
The result should look like this (with the key data trimmed down for clarity):

  ; RSA 2048 bits   xy.example.com   Sat Apr 15 13:53:22 2000
  xy.example.com.   IN   KEY   0x4200 4 1 AQOF8tZ2...+buFuFn/

The name here is taken from ipsec.secrets(5). If it is not what you want, edit that file to correct it, then run ipsec showhostkey again.

The name must also match what you used for rightid= in ipsec.conf(5).

Give this record to the DNS administrator, for insertion into the zone file of the domain.

Opportunistic gateway

An IPsec gateway is a system that does IPsec for a group of client machines located behind it. Typically, gateways are installed at or near organisational boundaries. Often the same machine is used as a firewall and as an IPsec gateway, but these functions can also be separated.

There are two steps in the setup. Setting up your ipsec.conf(5) for this is quite simple. Setting up the DNS entries to support it is a bit more complex.

ipsec.conf(5) for an opportunistic gateway

You need only make a few additions to in the ipsec.conf(5) file to expand from a standalone system (which protects only its own traffic) to a gateway (which protects traffic for other systems):

A few other things in ipsec.conf(5) will be changed as well in our example:

With those changes, the ipsec.conf(5) file is:

# general IPsec setup
config setup
        # Use the default interface
        interfaces=%defaultroute
        # Use auto= parameters in conn descriptions to control startup actions.
        plutoload=%search
        plutostart=%search

# defaults for subsequent connection descriptions
conn %default
        # How to authenticate gateways
        authby=rsasig
        # Default is to load all connection descriptions
        # but not try to start the connection
        # Some conns may over-ride this with auto=start
        auto=add

# opportunistic connections to our gateway
conn us-to-anyone
        also=gate_stuff             # our system details, stored below
        right=%opportunistic        # anyone we can authenticate via DNS
        rekey=no                    # let unused connections die

# opportunistic connections for client systems
# our gateway will build opportunistic tunnels on behalf of any
# machine in the specified subnet
conn subnet-to-anyone
        also=gate_stuff             # our system details, stored below
        also=public_subnet          # subnet description, below
        right=%opportunistic        # anyone we can authenticate via DNS
        rekey=no                    # let unused connections die

# description of our gateway system
# included in other connection descriptions via also= lines
# must come after the lines that use it
conn gate_stuff
        # all connections should use our default route
        # also controls the source address on IPsec packets
        left=%defaultroute
        # our identity for IPsec negotiations
        # must match what is in DNS and ipsec.secrets(5)
        leftid=gateway.example.com

# description of the subnet this gateway encrypts for
# numbers used here are arbitrary, just for example
conn public_subnet
       leftsubnet=1.2.3.0/24 
Supporting additional subnets
If required, a gateway can easily provide this service for more than one subnet. You just add a connection description and a subnet description for each. For example, leaving everything else above unchanged, you could add these sections:
# opportunistic connections for additional systems
conn second-to-anyone
        also=gate_stuff             # our system details, stored below
        also=second_subnet          # subnet description, below
        right=%opportunistic        # anyone we can authenticate via DNS
        rekey=no                    # let unused connections die

# description of a second subnet this gateway encrypts for
# numbers used here are arbitrary, just for example
conn second_subnet
       leftsubnet=4.5.6.0/24 

There is one small thing to be careful of here. An also= line must appear in the file before the conn it references, so the first section above must appear before conn gate_stuff.

The subnets used in these descriptions need not correspond to physical subnets. This is discussed in more detail in our advanced configuration document.

DNS entries for an opportunistic gateway

DNS setup for an opportunistic gateway involves several types of record:

If you are not familar with DNS, see our DNS background section.
Gateway record in forward map
The gateway should have a KEY record in its forward map. It will look like this (except that we shorten the key here):
  ; RSA 2048 bits   gateway.example.com   Sat Apr 15 13:53:22 2000
  gateway.example.com.   IN   KEY   0x4200 4 1 AQOF8tZ2...+buFuFn/
This can be generated with ipsec showhostkey.
Gateway record in reverse map
To accept incoming connections, you also need a KEY record in the reverse map. The initiator will not always know your gateway's name. It must be possible to look up the key knowing only the IP address.

The record you need looks like this:

  ; RSA 2048 bits   gateway.example.com   Sat Apr 15 13:53:22 2000
  4.3.2.1.in-addr.arpa.   IN   KEY   0x4200 4 1 AQOF8tZ2...+buFuFn/

Generate a record with ipsec showhostkey, and then edit it to insert the IP address.

As always, IP addresses in the reverse map are written backwards. In the above example, the gateway IP address is 1.2.3.4.

Authorisation records in reverse map
For the gateway to provide an opportunistic encryption service for other systems, it must be possible for the initiator of an IPsec connection to: This is done by adding a KEY record to the reverse map for the endpoint. The record looks like this:
	; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
	IN TXT  "X-IPsec-Server(10)=1.2.3.4 AQOF8tZ2...+buFuFn/"
This record must be generated on the gateway so it can get the key from ipsec.secrets(5). The command is:
     ipsec showhostkey --txt 1.2.3.4
You must supply the gateway IP address on the command line.

One of these records is required in the reverse map for each system using this gateway for opportunistic IPsec.

"Road Warrior" remote access

A common requirement is for pre-configured connections between a specfic network and some set of remote machines. For example, an office network will often need to provide remote access services for:

We refer to the remote machines as "Road Warriors". For purposes of IPsec, anyone with a dynamic IP address is a road warrior.

Of course, if both the warrior and the gateway at the office are set up for opportunistic encryption, then you may not need the pre-configured connection. Here we assume that you do need it. For example:

This section has three sub-sections:

On either end, the opportunistic setup is unaffected by this. You leave it in place so both systems can continue to do opportunistic encryption with everyone but each other.

Information exchange

To set up an explicitly configured connection, you need some information about the system on the other end.

The gateway adminstrator needs to know some things about each Road Warrior:

To get this information, in a format suitable for insertion directly into the gateway's ipsec.conf(5) file, issue this command on the Warrior machine:

	ipsec showhostkey --right
The output should look like this (with the key shortened for easy reading):
	rightid=xy.example.com
	rightrsasigkey=

The Road Warrior needs to know:

which can be generated by runing ipsec showhostkey --left on the gateway. Each Warrior must also know:

This information should be provided in a convenient format, ready for insertion in the Warrior's ipsec.conf(5) file. For example:

	left=1.2.3.4
	leftsubnet=5.6.7.0/24
	leftid=gateway.example.com
	leftrsasigkey=

The gateway administrator typically needs to generate this only once. The same file can be given to all Warriors.

Of course it is also possible to provide different versions (in particular, access to differnet subnets) to different groups of Warriors. See our advanced configuration document.

Setup on the Road Warrior machine

To set up a Road Warrior machine, we start from the opportunistic client setup shown above. We need not change anything there, only add a connection description for the pre-configured tunnel.

Connection description for a pre-configured tunnel

We insert the new connection description before the conn our_stuff section, so that it can use an also= line referring to that section.

# pre-configured link to office network
conn us-to-office
        also=our_stuff             # our system details, stored below
        #
        # information obtained from office system admin
        # goes to the right of the = signs in these lines
        # values shown here are just for example
        # 
        left=1.2.3.4               # gateway IP address
        leftsubnet=5.6.7.0/24      # the office network
        leftid=gateway.example.com
        # real keys are much longer than shown here
        leftrsasigkey=

Everything else remains as it was when we had only opportunistic connections.

We could easily add more connections as required, perhaps one each for his office, her office, the kid's school, ... The file would grow longer, but nothing already in the file would need to change.

NAT for hidden clients

In many cases, the gateway for a small home network can use exactly the same Road Warrior ipsec.conf(5) file that a traveller's laptop would.

If your gateway uses NAT to allow machines to access the Internet without having their own routable IP addresses, then from the point of view of anyone else on the Internet:

For purposes of IPsec across the Internet, your gateway can be treated as a standalone machine. Consequently, your ipsec.conf(5) file needs no changes to support the NAT. It can be identical to what you would use on a standalone system, as shown above.

Firewall rules do need to be a little more complex to support the NAT. See the firewall section below for details.

For a more detailed discussion of NAT, see our background section.

Road Warrior support on an office gateway

Adding road warrior support so people can connect remotely to your office network is straightforward.

We start from the opportunistic gateway setup shown above.

Putting connection descriptions in separate files

You could put a complete connection description for each Warrior in your ipsec.conf(5) file, but this makes for a rather unmanageable file if you have many Warriors.

Instead, we suggest you give each warrior its own file, choosing some directory and naming convention that suits your system and style.

For this example, we use the directory /etc/ipsec.road and use filenames based on IPsec ID, so the Warrior using ID xy.example.com gets a file named xy.conf.

Using such files, you need add only one line to ipsec.conf(5). With our naming convention, the line is:

      include /etc/ipsec.road/*.conf

FreeS/WAN will then read all those files and behave as if they were part of the ipsec.conf(5) file.

This needs to come before the conn gate_stuff section, so that the Warriors' connection descriptions can use also=gate_stuff. A convenient place for the line is right after the conn %default section.

Each of the Road Warrior files then contains a connection description for that Warrior. For example:

# connection description for Road Warrior "xy"
conn gate-xy
	# use the gateway description in ipsec.conf(5)
	also=gate_stuff
	# allow connection attempt from any address
	# attempt fails if caller cannot authenticate
	right=%any
	# authentication information
	rightid=xy.example.com
	rightrsasigkey=

With this technique, it becomes fairly simple to administer a gateway that supports many Road Warriors. For example:

To add a new user, simply add a suitable file.

To disable an account -- for example if a key is compromised -- first remove the file, then take any existing connection down with:

	ipsec auto --down connection
and delete it from Pluto's internal database with:
	ipsec auto --delete connection

If you have many users, it would be worthwhile to write scripts to automate such tasks.

Network-to-network VPN

Often it is useful to have explicitly configured IPsec tunnels between different offices of an organisation, or between organisations that have joint projects.

Of course, if both offices are set up for opportunistic encryption and the security policies in place allow you to use that, explicitly configured tunnels become unnecessary. However, this will not always be the case.

Gateway setup for net-to-net

Adding up a network-to-network tunnel does not require any change to the opportunistic or Road warrior parts of your ipsec.conf(5). You can keep those parts exactly as shown above.

Of course, a network-to-network tunnel requires its own connection description, so you have to add that. There are two ways to do this.

identical connection description on the two ends
needs to specify more detail so the machine can figure out which end it is on
slightly different descriptions on the two ends
needs less detail, but you need to manage two descriptions
Choose whichever is more convenient to administer in your environment.

A connection description that works on either end

Here is a network-to-network tunnel description from our examples file:
# 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
Due to an unfortunate interaction between FreeS/WAN and the kernel routing code, you must specify leftnexthop (the router which left sends packets to in order to get them delivered to right) and rightnexthop (vice versa).

The *nexthop parameters will be eliminated in a future release, but perhaps not soon. We know they should go, but getting them out is not a simple problem. For now, live with them.

This description can be generated on either machine and simply inserted in the ipsec.conf(5) file on the other. No change is required or desired.

Using slightly different descriptions

Provided both machines do IPsec over the interface that is their default route to the Internet (a common case, but by no means the only one) you can simplify the description somewhat.

When using left=%defaultroute, you do not need to specify leftnexthop. left does not need to know rightnexthop either, so on left the connection description can be:

conn sample
        # left security gateway (public-network address)
        left=%defaultroute
         # subnet behind left (omit if there is no subnet)
        leftsubnet=172.16.0.0/24
        # right s.g., subnet behind it
        right=10.12.12.1
        rightsubnet=192.168.0.0/24
        auto=start
On right it is:
conn sample
        # left security gateway (public-network address)
        left=10.0.0.1
        # subnet behind left (omit if there is no subnet)
        leftsubnet=172.16.0.0/24
        # right s.g., subnet behind it
        right=%defaultroute
        rightsubnet=192.168.0.0/24
        auto=start

Firewalling

FreeS/WAN often runs on a firewall machine and, even if it is on a separate machine, it must interact with firewalls to get its job done.

This section describes simple firewall setups, suitable for getting a FreeS/WAN machine running. A separate FreeS/WAN and firewalls document provides more detail.

Firewalling for a standalone system

Firewall rules on a standalone system doing IPsec -- opportunistic, "road warrior" remote access, or both -- can be very simple.

The first step is to allow IPsec packets (IKE on UDP port 500 plus ESP, protocol 50) in and out of your gateway. A script to set up iptables(8) rules for this is:

# edit this line to match the interface you use as default route
# ppp0 is correct for many modem, DSL or cable connections
# but perhaps not for you
world=ppp0
#
# allow IPsec
#
# IKE negotiations
iptables -A INPUT  -p udp -i $world --sport 500 --dport 500 -j ACCEPT
iptables -A OUTPUT -p udp -o $world --sport 500 --dport 500 -j ACCEPT
# ESP encrypton and authentication
iptables -A INPUT  -p 50 -i $world -j ACCEPT
iptables -A OUTPUT -p 50 -o $world -j ACCEPT

Optionally, you could restrict this, allowing these packets only to and from a list of known gateways.

A second firewalling step -- access controls built into the IPsec protocols -- is automatically applied:

Pluto -- the FreeS/WAN keying daemon -- deals with the IKE packets.
Pluto authenticates its partners during the IKE negotiation, and drops negotiation if authentication fails.
KLIPS -- the FreeS/WAN kernel component -- handles the ESP packets.
KLIPS drops outgoing packets
if they are routed to IPsec, but no tunnel has been negotiated for them
KLIPS drops incoming unencrypted packets
if source and destination addresses match a tunnel; the packets should have been encrypted
KLIPS drops incoming encrypted packets
if source and destination address do not match the negotiated parameters of the tunnel that delivers them
if packet-level authentication fails
These errors are logged. See our troubleshooting document for details.

Optionally, you can add a third step using whatever additional firewall rules are required for your situation. These rules can recognise packets emerging from IPsec. They are marked as arriving on an interface such as ipsec0, rather than eth0, ppp0 or whatever. For example, in an iptables(8) rule set, you would use:

-i ipsec+
to specify packets arriving on any ipsec device
-o ipsec+
to specify packets leaving via any ipsec device
It is therefore straightforward to apply whatever filtering you like to these packets.

Firewalling for gateways

On a gateway, the IPsec-related firewall rules applied for input and output on the Internet side are exactly as shown above. A gateway exchanges exactly the same things -- UDP 500 packets and IPsec packets -- with other gateways that a standalone system does, so it can use exactly the same firewall rules as a standalone system would.

However, on a gateway there are additional things to do:

You need additional rules to handle these things. For example, adding some rules to the set shown above we get:

# edit this line to match the interface you use as default route
# ppp0 is correct for many modem, DSL or cable connections
# but perhaps not for you
world=ppp0
#
# edit these lines to describe your internal subnet and interface
localnet=42.42.42.0/24
internal=eth1
#
# allow IPsec
#
# IKE negotiations
iptables -A INPUT  -p udp -i $world --sport 500 --dport 500 -j ACCEPT
iptables -A OUTPUT -p udp -o $world --sport 500 --dport 500 -j ACCEPT
# ESP encrypton and authentication
iptables -A INPUT  -p 50 -i $world -j ACCEPT
iptables -A OUTPUT -p 50 -o $world -j ACCEPT
#
# packet forwarding for an IPsec gateway
#
# handle packets emerging from IPsec
# ipsec+ means any of ipsec0, ipsec1, ...
iptables -A FORWARD -d $localnet -i ipsec+ -j ACCEPT
# simple rule for outbound packets
# let local net send anything
# IPsec will encrypt some of it
iptables -A FORWARD -s $localnet -i $internal -j ACCEPT 

On a production gateway, you would no doubt need tighter rules than the above. For details, see:


Contents Previous Next