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