[ovs-dev,v5,6/6] Documentation: OVN RBAC and IPsec tutorial

Message ID 20180807164245.18639-7-qiuyu.xiao.qyx@gmail.com
State New
Headers show
Series
  • IPsec support for tunneling
Related show

Commit Message

Qiuyu Xiao Aug. 7, 2018, 4:42 p.m.
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>
---
 Documentation/automake.mk             |   2 +
 Documentation/index.rst               |   4 +-
 Documentation/tutorials/index.rst     |   2 +
 Documentation/tutorials/ovn-ipsec.rst | 147 ++++++++++++++++++++++++++
 Documentation/tutorials/ovn-rbac.rst  | 134 +++++++++++++++++++++++
 5 files changed, 288 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/tutorials/ovn-ipsec.rst
 create mode 100644 Documentation/tutorials/ovn-rbac.rst

Comments

Ansis Atteka Aug. 13, 2018, 4:37 p.m. | #1
On Tue, 7 Aug 2018 at 09:46, Qiuyu Xiao <qiuyu.xiao.qyx@gmail.com> wrote:
>
> 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>
> ---
>  Documentation/automake.mk             |   2 +
>  Documentation/index.rst               |   4 +-
>  Documentation/tutorials/index.rst     |   2 +
>  Documentation/tutorials/ovn-ipsec.rst | 147 ++++++++++++++++++++++++++
>  Documentation/tutorials/ovn-rbac.rst  | 134 +++++++++++++++++++++++
>  5 files changed, 288 insertions(+), 1 deletion(-)
>  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/index.rst b/Documentation/index.rst
> index bab5ba1f1..46261235c 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -66,7 +66,9 @@ vSwitch? Start here.
>    :doc:`tutorials/ovn-sandbox` |
>    :doc:`tutorials/ovn-openstack` |
>    :doc:`tutorials/ovs-conntrack` |
> -  :doc:`tutorials/ipsec`
> +  :doc:`tutorials/ipsec` |
> +  :doc:`tutorials/ovn-ipsec` |
> +  :doc:`tutorials/ovn-rbac`
>
>  Deeper Dive
>  -----------
> 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..db3d5bc43
> --- /dev/null
> +++ b/Documentation/tutorials/ovn-ipsec.rst
> @@ -0,0 +1,147 @@
> +..
> +      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
I think the version number should be 2.11.

> +   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
> +   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.  ``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.

The IPsec part Looks Good To Me.

While I don't have strong opinion, the RBAC part of this patch seems
to me independent from the IPsec patch series, no (execpt w.r.t to
certificates)?

> 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
> --
> 2.18.0
>
> _______________________________________________
> dev mailing list
> dev@openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Patch

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/index.rst b/Documentation/index.rst
index bab5ba1f1..46261235c 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -66,7 +66,9 @@  vSwitch? Start here.
   :doc:`tutorials/ovn-sandbox` |
   :doc:`tutorials/ovn-openstack` |
   :doc:`tutorials/ovs-conntrack` |
-  :doc:`tutorials/ipsec`
+  :doc:`tutorials/ipsec` |
+  :doc:`tutorials/ovn-ipsec` |
+  :doc:`tutorials/ovn-rbac`
 
 Deeper Dive
 -----------
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..db3d5bc43
--- /dev/null
+++ b/Documentation/tutorials/ovn-ipsec.rst
@@ -0,0 +1,147 @@ 
+..
+      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
+   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.  ``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