shorewall_code/docs/OPENVPN.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article id="OPENVPN">
  <!--$Id$-->

  <articleinfo>
    <title>OpenVPN Tunnels and Bridges</title>

    <authorgroup>
      <author>
        <firstname>Simon</firstname>

        <surname>Matter</surname>
      </author>

      <author>
        <firstname>Tom</firstname>

        <surname>Eastep</surname>
      </author>
    </authorgroup>

    <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>

    <copyright>
      <year>2003</year>

      <year>2004</year>

      <year>2005</year>

      <year>2006</year>

      <holder>Simon Mater</holder>

      <holder>Thomas M. Eastep</holder>
    </copyright>

    <legalnotice>
      <para>Permission is granted to copy, distribute and/or modify this
      document under the terms of the GNU Free Documentation License, Version
      1.2 or any later version published by the Free Software Foundation; with
      no Invariant Sections, with no Front-Cover, and with no Back-Cover
      Texts. A copy of the license is included in the section entitled
      <quote><ulink url="GnuCopyright.htm">GNU Free Documentation
      License</ulink></quote>.</para>
    </legalnotice>
  </articleinfo>

  <caution>
    <para><emphasis role="bold">This article applies to Shorewall 3.0 and
    later and to OpenVPN 2.0 and later. If you are running a version of
    Shorewall earlier than Shorewall 3.0.0 then please see the documentation
    for that release.</emphasis></para>
  </caution>

  <para>OpenVPN is a robust and highly configurable VPN (Virtual Private
  Network) daemon which can be used to securely link two or more private
  networks using an encrypted tunnel over the internet. OpenVPN is an Open
  Source project and is <ulink
  url="http://openvpn.sourceforge.net/license.html">licensed under the
  GPL</ulink>. OpenVPN can be downloaded from <ulink
  url="http://openvpn.net/">http://openvpn.net/</ulink>.</para>

  <para>Unless there are interoperability issues (the remote systems do not
  support OpenVPN), OpenVPN is my choice any time that I need a VPN.</para>

  <orderedlist>
    <listitem>
      <para>It is widely supported -- I run it on both Linux and Windows
      XP.</para>
    </listitem>

    <listitem>
      <para>It requires no kernel patching.</para>
    </listitem>

    <listitem>
      <para>It is very easy to configure.</para>
    </listitem>

    <listitem>
      <para>It just works!</para>
    </listitem>
  </orderedlist>

  <section id="Prelim">
    <title>Preliminary Reading</title>

    <para>I recommend reading the <ulink url="VPNBasics.html">VPN
    Basics</ulink> article if you plan to implement any type of VPN.</para>
  </section>

  <section id="Routed">
    <title>Bridging two Masqueraded Networks</title>

    <para>Suppose that we have the following situation:</para>

    <graphic fileref="images/TwoNets1.png" />

    <para>We want systems in the 192.168.1.0/24 subnetwork to be able to
    communicate with the systems in the 10.0.0.0/8 network. This is
    accomplished through use of the
    <filename>/etc/shorewall/tunnels</filename> file and the
    <filename>/etc/shorewall/policy file</filename> and OpenVPN.</para>

    <para>While it was possible to use the Shorewall start and stop script to
    start and stop OpenVPN, I decided to use the init script of OpenVPN to
    start and stop it.</para>

    <para>On each firewall, you will need to declare a zone to represent the
    remote subnet. We'll assume that this zone is called <quote>vpn</quote>
    and declare it in <filename>/etc/shorewall/zones</filename> on both
    systems as follows.</para>

    <blockquote>
      <para><filename>/etc/shorewall/zones</filename> — Systems A &amp;
      B</para>

      <programlisting>#ZONE   TYPE   OPTIONS                 IN                      OUT
#                                      OPTIONS                 OPTIONS
vpn     ipv4</programlisting>
    </blockquote>

    <para>On system A, the 10.0.0.0/8 will comprise the <emphasis
    role="bold">vpn</emphasis> zone.</para>

    <blockquote>
      <para>In <filename>/etc/shorewall/interfaces</filename> on system
      A:</para>

      <programlisting>#ZONE      INTERFACE        BROADCAST     OPTIONS
