ovn-nb: Add support for IP+MAC binding pairs in Port_Binding 'address'.

[cascardo/ovs.git] / ovn / ovn-nb.xml

diff --git a/ovn/ovn-nb.xml b/ovn/ovn-nb.xml
index 4ca7757..7f6f703 100644 (file)
--- a/ovn/ovn-nb.xml
+++ b/ovn/ovn-nb.xml
@@ -216,13 +216,57 @@
       ingress and egress traffic dropped.
     </column>
 
-    <column name="macs">
-      The logical port's own Ethernet address or addresses, each in the form
-      <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
-      Like a physical Ethernet NIC, a logical port ordinarily has a single
-      fixed Ethernet address.  The string <code>unknown</code> is also allowed
-      to indicate that the logical port has an unknown set of (additional)
-      source addresses.
+    <column name="addresses">
+      <p>
+        Addresses owned by the logical port.
+      </p>
+
+      <p>
+        Each element in the set must take one of the following forms:
+      </p>
+
+      <dl>
+        <dt><code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code></dt>
+        <dd>
+          <p>
+            An Ethernet address owned by the logical port.  Like a physical
+            Ethernet NIC, a logical port ordinarily has a single fixed Ethernet
+            address.
+          </p>
+
+          <p>
+            When a OVN logical switch processes a unicast Ethernet frame whose
+            destination MAC address is in a logical port's <ref
+            column="addresses"/> column, it delivers it only to that port, as
+            if a MAC learning process had learned that MAC address on the port.
+          </p>
+        </dd>
+
+        <dt><code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var> <var>a</var>.<var>b</var>.<var>c</var>.<var>d</var></code></dt>
+        <dd>
+          <p>
+            This form has all the effects of the previous form.  It also
+            indicates that the logical port owns the given IPv4 address.
+          </p>
+
+          <p>
+            The OVN logical switch uses this information to synthesize
+            responses to ARP requests without traversing the physical network.
+            The OVN logical router connected to the logical switch, if any,
+            uses this information to avoid issuing ARP requests for logical
+            switch ports.
+          </p>
+        </dd>
+
+        <dt><code>unknown</code></dt>
+        <dd>
+          This indicates that the logical port has an unknown set of Ethernet
+          addresses.  When an OVN logical switch processes a unicast Ethernet
+          frame whose destination MAC address is not in any logical port's <ref
+          column="addresses"/> column, it delivers it to the port (or ports)
+          whose <ref column="addresses"/> columns include <code>unknown</code>.
+        </dd>
+      </dl>
     </column>
 
     <column name="port_security">
@@ -373,9 +417,7 @@
     </column>
 
     <column name="ports">
-      The router's ports.  This is a set of weak references, so a <ref
-      table="Logical_Switch"/> must also refer to any given <ref
-      table="Logical_Router_Port"/> or it will automatically be deleted.
+      The router's ports.
     </column>
 
     <column name="default_gw">
@@ -395,14 +437,8 @@
     </p>
 
     <p>
-      A router port is always attached to a logical switch and to a logical
-      router.  The former attachment, which is enforced by the database schema,
-      can be identified by finding the <ref table="Logical_Switch"/> row whose
-      <ref column="router_port" table="Logical_Switch"/> column points to the
-      router port.  The latter attachment, which the database schema does not
-      enforce, can be identified by finding the <ref table="Logical_Router"/>
-      row whose <ref column="ports" table="Logical_Router"/> column includes
-      the router port.
+      Exactly one <ref table="Logical_Router"/> row must reference a given
+      logical router port.
     </p>
 
     <column name="name">
@@ -425,6 +461,41 @@
       The Ethernet address that belongs to this router port.
     </column>
 
+    <group title="Attachment">
+      <p>
+        A given router port serves one of two purposes:
+      </p>
+
+      <ul>
+        <li>
+          To attach a logical switch to a logical router.  A logical router
+          port of this type is referenced by exactly the <ref
+          column="router_port" table="Logical_Switch"/> column in exactly one
+          <ref table="Logical_Switch"/> row.  The <ref column="peer"/> column
+          is empty.
+        </li>
+
+        <li>
+          To connect one logical router to another.  This requires a pair of
+          logical router ports, each connected to a different router.  Each
+          router port in the pair specifies the other in its <ref
+          column="peer"/> column.  No <ref table="Logical_Switch"/> refers to
+          the router port.
+        </li>
+      </ul>
+
+      <column name="peer">
+        <p>
+          For a router port used to connect two logical routers, this
+          identifies the other router port in the pair.
+        </p>
+
+        <p>
+          For a router port attached to a logical switch, this column is empty.
+        </p>
+      </column>
+    </group>
+
     <group title="Common Columns">
       <column name="external_ids">
         See <em>External IDs</em> at the beginning of this document.