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="type">
 112       <p>
 113       Specify a type for this logical port.  Logical ports can be used to model
 114       other types of connectivity into an OVN logical switch.  Leaving this
 115       column blank maintains the default logical port behavior, which is
 116       for a VM (or VIF) interface.  The following other types are defined:
 117       </p>
 118
 119       <dl>
 120         <dt><code>localnet</code></dt>
 121         <dd>A connection to a locally accessible network from each
 122         <code>ovn-controller</code> instance.  A logical switch can only
 123         have a single <code>localnet</code> port attached and at most one
 124         regular logical port.  This is used to model direct connectivity
 125         to an existing network.</dd>
 126       </dl>
 127
 128       <dl>
 129         <dt><code>vtep</code></dt>
 130         <dd>A port to a logical switch on a VTEP gateway.  In order
 131         to get this port correctly recognized by the OVN controller, the
 132         <ref column="options" table="Logical_Port"/>:<code>vtep-physical-switch</code>
 133         and <ref column="options" table="Logical_Port"/>:<code>vtep-logical-switch</code>
 134         must also be defined.</dd>
 135       </dl>
 136     </column>
 137
 138     <column name="options">
 139       <p>
 140         This column provides key/value settings specific to the logical port
 141         <ref column="type"/>.  The following options are defined:
 142       </p>
 143
 144       <dl>
 145         <dt><code>network_name</code></dt>
 146         <dd>
 147           Must be set when <ref column="type"/> is <code>localnet</code>.
 148           <code>ovn-controller</code> uses local configuration to determine
 149           exactly how to connect to this locally accessible network.
 150         </dd>
 151       </dl>
 152
 153       <dl>
 154         <dt><code>vtep-physical-switch</code></dt>
 155         <dd>
 156           The name of the VTEP gateway.  Must be set when
 157           <ref column="type"/> is <code>vtep</code>.
 158         </dd>
 159       </dl>
 160
 161       <dl>
 162         <dt><code>vtep-logical-switch</code></dt>
 163         <dd>
 164           A logical switch name connected by the VTEP gateway.  Must be
 165           set when <ref column="type"/> is <code>vtep</code>.
 166         </dd>
 167       </dl>
 168     </column>
 169
 170     <column name="parent_name">
 171       When <ref column="name"/> identifies the interface of a container
 172       spawned inside a tenant VM, this column represents the VM interface
 173       through which the container interface sends its network traffic.
 174       The name used here must match those used in the <ref key="iface-id"
 175       table="Interface" column="external_ids" db="Open_vSwitch"/> in the
 176       <ref db="Open_vSwitch"/> table, because hypervisors in this case use
 177       <ref key="iface-id" table="Interface" column="external_ids"
 178       db="Open_vSwitch"/> as a lookup key to identify the network interface
 179       of the tenant VM.
 180     </column>
 181
 182     <column name="tag">
 183      <p>
 184       When <ref column="type"/> is empty and <ref column="name"/> identifies
 185       the interface of a container spawned inside a tenant VM, this column
 186       identifies the VLAN tag in the network traffic associated with that
 187       container's network interface. When there are multiple container
 188       interfaces inside a VM, all of them send their network traffic through a
 189       single VM network interface and this value helps OVN identify the correct
 190       container interface.
 191      </p>
 192
 193      <p>
 194       When <ref column="type"/> is set to <code>localnet</code>, this can be
 195       set to indicate that the port represents a connection to a specific
 196       VLAN on a locally accessible network. The VLAN ID is used to match
 197       incoming traffic and is also added to outgoing traffic.
 198      </p>
 199     </column>
 200
 201     <column name="up">
 202       This column is populated by <code>ovn-northd</code>, rather than by
 203       the CMS plugin as is most of this database.  When a logical port is bound
 204       to a physical location in the OVN Southbound database <ref
 205       db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
 206       sets this column to <code>true</code>; otherwise, or if the port
 207       becomes unbound later, it sets it to <code>false</code>.  This
 208       allows the CMS to wait for a VM's (or container's) networking to
 209       become active before it allows the VM (or container) to start.
 210     </column>
 211
 212     <column name="enabled">
 213       This column is used to administratively set port state.  If this column is
 214       empty or is set to <code>true</code>, the port is enabled.  If this column
 215       is set to <code>false</code>, the port is disabled.  A disabled port has all
 216       ingress and egress traffic dropped.
 217     </column>
 218
 219     <column name="addresses">
 220       <p>
 221         Addresses owned by the logical port.
 222       </p>
 223
 224       <p>
 225         Each element in the set must take one of the following forms:
 226       </p>
 227
 228       <dl>
 229         <dt><code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code></dt>
 230         <dd>
 231           <p>
 232             An Ethernet address owned by the logical port.  Like a physical
 233             Ethernet NIC, a logical port ordinarily has a single fixed Ethernet
 234             address.
 235           </p>
 236
 237           <p>
 238             When a OVN logical switch processes a unicast Ethernet frame whose
 239             destination MAC address is in a logical port's <ref
 240             column="addresses"/> column, it delivers it only to that port, as
 241             if a MAC learning process had learned that MAC address on the port.
 242           </p>
 243         </dd>
 244
 245         <dt><code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var> <var>a</var>.<var>b</var>.<var>c</var>.<var>d</var></code></dt>
 246         <dd>
 247           <p>
 248             This form has all the effects of the previous form.  It also
 249             indicates that the logical port owns the given IPv4 address.
 250           </p>
 251
 252           <p>
 253             The OVN logical switch uses this information to synthesize
 254             responses to ARP requests without traversing the physical network.
 255             The OVN logical router connected to the logical switch, if any,
 256             uses this information to avoid issuing ARP requests for logical
 257             switch ports.
 258           </p>
 259         </dd>
 260
 261         <dt><code>unknown</code></dt>
 262         <dd>
 263           This indicates that the logical port has an unknown set of Ethernet
 264           addresses.  When an OVN logical switch processes a unicast Ethernet
 265           frame whose destination MAC address is not in any logical port's <ref
 266           column="addresses"/> column, it delivers it to the port (or ports)
 267           whose <ref column="addresses"/> columns include <code>unknown</code>.
 268         </dd>
 269       </dl>
 270     </column>
 271
 272     <column name="port_security">
 273       <p>
 274         A set of L2 (Ethernet) addresses
 275         from which the logical port is allowed to send packets and to which it
 276         is allowed to receive packets.  If this column is empty, all addresses
 277         are permitted.  Logical ports are always allowed to receive packets
 278         addressed to multicast and broadcast addresses.
 279       </p>
 280
 281       <p>
 282         Each member of the set is an Ethernet address in the form
 283         <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
 284       </p>
 285
 286       <p>
 287         This specification will be extended to support L3 port security.
 288       </p>
 289     </column>
 290
 291     <group title="Common Columns">
 292       <column name="external_ids">
 293         See <em>External IDs</em> at the beginning of this document.
 294       </column>
 295     </group>
 296   </table>
 297
 298   <table name="ACL" title="Access Control List (ACL) rule">
 299     <p>
 300       Each row in this table represents one ACL rule for a logical switch
 301       that points to it through its <ref column="acls"/> column.  The <ref
 302       column="action"/> column for the highest-<ref column="priority"/>
 303       matching row in this table determines a packet's treatment.  If no row
 304       matches, packets are allowed by default.  (Default-deny treatment is
 305       possible: add a rule with <ref column="priority"/> 1, <code>1</code> as
 306       <ref column="match"/>, and <code>deny</code> as <ref column="action"/>.)
 307     </p>
 308
 309     <column name="priority">
 310       <p>
 311         The ACL rule's priority.  Rules with numerically higher priority
 312         take precedence over those with lower.  If two ACL rules with
 313         the same priority both match, then the one actually applied to a
 314         packet is undefined.
 315       </p>
 316
 317       <p>
 318         Return traffic from an <code>allow-related</code> flow is always
 319         allowed and cannot be changed through an ACL.
 320       </p>
 321     </column>
 322
 323     <column name="direction">
 324       <p>Direction of the traffic to which this rule should apply:</p>
 325       <ul>
 326         <li>
 327           <code>from-lport</code>: Used to implement filters on traffic
 328           arriving from a logical port.  These rules are applied to the
 329           logical switch's ingress pipeline.
 330         </li>
 331         <li>
 332           <code>to-lport</code>: Used to implement filters on traffic
 333           forwarded to a logical port.  These rules are applied to the
 334           logical switch's egress pipeline.
 335         </li>
 336       </ul>
 337     </column>
 338
 339     <column name="match">
 340       <p>
 341         The packets that the ACL should match, in the same expression
 342         language used for the <ref column="match" table="Logical_Flow"
 343         db="OVN_Southbound"/> column in the OVN Southbound database's
 344         <ref table="Logical_Flow" db="OVN_Southbound"/> table.  The
 345         <code>outport</code> logical port is only available in the
 346         <code>to-lport</code> direction (the <code>inport</code> is
 347         available in both directions).
 348       </p>
 349
 350       <p>
 351         By default all traffic is allowed.  When writing a more
 352         restrictive policy, it is important to remember to allow flows
 353         such as ARP and IPv6 neighbor discovery packets.
 354       </p>
 355
 356       <p>
 357         In logical switches connected to logical routers, the special
 358         port name <code>ROUTER</code> refers to the logical router port.
 359       </p>
 360     </column>
 361
 362     <column name="action">
 363       <p>The action to take when the ACL rule matches:</p>
 364       <ul>
 365         <li>
 366           <code>allow</code>: Forward the packet.
 367         </li>
 368
 369         <li>
 370           <code>allow-related</code>: Forward the packet and related traffic
 371           (e.g. inbound replies to an outbound connection).
 372         </li>
 373
 374         <li>
 375           <code>drop</code>: Silently drop the packet.
 376         </li>
 377
 378         <li>
 379           <code>reject</code>: Drop the packet, replying with a RST for TCP or
 380           ICMP unreachable message for other IP-based protocols.
 381           <code>Not implemented--currently treated as drop</code>
 382         </li>
 383       </ul>
 384     </column>
 385
 386     <column name="log">
 387       <p>
 388         If set to <code>true</code>, packets that match the ACL will trigger a
 389         log message on the transport node or nodes that perform ACL processing.
 390         Logging may be combined with any <ref column="action"/>.
 391       </p>
 392
 393       <p>
 394         Logging is not yet implemented.
 395       </p>
 396     </column>
 397
 398     <group title="Common Columns">
 399       <column name="external_ids">
 400         See <em>External IDs</em> at the beginning of this document.
 401       </column>
 402     </group>
 403   </table>
 404
 405   <table name="Logical_Router" title="L3 logical router">
 406     <p>
 407       Each row represents one L3 logical router.
 408     </p>
 409
 410     <column name="name">
 411       <p>
 412         A name for the logical router.  This name has no special meaning or purpose
 413         other than to provide convenience for human interaction with the ovn-nb
 414         database.  There is no requirement for the name to be unique.  The
 415         logical router's UUID should be used as the unique identifier.
 416       </p>
 417     </column>
 418
 419     <column name="ports">
 420       The router's ports.
 421     </column>
 422
 423     <column name="default_gw">
 424       IP address to use as default gateway, if any.
 425     </column>
 426
 427     <group title="Common Columns">
 428       <column name="external_ids">
 429         See <em>External IDs</em> at the beginning of this document.
 430       </column>
 431     </group>
 432   </table>
 433
 434   <table name="Logical_Router_Port" title="L3 logical router port">
 435     <p>
 436       A port within an L3 logical router.
 437     </p>
 438
 439     <p>
 440       Exactly one <ref table="Logical_Router"/> row must reference a given
 441       logical router port.
 442     </p>
 443
 444     <column name="name">
 445       <p>
 446         A name for the logical router port.  This name has no special meaning or purpose
 447         other than to provide convenience for human interaction with the ovn-nb
 448         database.  There is no requirement for the name to be unique.  The
 449         logical router port's UUID should be used as the unique identifier.
 450       </p>
 451     </column>
 452
 453     <column name="network">
 454       The IP address of the router and the netmask.  For example,
 455       <code>192.168.0.1/24</code> indicates that the router's IP address is
 456       192.168.0.1 and that packets destined to 192.168.0.<var>x</var> should be
 457       routed to this port.
 458     </column>
 459
 460     <column name="mac">
 461       The Ethernet address that belongs to this router port.
 462     </column>
 463
 464     <group title="Attachment">
 465       <p>
 466         A given router port serves one of two purposes:
 467       </p>
 468
 469       <ul>
 470         <li>
 471           To attach a logical switch to a logical router.  A logical router
 472           port of this type is referenced by exactly the <ref
 473           column="router_port" table="Logical_Switch"/> column in exactly one
 474           <ref table="Logical_Switch"/> row.  The <ref column="peer"/> column
 475           is empty.
 476         </li>
 477
 478         <li>
 479           To connect one logical router to another.  This requires a pair of
 480           logical router ports, each connected to a different router.  Each
 481           router port in the pair specifies the other in its <ref
 482           column="peer"/> column.  No <ref table="Logical_Switch"/> refers to
 483           the router port.
 484         </li>
 485       </ul>
 486
 487       <column name="peer">
 488         <p>
 489           For a router port used to connect two logical routers, this
 490           identifies the other router port in the pair.
 491         </p>
 492
 493         <p>
 494           For a router port attached to a logical switch, this column is empty.
 495         </p>
 496       </column>
 497     </group>
 498
 499     <group title="Common Columns">
 500       <column name="external_ids">
 501         See <em>External IDs</em> at the beginning of this document.
 502       </column>
 503     </group>
 504   </table>
 505 </database>