vpn        tun0</programlisting>
    </blockquote>

    <para>In <filename>/etc/shorewall/tunnels</filename> on system A, we need
    the following:</para>

    <blockquote>
      <programlisting>#TYPE         ZONE           GATEWAY        GATEWAY ZONE
openvpn       net            134.28.54.2</programlisting>
    </blockquote>

    <para>This entry in <filename>/etc/shorewall/tunnels</filename> opens the
    firewall so that OpenVPN traffic on the default port 1194/udp will be
    accepted to/from the remote gateway. If you change the port used by
    OpenVPN to 7777, you can define /etc/shorewall/tunnels like this:</para>

    <blockquote>
      <para>/etc/shorewall/tunnels with port 7777:</para>

      <programlisting>#TYPE             ZONE           GATEWAY         GATEWAY ZONE
openvpn:7777      net            134.28.54.2</programlisting>
    </blockquote>

    <para>Similarly, if you want to use TCP for your tunnel rather than UDP
    (the default), then you can define /etc/shorewall/tunnels like
    this:</para>

    <blockquote>
      <para>/etc/shorewall/tunnels using TCP:</para>

      <programlisting>#TYPE             ZONE           GATEWAY         GATEWAY ZONE
openvpn:tcp       net            134.28.54.2</programlisting>
    </blockquote>

    <para>Finally, if you want to use TCP and port 7777:</para>

    <blockquote>
      <para>/etc/shorewall/tunnels using TCP port 7777:</para>

      <programlisting>#TYPE             ZONE           GATEWAY         GATEWAY ZONE
openvpn:tcp:7777  net            134.28.54.2</programlisting>
    </blockquote>

    <para>This is the OpenVPN config on system A:</para>

    <blockquote>
      <programlisting>dev tun
local 206.162.148.9
remote 134.28.54.2
ifconfig 192.168.99.1 192.168.99.2
route 10.0.0.0 255.0.0.0 192.168.99.2
tls-server
dh dh1024.pem
ca ca.crt
cert my-a.crt
key my-a.key
comp-lzo
verb 5</programlisting>
    </blockquote>

    <para>Similarly, On system B the 192.168.1.0/24 subnet will comprise the
    <emphasis role="bold">vpn</emphasis> zone</para>

    <blockquote>
      <para>In <filename>/etc/shorewall/interfaces</filename> on system
      B:</para>

      <programlisting>#ZONE      INTERFACE        BROADCAST     OPTIONS
vpn        tun0 </programlisting>
    </blockquote>

    <para>In <filename>/etc/shorewall/tunnels</filename> on system B, we
    have:</para>

    <blockquote>
      <programlisting>#TYPE         ZONE           GATEWAY        GATEWAY ZONE
openvpn       net            206.191.148.9</programlisting>
    </blockquote>

    <para>And in the OpenVPN config on system B:</para>

    <blockquote>
      <programlisting>dev tun
local 134.28.54.2
remote 206.162.148.9
ifconfig 192.168.99.2 192.168.99.1
route 192.168.1.0 255.255.255.0 192.168.99.1
tls-client
ca ca.crt
cert my-b.crt
key my-b.key
comp-lzo
verb 5</programlisting>
    </blockquote>

    <para>You will need to allow traffic between the <quote>vpn</quote> zone
    and the <quote>loc</quote> zone on both systems -- if you simply want to
    admit all traffic in both directions, you can use the policy file:</para>

    <blockquote>
      <para><filename>/etc/shorewall/policy </filename>on systems A &amp;
      B</para>

      <programlisting>#SOURCE        DEST          POLICY          LOG LEVEL
