[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