netns: Add documentation and update NEWS.

Create a document to describe the how it works and known
limitations and update the NEWS accordingly.

Signed-off-by: Flavio Leitner <fbl@sysclose.org>
Signed-off-by: Ben Pfaff <blp@ovn.org>

4 files changed, 71 insertions, 0 deletions

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 93cf3a11b..c05a2313a 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -40,6 +40,7 @@ DOC_SOURCE = \
 	Documentation/topics/high-availability.rst \
 	Documentation/topics/integration.rst \
 	Documentation/topics/language-bindings.rst \
+	Documentation/topics/networking-namespaces.rst \
 	Documentation/topics/openflow.rst \
 	Documentation/topics/ovn-news-2.8.rst \
 	Documentation/topics/ovsdb-replication.rst \
diff --git a/Documentation/topics/index.rst b/Documentation/topics/index.rst
index 13b6d8abb..fa7f0a2fb 100644
--- a/Documentation/topics/index.rst
+++ b/Documentation/topics/index.rst
@@ -42,6 +42,7 @@ OVS
    porting
    openflow
    bonding
+   networking-namespaces
    ovsdb-replication
    dpdk/index
    windows
diff --git a/Documentation/topics/networking-namespaces.rst b/Documentation/topics/networking-namespaces.rst
new file mode 100644
index 000000000..5c265cd02
--- /dev/null
+++ b/Documentation/topics/networking-namespaces.rst
@@ -0,0 +1,68 @@
+..
+      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.
+
+===========================================
+Open vSwitch Networking Namespaces on Linux
+===========================================
+
+The Open vSwitch has networking namespaces basic support on Linux. That allows
+ovs-vswitchd daemon to continue tracking status and statistics after moving a
+port to another networking namespace.
+
+
+How It Works
+------------
+
+The daemon ovs-vswitchd runs on what is called parent network namespace. It
+listens to netlink event messages from all networking namespaces (netns)
+with an identifier on the parent. Each netlink message contains the network
+namespace identifier (netnsid) as ancillary data which is used to match the
+event to the corresponding port.
+
+The ovs-vswitchd uses an extended openvswitch kernel API [1]_ to get the
+current netnsid (stored in struct netdev_linux) and statistics from a specific
+port.  The netnsid remains cached in userspace until a changing event is
+received, for example, when the port is moved to another network namespace.
+
+Using another extended kernel API [2]_, the daemon gets port's information
+such as flags, MTU, MAC address and ifindex from a port already in another
+namespace.
+
+The upstream kernel 4.15 includes the necessary changes for the basic support.
+In case of the running kernel doesn't provide the APIs, the daemon falls back
+to the previous behavior.
+
+.. [1] Request cmd: OVS_VPORT_CMD_GET, attribute: OVS_VPORT_ATTR_NETNSID
+.. [2] Request cmd: RTM_GETLINK passing IFLA_IF_NETNSID attribute.
+
+
+Limitations
+-----------
+
+Currently it is only possible to retrieve the information listed in the
+above section.  Most of other operations, for example querying MII or
+setting MTU, lacks the proper API in the kernel, so they remain unsupported.
+
+In most use cases that needs to move ports to another networking namespaces
+should use veth pairs instead because it offers a cleaner and more robust
+solution with no noticeable performance penalty.
diff --git a/NEWS b/NEWS
index 757d648a1..83fbe6038 100644
--- a/NEWS
+++ b/NEWS
@@ -6,6 +6,7 @@ Post-v2.9.0
        "table#".  These are not helpful names for the purpose of accepting
        and displaying table names, so now tables by default have no names.
      * The "null" interface type, deprecated since 2013, has been removed.
+     * Add minimum network namespace support for Linux.
    - ovs-ofctl:
      * ovs-ofctl now accepts and display table names in place of numbers.  By
        default it always accepts names and in interactive use it displays them;