loc            vpn           ACCEPT
vpn            loc           ACCEPT</programlisting>
    </blockquote>

    <para>On both systems, restart Shorewall and start OpenVPN. The systems in
    the two masqueraded subnetworks can now talk to each other.</para>
  </section>

  <section id="RoadWarrior">
    <title>Roadwarrior</title>

    <para>OpenVPN 2.0 provides excellent support for roadwarriors. Consider
    the setup in the following diagram:</para>

    <graphic fileref="images/Mobile.png" />

    <para>On the gateway system (System A), we need a zone to represent the
    remote clients — we'll call that zone <quote>road</quote>.</para>

    <blockquote>
      <para><filename>/etc/shorewall/zones</filename> — System A:</para>

      <programlisting>#ZONE   TYPE   OPTIONS                 IN                      OUT
#                                      OPTIONS                 OPTIONS
road    ipv4</programlisting>
    </blockquote>

    <para>On system A, the remote clients will comprise the <emphasis
    role="bold">road</emphasis> zone.</para>

    <blockquote>
      <para>In <filename>/etc/shorewall/interfaces</filename> on system
      A:</para>

      <programlisting>#ZONE      INTERFACE        BROADCAST     OPTIONS
road       tun+</programlisting>
    </blockquote>

    <para>In <filename>/etc/shorewall/tunnels</filename> on system A, we need
    the following:</para>

    <blockquote>
      <programlisting>#TYPE         ZONE           GATEWAY        GATEWAY ZONE
openvpn:1194  net            0.0.0.0/0</programlisting>
    </blockquote>

    <para>If you are running Shorewall 2.4.3 or later, you might prefer the
    following in <filename>/etc/shorewall/tunnels</filename> on system A.
    Specifying the tunnel type as openvpnserver has the advantage that the VPN
    connection will still work if the client is behind a gateway/firewall that
    uses NAT.</para>

    <blockquote>
      <programlisting>#TYPE               ZONE           GATEWAY        GATEWAY ZONE
openvpnserver:1194  net            0.0.0.0/0</programlisting>
    </blockquote>

    <para>We want the remote systems to have access to the local LAN — we do
    that with an entry in <filename>/etc/shorewall/policy</filename> (assume
    that the local LAN comprises the zone <quote>loc</quote>).</para>

    <blockquote>
      <programlisting>#SOURCE      DESTINATION        POLICY
road         loc                ACCEPT</programlisting>
    </blockquote>

    <para>The OpenVPN configuration file on system A is something like the
    following:</para>

    <blockquote>
      <programlisting>dev tun

server 192.168.2.0 255.255.255.0

dh dh1024.pem

ca /etc/certs/cacert.pem

crl-verify /etc/certs/crl.pem

cert /etc/certs/SystemA.pem
key /etc/certs/SystemA_key.pem

port 1194

comp-lzo

user nobody

group nogroup

ping 15
ping-restart 45
ping-timer-rem
persist-tun
persist-key

verb 3</programlisting>
    </blockquote>

    <para>Configuration on the remote clients follows a similar line. We
    define a zone to represent the remote LAN:</para>

    <blockquote>
      <para><filename>/etc/shorewall/zones</filename> — System B:</para>

      <programlisting>#ZONE   TYPE   OPTIONS                 IN                      OUT
#                                      OPTIONS                 OPTIONS
home    ipv4</programlisting>
    </blockquote>

    <para>On system A, the hosts accessible through the tunnel will comprise
    the <emphasis role="bold">home</emphasis> zone.</para>

    <blockquote>
      <para>In <filename>/etc/shorewall/interfaces</filename> on system
      B:</para>

      <programlisting>#ZONE      INTERFACE        BROADCAST     OPTIONS
home       tun0</programlisting>
    </blockquote>

    <para>In <filename>/etc/shorewall/tunnels</filename> on system B, we need
    the following:</para>

    <blockquote>
      <programlisting>#TYPE         ZONE           GATEWAY        GATEWAY ZONE
openvpn:1194  net            206.162.148.9</programlisting>
    </blockquote>

    <para>Again in you are running Shorewall 2.4.3 or later, in
    <filename>/etc/shorewall/tunnels</filename> on system B you might
    prefer:</para>

    <blockquote>
      <programlisting>#TYPE               ZONE           GATEWAY        GATEWAY ZONE
