This section describes setting up and testing Linux FreeS/WAN.
This document is almost obsolete. It is being replaced by our new Quickstart Guide. We recommend that most users use that.
There are separate documents on testbed configurations and performance measurement which some users may want to consult along with this one. If you just want to get a few connections up, this document should have everything you need.
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.
In our examples, we describe a setup with three networks -- 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.
We'll call the two gateways East and West. We'll have a client machine on each net: Sunrise in the East and Sunset in the West.
Sunset==========West------------------East=========Sunrise
local net untrusted net local net
Of course one does not always have a security gateway separate from the client machine. It is also quite common to use IPsec on a network that looks like this:
telecommuter's PC or
traveller's laptop
Sunset==========West------------------East
corporate LAN untrusted net
We treat this setup as degenerate cases of the network-to-network link. The East computer is a gateway for a one-client subnet, and it is also the client.
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.
More complicated network configurations are described later.
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 client subnets must have distinct addresses. You cannot have them both masqueraded to the same range of RFC 1918 addresses.
You must have a working IP network before you try to add IPsec:
It is not enough to just test that your gateways (East and West in the example) can communicate. You need to test routing to the clients (Sunrise and Sunset) as well.
If you want to run some service encapsulated in IP -- perhaps to use Novell protocols encapsulated in IPX or to make Windows file sharing or NT domains work across the IPsec tunnel -- then please build and test what you need for that service on plain IP before trying it over IPsec. It can be a real nightmare trying to debug such things when you don't know if the problem is in IPsec, firewall rules, routing, or the configuration of the service itself. Some advice on making such things work with IPsec is in our interoperation section.
Some systems turn off packet forwarding by default. This is the safe default. You don't want systems forwarding packets in uncontrolled ways.
There are three places where you can enable or disable IP forwarding:
echo "1" > /proc/sys/net/ipv4/ip_forwardYou need root privileges to write to that file.
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 your distribution's standard boot scripts. See above.
A more conservative approach is to disable forwarding in your system configuration, and only enable it after appropriate firewall rules and IPsec tunnels are in place. This reduces the risk of something slipping past your defenses before they are fully set up. On most systems, this can conveniently be done by adding a line to /etc/rc.d/rc.local , which is usually the last script run at boot time.
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.
To build a connection, the two gateway machines must be able to authenticate each other. For FreeS/WAN, the default is public key authentication based on the RSA algorithm. IPsec does allow several other authentication methods; using some of them with FreeS/WAN is discussed in our advanced configuration section.
This section covers setting up RSA keys. The example connections to follow (VPN, road warrior and opportunistic) all use RSA.
RSA 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.
Public keys for the gateways you communicate with must be made available to your gateway. There are several ways to do this:
The first two methods are described in more detail below. See the X.509 patch documentation for details of the third, if required.
Remember that public key systems are designed so that it does not matter if an enemy knows the public keys. However, the private keys must be scrupulously protected.
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, then you need to generate an RSA key pair (private and public).
If you have the common simple situation where:
then you can just give these commands as root:
ipsec newhostkey > /etc/ipsec.secrets
chmod 600 /etc/ipsec.secrets
For other options, for example if you want to use different identities with different partners, see the ipsec.secrets(5) and ipsec_newhostkey(8) man pages.
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
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.
You need to extract the public part in a suitable suitable format. This done with the ipsec_showhostkey(8) command. For VPN or Road Warrior applications, use one of:
ipsec showhostkey --left
ipsec showhostkey --right
These two produce the key formatted for insertion in an ipsec.conf(5) file.
For opportunistic encryption, just use:
ipsec showhostkeyThis gives the key in a format suitable for use in DNS records.
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. You can safely make them publicly accessible -- for example, put a gateway key on a web page, make in available in DNS or via finger(1) -- or transmit it with an insecure method such as email. However, the recipient must be able to authenticate them, as described in the next section.
For example, consider the fellow who wants to communicate with his mistress, keeping messages secret from his wife.
The minute he begins to trust a bogus key, the cryptography does not just stop working for him. Instead, it becomes a powerful weapon against him.
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). Keys posted on the web or made available for finger(1) should also be PGP-signed. Keys in DNS should be protected by DNS Security . For nearby machines, a floppy disk or trusted network is fine.
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.
The syntax rules allow four types of identifier:
We recommend that only the @FQDN form be used in most applications. The other three forms have problems:
If your domain is example.com, the gateway identifiers you use should be all be of the form "@something.example.com" with some convenient string replacing something.
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.
One convenient scheme is to
FreeS/WAN uses a configuration file, ipsec.conf(5).
This section describes setting up the parts of that file that 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:
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.
For more detail, see the man page.
The confguration file uses left and right to refer to the two gateways involved in a connection, and has other parameters which come in left/right pairs. For example, leftsubnet is the subnet behind left.
Which gateway is left and which is right is arbitrary, entirely up to you.
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(5) files on both ends. The name reno , for example, should refer to the machine in Reno, no matter which city the file is in.
Then when you copy the file from one machine to the other, the only change you need to 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.
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:
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 and plutodebug can each be set to "none" or to "all" in most circumstances. There are other options; see the relevant man pages.
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.
There is a special name %default that lets you define things that apply to all connections.
You can also set general defaults here but override them later for specific connections. If both the %default section and the actual connection description set the same variable, then the connection description takes precedence.
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
# Load all connection descriptions by default
# Some will override this with auto=start
auto=add
Variables set here are:
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 might 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.
To actually start negotiations for a given connection, you need auto=start. You could make that the default here or leave auto=add as the default and override it where needed with auto=start in individual connection descriptions.
Once you are finished testing, you can edit these defaults, adding anything that is standard for all gateways in your organisation.
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
|
| [whatever]
|
inside interface
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
inside interface
|
| [whatever]
|
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.
The [whatever]s above indicate places where all that matters is routing.
You do not need to tell FreeS/WAN anything about the inside interfaces. In fact, there is no parameter you could use to do that. What you do have to do is make sure the gateway can route to its client subnet.
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:
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.)
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.
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.
Sunset==========West------------------East=========Sunrise
local net untrusted net local net
which we describe in our config files as:
leftsubnet === West------------------East=== rightsubnet
^left right^
In most cases, we also have to provide next hop information. A more
detailed diagram might look like this:
(using a, b, c, ... to refer to arbitrary numbers 0 to 255)
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 for the above network would look like this (with RSA keys shortened for easy display):
# basic configuration
config setup
interfaces="%defaultroute"
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
# So you have three choices, none of them ideal
#
# uncomment this to use our default script
# which works only with ipfwadm(8) on 2.0 kernels
# or ipchains(8) on 2.2 in ipfwadm(8) emulation mode
# rightfirewall=yes
#
# uncomment this and enter a name to write your own script
# to use all features of ipchains(8) on 2.2
# or to use iptables(8) on 2.4
# rightupdown=whatever_you_want_to_name_the_script
#
# if you uncomment neither and remove the rightsubnet= line
# then the tunnel terminates on the outside of your gateway
# and the masqueraded subnet is not visible to the remote
# subnet; they all think they're talking to the gateway
#
# try to start the connection
auto=start
For more on the use of the firewalling parameters -- leftfirewall, rightfirewall, leftupdown and rightupdown -- see our IPsec and firewalls section.
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.
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:
If you do this, the non-routable 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.
Of course FreeS/WAN can also tunnel packets between subnets with normal routable IP address.
For our purposes, a "road warrior" is any machine that does not have a fixed IP address. 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.
Some machines, such as home firewalls, may have a dynamic IP address and have a protected subnet behind them. For this example, however, we assume the Road Warrior is a standalone machine:
telecommuter's PC or
traveller's laptop
Sunset==========West------------------East
corporate LAN untrusted net
In more detail, the network looks like this:
(using a, b, c, ... to refer to arbitrary numbers 0 to 255)
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 setup and conn %default sections as in the VPN example.
# basic configuration
config setup
interfaces="%defaultroute"
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.road.example.com
rightrsasigkey=0xd9a24765fe...
#
# no subnet for a typical road warrior
# it is possible, but usually not needed
# so the rightsubnet= parameter is omitted
#
# 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 values shown above:
The file on the road warrior end is nearly identical, except that it has:
Because we are using right=%defaultroute, we omit the rightnexthop parameter.
Additional road warriors can be added as required. Each should have his or her own connection description with unique settings for rightid and rightrsasigkey.
If necessary, a single road warrior can have multiple connections, all with the same rightid and rightrsasigkey, but with different values for leftsubnet to give access to different parts of the office network.
Jean-Francois Nadeau's Practical Configurations document also has an example of using RSA authentication for road warriors.
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:
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.
The main documentation items so far are:
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.
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 # anyone we can authenticate via DNS
rekey=no # let unused connections die
The public key, in our format, must be in a KEY record of the appropriate DNS entry for this to work. We provide some background information on DNS in another file.
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.
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.
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.
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...nYyUkKK8This allows lookups on the IP address of the gateway to retrieve the key.
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...nYyUkKK8Your 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.
If your network is simple enough that one of the examples had all you need, then you can skip ahead to firewall setup .
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
# set some defaults appropriate for the gateway
# these should be changed or overridden on the road warriors
keyingtries=1 # road warrior can retry, we shouldn't
auto=add # default is to load, but not start
# some parameters are common to all remote systems
authby=rsasig # all connections use RSA authentication
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 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
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...
Be careful with the order of sections in ipsec.conf(5) and any included files. The parser 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.
The above method, using conn leftstuff and also= , is only one alternative. In simple cases, you can just put all the information about the left gateway in the conn default section instead and use no also= lines.
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.
This section covers testing connections once you have FreeS/WAN installed and your ipsec.conf(5) file set up. A separate testing document has more information if required.
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.
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, 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 and the FAQ section om error messages to get help interpreting them if required.
We recommend double-checking for consistency here before starting actual tests..
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 these ipsec pseudo-devices causes the data to be encrypted before being delivered to the underlying network interface. This can be done manually with our eroute(8) utility, but in most cases you do not need to use that utility directly. Just bring the connections up and down and the scripts call it as required.
Don't be surprised when you cannot find /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.
On one gateway, start IPsec with:
ipsec auto --up name
replacing name with the connection name you used in ipsec.conf(5).
For this to work, the connection description must already be loaded
into Pluto's database, either via auto=add in the connection
description or with an explicit
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.
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.
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 this discussion.
If packets look like total garbage, nothing recognizable, all is well.
See our document on testing for more detail if required.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.
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 go to:
Of course you might just go off for a beverage or meal at this point as well.