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

Ansis Atteka ansisatteka at gmail.com
Mon Aug 13 16:37:55 UTC 2018


On Tue, 7 Aug 2018 at 09:46, Qiuyu Xiao <qiuyu.xiao.qyx at 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 at 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 at 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 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 ``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
>
> _______________________________________________
> dev mailing list
> dev at openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev


More information about the dev mailing list