openvpnclient:1194  net            206.162.148.9</programlisting>
    </blockquote>

    <para>We want the remote client to have access to the local LAN — we do
    that with an entry in <filename>/etc/shorewall/policy</filename>.</para>

    <blockquote>
      <programlisting>#SOURCE      DESTINATION        POLICY
$FW          home               ACCEPT</programlisting>
    </blockquote>

    <para>The OpenVPN configuration on the remote clients is along the
    following line:</para>

    <blockquote>
      <programlisting>dev tun
remote 206.162.148.9
up /etc/openvpn/home.up

tls-client
pull

ca /etc/certs/cacert.pem

cert /etc/certs/SystemB.pem
key /etc/certs/SystemB_key.pem

port 1194

user nobody
group nogroup

comp-lzo

ping 15
ping-restart 45
ping-timer-rem
persist-tun
persist-key

verb 3</programlisting>
    </blockquote>

    <para>If you want multiple remote clients to be able to communicate openly
    with each other then you must:</para>

    <orderedlist>
      <listitem>
        <para>Include the <emphasis role="bold">client-to-client</emphasis>
        directive in the server's OpenVPN configuration; and</para>
      </listitem>

      <listitem>
        <para>Specify the <emphasis role="bold">routeback</emphasis> option on
        the <filename class="devicefile">tun+</filename> device in <ulink
        url="manpages/shorewall-interfaces.html">/etc/shorewall/interfaces</ulink>.</para>
      </listitem>
    </orderedlist>

    <para>If you want to selectively allow communication between the clients,
    then see <ulink
    url="http://marc.zonzon.free.fr/public_html/home.php?section=WRTMemo&amp;subsec=vpnwithshorewall">this
    article</ulink> by Marc Zonzon</para>
  </section>

  <section id="Bridge">
    <title>Securing a Home Wireless Network with OpenVPN (OpenVPN
    Bridge)</title>

    <para>This section will describe how we once secured our home wireless
    network using OpenVPN. Our network as it was then<footnote>
        <para>Our current network uses a similar technique -- see the <ulink
        url="XenMyWay.html">Xen My Way</ulink> article.</para>
      </footnote> is as shown in the following diagram.</para>

    <graphic fileref="images/network3.png" />

    <para>The Wireless network is in the lower right of the diagram and
    consists of two laptops: Eastepnc6000 (Dual Boot Windows XP - SP1, SUSE
    10.0) and Tipper (SUSE 10.0). We used OpenVPN to bridge those two laptops
    with the local LAN shown in the lower left hand corner. The laptops were
    configured with addresses in the 192.168.3.0/24 network connected to the
    firewall's <filename class="devicefile">eth0</filename> interface which
    places them in the firewall's <emphasis role="bold">Wifi</emphasis> zone.
    OpenVPN bridging allowed them to be assigned an additional IP address from
    the 192.168.1.0/24 network and to be securely bridged to the LAN on the
    lower left.</para>

    <note>
      <para>Eastepnc6000 is shown in both the local LAN and in the Wifi zone
      with IP address 192.168.1.6 -- clearly, the computer could only be in
      one place or the other. Tipper could also be in either place and would
      have the IP address 192.168.1.8 regardless.</para>
    </note>

    <section id="bridge">
      <title>Configuring the Bridge</title>

      <para>The firewall ran Debian Sarge so the bridge was defined in
      <filename>/etc/network/interfaces</filename>.</para>

      <programlisting># LAN interface
