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
 289             <p>
 290               Note that the order here is important. The Ethernet address must
 291               be listed before the IP address.
 292             </p>
 293           </dd>
 294
 295           <dt><code>unknown</code></dt>
 296           <dd>
 297             This indicates that the logical port has an unknown set of Ethernet
 298             addresses.  When an OVN logical switch processes a unicast Ethernet
 299             frame whose destination MAC address is not in any logical port's
 300             <ref column="addresses"/> column, it delivers it to the port (or
 301             ports) whose <ref column="addresses"/> columns include
 302             <code>unknown</code>.
 303           </dd>
 304         </dl>
 305       </column>
 306
 307       <column name="port_security">
 308         <p>
 309           A set of L2 (Ethernet) addresses from which the logical port is
 310           allowed to send packets and to which it is allowed to receive
 311           packets.  If this column is empty, all addresses are permitted.
 312           Logical ports are always allowed to receive packets addressed to
 313           multicast and broadcast addresses.
 314         </p>
 315
 316         <p>
 317           Each member of the set is an Ethernet address in the form
 318           <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
 319         </p>
 320
 321         <p>
 322           This specification will be extended to support L3 port security.
 323         </p>
 324       </column>
 325     </group>
 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
 334   <table name="ACL" title="Access Control List (ACL) rule">
 335     <p>
 336       Each row in this table represents one ACL rule for a logical switch
 337       that points to it through its <ref column="acls"/> column.  The <ref
 338       column="action"/> column for the highest-<ref column="priority"/>
 339       matching row in this table determines a packet's treatment.  If no row
 340       matches, packets are allowed by default.  (Default-deny treatment is
 341       possible: add a rule with <ref column="priority"/> 0, <code>0</code> as
 342       <ref column="match"/>, and <code>deny</code> as <ref column="action"/>.)
 343     </p>
 344
 345     <column name="priority">
 346       <p>
 347         The ACL rule's priority.  Rules with numerically higher priority
 348         take precedence over those with lower.  If two ACL rules with
 349         the same priority both match, then the one actually applied to a
 350         packet is undefined.
 351       </p>
 352
 353       <p>
 354         Return traffic from an <code>allow-related</code> flow is always
 355         allowed and cannot be changed through an ACL.
 356       </p>
 357     </column>
 358
 359     <column name="direction">
 360       <p>Direction of the traffic to which this rule should apply:</p>
 361       <ul>
 362         <li>
 363           <code>from-lport</code>: Used to implement filters on traffic
 364           arriving from a logical port.  These rules are applied to the
 365           logical switch's ingress pipeline.
 366         </li>
 367         <li>
 368           <code>to-lport</code>: Used to implement filters on traffic
 369           forwarded to a logical port.  These rules are applied to the
 370           logical switch's egress pipeline.
 371         </li>
 372       </ul>
 373     </column>
 374
 375     <column name="match">
 376       <p>
 377         The packets that the ACL should match, in the same expression
 378         language used for the <ref column="match" table="Logical_Flow"
 379         db="OVN_Southbound"/> column in the OVN Southbound database's
 380         <ref table="Logical_Flow" db="OVN_Southbound"/> table.  The
 381         <code>outport</code> logical port is only available in the
 382         <code>to-lport</code> direction (the <code>inport</code> is
 383         available in both directions).
 384       </p>
 385
 386       <p>
 387         By default all traffic is allowed.  When writing a more
 388         restrictive policy, it is important to remember to allow flows
 389         such as ARP and IPv6 neighbor discovery packets.
 390       </p>
 391
 392       <p>
 393         Note that you can not create an ACL matching on a port with
 394         type=router.
 395       </p>
 396     </column>
 397
 398     <column name="action">
 399       <p>The action to take when the ACL rule matches:</p>
 400       <ul>
 401         <li>
 402           <code>allow</code>: Forward the packet.
 403         </li>
 404
 405         <li>
 406           <code>allow-related</code>: Forward the packet and related traffic
 407           (e.g. inbound replies to an outbound connection).
 408         </li>
 409
 410         <li>
 411           <code>drop</code>: Silently drop the packet.
 412         </li>
 413
 414         <li>
 415           <code>reject</code>: Drop the packet, replying with a RST for TCP or
 416           ICMP unreachable message for other IP-based protocols.
 417           <code>Not implemented--currently treated as drop</code>
 418         </li>
 419       </ul>
 420     </column>
 421
 422     <column name="log">
 423       <p>
 424         If set to <code>true</code>, packets that match the ACL will trigger a
 425         log message on the transport node or nodes that perform ACL processing.
 426         Logging may be combined with any <ref column="action"/>.
 427       </p>
 428
 429       <p>
 430         Logging is not yet implemented.
 431       </p>
 432     </column>
 433
 434     <group title="Common Columns">
 435       <column name="external_ids">
 436         See <em>External IDs</em> at the beginning of this document.
 437       </column>
 438     </group>
 439   </table>
 440
 441   <table name="Logical_Router" title="L3 logical router">
 442     <p>
 443       Each row represents one L3 logical router.
 444     </p>
 445
 446     <column name="name">
 447       <p>
 448         A name for the logical router.  This name has no special meaning or purpose
 449         other than to provide convenience for human interaction with the ovn-nb
 450         database.  There is no requirement for the name to be unique.  The
 451         logical router's UUID should be used as the unique identifier.
 452       </p>
 453     </column>
 454
 455     <column name="ports">
 456       The router's ports.
 457     </column>
 458
 459     <column name="default_gw">
 460       IP address to use as default gateway, if any.
 461     </column>
 462
 463     <group title="Common Columns">
 464       <column name="external_ids">
 465         See <em>External IDs</em> at the beginning of this document.
 466       </column>
 467     </group>
 468   </table>
 469
 470   <table name="Logical_Router_Port" title="L3 logical router port">
 471     <p>
 472       A port within an L3 logical router.
 473     </p>
 474
 475     <p>
 476       Exactly one <ref table="Logical_Router"/> row must reference a given
 477       logical router port.
 478     </p>
 479
 480     <column name="name">
 481       <p>
 482         A name for the logical router port.
 483       </p>
 484
 485       <p>
 486         In addition to provide convenience for human interaction with the
 487         ovn-nb database, this column is used as reference by its patch port in
 488         <ref table="Logical_Port"/> or another logical router port in <ref
 489         table="Logical_Router_Port"/>.
 490       </p>
 491     </column>
 492
 493     <column name="network">
 494       The IP address of the router and the netmask.  For example,
 495       <code>192.168.0.1/24</code> indicates that the router's IP address is
 496       192.168.0.1 and that packets destined to 192.168.0.<var>x</var> should be
 497       routed to this port.
 498     </column>
 499
 500     <column name="mac">
 501       The Ethernet address that belongs to this router port.
 502     </column>
 503
 504     <column name="enabled">
 505       This column is used to administratively set port state.  If this column
 506       is empty or is set to <code>true</code>, the port is enabled.  If this
 507       column is set to <code>false</code>, the port is disabled.  A disabled
 508       port has all ingress and egress traffic dropped.
 509     </column>
 510
 511     <group title="Attachment">
 512       <p>
 513         A given router port serves one of two purposes:
 514       </p>
 515
 516       <ul>
 517         <li>
 518           To attach a logical switch to a logical router.  A logical router
 519           port of this type is referenced by exactly one <ref
 520           table="Logical_Port"/> of type <code>router</code>.  The value of
 521           <ref column="name"/> is set as <code>router-port</code> in column
 522           <ref column="options"/> of <ref table="Logical_Port"/>.
 523           In this case <ref column="peer"/> column is empty.
 524         </li>
 525
 526         <li>
 527           To connect one logical router to another.  This requires a pair of
 528           logical router ports, each connected to a different router.  Each
 529           router port in the pair specifies the other in its <ref
 530           column="peer"/> column.  No <ref table="Logical_Switch"/> refers to
 531           the router port.
 532         </li>
 533       </ul>
 534
 535       <column name="peer">
 536         <p>
 537           For a router port used to connect two logical routers, this
 538           identifies the other router port in the pair by <ref column="name"/>.
 539         </p>
 540
 541         <p>
 542           For a router port attached to a logical switch, this column is empty.
 543         </p>
 544       </column>
 545     </group>
 546
 547     <group title="Common Columns">
 548       <column name="external_ids">
 549         See <em>External IDs</em> at the beginning of this document.
 550       </column>
 551     </group>
 552   </table>
 553 </database>