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