Documentation: IPsec tunnel tutorial and documentation.

tutorials/index.rst gives a step-by-setp guide to set up OVS IPsec
tunnel.

tutorials/ipsec.rst gives detailed explanation on the IPsec tunnel
configuration methods and forwarding modes.

Signed-off-by: Qiuyu Xiao <qiuyu.xiao.qyx@gmail.com>
Signed-off-by: Ansis Atteka <aatteka@ovn.org>
Co-authored-by: Ansis Atteka <aatteka@ovn.org>
Signed-off-by: Ben Pfaff <blp@ovn.org>

2 files changed, 348 insertions, 0 deletions

diff --git a/Documentation/tutorials/index.rst b/Documentation/tutorials/index.rst
index ab90b7c84..b481090a0 100644
--- a/Documentation/tutorials/index.rst
+++ b/Documentation/tutorials/index.rst
@@ -40,6 +40,7 @@ vSwitch.
    :maxdepth: 2
 
    faucet
+   ipsec
    ovs-advanced
    ovn-sandbox
    ovn-openstack
diff --git a/Documentation/tutorials/ipsec.rst b/Documentation/tutorials/ipsec.rst
new file mode 100644
index 000000000..b4c323513
--- /dev/null
+++ b/Documentation/tutorials/ipsec.rst
@@ -0,0 +1,347 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Open vSwitch documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+==================
+OVS IPsec Tutorial
+==================
+
+This document provides a step-by-step guide for running IPsec tunnel in Open
+vSwitch. A more detailed description on OVS IPsec tunnel and its
+configuration modes can be found in :doc:`/howto/ipsec`.
+
+Requirements
+------------
+
+OVS IPsec tunnel requires Linux kernel (>= v3.10.0) and OVS out-of-tree kernel
+module. The compatible IKE daemons are LibreSwan (>= v3.23) and StrongSwan
+(>= v5.3.5).
+
+.. _install-ovs-ipsec:
+
+Installing OVS and IPsec Packages
+---------------------------------
+
+OVS IPsec has .deb and .rpm packages. You should use the right package
+based on your Linux distribution. This tutorial uses Ubuntu 16.04 and Fedora 27
+as examples.
+
+Ubuntu
+~~~~~~
+
+1. Follow :doc:`/intro/install/debian` to build debian packages.
+
+   .. note::
+
+     If you have already installed OVS, then you only need to install
+     openvswitch-pki_*.deb and openvswitch-ipsec_*.deb in the following step.
+     If your kernel version is below v4.13.0, update your kernel to v4.13.0 or
+     above.
+
+2. Install the related packages::
+
+       $ apt-get install dkms strongswan
+       $ dpkg -i libopenvswitch_*.deb openvswitch-common_*.deb \
+             openvswitch-switch_*.deb openvswitch-datapath-dkms_*.deb \
+             python-openvswitch_*.deb openvswitch-pki_*.deb \
+             openvswitch-ipsec_*.deb
+
+   If the installation is successful, you should be able to see the
+   ovs-monitor-ipsec daemon is running in your system.
+
+Fedora
+~~~~~~
+
+1. Follow :doc:`/intro/install/fedora` to build RPM packages.
+
+2. Install the related packages::
+
+       $ dnf install python2-openvswitch libreswan \
+                     "kernel-devel-uname-r == $(uname -r)"
+       $ rpm -i openvswitch-*.rpm openvswitch-kmod-*.rpm \
+                openvswitch-openvswitch-ipsec-*.rpm
+
+3. Install firewall rules to allow ESP and IKE traffic::
+
+       $ iptables -A IN_FedoraServer_allow -p esp -j ACCEPT
+       $ iptables -A IN_FedoraServer_allow -p udp --dport 500 -j ACCEPT
+
+4. Run the openvswitch-ipsec service::
+
+       $ systemctl start openvswitch-ipsec.service
+
+   .. note::
+
+     The SELinux policies might prevent openvswitch-ipsec.service to access
+     certain resources. You can configure SELinux to remove such restrictions.
+
+Configuring IPsec tunnel
+------------------------
+
+Suppose you want to build IPsec tunnel between two hosts. Assume `host_1`'s
+external IP is 1.1.1.1, and `host_2`'s external IP is 2.2.2.2. Make sure
+`host_1` and `host_2` can ping each other via these external IPs.
+
+0. Set up some variables to make life easier.  On both hosts, set ``ip_1`` and
+   ``ip_2`` variables, e.g.::
+
+     $ ip_1=1.1.1.1
+     $ ip_2=2.2.2.2
+
+1. Set up OVS bridges in both hosts.
+
+   In `host_1`::
+
+       $ ovs-vsctl add-br br-ipsec
+       $ ip addr add 192.0.0.1/24 dev br-ipsec
+       $ ip link set br-ipsec up
+
+   In `host_2`::
+
+       $ ovs-vsctl add-br br-ipsec
+       $ ip addr add 192.0.0.2/24 dev br-ipsec
+       $ ip link set br-ipsec up
+
+2. Set up IPsec tunnel.
+
+   There are three authentication methods. You can choose one to set up your
+   IPsec tunnel.
+
+   a) Using pre-shared key:
+
+      In `host_1`::
+
+          $ ovs-vsctl add-port br-ipsec tun -- \
+                      set interface tun type=gre \
+                                    options:remote_ip=$ip_2 \
+                                    options:psk=swordfish
+
+      In `host_2`::
+
+          $ ovs-vsctl add-port br-ipsec tun -- \
+                      set interface tun type=gre \
+                                    options:remote_ip=$ip_1 \
+                                    options:psk=swordfish
+
+      .. note::
+
+        Pre-shared key (PSK) based authentication is easy to set up but less
+        secure compared with other authentication methods. You should use it
+        cautiously in production systems.
+
+   b) Using self-signed certificate:
+
+      Generate self-signed certificate in both `host_1` and `host_2`. Then copy
+      the certificate of `host_1` to `host_2` and the certificate of `host_2`
+      to `host_1`.
+
+      In `host_1`::
+
+          $ ovs-pki req -u host_1
+          $ ovs-pki self-sign host_1
+          $ scp host_1-cert.pem $ip_2:/etc/keys/host_1-cert.pem
+
+      In `host_2`::
+
+          $ ovs-pki req -u host_2
+          $ ovs-pki self-sign host_2
+          $ scp host_2-cert.pem $ip_1:/etc/keys/host_2-cert.pem
+
+      .. note::
+
+        If you use StrongSwan as IKE daemon, please move the host certificates
+        to /etc/ipsec.d/certs/ and private key to /etc/ipsec.d/private/ so that
+        StrongSwan has permission to access those files.
+
+      Configure IPsec tunnel to use self-signed certificates.
+
+      In `host_1`::
+
+          $ ovs-vsctl set Open_vSwitch . \
+                     other_config:certificate=/etc/keys/host_1-cert.pem \
+                     other_config:private_key=/etc/keys/host_1-privkey.pem
+          $ ovs-vsctl add-port br-ipsec tun -- \
+                      set interface tun type=gre \
+                             options:remote_ip=$ip_2 \
+                             options:remote_cert=/etc/keys/host_2-cert.pem
+
+      In `host_2`::
+
+          $ ovs-vsctl set Open_vSwitch . \
+                     other_config:certificate=/etc/keys/host_2-cert.pem \
+                     other_config:private_key=/etc/keys/host_2-privkey.pem
+          $ ovs-vsctl add-port br-ipsec tun -- \
+                      set interface tun type=gre \
+                             options:remote_ip=$ip_1 \
+                             options:remote_cert=/etc/keys/host_1-cert.pem
+
+      .. note::
+
+        The confidentiality of the private key is very critical.  Don't copy it
+        to places where it might be compromised.  (The certificate need not be
+        kept confidential.)
+
+   c) Using CA-signed certificate:
+
+      First you need to establish a public key infrastructure (PKI). Suppose
+      you choose `host_1` to host PKI.
+
+      In `host_1`::
+
+          $ ovs-pki init
+
+      Generate certificate requests and copy the certificate request of
+      `host_2` to `host_1`.
+
+      In `host_1`::
+
+          $ ovs-pki req -u host_1
+
+      In `host_2`::
+
+          $ ovs-pki req -u host_2
+          $ scp host_2-req.pem $ip_1:/etc/keys/host_2-req.pem
+
+      Sign the certificate requests with the CA key. Copy `host_2`'s signed
+      certificate and the CA certificate to `host_2`.
+
+      In `host_1`::
+
+          $ ovs-pki sign host_1 switch
+          $ ovs-pki sign host_2 switch
+          $ scp host_2-cert.pem $ip_2:/etc/keys/host_2-cert.pem
+          $ scp /var/lib/openvswitch/pki/switchca/cacert.pem \
+                    $ip_2:/etc/keys/cacert.pem
+
+      .. note::
+
+        If you use StrongSwan as IKE daemon, please move the host certificates
+        to /etc/ipsec.d/certs/, CA certificate to /etc/ipsec.d/cacerts/, and
+        private key to /etc/ipsec.d/private/ so that StrongSwan has permission
+        to access those files.
+
+      Configure IPsec tunnel to use CA-signed certificate.
+
+      In `host_1`::
+
+          $ ovs-vsctl set Open_vSwitch . \
+                  other_config:certificate=/etc/keys/host_1-cert.pem \
+                  other_config:private_key=/etc/keys/host_1-privkey.pem \
+                  other_config:ca_cert=/etc/keys/cacert.pem
+          $ ovs-vsctl add-port br-ipsec tun -- \
+                   set interface tun type=gre \
+                                 options:remote_ip=$ip_2 \
+                                 options:remote_name=host_2
+
+      In `host_2`::
+
+          $ ovs-vsctl set Open_vSwitch . \
+                  other_config:certificate=/etc/keys/host_2-cert.pem \
+                  other_config:private_key=/etc/keys/host_2-privkey.pem \
+                  other_config:ca_cert=/etc/keys/cacert.pem
+          $ ovs-vsctl add-port br-ipsec tun -- \
+                   set interface tun type=gre \
+                                 options:remote_ip=$ip_1 \
+                                 options:remote_name=host_1
+
+      .. note::
+
+        remote_name is the common name (CN) of the signed-certificate.  It must
+        match the name given as the argument to the ``ovs-pki sign command``.
+        It ensures that only certificate with the expected CN can be
+        authenticated; otherwise, any certificate signed by the CA would be
+        accepted.
+
+3. Test IPsec tunnel.
+
+   Now you should have an IPsec GRE tunnel running between two hosts. To verify
+   it, in `host_1`::
+
+       $ ping 192.0.0.2 &
+       $ tcpdump -ni any net $ip_2
+
+   You should be able to see that ESP packets are being sent from `host_1` to
+   `host_2`.
+
+Troubleshooting
+---------------
+
+The ``ovs-monitor-ipsec`` daemon manages and monitors the IPsec tunnel state.
+Use the following ``ovs-appctl`` command to view ``ovs-monitor-ipsec`` internal
+representation of tunnel configuration::
+
+    $ ovs-appctl -t ovs-monitor-ipsec tunnels/show
+
+If there is misconfiguration, then ``ovs-appctl`` should indicate why.
+For example::
+
+   Interface name: gre0 v5 (CONFIGURED) <--- Should be set to CONFIGURED.
+                                             Otherwise, error message will
+                                             be provided
+   Tunnel Type:    gre
+   Remote IP:      2.2.2.2
+   SKB mark:       None
+   Local cert:     None
+   Local name:     None
+   Local key:      None
+   Remote cert:    None
+   Remote name:    None
+   CA cert:        None
+   PSK:            swordfish
+   Ofport:         1          <--- Whether ovs-vswitchd has assigned Ofport
+                                   number to this Tunnel Port
+   CFM state:      Up         <--- Whether CFM declared this tunnel healthy
+   Kernel policies installed:
+   ...                          <--- IPsec policies for this OVS tunnel in
+                                     Linux Kernel installed by strongSwan
+   Kernel security associations installed:
+   ...                          <--- IPsec security associations for this OVS
+                                     tunnel in Linux Kernel installed by
+                                     strongswan
+   IPsec connections that are active:
+   ...                          <--- IPsec "connections" for this OVS
+                                     tunnel
+
+If you don't see any active connections, try to run the following command to
+refresh the ``ovs-monitor-ipsec`` daemon::
+
+    $ ovs-appctl -t ovs-monitor-ipsec refresh
+
+You can also check the logs of the ``ovs-monitor-ipsec`` daemon and the IKE
+daemon to locate issues. ``ovs-monitor-ipsec`` outputs log messages to
+/var/log/openvswitch/ovs-monitor-ipsec.log.
+
+Bug Reporting
+-------------
+
+If you think you may have found a bug with security implications, like
+
+1. IPsec protected tunnel accepted packets that came unencrypted; OR
+2. IPsec protected tunnel allowed packets to leave unencrypted;
+
+Then report such bugs according to :doc:`/internals/security`.
+
+If bug does not have security implications, then report it according to
+instructions in :doc:`/internals/bugs`.
+
+If you have suggestions to improve this tutorial, please send a email to
+ovs-discuss@openvswitch.org.