ovn/ovn-nb.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <database name="ovn-nb" title="OVN Northbound Database">
   3   <p>
   4     This database is the interface between OVN and the cloud management system
   5     (CMS), such as OpenStack, running above it.  The CMS produces almost all of
   6     the contents of the database.  The <code>ovs-nbd</code> program monitors
   7     the database contents, transforms it, and stores it into the <ref
   8     db="OVN"/> database.
   9   </p>
  10
  11   <p>
  12     We generally speak of ``the'' CMS, but one can imagine scenarios in
  13     which multiple CMSes manage different parts of an OVN deployment.
  14   </p>
  15
  16   <h2>External IDs</h2>
  17
  18   <p>
  19     Each of the tables in this database contains a special column, named
  20     <code>external_ids</code>.  This column has the same form and purpose each
  21     place it appears.
  22   </p>
  23
  24   <dl>
  25     <dt><code>external_ids</code>: map of string-string pairs</dt>
  26     <dd>
  27       Key-value pairs for use by the CMS.  The CMS might use certain pairs, for
  28       example, to identify entities in its own configuration that correspond to
  29       those in this database.
  30     </dd>
  31   </dl>
  32
  33   <table name="Logical_Switch" title="L2 logical switch">
  34     <p>
  35       Each row represents one L2 logical switch.  A given switch's ports are
  36       the <ref table="Logical_Port"/> rows whose <ref table="Logical_Port"
  37       column="lswitch"/> column points to its row.
  38     </p>
  39
  40     <column name="name">
  41       <p>
  42         A name for the logical switch.  This name has no special meaning or purpose
  43         other than to provide convenience for human interaction with the ovn-nb
  44         database.  There is no requirement for the name to be unique.  The
  45         logical switch's UUID should be used as the unique identifier.
  46       </p>
  47     </column>
  48
  49     <column name="router_port">
  50       <p>
  51         The router port to which this logical switch is connected, or empty if
  52         this logical switch is not connected to any router.  A switch may be
  53         connected to at most one logical router, but this is not a significant
  54         restriction because logical routers may be connected into arbitrary
  55         topologies.
  56       </p>
  57     </column>
  58
  59     <group title="Common Columns">
  60       <column name="external_ids">
  61         See <em>External IDs</em> at the beginning of this document.
  62       </column>
  63     </group>
  64   </table>
  65
  66   <table name="Logical_Port" title="L2 logical switch port">
  67     <p>
  68       A port within an L2 logical switch.
  69     </p>
  70
  71     <column name="lswitch">
  72       The logical switch to which the logical port is connected.
  73     </column>
  74
  75     <column name="name">
  76       The logical port name.  The name used here must match those used in the
  77       <ref key="iface-id" table="Interface" column="external_ids"
  78       db="Open_vSwitch"/> in the <ref db="Open_vSwitch"/> database's <ref
  79       table="Interface" db="Open_vSwitch"/> table, because hypervisors use <ref
  80       key="iface-id" table="Interface" column="external_ids"
  81       db="Open_vSwitch"/> as a lookup key for logical ports.
  82     </column>
  83
  84     <column name="up">
  85       This column is populated by <code>ovn-nbd</code>, rather than by the CMS
  86       plugin as is most of this database.  When a logical port is bound to a
  87       physical location in the OVN database <ref db="OVN" table="Bindings"/>
  88       table, <code>ovn-nbd</code> sets this column to <code>true</code>;
  89       otherwise, or if the port becomes unbound later, it sets it to
  90       <code>false</code>.  This allows the CMS to wait for a VM's networking to
  91       become active before it allows the VM to start.
  92     </column>
  93
  94     <column name="macs">
  95       The logical port's own Ethernet address or addresses, each in the form
  96       <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
  97       Like a physical Ethernet NIC, a logical port ordinarily has a single
  98       fixed Ethernet address.  The string <code>unknown</code> is also allowed
  99       to indicate that the logical port has an unknown set of (additional)
 100       source addresses.
 101     </column>
 102
 103     <column name="port_security">
 104       <p>
 105         A set of L2 (Ethernet) or L3 (IPv4 or IPv6) addresses or L2+L3 pairs
 106         from which the logical port is allowed to send packets and to which it
 107         is allowed to receive packets.  If this column is empty, all addresses
 108         are permitted.
 109       </p>
 110
 111       <p>
 112         Exact syntax is TBD.  One could simply use comma- or space-separated L2
 113         and L3 addresses in each set member, or replace this by a subset of the
 114         general-purpose expression language used for the <ref column="match"
 115         table="Pipeline" db="OVN"/> column in the OVN database's <ref
 116         table="Pipeline" db="OVN"/> table.
 117       </p>
 118     </column>
 119
 120     <group title="Common Columns">
 121       <column name="external_ids">
 122         See <em>External IDs</em> at the beginning of this document.
 123       </column>
 124     </group>
 125   </table>
 126
 127   <table name="ACL" title="Access Control List (ACL) rule">
 128     <p>
 129       Each row in this table represents one ACL rule for the logical switch in
 130       its <ref column="lswitch"/> column.  The <ref column="action"/> column for
 131       the highest-<ref column="priority"/> matching row in this table
 132       determines a packet's treatment.  If no row matches, packets are allowed
 133       by default.  (Default-deny treatment is possible: add a rule with <ref
 134       column="priority"/> 0, <code>true</code> as <ref column="match"/>, and
 135       <code>deny</code> as <ref column="action"/>.)
 136     </p>
 137
 138     <column name="lswitch">
 139       The switch to which the ACL rule applies.  The expression in the
 140       <ref column="match"/> column may match against logical ports
 141       within this switch.
 142     </column>
 143
 144     <column name="priority">
 145       The ACL rule's priority.  Rules with numerically higher priority take
 146       precedence over those with lower.  If two ACL rules with the same
 147       priority both match, then the one actually applied to a packet is
 148       undefined.
 149     </column>
 150
 151     <column name="match">
 152       The packets that the ACL should match, in the same expression language
 153       used for the <ref column="match" table="Pipeline" db="OVN"/> column in
 154       the OVN database's <ref table="Pipeline" db="OVN"/> table.  Match
 155       <code>inport</code> and <code>outport</code> against names of logical
 156       ports within <ref column="lswitch"/> to implement ingress and egress ACLs,
 157       respectively.  In logical switches connected to logical routers, the
 158       special port name <code>ROUTER</code> refers to the logical router port.
 159     </column>
 160
 161     <column name="action">
 162       <p>The action to take when the ACL rule matches:</p>
 163
 164       <ul>
 165         <li>
 166           <code>allow</code>: Forward the packet.
 167         </li>
 168
 169         <li>
 170           <code>allow-related</code>: Forward the packet and related traffic
 171           (e.g. inbound replies to an outbound connection).
 172         </li>
 173
 174         <li>
 175           <code>drop</code>: Silently drop the packet.
 176         </li>
 177
 178         <li>
 179           <code>reject</code>: Drop the packet, replying with a RST for TCP or
 180           ICMP unreachable message for other IP-based protocols.
 181         </li>
 182       </ul>
 183     </column>
 184
 185     <column name="log">
 186       If set to <code>true</code>, packets that match the ACL will trigger a
 187       log message on the transport node or nodes that perform ACL processing.
 188       Logging may be combined with any <ref column="action"/>.
 189     </column>
 190
 191     <group title="Common Columns">
 192       <column name="external_ids">
 193         See <em>External IDs</em> at the beginning of this document.
 194       </column>
 195     </group>
 196   </table>
 197
 198   <table name="Logical_Router" title="L3 logical router">
 199     <p>
 200       Each row represents one L3 logical router.  A given router's ports are
 201       the <ref table="Logical_Router_Port"/> rows whose <ref
 202       table="Logical_Router_Port" column="router"/> column points to its row.
 203     </p>
 204
 205     <column name="ip">
 206       The logical router's own IP address.  The logical router uses this
 207       address for ICMP replies (e.g. network unreachable messages) and other
 208       traffic that it originates and responds to traffic destined to this
 209       address (e.g. ICMP echo requests).
 210     </column>
 211
 212     <column name="default_gw">
 213       IP address to use as default gateway, if any.
 214     </column>
 215
 216     <group title="Common Columns">
 217       <column name="external_ids">
 218         See <em>External IDs</em> at the beginning of this document.
 219       </column>
 220     </group>
 221   </table>
 222
 223   <table name="Logical_Router_Port" title="L3 logical router port">
 224     <p>
 225       A port within an L3 logical router.
 226     </p>
 227
 228     <p>
 229       A router port is always attached to a switch port.  The connection can be
 230       identified by following the <ref column="router_port"
 231       table="Logical_Port"/> column from an appropriate <ref
 232       table="Logical_Port"/> row.
 233     </p>
 234
 235     <column name="router">
 236       The router to which the port belongs.
 237     </column>
 238
 239     <column name="network">
 240       The IP network and netmask of the network on the router port.  Used for
 241       routing.
 242     </column>
 243
 244     <column name="mac">
 245       The Ethernet address that belongs to this router port.
 246     </column>
 247
 248     <group title="Common Columns">
 249       <column name="external_ids">
 250         See <em>External IDs</em> at the beginning of this document.
 251       </column>
 252     </group>
 253   </table>
 254 </database>