Re: [ovs-dev] [PATCH v4 9/9] Documentation: OVN RBAC and IPsec tutorial

2018-08-02 Thread Ben Pfaff
On Tue, Jul 31, 2018 at 02:08:54PM -0700, Qiuyu Xiao wrote:
> This patch adds step-by-step guide for configuring OVN Role-Based Access
> Control and IPsec.
> 
> Signed-off-by: Qiuyu Xiao 

Here are my suggestions for this patch (really for this one, this time).

I'll look forward to v5 of this series!

Thanks,

Ben.

--8<--cut here-->8--

diff --git a/Documentation/index.rst b/Documentation/index.rst
index bab5ba1f1a98..46261235c732 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/ovn-ipsec.rst 
b/Documentation/tutorials/ovn-ipsec.rst
index 76269c46a784..5a8701905fa1 100644
--- a/Documentation/tutorials/ovn-ipsec.rst
+++ b/Documentation/tutorials/ovn-ipsec.rst
@@ -43,15 +43,17 @@ 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
+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.  Please generate compatible certificates if you use
-   another PKI tool to manage certificates.
+   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
 -
@@ -67,27 +69,27 @@ each chassis. Use the following command::
 Enabling OVN IPsec
 --
 
-To enable OVN IPsec, set `ipsec` column in `NB_Global` table of the northbound
-database to be true::
+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 be false::
+To disable it, set ``ipsec`` column in ``NB_Global`` table of the northbound
+database to 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::
+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 misconfiguration then ovs-appctl should indicate why.
+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.
@@ -119,13 +121,13 @@ For example::
  tunnel
 
 If you don't see any active connections, try to run the following command to
-refresh the ovs-monitor-ipsec daemon::
+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.
+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
 -
diff --git a/Documentation/tutorials/ovn-rbac.rst 
b/Documentation/tutorials/ovn-rbac.rst
index ff93ba54bdc6..ec163e2df369 100644
--- a/Documentation/tutorials/ovn-rbac.rst
+++ b/Documentation/tutorials/ovn-rbac.rst
@@ -81,7 +81,7 @@ address `machine_3-ip`. `machine_3` also hosts public key 
infrastructure (PKI).
 
.. note::
 
- chassis_1 must be the same string as the external_ids:system-id in the
+ 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.
 
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev


Re: [ovs-dev] [PATCH v4 9/9] Documentation: OVN RBAC and IPsec tutorial

2018-08-02 Thread Ben Pfaff
Thanks for the comments.  Can you integrate my suggestions and your
comments for v5?

Thanks,

Ben.

