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.
  36     </p>
  37
  38     <column name="name">
  39       <p>
  40         A name for the logical switch.  This name has no special meaning or purpose
  41         other than to provide convenience for human interaction with the ovn-nb
  42         database.  There is no requirement for the name to be unique.  The
  43         logical switch's UUID should be used as the unique identifier.
  44       </p>
  45     </column>
  46
  47     <column name="ports">
  48       <p>
  49         The logical ports connected to the logical switch.
  50       </p>
  51
  52       <p>
  53         It is an error for multiple logical switches to include the same
  54         logical port.
  55       </p>
  56     </column>
  57
  58     <column name="router_port">
  59       <p>
  60         The router port to which this logical switch is connected, or empty if
  61         this logical switch is not connected to any router.  A switch may be
  62         connected to at most one logical router, but this is not a significant
  63         restriction because logical routers may be connected into arbitrary
  64         topologies.
  65       </p>
  66
  67       <p>
  68         It is an error for multiple logical switches to refer to the same
  69         router port.
  70       </p>
  71     </column>
  72
  73     <column name="acls">
  74       Access control rules that apply to packets within the logical switch.
  75     </column>
  76
  77     <group title="Common Columns">
  78       <column name="external_ids">
  79         See <em>External IDs</em> at the beginning of this document.
  80       </column>
  81     </group>
  82   </table>
  83
  84   <table name="Logical_Port" title="L2 logical switch port">
  85     <p>
  86       A port within an L2 logical switch.
  87     </p>
  88
  89     <column name="name">
  90       <p>
  91       The logical port name.
  92       </p>
  93
  94       <p>
  95       For entities (VMs or containers) that are spawned in the hypervisor,
  96       the name used here must match those used in the <ref key="iface-id"
  97       table="Interface" column="external_ids" db="Open_vSwitch"/> in the
  98       <ref db="Open_vSwitch"/> database's <ref table="Interface"
  99       db="Open_vSwitch"/> table, because hypervisors use <ref key="iface-id"
 100       table="Interface" column="external_ids" db="Open_vSwitch"/> as a lookup
 101       key to identify the network interface of that entity.
 102       </p>
 103
 104       <p>
 105       For containers that are spawned inside a VM, the name can be
 106       any unique identifier.  In such a case, <ref column="parent_name"/>
 107       must be populated.
 108       </p>
 109     </column>
 110
 111     <column name="parent_name">
 112       When <ref column="name"/> identifies the interface of a container
 113       spawned inside a tenant VM, this column represents the VM interface
 114       through which the container interface sends its network traffic.
 115       The name used here must match those used in the <ref key="iface-id"
 116       table="Interface" column="external_ids" db="Open_vSwitch"/> in the
 117       <ref db="Open_vSwitch"/> table, because hypervisors in this case use
 118       <ref key="iface-id" table="Interface" column="external_ids"
 119       db="Open_vSwitch"/> as a lookup key to identify the network interface
 120       of the tenant VM.
 121     </column>
 122
 123     <column name="tag">
 124       When <ref column="name"/> identifies the interface of a container
 125       spawned inside a tenant VM, this column identifies the VLAN tag in
 126       the network traffic associated with that container's network interface.
 127       When there are multiple container interfaces inside a VM, all of
 128       them send their network traffic through a single VM network interface and
 129       this value helps OVN identify the correct container interface.
 130     </column>
 131
 132     <column name="up">
 133       This column is populated by <code>ovn-northd</code>, rather than by
 134       the CMS plugin as is most of this database.  When a logical port is bound
 135       to a physical location in the OVN Southbound database <ref
 136       db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
 137       sets this column to <code>true</code>; otherwise, or if the port
 138       becomes unbound later, it sets it to <code>false</code>.  This
 139       allows the CMS to wait for a VM's (or container's) networking to
 140       become active before it allows the VM (or container) to start.
 141     </column>
 142
 143     <column name="enabled">
 144       This column is used to administratively set port state.  If this column is
 145       empty or is set to <code>true</code>, the port is enabled.  If this column
 146       is set to <code>false</code>, the port is disabled.  A disabled port has all
 147       ingress and egress traffic dropped.
 148     </column>
 149
 150     <column name="macs">
 151       The logical port's own Ethernet address or addresses, each in the form
 152       <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
 153       Like a physical Ethernet NIC, a logical port ordinarily has a single
 154       fixed Ethernet address.  The string <code>unknown</code> is also allowed
 155       to indicate that the logical port has an unknown set of (additional)
 156       source addresses.
 157     </column>
 158
 159     <column name="port_security">
 160       <p>
 161         A set of L2 (Ethernet) addresses
 162         from which the logical port is allowed to send packets and to which it
 163         is allowed to receive packets.  If this column is empty, all addresses
 164         are permitted.  Logical ports are always allowed to receive packets
 165         addressed to multicast and broadcast addresses.
 166       </p>
 167
 168       <p>
 169         Each member of the set is an Ethernet address in the form
 170         <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
 171       </p>
 172
 173       <p>
 174         This specification will be extended to support L3 port security.
 175       </p>
 176     </column>
 177
 178     <group title="Common Columns">
 179       <column name="external_ids">
 180         See <em>External IDs</em> at the beginning of this document.
 181       </column>
 182     </group>
 183   </table>
 184
 185   <table name="ACL" title="Access Control List (ACL) rule">
 186     <p>
 187       Each row in this table represents one ACL rule for a logical switch
 188       that points to it through its <ref column="acls"/> column.  The <ref
 189       column="action"/> column for the highest-<ref column="priority"/>
 190       matching row in this table determines a packet's treatment.  If no row
 191       matches, packets are allowed by default.  (Default-deny treatment is
 192       possible: add a rule with <ref column="priority"/> 1, <code>1</code> as
 193       <ref column="match"/>, and <code>deny</code> as <ref column="action"/>.)
 194     </p>
 195
 196     <column name="priority">
 197       The ACL rule's priority.  Rules with numerically higher priority take
 198       precedence over those with lower.  If two ACL rules with the same
 199       priority both match, then the one actually applied to a packet is
 200       undefined.
 201     </column>
 202
 203     <column name="match">
 204       The packets that the ACL should match, in the same expression
 205       language used for the <ref column="match" table="Pipeline"
 206       db="OVN_Southbound"/> column in the OVN Southbound database's <ref
 207       table="Pipeline" db="OVN_Southbound"/> table.  Match
 208       <code>inport</code> and <code>outport</code> against names of
 209       logical ports within <ref column="lswitch"/> to implement ingress
 210       and egress ACLs, respectively.  In logical switches connected to
 211       logical routers, the special port name <code>ROUTER</code> refers
 212       to the logical router port.
 213     </column>
 214
 215     <column name="action">
 216       <p>The action to take when the ACL rule matches:</p>
 217
 218       <ul>
 219         <li>
 220           <code>allow</code>: Forward the packet.
 221         </li>
 222
 223         <li>
 224           <code>allow-related</code>: Forward the packet and related traffic
 225           (e.g. inbound replies to an outbound connection).
 226         </li>
 227
 228         <li>
 229           <code>drop</code>: Silently drop the packet.
 230         </li>
 231
 232         <li>
 233           <code>reject</code>: Drop the packet, replying with a RST for TCP or
 234           ICMP unreachable message for other IP-based protocols.
 235         </li>
 236       </ul>
 237
 238       <p>
 239         Only <code>allow</code> and <code>drop</code> are implemented:
 240         <code>allow-related</code> is currently treated as <code>allow</code>,
 241         and <code>reject</code> as <code>drop</code>.
 242       </p>
 243     </column>
 244
 245     <column name="log">
 246       <p>
 247         If set to <code>true</code>, packets that match the ACL will trigger a
 248         log message on the transport node or nodes that perform ACL processing.
 249         Logging may be combined with any <ref column="action"/>.
 250       </p>
 251
 252       <p>
 253         Logging is not yet implemented.
 254       </p>
 255     </column>
 256
 257     <group title="Common Columns">
 258       <column name="external_ids">
 259         See <em>External IDs</em> at the beginning of this document.
 260       </column>
 261     </group>
 262   </table>
 263
 264   <table name="Logical_Router" title="L3 logical router">
 265     <p>
 266       Each row represents one L3 logical router.
 267     </p>
 268
 269     <column name="name">
 270       <p>
 271         A name for the logical router.  This name has no special meaning or purpose
 272         other than to provide convenience for human interaction with the ovn-nb
 273         database.  There is no requirement for the name to be unique.  The
 274         logical router's UUID should be used as the unique identifier.
 275       </p>
 276     </column>
 277
 278     <column name="ports">
 279       The router's ports.  This is a set of weak references, so a <ref
 280       table="Logical_Switch"/> must also refer to any given <ref
 281       table="Logical_Router_Port"/> or it will automatically be deleted.
 282     </column>
 283
 284     <column name="ip">
 285       The logical router's own IP address.  The logical router uses this
 286       address for ICMP replies (e.g. network unreachable messages) and other
 287       traffic that it originates and responds to traffic destined to this
 288       address (e.g. ICMP echo requests).
 289     </column>
 290
 291     <column name="default_gw">
 292       IP address to use as default gateway, if any.
 293     </column>
 294
 295     <group title="Common Columns">
 296       <column name="external_ids">
 297         See <em>External IDs</em> at the beginning of this document.
 298       </column>
 299     </group>
 300   </table>
 301
 302   <table name="Logical_Router_Port" title="L3 logical router port">
 303     <p>
 304       A port within an L3 logical router.
 305     </p>
 306
 307     <p>
 308       A router port is always attached to a logical switch and to a logical
 309       router.  The former attachment, which is enforced by the database schema,
 310       can be identified by finding the <ref table="Logical_Switch"/> row whose
 311       <ref column="router_port" table="Logical_Switch"/> column points to the
 312       router port.  The latter attachment, which the database schema does not
 313       enforce, can be identified by finding the <ref table="Logical_Router"/>
 314       row whose <ref column="ports" table="Logical_Router"/> column includes
 315       the router port.
 316     </p>
 317
 318     <column name="network">
 319       The IP network and netmask of the network on the router port.  Used for
 320       routing.
 321     </column>
 322
 323     <column name="mac">
 324       The Ethernet address that belongs to this router port.
 325     </column>
 326
 327     <group title="Common Columns">
 328       <column name="external_ids">
 329         See <em>External IDs</em> at the beginning of this document.
 330       </column>
 331     </group>
 332   </table>
 333 </database>