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