Documentation: OVN RBAC and IPsec tutorial

This patch adds step-by-step guide for configuring OVN Role-Based Access
Control and IPsec.

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

3 files changed, 282 insertions, 0 deletions

diff --git a/Documentation/tutorials/index.rst b/Documentation/tutorials/index.rst
index b481090a0..35340ee56 100644
--- a/Documentation/tutorials/index.rst
+++ b/Documentation/tutorials/index.rst
@@ -44,4 +44,6 @@ vSwitch.
    ovs-advanced
    ovn-sandbox
    ovn-openstack
+   ovn-rbac
+   ovn-ipsec
    ovs-conntrack
diff --git a/Documentation/tutorials/ovn-ipsec.rst b/Documentation/tutorials/ovn-ipsec.rst
new file mode 100644
index 000000000..feb695ea3
--- /dev/null
+++ b/Documentation/tutorials/ovn-ipsec.rst
@@ -0,0 +1,146 @@
+..
+      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.
+
+==================
+OVN IPsec Tutorial
+==================
+
+This document provides a step-by-step guide for encrypting tunnel traffic with
+IPsec in Open Virtual Network (OVN). OVN tunnel traffic is transported by
+physical routers and switches. These physical devices could be untrusted
+(devices in public network) or might be compromised.  Enabling IPsec encryption
+for the tunnel traffic can prevent the traffic data from being monitored and
+manipulated. More details about the OVN IPsec design can be found in
+``ovn-architecture``\(7) manpage.
+
+This document assumes OVN is installed in your system and runs normally. Also,
+you need to install OVS IPsec packages in each chassis (refer to
+:ref:`install-ovs-ipsec`).
+
+Generating Certificates and Keys
+--------------------------------
+
+OVN chassis uses CA-signed certificate to authenticate peer chassis for
+building IPsec tunnel. If you have enabled Role-Based Access Control (RBAC) in
+OVN, you can use the RBAC SSL certificates and keys to set up OVN IPsec. Or you
+can generate separate certificates and keys with ``ovs-pki`` (refer to
+:ref:`gen-certs-keys`).
+
+.. note::
+
+   OVN IPsec requires x.509 version 3 certificate with the subjectAltName DNS
+   field setting the same string as the common name (CN) field. CN should be
+   set as the chassis name.  ``ovs-pki`` in Open vSwitch 2.10.90 and later
+   generates such certificates.  Please generate compatible certificates if you
+   use another PKI tool, or an older version of ``ovs-pki``, to manage
+   certificates.
+
+Configuring OVN IPsec
+---------------------
+
+You need to install the CA certificate, chassis certificate and private key in
+each chassis. Use the following command::
+
+    $ ovs-vsctl set Open_vSwitch . \
+            other_config:certificate=/path/to/chassis-cert.pem \
+            other_config:private_key=/path/to/chassis-privkey.pem \
+            other_config:ca_cert=/path/to/cacert.pem
+
+Enabling OVN IPsec
+------------------
+
+To enable OVN IPsec, set ``ipsec`` column in ``NB_Global`` table of the
+northbound database to true::
+
+    $ ovn-nbctl set nb_global . ipsec=true
+
+With OVN IPsec enabled, all tunnel traffic in OVN will be encrypted with IPsec.
+To disable it, set ``ipsec`` column in ``NB_Global`` table of the northbound
+database to false::
+
+    $ ovn-nbctl set nb_global . ipsec=false
+
+Troubleshooting
+---------------
+
+The ``ovs-monitor-ipsec`` daemon in each chassis 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 a misconfiguration, then ``ovs-appctl`` should indicate why.
+For example::
+
+   Interface name: ovn-host_2-0 v1 (CONFIGURED) <--- Should be set
+                                             to CONFIGURED. Otherwise,
+                                             error message will be
+                                             provided
+   Tunnel Type:    geneve
+   Remote IP:      2.2.2.2
+   SKB mark:       None
+   Local cert:     /path/to/chassis-cert.pem
+   Local name:     host_1
+   Local key:      /path/to/chassis-privkey.pem
+   Remote cert:    None
+   Remote name:    host_2
+   CA cert:        /path/to/cacert.pem
+   PSK:            None
+   Ofport:         2          <--- Whether ovs-vswitchd has assigned Ofport
+                                   number to this Tunnel Port
+   CFM state:      Disabled     <--- 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.
diff --git a/Documentation/tutorials/ovn-rbac.rst b/Documentation/tutorials/ovn-rbac.rst
new file mode 100644
index 000000000..ec163e2df
--- /dev/null
+++ b/Documentation/tutorials/ovn-rbac.rst
@@ -0,0 +1,134 @@
+..
+      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.
+
+=============================================
+OVN Role-Based Access Control (RBAC) Tutorial
+=============================================
+
+This document provides a step-by-step guide for setting up role-based access
+control (RBAC) in OVN. In OVN, hypervisors (chassis) read and write the
+southbound database to do configuration. Without restricting hypervisor's
+access to the southbound database, a compromised hypervisor might disrupt the
+entire OVN deployment by corrupting the database. RBAC ensures that each
+hypervisor can only modify its own data and thus improves the security of OVN.
+More details about the RBAC design can be found in ``ovn-architecture``\(7)
+manpage.
+
+This document assumes OVN is installed in your system and runs normally.
+
+.. _gen-certs-keys:
+
+Generating Certificates and Keys
+--------------------------------
+
+In the OVN RBAC deployment, ovn-controller connects to the southbound database
+via SSL connection. The southbound database uses CA-signed certificate to
+authenticate ovn-controller.
+
+Suppose there are three machines in your deployment. `machine_1` runs
+`chassis_1` and has IP address `machine_1-ip`. `machine_2` runs `chassis_2` and
+has IP address `machine_2-ip`. `machine_3` hosts southbound database and has IP
+address `machine_3-ip`. `machine_3` also hosts public key infrastructure (PKI).
+
+1. Initiate PKI.
+
+   In `machine_3`::
+
+      $ ovs-pki init
+
+2. Generate southbound database's certificate request. Sign the certificate
+   request with the CA key.
+
+   In `machine_3`::
+
+      $ ovs-pki req -u sbdb
+      $ ovs-pki sign sbdb switch
+
+3. Generate chassis certificate requests. Copy the certificate requests to
+   `machine_3`.
+
+   In `machine_1`::
+
+      $ ovs-pki req -u chassis_1
+      $ scp chassis_1-req.pem \
+                    machine_3@machine_3-ip:/path/to/chassis_1-req.pem
+
+   In `machine_2`::
+
+      $ ovs-pki req -u chassis_2
+      $ scp chassis_2-req.pem \
+                    machine_3@machine_3-ip:/path/to/chassis_2-req.pem
+
+   .. note::
+
+     chassis_1 must be the same string as ``external_ids:system-id`` in the
+     Open_vSwitch table (the chassis name) of machine_1. Same applies for
+     chassis_2.
+
+4. Sign the chassis certificate requests with the CA key. Copy `chassis_1`'s
+   signed certificate and the CA certificate to `machine_1`. Copy `chassis_2`'s
+   signed certificate and the CA certificate to `machine_2`.
+
+   In `machine_3`::
+
+      $ ovs-pki sign chassis_1 switch
+      $ ovs-pki sign chassis_2 switch
+      $ scp chassis_1-cert.pem \
+                    machine_1@machine_1-ip:/path/to/chassis_1-cert.pem
+      $ scp /var/lib/openvswitch/pki/switchca/cacert.pem \
+                    machine_1@machine_1-ip:/path/to/cacert.pem
+      $ scp chassis_2-cert.pem \
+                    machine_2@machine_2-ip:/path/to/chassis_2-cert.pem
+      $ scp /var/lib/openvswitch/pki/switchca/cacert.pem \
+                    machine_2@machine_2-ip:/path/to/cacert.pem
+
+Configuring RBAC
+----------------
+
+1. Set certificate, private key, and CA certificate for the southbound
+   database. Configure the southbound database to listen on SSL connection and
+   enforce role-based access control.
+
+   In `machine_3`::
+
+      $ ovn-sbctl set-ssl /path/to/sbdb-privkey.pem \
+                          /path/to/sbdb-cert.pem /path/to/cacert.pem
+      $ ovn-sbctl set-connection role=ovn-controller pssl:6642
+
+2. Set certificate, private key, and CA certificate for `chassis_1` and
+   `chassis_2`. Configure `chassis_1` and `chassis_2` to connect southbound
+   database via SSL.
+
+   In `machine_1`::
+
+      $ ovs-vsctl set-ssl /path/to/chassis_1-privkey.pem \
+                    /path/to/chassis_1-cert.pem /path/to/cacert.pem
+      $ ovs-vsctl set open_vswitch . \
+                    external_ids:ovn-remote=ssl:machine_3-ip:6642
+
+   In `machine_2`::
+
+      $ ovs-vsctl set-ssl /path/to/chassis_2-privkey.pem \
+                    /path/to/chassis_2-cert.pem /path/to/cacert.pem
+      $ ovs-vsctl set open_vswitch . \
+                    external_ids:ovn-remote=ssl:machine_3-ip:6642