On Wed, Aug 01, 2018 at 05:28:02PM -0700, Qiuyu Xiao wrote:
> Thanks Ben! I made a few comments below. Other than that, all looks pretty 
> good!
> 
> -Qiuyu
> 
> On Wed, Aug 1, 2018 at 10:03 AM, Ben Pfaff  wrote:
> > On Tue, Jul 31, 2018 at 02:08:54PM -0700, Qiuyu Xiao wrote:
> >> This patch adds step-by-step guide for configuring OVN Role-Based Access
> >> Control and IPsec.
> >>
> >> Signed-off-by: Qiuyu Xiao 
> >
> > You wrote a lot of documentation, and it's really good!  Thank you.
> >
> > I spent some time working to make it even better.  I'm appending an
> > incremental that I'd suggest folding in.  Does it make sense to you?
> >
> > Thanks,
> >
> > Ben.
> >
> > --8<--cut here-->8--
> >
> > diff --git a/Documentation/howto/ipsec.rst b/Documentation/howto/ipsec.rst
> > index 17dead5010cf..32e55b5acd0d 100644
> > --- a/Documentation/howto/ipsec.rst
> > +++ b/Documentation/howto/ipsec.rst
> > @@ -48,7 +48,10 @@ OVS IPsec aims to provide a simple interface for user to 
> > add encryption on OVS
> >  tunnels. It supports GRE, GENEVE, VXLAN, and STT tunnel. The IPsec
> >  configuration is done by setting options of the tunnel interface and
> >  other_config of Open_vSwitch. You can choose different authentication 
> > methods
> > -and fowarding modes based on your system requirement.
> > +and forwarding modes based on your requirements.
> > +
> > +OVS does not currently provide any support for IPsec encryption for 
> > traffic not
> > +encapsulated in a tunnel.
> >
> >  Configuration
> >  -
> > @@ -59,7 +62,7 @@ Authentication Methods
> >  Hosts of the IPsec tunnel need to authenticate each other to build a secure
> >  channel. There are three authentication methods:
> >
> > -1) You can use pre-shared key (PSK) to do authentication. In both hosts, 
> > set
> > +1) You can use a pre-shared key (PSK) to do authentication. In both hosts, 
> > set
> > the same PSK value. This PSK is like your password. You should never 
> > reveal
> > it to untrusted parties. This method is easier to use but less secure 
> > than
> > the certificate-based methods::
> > @@ -72,9 +75,9 @@ channel. There are three authentication methods:
> >
> > .. note::
> >
> > -  The local_ip field is required for the IPsec tunnel.
> > +  The ``local_ip`` field is required for the IPsec tunnel.
> >
> > -2) You can use self-signed certificate to do authentication. In each host,
> > +2) You can use a self-signed certificate to do authentication. In each 
> > host,
> > generate a certificate and the paired private key. Copy the certificate 
> > of
> > the remote host to the local host and configure the OVS as following::
> >
> > @@ -98,6 +101,10 @@ channel. There are three authentication methods:
> >follow the tutorial in :doc:`/tutorials/ipsec` and use ovs-pki(8) to
> >generate compatible certificate and key.
> >
> > +  (Before OVS version 2.10.90, ovs-pki(8) did not generate x.509 v3
> > +  certificates, so if your existing PKI was generated by an older 
> > version,
> > +  it is not suitable for this purpose.)
> > +
> >  3) You can also use CA-signed certificate to do authentication. First, you 
> > need
> > to create a CA certificate and sign each host certificate with the CA 
> > key
> > (please see :doc:`/tutorials/ipsec`). Copy the CA certificate to each
> > @@ -133,8 +140,8 @@ actually taking affect to encrypt packets. To offset 
> > the risk of unencrypted
> >  packets leaking out during this period, you can choose a more secure 
> > forwarding
> >  mode.  There are three forwarding modes:
> >
> > -1) The default mode allows unencrypted packets being sent out before IPsec
> > -   taking effect::
> > +1) The default mode allows unencrypted packets to be sent before IPsec
> > +   completes negotiation::
> >
> >   $ ovs-vsctl add-port br0 ipsec_gre0 -- \
> >set interface ipsec_gre0 type=gre \
> > @@ -146,7 +153,7 @@ mode.  There are three forwarding modes:
> > and/or if there is firewall that can drop the plain packets that
> > occasionally leak the tunnel unencrypted on OVSDB (re)configuration 
> > events.
> >
> > -2) The ipsec_skb_mark mode filters unencrypted packets by using skb mark of
> > +2) The ipsec_skb_mark mode drops unencrypted packets by using skb_mark of
> > tunnel packets::
> >
> >   $ ovs-vsctl set Open_vSwitch . other_config:ipsec_skb_mark=0/1
> > @@ -156,15 +163,15 @@ mode.  There are three forwarding modes:
> >  options:remote_ip=2.2.2.2 \
> >  options:psk=swordfish
> >
> > -   OVS IPsec filters unencrypted packets which carry the same skb mark as
> > +   OVS IPsec drops unencrypted packets which carry the same skb_mark as
> > `ipsec_skb_mark`. By setting the ipsec_skb_mark as 

Re: [ovs-dev] [PATCH v4 9/9] Documentation: OVN RBAC and IPsec tutorial

2018-08-01 Thread Qiuyu Xiao
Thanks Ben! I made a few comments below. Other than that, all looks pretty good!

-Qiuyu

