[ovs-dev] [PATCH v4 9/9] Documentation: OVN RBAC and IPsec tutorial
Qiuyu Xiao
qiuyu.xiao.qyx at gmail.com
Tue Jul 31 21:08:54 UTC 2018
This patch adds step-by-step guide for configuring OVN Role-Based Access
Control and IPsec.
Signed-off-by: Qiuyu Xiao <qiuyu.xiao.qyx at gmail.com>
---
Documentation/automake.mk | 2 +
Documentation/tutorials/index.rst | 2 +
Documentation/tutorials/ovn-ipsec.rst | 144 ++++++++++++++++++++++++++
Documentation/tutorials/ovn-rbac.rst | 134 ++++++++++++++++++++++++
4 files changed, 282 insertions(+)
create mode 100644 Documentation/tutorials/ovn-ipsec.rst
create mode 100644 Documentation/tutorials/ovn-rbac.rst
diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 5401b9bad..082438e09 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -29,6 +29,8 @@ DOC_SOURCE = \
Documentation/tutorials/ovn-sandbox.rst \
Documentation/tutorials/ovs-conntrack.rst \
Documentation/tutorials/ipsec.rst \
+ Documentation/tutorials/ovn-ipsec.rst \
+ Documentation/tutorials/ovn-rbac.rst \
Documentation/topics/index.rst \
Documentation/topics/bonding.rst \
Documentation/topics/idl-compound-indexes.rst \
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..76269c46a
--- /dev/null
+++ b/Documentation/tutorials/ovn-ipsec.rst
@@ -0,0 +1,144 @@
+..
+ 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 seperate 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. Please generate compatible certificates if you use
+ another PKI tool 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 be 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 be false::
+
+ $ ovn-nbctl set nb_global . ipsec=false
+
+Troubleshooting
+---------------
+
+ovs-monitor-ipsec daemon in each chassis manages and monitors the IPsec tunnel
+state. Use the following ovs-apptcl command to get 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: ovn-host_2-0 v1 (CONFIGURED) <--- Should be set to CONFIGURED.
+ Otherwise, error message will
+ be provided
+ Tunnel Type: geneve
+ Local IP: 1.1.1.1
+ 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. The logs of the ovs-monitor-ipsec is in
+/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 at openvswitch.org.
diff --git a/Documentation/tutorials/ovn-rbac.rst b/Documentation/tutorials/ovn-rbac.rst
new file mode 100644
index 000000000..ff93ba54b
--- /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 at 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 at machine_3-ip:/path/to/chassis_2-req.pem
+
+ .. note::
+
+ chassis_1 must be the same string as the 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 at machine_1-ip:/path/to/chassis_1-cert.pem
+ $ scp /var/lib/openvswitch/pki/switchca/cacert.pem \
+ machine_1 at machine_1-ip:/path/to/cacert.pem
+ $ scp chassis_2-cert.pem \
+ machine_2 at machine_2-ip:/path/to/chassis_2-cert.pem
+ $ scp /var/lib/openvswitch/pki/switchca/cacert.pem \
+ machine_2 at 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
--
2.18.0
More information about the dev
mailing list