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-nbd</code> program monitors
   7     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-nbd</code>, rather than by the CMS
 120       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-nbd</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         Exact syntax is TBD.  One could simply use comma- or
 148         space-separated L2 and L3 addresses in each set member, or
 149         replace this by a subset of the general-purpose expression
 150         language used for the <ref column="match" table="Pipeline"
 151         db="OVN_Southbound"/> column in the OVN Southbound database's
 152         <ref table="Pipeline" db="OVN_Southbound"/> table.
 153       </p>
 154     </column>
 155
 156     <group title="Common Columns">
 157       <column name="external_ids">
 158         See <em>External IDs</em> at the beginning of this document.
 159       </column>
 160     </group>
 161   </table>
 162
 163   <table name="ACL" title="Access Control List (ACL) rule">
 164     <p>
 165       Each row in this table represents one ACL rule for the logical switch in
 166       its <ref column="lswitch"/> column.  The <ref column="action"/> column for
 167       the highest-<ref column="priority"/> matching row in this table
 168       determines a packet's treatment.  If no row matches, packets are allowed
 169       by default.  (Default-deny treatment is possible: add a rule with <ref
 170       column="priority"/> 0, <code>true</code> as <ref column="match"/>, and
 171       <code>deny</code> as <ref column="action"/>.)
 172     </p>
 173
 174     <column name="lswitch">
 175       The switch to which the ACL rule applies.  The expression in the
 176       <ref column="match"/> column may match against logical ports
 177       within this switch.
 178     </column>
 179
 180     <column name="priority">
 181       The ACL rule's priority.  Rules with numerically higher priority take
 182       precedence over those with lower.  If two ACL rules with the same
 183       priority both match, then the one actually applied to a packet is
 184       undefined.
 185     </column>
 186
 187     <column name="match">
 188       The packets that the ACL should match, in the same expression
 189       language used for the <ref column="match" table="Pipeline"
 190       db="OVN_Southbound"/> column in the OVN Southbound database's <ref
 191       table="Pipeline" db="OVN_Southbound"/> table.  Match
 192       <code>inport</code> and <code>outport</code> against names of
 193       logical ports within <ref column="lswitch"/> to implement ingress
 194       and egress ACLs, respectively.  In logical switches connected to
 195       logical routers, the special port name <code>ROUTER</code> refers
 196       to the logical router port.
 197     </column>
 198
 199     <column name="action">
 200       <p>The action to take when the ACL rule matches:</p>
 201
 202       <ul>
 203         <li>
 204           <code>allow</code>: Forward the packet.
 205         </li>
 206
 207         <li>
 208           <code>allow-related</code>: Forward the packet and related traffic
 209           (e.g. inbound replies to an outbound connection).
 210         </li>
 211
 212         <li>
 213           <code>drop</code>: Silently drop the packet.
 214         </li>
 215
 216         <li>
 217           <code>reject</code>: Drop the packet, replying with a RST for TCP or
 218           ICMP unreachable message for other IP-based protocols.
 219         </li>
 220       </ul>
 221     </column>
 222
 223     <column name="log">
 224       If set to <code>true</code>, packets that match the ACL will trigger a
 225       log message on the transport node or nodes that perform ACL processing.
 226       Logging may be combined with any <ref column="action"/>.
 227     </column>
 228
 229     <group title="Common Columns">
 230       <column name="external_ids">
 231         See <em>External IDs</em> at the beginning of this document.
 232       </column>
 233     </group>
 234   </table>
 235
 236   <table name="Logical_Router" title="L3 logical router">
 237     <p>
 238       Each row represents one L3 logical router.  A given router's ports are
 239       the <ref table="Logical_Router_Port"/> rows whose <ref
 240       table="Logical_Router_Port" column="router"/> column points to its row.
 241     </p>
 242
 243     <column name="ip">
 244       The logical router's own IP address.  The logical router uses this
 245       address for ICMP replies (e.g. network unreachable messages) and other
 246       traffic that it originates and responds to traffic destined to this
 247       address (e.g. ICMP echo requests).
 248     </column>
 249
 250     <column name="default_gw">
 251       IP address to use as default gateway, if any.
 252     </column>
 253
 254     <group title="Common Columns">
 255       <column name="external_ids">
 256         See <em>External IDs</em> at the beginning of this document.
 257       </column>
 258     </group>
 259   </table>
 260
 261   <table name="Logical_Router_Port" title="L3 logical router port">
 262     <p>
 263       A port within an L3 logical router.
 264     </p>
 265
 266     <p>
 267       A router port is always attached to a switch port.  The connection can be
 268       identified by following the <ref column="router_port"
 269       table="Logical_Port"/> column from an appropriate <ref
 270       table="Logical_Port"/> row.
 271     </p>
 272
 273     <column name="router">
 274       The router to which the port belongs.
 275     </column>
 276
 277     <column name="network">
 278       The IP network and netmask of the network on the router port.  Used for
 279       routing.
 280     </column>
 281
 282     <column name="mac">
 283       The Ethernet address that belongs to this router port.
 284     </column>
 285
 286     <group title="Common Columns">
 287       <column name="external_ids">
 288         See <em>External IDs</em> at the beginning of this document.
 289       </column>
 290     </group>
 291   </table>
 292 </database>