On Wed, Aug 1, 2018 at 10:03 AM, Ben Pfaff  wrote:
> On Tue, Jul 31, 2018 at 02:08:54PM -0700, Qiuyu Xiao wrote:
>> This patch adds step-by-step guide for configuring OVN Role-Based Access
>> Control and IPsec.
>>
>> Signed-off-by: Qiuyu Xiao 
>
> You wrote a lot of documentation, and it's really good!  Thank you.
>
> I spent some time working to make it even better.  I'm appending an
> incremental that I'd suggest folding in.  Does it make sense to you?
>
> Thanks,
>
> Ben.
>
> --8<--cut here-->8--
>
> diff --git a/Documentation/howto/ipsec.rst b/Documentation/howto/ipsec.rst
> index 17dead5010cf..32e55b5acd0d 100644
> --- a/Documentation/howto/ipsec.rst
> +++ b/Documentation/howto/ipsec.rst
> @@ -48,7 +48,10 @@ OVS IPsec aims to provide a simple interface for user to 
> add encryption on OVS
>  tunnels. It supports GRE, GENEVE, VXLAN, and STT tunnel. The IPsec
>  configuration is done by setting options of the tunnel interface and
>  other_config of Open_vSwitch. You can choose different authentication methods
> -and fowarding modes based on your system requirement.
> +and forwarding modes based on your requirements.
> +
> +OVS does not currently provide any support for IPsec encryption for traffic 
> not
> +encapsulated in a tunnel.
>
>  Configuration
>  -
> @@ -59,7 +62,7 @@ Authentication Methods
>  Hosts of the IPsec tunnel need to authenticate each other to build a secure
>  channel. There are three authentication methods:
>
> -1) You can use pre-shared key (PSK) to do authentication. In both hosts, set
> +1) You can use a pre-shared key (PSK) to do authentication. In both hosts, 
> set
> the same PSK value. This PSK is like your password. You should never 
> reveal
> it to untrusted parties. This method is easier to use but less secure than
> the certificate-based methods::
> @@ -72,9 +75,9 @@ channel. There are three authentication methods:
>
> .. note::
>
> -  The local_ip field is required for the IPsec tunnel.
> +  The ``local_ip`` field is required for the IPsec tunnel.
>
> -2) You can use self-signed certificate to do authentication. In each host,
> +2) You can use a self-signed certificate to do authentication. In each host,
> generate a certificate and the paired private key. Copy the certificate of
> the remote host to the local host and configure the OVS as following::
>
> @@ -98,6 +101,10 @@ channel. There are three authentication methods:
>follow the tutorial in :doc:`/tutorials/ipsec` and use ovs-pki(8) to
>generate compatible certificate and key.
>
> +  (Before OVS version 2.10.90, ovs-pki(8) did not generate x.509 v3
> +  certificates, so if your existing PKI was generated by an older 
> version,
> +  it is not suitable for this purpose.)
> +
>  3) You can also use CA-signed certificate to do authentication. First, you 
> need
> to create a CA certificate and sign each host certificate with the CA key
> (please see :doc:`/tutorials/ipsec`). Copy the CA certificate to each
> @@ -133,8 +140,8 @@ actually taking affect to encrypt packets. To offset the 
> risk of unencrypted
>  packets leaking out during this period, you can choose a more secure 
> forwarding
>  mode.  There are three forwarding modes:
>
> -1) The default mode allows unencrypted packets being sent out before IPsec
> -   taking effect::
> +1) The default mode allows unencrypted packets to be sent before IPsec
> +   completes negotiation::
>
>   $ ovs-vsctl add-port br0 ipsec_gre0 -- \
>set interface ipsec_gre0 type=gre \
> @@ -146,7 +153,7 @@ mode.  There are three forwarding modes:
> and/or if there is firewall that can drop the plain packets that
> occasionally leak the tunnel unencrypted on OVSDB (re)configuration 
> events.
>
> -2) The ipsec_skb_mark mode filters unencrypted packets by using skb mark of
> +2) The ipsec_skb_mark mode drops unencrypted packets by using skb_mark of
> tunnel packets::
>
>   $ ovs-vsctl set Open_vSwitch . other_config:ipsec_skb_mark=0/1
> @@ -156,15 +163,15 @@ mode.  There are three forwarding modes:
>  options:remote_ip=2.2.2.2 \
>  options:psk=swordfish
>
> -   OVS IPsec filters unencrypted packets which carry the same skb mark as
> +   OVS IPsec drops unencrypted packets which carry the same skb_mark as
> `ipsec_skb_mark`. By setting the ipsec_skb_mark as 0/1, OVS IPsec prevents
> -   all unencrypted tunnel packets leaving the host since the default skb mark
> +   all unencrypted tunnel packets leaving the host since the default skb_mark
> value for tunnel packets are 0. This affects all OVS tunnels including 
> those
> without IPsec being set up. You can install OpenFlow rules to whitelist
> -   those non-IPsec tunnels by setting the skb mark of 

Re: [ovs-dev] [PATCH v4 9/9] Documentation: OVN RBAC and IPsec tutorial

2018-08-01 Thread Ben Pfaff
On Wed, Aug 01, 2018 at 10:03:38AM -0700, Ben Pfaff wrote:
> On Tue, Jul 31, 2018 at 02:08:54PM -0700, Qiuyu Xiao wrote:
> > This patch adds step-by-step guide for configuring OVN Role-Based Access
> > Control and IPsec.
> > 
> > Signed-off-by: Qiuyu Xiao 
> 
> You wrote a lot of documentation, and it's really good!  Thank you.
> 
> I spent some time working to make it even better.  I'm appending an
> incremental that I'd suggest folding in.  Does it make sense to you?

Oops, this was supposed to be for the patch "Documentation: IPsec tunnel
tutorial and documentation."
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev


Re: [ovs-dev] [PATCH v4 9/9] Documentation: OVN RBAC and IPsec tutorial

2018-08-01 Thread Ben Pfaff
On Tue, Jul 31, 2018 at 02:08:54PM -0700, Qiuyu Xiao wrote:
> This patch adds step-by-step guide for configuring OVN Role-Based Access
> Control and IPsec.
> 
> Signed-off-by: Qiuyu Xiao 

You wrote a lot of documentation, and it's really good!  Thank you.

I spent some time working to make it even better.  I'm appending an
incremental that I'd suggest folding in.  Does it make sense to you?

Thanks,

Ben.

--8<--cut here-->8--

