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