Documentation: Add document describing RBAC

Role based access control is a relatively new addition to OVS/OVN, and
aside from the database documentation in ovn-sb(5), there is not much
explaining what RBAC is, how to use it, and the available roles. This
document remedies that situation.

It is hopeful that any new roles added will be added to this document in
the future.

Signed-off-by: Mark Michelson <mmichels@redhat.com>
Signed-off-by: Ben Pfaff <blp@ovn.org>

3 files changed, 103 insertions, 0 deletions

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 2a0c8e868..630fdf197 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -42,6 +42,7 @@ DOC_SOURCE = \
 	Documentation/topics/openflow.rst \
 	Documentation/topics/ovsdb-replication.rst \
 	Documentation/topics/porting.rst \
+	Documentation/topics/role-based-access-control.rst \
 	Documentation/topics/tracing.rst \
 	Documentation/topics/windows.rst \
 	Documentation/howto/index.rst \
diff --git a/Documentation/topics/index.rst b/Documentation/topics/index.rst
index f68334b4b..00d6b0b83 100644
--- a/Documentation/topics/index.rst
+++ b/Documentation/topics/index.rst
@@ -57,6 +57,7 @@ OVN
    :maxdepth: 2
 
    high-availability
+   role-based-access-control
 
 .. list-table::
 
diff --git a/Documentation/topics/role-based-access-control.rst b/Documentation/topics/role-based-access-control.rst
new file mode 100644
index 000000000..8f2a3a998
--- /dev/null
+++ b/Documentation/topics/role-based-access-control.rst
@@ -0,0 +1,101 @@
+..
+      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.
+
+=========================
+Role Based Access Control
+=========================
+
+Where SSL provides authentication when connecting to an OVS database, role
+based access control (RBAC) provides authorization to operations performed
+by clients connecting to an OVS database. RBAC allows for administrators to
+restrict the database operations a client may perform and thus enhance the
+security already provided by SSL.
+
+In theory, any OVS database could define RBAC roles and permissions, but at
+present only the OVN southbound database has the appropriate tables defined to
+facilitate RBAC.
+
+Mechanics
+---------
+RBAC is intended to supplement SSL. In order to enable RBAC, the connection to
+the database must use SSL. Some permissions in RBAC are granted based on the
+certificate common name (CN) of the connecting client.
+
+RBAC is controlled with two database tables, RBAC_Role and RBAC_Permission.
+The RBAC_Permission table contains records that describe a set of permissions
+for a given table in the database.
+
+The RBAC_Permission table contains the following columns:
+
+table
+  The table in the database for which permissions are being described.
+insert_delete
+  Describes whether insertion and deletion of records is allowed.
+update
+  A list of columns that are allowed to be updated.
+authorization
+  A list of column names. One of the listed columns must match the SSL
+  certificate CN in order for the attempted operation on the table to
+  succeed. If a key-value pair is provided, then the key is the column name,
+  and the value is the name of a key in that column. An empty string gives
+  permission to all clients to perform operations.
+
+The RBAC_Role table contains the following columns:
+
+name
+  The name of the role being defined
+permissions
+  A list of key-value pairs. The key is the name of a table in the database,
+  and the value is a UUID of a record in the RBAC_Permission table that
+  describes the permissions the role has for that table.
+
+.. note::
+
+   All tables not explicitly referenced in an RBAC_Role record are read-only
+
+In order to enable RBAC, specify the role name as an argument to the
+set-connection command for the database. As an example, to enable the
+"ovn-controller" role on the OVN southbound database, use the following
+command:
+
+::
+
+   $ ovn-sbctl set-connection role=ovn-controller ssl:192.168.0.1:6642
+
+Pre-defined Roles
+-----------------
+This section describes roles that have been defined internally by OVS/OVN.
+
+ovn-controller
+~~~~~~~~~~~~~~
+The ovn-controller role is specified in the OVN southbound database and is
+intended for use by hypervisors running the ovn-controller daemon.
+ovn-controller connects to the OVN southbound database mostly to read
+information, but there are a few cases where ovn-controller also needs to
+write. The ovn-controller role was designed to allow for ovn-controllers
+to write to the southbound database only in places where it makes sense to do
+so. This way, if an intruder were to take over a hypervisor running
+ovn-controller, it is more difficult to compromise the entire overlay network.
+
+It is strongly recommended to set the ovn-controller role for the OVN
+southbound database to enhance security.