Developers Documentation



301 error for file:

User Tools

Site Tools

Ipsec Under the Hood

ClearOS 6 contains functionality for lots of IPSec functionality from the Marketplace through the Dynamic VPN app, Basic Static VPN app, and the Static VPN app and potentially others! Special care has to be done when making IPSec VPN apps so that they don't conflict with other packages (like multiwan) and there is some special tweaking that goes on in the various VPN technologies that overcomes these issues in a way that the plain open source application cannot automatically provide.

Moreover, IPSec is prone to stale sessions and disconnect to which its own service is unable to detect and resolve. The reason for the existence of the Managed VPN service is that IPSec is inherently a flaky technology. We recommend using OpenVPN for unmanaged tunnels.

This guide, however, gives some minimal help for configuring an IPSec VPN tunnel manually between two ClearOS boxes in case you have to use IPSec. Consider, however, resolving your issues with the apps in the marketplace before using this guide which is mostly useful to software developers that wish to create new IPSec VPN apps. Another reason for requiring a manual IPSec is that you may need to set up a tunnel between ClearOS and a third party firewall/router which only has this option and the paid app is not able to provide the connection or perhaps you just want to do it for free. These type of multi-vendor tunnels are possible but it is beyond the scope of this document to address them all. You can have success but you will need to familiarize yourself extensively with OpenSwan (the package which provides ipsec under ClearOS) and the terms involved. Also, you will need to google … a lot.

Getting started

Under ClearOS 6 you can download and install openswan IPSec by running the following:

yum install openswan

You might also want to grab the documentation.

yum install openswan-doc

Structure of OpenSwan

Openswan will install the following configuration files in etc:

  • /etc/ipsec.conf
    • contains global settings which affect all tunnels. Also contains the include which makes the /etc/ipsec.d directory do its magic.
  • /etc/ipsec.d
    • this is where the magic happens, all .conf files in this directory are treated as discrete tunnels. 99.9% of what you need to do is in this directory.
  • /etc/ipsec.d/policies
  • /etc/ipsec.d/policies/block
  • /etc/ipsec.d/policies/clear
  • /etc/ipsec.d/policies/clear-or-private
  • /etc/ipsec.d/policies/private
  • /etc/ipsec.d/policies/private-or-clear
  • /etc/ipsec.secrets
    • sets up the includes for .secrets files in the /etc/ipsec.d directory. Leave this alone.
  • /etc/rc.d/init.d/ipsec
    • this is the initial stub for the init scripts. The run levels and structure are created off of this stub

Lock files:

  • /var/run/pluto/pluto.ctl
    • a named socket
  • /var/run/pluto/
    • a named socket
  • /var/run/pluto/
    • process ID (only present when service is running)
  • /var/run/pluto/
    • contains info about active/running tunnels (only present when service is running)
  • /var/run/pluto/
    • process ID (only present when service is running)

Binaries and libraries:

  • /usr/sbin/.ipsec.hmac
  • /usr/sbin/ipsec
  • /usr/libexec/ipsec/

OpenSwan Daemon

The OpenSwan IPSec daemon is controlled by the following init script:



  • start
  • stop
  • restart
  • reload
  • force-reload
  • condrestart
  • try-restart
  • status
  • version

Setting the ipsec daemon to autostart

By default the ipsec daemon will not be automatically started. You can check the automatic start status by running the following (note: this works for all services in the init scripts)

chkconfig --list ipsec

You should get the following results after a fresh install:

[root@home pluto]# chkconfig --list ipsec
ipsec          	0:off	1:off	2:off	3:off	4:off	5:off	6:off

If you want ipsec to automatically start when you start your server, run the following command.

chkconfig --level 345 ipsec on && chkconfig --list ipsec
[root@home pluto]# chkconfig --level 345 ipsec on && chkconfig --list ipsec
ipsec          	0:off	1:off	2:off	3:on	4:on	5:on	6:off

The Webconfig Daemon class should handle this nicely when converted to an app.

Configuration files


The main two things that you will need for a tunnel are a properly configured .conf file and .secrets file which should be contained in the /etc/ipsec.d folder.

To build a minimal tunnel, create a file that ends in .conf in the /etc/ipsec.d folder. For example:

vi ipsec-here-to-there.conf
conn ipsec-here-to-there

For ClearOS to ClearOS connections this is pretty much it. Here are the values you will need to modify (in all examples our current/first box is the 'right' box):

  • conn ipsec-here-to-there
    • replace ipsec-here-to-there with whatever name you want. This is your tunnel name
  • left=
    • this is the IP address at the far end
  • leftnexthop=
    • this is the ip address of the default gateway of the far end ClearOS server. Crazy huh? IPSec sometimes need to know the gateway address. It needs this because when the tunnel is up, it needs to know where to send the packets in regards to the routing table.
  • leftsubnet=
    • this is the subnet of behind the firewall at the far side. We need this to build a proper router across the VPN.
  • right=
    • this is my public IP address. NOTE: ipsec does NOT work well behind NAT.
  • rightnexthop=
    • this is my default gateway address
  • rightsubnet=
    • this is the subnet on this side of the tunnel
  • authby=secret
    • instructs the tunnel to load the appropriate .secrets file
  • auto=start
    • this is useful to automatically bring up the tunnel

OK. That file needs to be that same way on both sides of the tunnel. No need to reverse the left and right sides of the thing. It can figure out by a comparison of the IP address and the next hop as to which side it is. This makes it easy to just copy the file so that it is the same on both sides.

Next is an example of a file that works to connect ClearOS to a Netgear router. I don't have the GUI snapshot of the Netgear but this is what a certain Netgear router needs for a 3rd party IPSec tunnel.

conn ipsec-here-to-netgear
	#rightnexthop= #Wasn't needed


The .secrets file should be named the same as the .conf for simplicity sake more than anything. If your .conf file was ipsec-here-to-there.conf then your secrets file should be ipsec-here-to-there.secrets. Both should be placed in /etc/ipsec.d/.

The .secrets file is the easy configuration. Here is an example: : PSK "blahblahblah.this-is_mySecretPRE-SHARED_key"

The elements are“

    • the left side public IP address
    • the right side public IP address
  • : PSK
    • divider which indicates a preshared key
  • “blahblahblah.this-is_mySecretPRE-SHARED_key”
    • the actual secret bounded by double quotes

Starting and stopping ipsec

To start ipsec run the following:

service ipsec start

To stop ipsec run the following:

service ipsec stop


Most of the information that will be useful can be found in two places.

tail -n 500 -f /var/log/secure | grep pluto

And the more verbose tool:

ipsec auto --status
content/en_us/kb_o_ipsec.txt · Last modified: 2015/11/12 15:57 by dloper