auto br0
iface br0 inet static
        address 192.168.1.254
        netmask 255.255.255.0
        pre-up /usr/sbin/openvpn --mktun --dev tap0
        pre-up /sbin/ip link set tap0 up
        pre-up /sbin/ip link set eth3 up
        pre-up /usr/sbin/brctl addbr br0
        pre-up /usr/sbin/brctl addif br0 eth3
        pre-up /usr/sbin/brctl addif br0 tap0
        pre-down /usr/sbin/brctl delif br0 eth3
        pre-down /sbin/ip link set eth3 down
        pre-down /usr/sbin/brctl delif br0 tap0
        pre-down /sbin/ip link set tap0 down
        post-down /usr/sbin/brctl delbr br0
        post-down /usr/sbin/openvpn --rmtun --dev tap0</programlisting>

      <para>Note that the IP address assigned to the bridge is 192.168.1.254
      -- that was the default gateway address for hosts in the local
      zone.</para>
    </section>

    <section id="openvpn">
      <title>Configuring OpenVPN</title>

      <para>We used X.509 certificates for authentication.</para>

      <section id="server">
        <title>Firewall (Server) configuration.</title>

        <para>/etc/openvpn/server-bridge.conf defined a bridge and reserved IP
        addresses 192.168.1.64-192.168.1.71 for VPN clients. Note that the
        bridge server only used local IP address 192.168.3.254. We ran two
        instances of OpenVPN; this one and a second tunnel-mode instance for
        remote access.</para>

        <programlisting>dev tap0

local 192.168.3.254

server-bridge 192.168.1.254 255.255.255.0 192.168.1.64 192.168.1.71

client-to-client

dh dh1024.pem

ca /etc/certs/cacert.pem

crl-verify /etc/certs/crl.pem

cert /etc/certs/gateway.pem
key /etc/certs/gateway_key.pem

port 1194

comp-lzo

user nobody
group nogroup

keepalive 15 45
ping-timer-rem
persist-tun
persist-key

client-config-dir /etc/openvpn/bridge-clients
ccd-exclusive

verb 3</programlisting>

        <para>The files in <filename>/etc/openvpn/bridge-clients</filename>
        were used to assign a fixed IP address to each laptop. For example,
        tipper.shorewall.net:</para>

        <programlisting>ifconfig-push 192.168.1.8 255.255.255.0</programlisting>
      </section>

      <section id="tipper">
        <title>Tipper Configuration</title>

        <para>/etc/openvpn/wireless.conf:</para>

        <programlisting>dev tap

remote 192.168.3.254
tls-remote gateway.shorewall.net

client

redirect-gateway

ca /etc/certs/cacert.pem

cert /etc/certs/tipper.pem
key /etc/certs/tipper_key.pem

port 1194

comp-lzo

ping 15
ping-restart 45
ping-timer-rem
persist-tun
persist-key

mute-replay-warnings

verb 3</programlisting>
      </section>

      <section id="XP">
        <title>Eastepnc6000 (Windows XP) Configuration</title>

        <para>C:\Program Files\Openvpn\config\homewireless.ovpn:</para>

        <programlisting>dev tap
remote 192.168.3.254
tls-remote gateway.shorewall.net

tls-client
pull

ca "/Program Files/OpenVPN/certs/cacert.pem"

cert "/Program Files/OpenVPN/certs/eastepnc6000.pem"
key "/Program Files/OpenVPN/certs/eastepnc6000_key.pem"

redirect-gateway

port 1194

comp-lzo

ping 15
ping-restart 45
ping-timer-rem
persist-tun
persist-key