diff --git a/Documentation/howto/ipsec.rst b/Documentation/howto/ipsec.rst
index 17dead5010cf..32e55b5acd0d 100644
--- a/Documentation/howto/ipsec.rst
+++ b/Documentation/howto/ipsec.rst
@@ -48,7 +48,10 @@ OVS IPsec aims to provide a simple interface for user to add 
encryption on OVS
 tunnels. It supports GRE, GENEVE, VXLAN, and STT tunnel. The IPsec
 configuration is done by setting options of the tunnel interface and
 other_config of Open_vSwitch. You can choose different authentication methods
-and fowarding modes based on your system requirement.
+and forwarding modes based on your requirements.
+
+OVS does not currently provide any support for IPsec encryption for traffic not
+encapsulated in a tunnel.
 
 Configuration
 -
@@ -59,7 +62,7 @@ Authentication Methods
 Hosts of the IPsec tunnel need to authenticate each other to build a secure
 channel. There are three authentication methods:
 
-1) You can use pre-shared key (PSK) to do authentication. In both hosts, set
+1) You can use a pre-shared key (PSK) to do authentication. In both hosts, set
the same PSK value. This PSK is like your password. You should never reveal
it to untrusted parties. This method is easier to use but less secure than
the certificate-based methods::
@@ -72,9 +75,9 @@ channel. There are three authentication methods:
 
.. note::
 
-  The local_ip field is required for the IPsec tunnel.
+  The ``local_ip`` field is required for the IPsec tunnel.
 
-2) You can use self-signed certificate to do authentication. In each host,
+2) You can use a self-signed certificate to do authentication. In each host,
generate a certificate and the paired private key. Copy the certificate of
the remote host to the local host and configure the OVS as following::
 
@@ -98,6 +101,10 @@ channel. There are three authentication methods:
   follow the tutorial in :doc:`/tutorials/ipsec` and use ovs-pki(8) to
   generate compatible certificate and key.
 
+  (Before OVS version 2.10.90, ovs-pki(8) did not generate x.509 v3
+  certificates, so if your existing PKI was generated by an older version,
+  it is not suitable for this purpose.)
+
 3) You can also use CA-signed certificate to do authentication. First, you need
to create a CA certificate and sign each host certificate with the CA key
(please see :doc:`/tutorials/ipsec`). Copy the CA certificate to each
@@ -133,8 +140,8 @@ actually taking affect to encrypt packets. To offset the 
risk of unencrypted
 packets leaking out during this period, you can choose a more secure forwarding
 mode.  There are three forwarding modes:
 
-1) The default mode allows unencrypted packets being sent out before IPsec
-   taking effect::
+1) The default mode allows unencrypted packets to be sent before IPsec
+   completes negotiation::
 
  $ ovs-vsctl add-port br0 ipsec_gre0 -- \
   set interface ipsec_gre0 type=gre \
@@ -146,7 +153,7 @@ mode.  There are three forwarding modes:
and/or if there is firewall that can drop the plain packets that
occasionally leak the tunnel unencrypted on OVSDB (re)configuration events.
 
-2) The ipsec_skb_mark mode filters unencrypted packets by using skb mark of
+2) The ipsec_skb_mark mode drops unencrypted packets by using skb_mark of
tunnel packets::
 
  $ ovs-vsctl set Open_vSwitch . other_config:ipsec_skb_mark=0/1
@@ -156,15 +163,15 @@ mode.  There are three forwarding modes:
 options:remote_ip=2.2.2.2 \
 options:psk=swordfish
 
-   OVS IPsec filters unencrypted packets which carry the same skb mark as
+   OVS IPsec drops unencrypted packets which carry the same skb_mark as
`ipsec_skb_mark`. By setting the ipsec_skb_mark as 0/1, OVS IPsec prevents
-   all unencrypted tunnel packets leaving the host since the default skb mark
+   all unencrypted tunnel packets leaving the host since the default skb_mark
value for tunnel packets are 0. This affects all OVS tunnels including those
without IPsec being set up. You can install OpenFlow rules to whitelist
-   those non-IPsec tunnels by setting the skb mark of the tunnel traffic as
+   those non-IPsec tunnels by setting the skb_mark of the tunnel traffic as
non-zero value.
 
-3) Setting `ipsec_skb_mark` as 1/1 only filters tunnel packets with skb mark
+3) Setting `ipsec_skb_mark` as 1/1 only drops tunnel packets with skb_mark
value being 1::
 
  $ ovs-vsctl set 

[ovs-dev] [PATCH v4 9/9] Documentation: OVN RBAC and IPsec tutorial

2018-07-31 Thread Qiuyu Xiao
This patch adds step-by-step guide for configuring OVN Role-Based Access
Control and IPsec.

Signed-off-by: Qiuyu Xiao 
---
 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 0..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