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>ovn-northd</code> program
   7     monitors the database contents, transforms it, and stores it into the <ref
   8     db="OVN_Southbound"/> 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       <p>
  77       The logical port name.
  78       </p>
  79
  80       <p>
  81       For entities (VMs or containers) that are spawned in the hypervisor,
  82       the name used here must match those used in the <ref key="iface-id"
  83       table="Interface" column="external_ids" db="Open_vSwitch"/> in the
  84       <ref db="Open_vSwitch"/> database's <ref table="Interface"
  85       db="Open_vSwitch"/> table, because hypervisors use <ref key="iface-id"
  86       table="Interface" column="external_ids" db="Open_vSwitch"/> as a lookup
  87       key to identify the network interface of that entity.
  88       </p>
  89
  90       <p>
  91       For containers that are spawned inside a VM, the name can be
  92       any unique identifier.  In such a case, <ref column="parent_name"/>
  93       must be populated.
  94       </p>
  95     </column>
  96
  97     <column name="parent_name">
  98       When <ref column="name"/> identifies the interface of a container
  99       spawned inside a tenant VM, this column represents the VM interface
 100       through which the container interface sends its network traffic.
 101       The name used here must match those used in the <ref key="iface-id"
 102       table="Interface" column="external_ids" db="Open_vSwitch"/> in the
 103       <ref db="Open_vSwitch"/> table, because hypervisors in this case use
 104       <ref key="iface-id" table="Interface" column="external_ids"
 105       db="Open_vSwitch"/> as a lookup key to identify the network interface
 106       of the tenant VM.
 107     </column>
 108
 109     <column name="tag">
 110       When <ref column="name"/> identifies the interface of a container
 111       spawned inside a tenant VM, this column identifies the VLAN tag in
 112       the network traffic associated with that container's network interface.
 113       When there are multiple container interfaces inside a VM, all of
 114       them send their network traffic through a single VM network interface and
 115       this value helps OVN identify the correct container interface.
 116     </column>
 117
 118     <column name="up">
 119       This column is populated by <code>ovn-northd</code>, rather than by
 120       the CMS plugin as is most of this database.  When a logical port is bound
 121       to a physical location in the OVN Southbound database <ref
 122       db="OVN_Southbound" table="Bindings"/> table, <code>ovn-northd</code>
 123       sets this column to <code>true</code>; otherwise, or if the port
 124       becomes unbound later, it sets it to <code>false</code>.  This
 125       allows the CMS to wait for a VM's (or container's) networking to
 126       become active before it allows the VM (or container) to start.
 127     </column>
 128
 129     <column name="macs">
 130       The logical port's own Ethernet address or addresses, each in the form
 131       <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
 132       Like a physical Ethernet NIC, a logical port ordinarily has a single
 133       fixed Ethernet address.  The string <code>unknown</code> is also allowed
 134       to indicate that the logical port has an unknown set of (additional)
 135       source addresses.
 136     </column>
 137
 138     <column name="port_security">
 139       <p>
 140         A set of L2 (Ethernet) or L3 (IPv4 or IPv6) addresses or L2+L3 pairs
 141         from which the logical port is allowed to send packets and to which it
 142         is allowed to receive packets.  If this column is empty, all addresses
 143         are permitted.
 144       </p>
 145
 146       <p>
 147         Each member of the set is a comma- or space-separated list.  A single
 148         set member may have an Ethernet address, an IPv4 address, and an IPv6
 149         address, or any subset.  Order is not significant.
 150       </p>
 151
 152       <p>
 153         TBD: exact semantics.  For now only Ethernet port security is
 154         implemented.
 155       </p>
 156     </column>
 157
 158     <group title="Common Columns">
 159       <column name="external_ids">
 160         See <em>External IDs</em> at the beginning of this document.
 161       </column>
 162     </group>
 163   </table>
 164
 165   <table name="ACL" title="Access Control List (ACL) rule">
 166     <p>
 167       Each row in this table represents one ACL rule for the logical switch in
 168       its <ref column="lswitch"/> column.  The <ref column="action"/> column for
 169       the highest-<ref column="priority"/> matching row in this table
 170       determines a packet's treatment.  If no row matches, packets are allowed
 171       by default.  (Default-deny treatment is possible: add a rule with <ref
 172       column="priority"/> 1, <code>1</code> as <ref column="match"/>, and
 173       <code>deny</code> as <ref column="action"/>.)
 174     </p>
 175
 176     <column name="lswitch">
 177       The switch to which the ACL rule applies.  The expression in the
 178       <ref column="match"/> column may match against logical ports
 179       within this switch.
 180     </column>
 181
 182     <column name="priority">
 183       The ACL rule's priority.  Rules with numerically higher priority take
 184       precedence over those with lower.  If two ACL rules with the same
 185       priority both match, then the one actually applied to a packet is
 186       undefined.
 187     </column>
 188
 189     <column name="match">
 190       The packets that the ACL should match, in the same expression
 191       language used for the <ref column="match" table="Pipeline"
 192       db="OVN_Southbound"/> column in the OVN Southbound database's <ref
 193       table="Pipeline" db="OVN_Southbound"/> table.  Match
 194       <code>inport</code> and <code>outport</code> against names of
 195       logical ports within <ref column="lswitch"/> to implement ingress
 196       and egress ACLs, respectively.  In logical switches connected to
 197       logical routers, the special port name <code>ROUTER</code> refers
 198       to the logical router port.
 199     </column>
 200
 201     <column name="action">
 202       <p>The action to take when the ACL rule matches:</p>
 203
 204       <ul>
 205         <li>
 206           <code>allow</code>: Forward the packet.
 207         </li>
 208
 209         <li>
 210           <code>allow-related</code>: Forward the packet and related traffic
 211           (e.g. inbound replies to an outbound connection).
 212         </li>
 213
 214         <li>
 215           <code>drop</code>: Silently drop the packet.
 216         </li>
 217
 218         <li>
 219           <code>reject</code>: Drop the packet, replying with a RST for TCP or
 220           ICMP unreachable message for other IP-based protocols.
 221         </li>
 222       </ul>
 223     </column>
 224
 225     <column name="log">
 226       If set to <code>true</code>, packets that match the ACL will trigger a
 227       log message on the transport node or nodes that perform ACL processing.
 228       Logging may be combined with any <ref column="action"/>.
 229     </column>
 230
 231     <group title="Common Columns">
 232       <column name="external_ids">
 233         See <em>External IDs</em> at the beginning of this document.
 234       </column>
 235     </group>
 236   </table>
 237
 238   <table name="Logical_Router" title="L3 logical router">
 239     <p>
 240       Each row represents one L3 logical router.  A given router's ports are
 241       the <ref table="Logical_Router_Port"/> rows whose <ref
 242       table="Logical_Router_Port" column="router"/> column points to its row.
 243     </p>
 244
 245     <column name="ip">
 246       The logical router's own IP address.  The logical router uses this
 247       address for ICMP replies (e.g. network unreachable messages) and other
 248       traffic that it originates and responds to traffic destined to this
 249       address (e.g. ICMP echo requests).
 250     </column>
 251
 252     <column name="default_gw">
 253       IP address to use as default gateway, if any.
 254     </column>
 255
 256     <group title="Common Columns">
 257       <column name="external_ids">
 258         See <em>External IDs</em> at the beginning of this document.
 259       </column>
 260     </group>
 261   </table>
 262
 263   <table name="Logical_Router_Port" title="L3 logical router port">
 264     <p>
 265       A port within an L3 logical router.
 266     </p>
 267
 268     <p>
 269       A router port is always attached to a switch port.  The connection can be
 270       identified by following the <ref column="router_port"
 271       table="Logical_Port"/> column from an appropriate <ref
 272       table="Logical_Port"/> row.
 273     </p>
 274
 275     <column name="router">
 276       The router to which the port belongs.
 277     </column>
 278
 279     <column name="network">
 280       The IP network and netmask of the network on the router port.  Used for
 281       routing.
 282     </column>
 283
 284     <column name="mac">
 285       The Ethernet address that belongs to this router port.
 286     </column>
 287
 288     <group title="Common Columns">
 289       <column name="external_ids">
 290         See <em>External IDs</em> at the beginning of this document.
 291       </column>
 292     </group>
 293   </table>
 294 </database>