verb 3</programlisting>
      </section>

      <section id="Linux">
        <title>Eastepnc6000 (SUSE 10.0) Configuration</title>

        <para>The configuration was the same as shown above only with
        "/Program Files/OpenVPN" replaced with "/etc/openvpn" (I love
        OpenVPN).</para>
      </section>

      <section>
        <title>Ursa (Windows Vista) Configuration</title>

        <para>In December 2007, I acquired a new laptop that runs Windows
        Vista. After a frustrating effort, I managed to get it working. The
        keys to getting it working were:</para>

        <orderedlist>
          <listitem>
            <para>You must run a version of OpenVPN that is "Vista Ready" -- I
            used Matias Sundman's combined OpenVPN 2.1_rc4/OpenVPN GUI 1.0.3
            installer (see <ulink
            url="http://openvpn.se/">http://openvpn.se/</ulink>).</para>
          </listitem>

          <listitem>
            <para>OpenVPN GUI must be run as the Administrator. In the
            Explorer, right click on the OpenVPN GUI binary and select
            Properties-&gt;Compatibilty and select "Run this program as an
            administrator".</para>
          </listitem>

          <listitem>
            <para>If you encounter problems where everything looks correct but
            it doesn't work, reboot and try it again.</para>
          </listitem>
        </orderedlist>
      </section>
    </section>

    <section id="Shorewall">
      <title>Configuring Shorewall</title>

      <para>In this configuration, we didn't need any firewalling between the
      laptops and the local LAN so we set BRIDGING=No in shorewall.conf. The
      configuration of the bridge then became as described in the <ulink
      url="SimpleBridge.html">Simple Bridge documentation</ulink>. If you need
      to control the traffic allowed through the VPN bridge then you will want
      to configure Shorewall as shown in the <ulink
      url="bridge-Shorewall-perl.html">Bridge/Firewall
      documentation</ulink>.</para>

      <section id="FW">
        <title>Firewall</title>

        <section id="interfaces">
          <title>/etc/shorewall/interfaces</title>

          <para>Note that the bridge (br0) is defined as the interface to the
          local zone and has the <emphasis role="bold">routeback</emphasis>
          option.</para>

          <programlisting>#ZONE   INTERFACE       BROADCAST               OPTIONS
net     eth2            206.124.146.255         dhcp,norfc1918,logmartians,blacklist,tcpflags,nosmurfs
loc     br0             192.168.1.255           dhcp,<emphasis role="bold">routeback</emphasis>
dmz     eth1            -                       logmartians
Wifi    eth0            192.168.3.255           dhcp,maclist
#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE</programlisting>
        </section>

        <section id="tunnels">
          <title>/etc/shorewall/tunnels</title>

          <programlisting>#TYPE                   ZONE    GATEWAY         GATEWAY
#                                               ZONE
openvpnserver:1194      Wifi    192.168.3.0/24
#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE</programlisting>
        </section>
      </section>

      <section id="Tipper">
        <title>Tipper</title>

        <para>Wireless networks pose a threat to all systems that are
        connected to them and we therefore ran Firewalls on the two Laptops.
        Eastepnc6000 ran <trademark>Sygate</trademark> Security Agent and
        Tipper ran a Shorewall-based Netfilter firewall.</para>

        <section id="zones">
          <title>/etc/shorewall/zones</title>

          <programlisting>#ZONE   TYPE    OPTIONS                 IN                      OUT
#                                       OPTIONS                 OPTIONS
<emphasis role="bold">lan     ipv4</emphasis>    #Wired LAN at our home
net     ipv4
#LAST LINE - ADD YOUR ENTRIES ABOVE THIS ONE - DO NOT REMOVE
</programlisting>
        </section>

        <section id="interfaces1">
          <title>/etc/shorewall/interfaces</title>

          <programlisting>#ZONE    INTERFACE      BROADCAST       OPTIONS
#
net      eth0           detect          routefilter,dhcp,tcpflags
<emphasis role="bold">lan      tap0           192.168.1.255</emphasis>
#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE</programlisting>
        </section>

        <section id="policy">
          <title>/etc/shorewall/policy</title>

          <para>Since we didn't expect any traffic between the <emphasis
          role="bold">net</emphasis> zone and the <emphasis
          role="bold">lan</emphasis> zone, we used NONE policies for that
          traffic. If any such traffic would have occurred, it would have been
          handled according to the all-&gt;all policy.</para>

          <programlisting>#SOURCE         DEST            POLICY          LOG             LIMIT:BURST
#                                               LEVEL
fw              net             ACCEPT
<emphasis role="bold">fw              lan             ACCEPT
lan             fw              ACCEPT
net             lan             NONE
lan             net             NONE</emphasis>
net             all             DROP            info
# The FOLLOWING POLICY MUST BE LAST
all             all             REJECT          info
#LAST LINE -- DO NOT REMOVE</programlisting>
        </section>
      </section>
    </section>
  </section>
</article>