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