vtep/vtep.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <database name="vtep" title="Hardware VTEP Database">
   3   <p>
   4     This schema specifies relations that a VTEP can use to integrate
   5     physical ports into logical switches maintained by a network
   6     virtualization controller such as NSX.
   7   </p>
   8
   9   <p>Glossary:</p>
  10
  11   <dl>
  12     <dt>VTEP</dt>
  13     <dd>
  14       VXLAN Tunnel End Point, an entity which originates and/or terminates
  15       VXLAN tunnels.
  16     </dd>
  17
  18     <dt>HSC</dt>
  19     <dd>
  20       Hardware Switch Controller.
  21     </dd>
  22
  23     <dt>NVC</dt>
  24     <dd>
  25       Network Virtualization Controller, e.g. NSX.
  26     </dd>
  27
  28     <dt>VRF</dt>
  29     <dd>
  30       Virtual Routing and Forwarding instance.
  31     </dd>
  32  </dl>
  33
  34   <table name="Global" title="Top-level configuration.">
  35     Top-level configuration for a hardware VTEP.  There must be
  36     exactly one record in the <ref table="Global"/> table.
  37
  38     <column name="switches">
  39       <p>
  40         The physical switch or switches managed by the VTEP.
  41       </p>
  42
  43       <p>
  44         When a physical switch integrates support for this VTEP schema, which
  45         is expected to be the most common case, this column should point to one
  46         <ref table="Physical_Switch"/> record that represents the switch
  47         itself.  In another possible implementation, a server or a VM presents
  48         a VTEP schema front-end interface to one or more physical switches,
  49         presumably communicating with those physical switches over a
  50         proprietary protocol.  In that case, this column would point to one
  51         <ref table="Physical_Switch"/> for each physical switch, and the set
  52         might change over time as the front-end server comes to represent a
  53         differing set of switches.
  54       </p>
  55     </column>
  56
  57     <group title="Database Configuration">
  58       <p>
  59         These columns primarily configure the database server
  60         (<code>ovsdb-server</code>), not the hardware VTEP itself.
  61       </p>
  62
  63       <column name="managers">
  64         Database clients to which the database server should connect or
  65         to which it should listen, along with options for how these
  66         connection should be configured.  See the <ref table="Manager"/>
  67         table for more information.
  68       </column>
  69     </group>
  70   </table>
  71
  72   <table name="Manager" title="OVSDB management connection.">
  73     <p>
  74       Configuration for a database connection to an Open vSwitch Database
  75       (OVSDB) client.
  76     </p>
  77
  78     <p>
  79       The database server can initiate and maintain active connections
  80       to remote clients.  It can also listen for database connections.
  81     </p>
  82
  83     <group title="Core Features">
  84       <column name="target">
  85         <p>Connection method for managers.</p>
  86         <p>
  87           The following connection methods are currently supported:
  88         </p>
  89         <dl>
  90           <dt><code>ssl:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
  91           <dd>
  92             <p>
  93               The specified SSL <var>port</var> (default: 6640) on the host at
  94               the given <var>ip</var>, which must be expressed as an IP address
  95               (not a DNS name).
  96             </p>
  97             <p>
  98               SSL key and certificate configuration happens outside the
  99               database.
 100             </p>
 101           </dd>
 102
 103           <dt><code>tcp:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
 104           <dd>
 105             The specified TCP <var>port</var> (default: 6640) on the host at
 106             the given <var>ip</var>, which must be expressed as an IP address
 107             (not a DNS name).
 108           </dd>
 109           <dt><code>pssl:</code>[<var>port</var>][<code>:<var>ip</var></code>]</dt>
 110           <dd>
 111             <p>
 112               Listens for SSL connections on the specified TCP <var>port</var>
 113               (default: 6640).  If <var>ip</var>, which must be expressed as an
 114               IP address (not a DNS name), is specified, then connections are
 115               restricted to the specified local IP address.
 116             </p>
 117           </dd>
 118           <dt><code>ptcp:</code>[<var>port</var>][<code>:<var>ip</var></code>]</dt>
 119           <dd>
 120             Listens for connections on the specified TCP <var>port</var>
 121             (default: 6640).  If <var>ip</var>, which must be expressed as an
 122             IP address (not a DNS name), is specified, then connections are
 123             restricted to the specified local IP address.
 124           </dd>
 125         </dl>
 126       </column>
 127     </group>
 128
 129     <group title="Client Failure Detection and Handling">
 130       <column name="max_backoff">
 131         Maximum number of milliseconds to wait between connection attempts.
 132         Default is implementation-specific.
 133       </column>
 134
 135       <column name="inactivity_probe">
 136         Maximum number of milliseconds of idle time on connection to the
 137         client before sending an inactivity probe message.  If the Open
 138         vSwitch database does not communicate with the client for the
 139         specified number of seconds, it will send a probe.  If a
 140         response is not received for the same additional amount of time,
 141         the database server assumes the connection has been broken
 142         and attempts to reconnect.  Default is implementation-specific.
 143         A value of 0 disables inactivity probes.
 144       </column>
 145     </group>
 146
 147     <group title="Status">
 148       <column name="is_connected">
 149         <code>true</code> if currently connected to this manager,
 150         <code>false</code> otherwise.
 151       </column>
 152
 153       <column name="status" key="last_error">
 154         A human-readable description of the last error on the connection
 155         to the manager; i.e. <code>strerror(errno)</code>.  This key
 156         will exist only if an error has occurred.
 157       </column>
 158
 159       <column name="status" key="state"
 160               type='{"type": "string", "enum": ["set", ["VOID", "BACKOFF", "CONNECTING", "ACTIVE", "IDLE"]]}'>
 161         <p>
 162           The state of the connection to the manager:
 163         </p>
 164         <dl>
 165           <dt><code>VOID</code></dt>
 166           <dd>Connection is disabled.</dd>
 167
 168           <dt><code>BACKOFF</code></dt>
 169           <dd>Attempting to reconnect at an increasing period.</dd>
 170
 171           <dt><code>CONNECTING</code></dt>
 172           <dd>Attempting to connect.</dd>
 173
 174           <dt><code>ACTIVE</code></dt>
 175           <dd>Connected, remote host responsive.</dd>
 176
 177           <dt><code>IDLE</code></dt>
 178           <dd>Connection is idle.  Waiting for response to keep-alive.</dd>
 179         </dl>
 180         <p>
 181           These values may change in the future.  They are provided only for
 182           human consumption.
 183         </p>
 184       </column>
 185
 186       <column name="status" key="sec_since_connect"
 187               type='{"type": "integer", "minInteger": 0}'>
 188         The amount of time since this manager last successfully connected
 189         to the database (in seconds). Value is empty if manager has never
 190         successfully connected.
 191       </column>
 192
 193       <column name="status" key="sec_since_disconnect"
 194               type='{"type": "integer", "minInteger": 0}'>
 195         The amount of time since this manager last disconnected from the
 196         database (in seconds). Value is empty if manager has never
 197         disconnected.
 198       </column>
 199
 200       <column name="status" key="locks_held">
 201         Space-separated list of the names of OVSDB locks that the connection
 202         holds.  Omitted if the connection does not hold any locks.
 203       </column>
 204
 205       <column name="status" key="locks_waiting">
 206         Space-separated list of the names of OVSDB locks that the connection is
 207         currently waiting to acquire.  Omitted if the connection is not waiting
 208         for any locks.
 209       </column>
 210
 211       <column name="status" key="locks_lost">
 212         Space-separated list of the names of OVSDB locks that the connection
 213         has had stolen by another OVSDB client.  Omitted if no locks have been
 214         stolen from this connection.
 215       </column>
 216
 217       <column name="status" key="n_connections"
 218               type='{"type": "integer", "minInteger": 2}'>
 219         <p>
 220           When <ref column="target"/> specifies a connection method that
 221           listens for inbound connections (e.g. <code>ptcp:</code> or
 222           <code>pssl:</code>) and more than one connection is actually active,
 223           the value is the number of active connections.  Otherwise, this
 224           key-value pair is omitted.
 225         </p>
 226         <p>
 227           When multiple connections are active, status columns and key-value
 228           pairs (other than this one) report the status of one arbitrarily
 229           chosen connection.
 230         </p>
 231       </column>
 232     </group>
 233
 234     <group title="Connection Parameters">
 235       <p>
 236         Additional configuration for a connection between the manager
 237         and the database server.
 238       </p>
 239
 240       <column name="other_config" key="dscp"
 241                 type='{"type": "integer"}'>
 242         The Differentiated Service Code Point (DSCP) is specified using 6 bits
 243         in the Type of Service (TOS) field in the IP header. DSCP provides a
 244         mechanism to classify the network traffic and provide Quality of
 245         Service (QoS) on IP networks.
 246
 247         The DSCP value specified here is used when establishing the
 248         connection between the manager and the database server.  If no
 249         value is specified, a default value of 48 is chosen.  Valid DSCP
 250         values must be in the range 0 to 63.
 251       </column>
 252     </group>
 253   </table>
 254
 255   <table name="Physical_Switch" title="A physical switch.">
 256     A physical switch that implements a VTEP.
 257
 258     <column name="ports">
 259       The physical ports within the switch.
 260     </column>
 261
 262     <column name="tunnels">
 263       Tunnels created by this switch as instructed by the NVC.
 264     </column>
 265
 266     <group title="Network Status">
 267       <column name="management_ips">
 268         IPv4 or IPv6 addresses at which the switch may be contacted
 269         for management purposes.
 270       </column>
 271
 272       <column name="tunnel_ips">
 273         <p>
 274           IPv4 or IPv6 addresses on which the switch may originate or
 275           terminate tunnels.
 276         </p>
 277
 278         <p>
 279           This column is intended to allow a <ref table="Manager"/> to
 280           determine the <ref table="Physical_Switch"/> that terminates
 281           the tunnel represented by a <ref table="Physical_Locator"/>.
 282         </p>
 283       </column>
 284     </group>
 285
 286     <group title="Identification">
 287       <column name="name">
 288         Symbolic name for the switch, such as its hostname.
 289       </column>
 290
 291       <column name="description">
 292         An extended description for the switch, such as its switch login
 293         banner.
 294       </column>
 295     </group>
 296     <group title="Error Notification">
 297       <p>
 298         An entry in this column indicates to the NVC that this switch
 299         has encountered a fault. The switch must clear this column
 300         when the fault has been cleared.
 301       </p>
 302
 303       <column name="switch_fault_status" key="mac_table_exhaustion">
 304         Indicates that the switch has been unable to process MAC
 305         entries requested by the NVC due to lack of table resources.
 306       </column>
 307
 308       <column name="switch_fault_status" key="tunnel_exhaustion">
 309         Indicates that the switch has been unable to create tunnels
 310         requested by the NVC due to lack of resources.
 311       </column>
 312
 313       <column name="switch_fault_status" key="unspecified_fault">
 314         Indicates that an error has occurred in the switch but that no
 315         more specific information is available.
 316       </column>
 317
 318     </group>
 319   </table>
 320
 321   <table name="Tunnel" title="A tunnel created by a physical switch.">
 322     A tunnel created by a <ref table="Physical_Switch"/>.
 323
 324     <column name="local">
 325       Tunnel end-point local to the physical switch.
 326     </column>
 327
 328     <column name="remote">
 329       Tunnel end-point remote to the physical switch.
 330     </column>
 331
 332     <group title="Bidirectional Forwarding Detection (BFD)">
 333       <p>
 334         BFD, defined in RFC 5880, allows point to point detection of
 335         connectivity failures by occasional transmission of BFD control
 336         messages. VTEPs are expected to implement BFD.
 337       </p>
 338
 339       <p>
 340         BFD operates by regularly transmitting BFD control messages at a
 341         rate negotiated independently in each direction.  Each endpoint
 342         specifies the rate at which it expects to receive control messages,
 343         and the rate at which it's willing to transmit them.  An endpoint
 344         which fails to receive BFD control messages for a period of three
 345         times the expected reception rate will signal a connectivity
 346         fault.  In the case of a unidirectional connectivity issue, the
 347         system not receiving BFD control messages will signal the problem
 348         to its peer in the messages it transmits.
 349       </p>
 350
 351       <p>
 352         A hardware VTEP is expected to use BFD to determine reachability of
 353         devices at the end of the tunnels with which it exchanges data. This
 354         can enable the VTEP to choose a functioning service node among a set of
 355         service nodes providing high availability. It also enables the NVC to
 356         report the health status of tunnels.
 357       </p>
 358
 359       <p>
 360         In most cases the BFD peer of a hardware VTEP will be an Open vSwitch
 361         instance. The Open vSwitch implementation of BFD aims to comply
 362         faithfully with the requirements put forth in RFC 5880.  Open vSwitch
 363         does not implement the optional Authentication or ``Echo Mode''
 364         features.
 365       </p>
 366
 367       <group title="BFD Local Configuration">
 368         <p>
 369           The HSC writes the key-value pairs in the
 370           <ref column="bfd_config_local"/> column to specify the local
 371           configurations to be used for BFD sessions on this tunnel.
 372         </p>
 373
 374         <column name="bfd_config_local" key="bfd_dst_mac">
 375           Set to an Ethernet address in the form
 376           <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
 377           to set the MAC expected as destination for received BFD packets.
 378           The default is <code>00:23:20:00:00:01</code>.
 379         </column>
 380
 381         <column name="bfd_config_local" key="bfd_dst_ip">
 382           Set to an IPv4 address to set the IP address that is expected as destination
 383           for received BFD packets.  The default is <code>169.254.1.0</code>.
 384         </column>
 385
 386       </group>
 387
 388       <group title="BFD Remote Configuration">
 389         <p>
 390           The <ref column="bfd_config_remote"/> column is the remote
 391           counterpart of the <ref column="bfd_config_local"/> column.
 392           The NVC writes the key-value pairs in this column.
 393         </p>
 394
 395         <column name="bfd_config_remote" key="bfd_dst_mac">
 396           Set to an Ethernet address in the form
 397           <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
 398           to set the destination MAC to be used for transmitted BFD packets.
 399           The default is <code>00:23:20:00:00:01</code>.
 400         </column>
 401
 402         <column name="bfd_config_remote" key="bfd_dst_ip">
 403           Set to an IPv4 address to set the IP address used as destination
 404           for transmitted BFD packets.  The default is <code>169.254.1.1</code>.
 405         </column>
 406
 407       </group>
 408
 409       <group title="BFD Parameters">
 410         <p>
 411           The NVC sets up key-value pairs in the <ref column="bfd_params"/>
 412           column to enable and configure BFD.
 413         </p>
 414
 415         <column name="bfd_params" key="enable" type='{"type": "boolean"}'>
 416           True to enable BFD on this tunnel.
 417           The default is False.
 418         </column>
 419
 420         <column name="bfd_params" key="min_rx"
 421                 type='{"type": "integer", "minInteger": 1}'>
 422           The shortest interval, in milliseconds, at which this BFD session
 423           offers to receive BFD control messages.  The remote endpoint may
 424           choose to send messages at a slower rate.  Defaults to
 425           <code>1000</code>.
 426         </column>
 427
 428         <column name="bfd_params" key="min_tx"
 429                 type='{"type": "integer", "minInteger": 1}'>
 430           The shortest interval, in milliseconds, at which this BFD session is
 431           willing to transmit BFD control messages.  Messages will actually be
 432           transmitted at a slower rate if the remote endpoint is not willing to
 433           receive as quickly as specified.  Defaults to <code>100</code>.
 434         </column>
 435
 436         <column name="bfd_params" key="decay_min_rx" type='{"type": "integer"}'>
 437           An alternate receive interval, in milliseconds, that must be greater
 438           than or equal to <ref column="bfd" key="min_rx"/>.  The
 439           implementation switches from <ref column="bfd" key="min_rx"/> to <ref
 440           column="bfd" key="decay_min_rx"/> when there is no obvious incoming
 441           data traffic at the interface, to reduce the CPU and bandwidth cost
 442           of monitoring an idle interface.  This feature may be disabled by
 443           setting a value of 0.  This feature is reset whenever <ref
 444           column="bfd" key="decay_min_rx"/> or <ref column="bfd" key="min_rx"/>
 445           changes.
 446         </column>
 447
 448         <column name="bfd_params" key="forwarding_if_rx" type='{"type": "boolean"}'>
 449           True to consider the interface capable of packet I/O as long as it
 450           continues to receive any packets (not just BFD packets).  This
 451           prevents link congestion that causes consecutive BFD control packets
 452           to be lost from marking the interface down.
 453         </column>
 454
 455         <column name="bfd_params" key="cpath_down" type='{"type": "boolean"}'>
 456           Set to true to notify the remote endpoint that traffic should not be
 457           forwarded to this system for some reason other than a connectivity
 458           failure on the interface being monitored.  The typical underlying
 459           reason is ``concatenated path down,'' that is, that connectivity
 460           beyond the local system is down.  Defaults to false.
 461         </column>
 462
 463         <column name="bfd_params" key="check_tnl_key" type='{"type": "boolean"}'>
 464           Set to true to make BFD accept only control messages with a tunnel
 465           key of zero.  By default, BFD accepts control messages with any
 466           tunnel key.
 467         </column>
 468
 469       </group>
 470
 471      <group title="BFD Status">
 472       <p>
 473         The VTEP sets key-value pairs in the <ref column="bfd_status"/>
 474         column to report the status of BFD on this tunnel.  When BFD is
 475         not enabled, with <ref column="bfd_params" key="enable"/>, the
 476         HSC clears all key-value pairs from <ref column="bfd_status"/>.
 477       </p>
 478
 479       <column name="bfd_status" key="enabled"
 480         type='{"type": "boolean"}'>
 481         Set to true if the BFD session has been successfully
 482         enabled. Set to false if the VTEP cannot support BFD or has
 483         insufficient resources to enable BFD on this tunnel. The NVC
 484         will disable the BFD monitoring on the other side of the tunnel
 485         once this value is set to false.
 486       </column>
 487
 488       <column name="bfd_status" key="state"
 489         type='{"type": "string",
 490               "enum": ["set", ["admin_down", "down", "init", "up"]]}'>
 491         Reports the state of the BFD session.  The BFD session is fully
 492         healthy and negotiated if <code>UP</code>.
 493       </column>
 494
 495       <column name="bfd_status" key="forwarding" type='{"type": "boolean"}'>
 496         Reports whether the BFD session believes this tunnel
 497         may be used to forward traffic.  Typically this means the local session
 498         is signaling <code>UP</code>, and the remote system isn't signaling a
 499         problem such as concatenated path down.
 500       </column>
 501
 502       <column name="bfd_status" key="diagnostic">
 503         In case of a problem, set to an error message that reports what the
 504         local BFD session thinks is wrong.  The error messages are defined
 505         in section 4.1 of [RFC 5880].
 506       </column>
 507
 508       <column name="bfd_status" key="remote_state"
 509         type='{"type": "string",
 510               "enum": ["set", ["admin_down", "down", "init", "up"]]}'>
 511         Reports the state of the remote endpoint's BFD session.
 512       </column>
 513
 514       <column name="bfd_status" key="remote_diagnostic">
 515         In case of a problem, set to an error message that reports what the
 516         remote endpoint's BFD session thinks is wrong.  The error messages
 517         are defined in section 4.1 of [RFC 5880].
 518       </column>
 519
 520       <column name="bfd_status" key="info">
 521         A short message providing further information about the BFD status
 522         (possibly including reasons why BFD could not be enabled).
 523       </column>
 524       </group>
 525     </group>
 526   </table>
 527
 528   <table name="Physical_Port" title="A port within a physical switch.">
 529     A port within a <ref table="Physical_Switch"/>.
 530
 531     <column name="vlan_bindings">
 532       Identifies how VLANs on the physical port are bound to logical switches.
 533       If, for example, the map contains a (VLAN, logical switch) pair, a packet
 534       that arrives on the port in the VLAN is considered to belong to the
 535       paired logical switch. A value of zero in the VLAN field means
 536       that untagged traffic on the physical port is mapped to the
 537       logical switch.
 538     </column>
 539
 540     <column name="vlan_stats">
 541       Statistics for VLANs bound to logical switches on the physical port.  An
 542       implementation that fully supports such statistics would populate this
 543       column with a mapping for every VLAN that is bound in <ref
 544       column="vlan_bindings"/>.  An implementation that does not support such
 545       statistics or only partially supports them would not populate this column
 546       or partially populate it, respectively. A value of zero in the
 547       VLAN field refers to untagged traffic on the physical port.
 548     </column>
 549
 550     <group title="Identification">
 551       <column name="name">
 552         Symbolic name for the port.  The name ought to be unique within a given
 553         <ref table="Physical_Switch"/>, but the database is not capable of
 554         enforcing this.
 555       </column>
 556
 557       <column name="description">
 558         An extended description for the port.
 559       </column>
 560     </group>
 561     <group title="Error Notification">
 562       <p>
 563         An entry in this column indicates to the NVC that the physical port has
 564         encountered a fault. The switch must clear this column when the error
 565         has been cleared.
 566       </p>
 567       <column name="port_fault_status" key="invalid_vlan_map">
 568         <p>
 569           Indicates that a VLAN-to-logical-switch mapping requested by
 570           the controller could not be instantiated by the switch
 571           because of a conflict with local configuration.
 572         </p>
 573       </column>
 574       <column name="port_fault_status" key="unspecified_fault">
 575         <p>
 576           Indicates that an error has occurred on the port but that no
 577           more specific information is available.
 578         </p>
 579       </column>
 580     </group>
 581
 582   </table>
 583
 584   <table name="Logical_Binding_Stats" title="Statistics for a VLAN on a physical port bound to a logical network.">
 585     Reports statistics for the <ref table="Logical_Switch"/> with which a VLAN
 586     on a <ref table="Physical_Port"/> is associated.
 587
 588     <group title="Statistics">
 589       These statistics count only packets to which the binding applies.
 590
 591       <column name="packets_from_local">
 592         Number of packets sent by the <ref table="Physical_Switch"/>.
 593       </column>
 594
 595       <column name="bytes_from_local">
 596         Number of bytes in packets sent by the <ref table="Physical_Switch"/>.
 597       </column>
 598
 599       <column name="packets_to_local">
 600         Number of packets received by the <ref table="Physical_Switch"/>.
 601       </column>
 602
 603       <column name="bytes_to_local">
 604         Number of bytes in packets received by the <ref
 605         table="Physical_Switch"/>.
 606       </column>
 607     </group>
 608   </table>
 609
 610   <table name="Logical_Switch" title="A layer-2 domain.">
 611     A logical Ethernet switch, whose implementation may span physical and
 612     virtual media, possibly crossing L3 domains via tunnels; a logical layer-2
 613     domain; an Ethernet broadcast domain.
 614
 615
 616
 617     <group title="Per Logical-Switch Tunnel Key">
 618       <p>
 619         Tunnel protocols tend to have a field that allows the tunnel
 620         to be partitioned into sub-tunnels: VXLAN has a VNI, GRE and
 621         STT have a key, CAPWAP has a WSI, and so on.  We call these
 622         generically ``tunnel keys.''  Given that one needs to use a
 623         tunnel key at all, there are at least two reasonable ways to
 624         assign their values:
 625       </p>
 626
 627       <ul>
 628         <li>
 629           <p>
 630             Per <ref table="Logical_Switch"/>+<ref table="Physical_Locator"/>
 631             pair.  That is, each logical switch may be assigned a different
 632             tunnel key on every <ref table="Physical_Locator"/>.  This model is
 633             especially flexible.
 634           </p>
 635
 636           <p>
 637             In this model, <ref table="Physical_Locator"/> carries the tunnel
 638             key.  Therefore, one <ref table="Physical_Locator"/> record will
 639             exist for each logical switch carried at a given IP destination.
 640           </p>
 641         </li>
 642
 643         <li>
 644           <p>
 645             Per <ref table="Logical_Switch"/>.  That is, every tunnel
 646             associated with a particular logical switch carries the same tunnel
 647             key, regardless of the <ref table="Physical_Locator"/> to which the
 648             tunnel is addressed.  This model may ease switch implementation
 649             because it imposes fewer requirements on the hardware datapath.
 650           </p>
 651
 652           <p>
 653             In this model, <ref table="Logical_Switch"/> carries the tunnel
 654             key.  Therefore, one <ref table="Physical_Locator"/> record will
 655             exist for each IP destination.
 656           </p>
 657         </li>
 658       </ul>
 659
 660       <column name="tunnel_key">
 661         <p>
 662           This column is used only in the tunnel key per <ref
 663           table="Logical_Switch"/> model (see above), because only in that
 664           model is there a tunnel key associated with a logical switch.
 665         </p>
 666
 667         <p>
 668           For <code>vxlan_over_ipv4</code> encapsulation, this column
 669           is the VXLAN VNI that identifies a logical switch.  It must
 670           be in the range 0 to 16,777,215.
 671         </p>
 672       </column>
 673     </group>
 674
 675     <group title="Identification">
 676       <column name="name">
 677         Symbolic name for the logical switch.
 678       </column>
 679
 680       <column name="description">
 681         An extended description for the logical switch, such as its switch
 682         login banner.
 683       </column>
 684     </group>
 685   </table>
 686
 687   <table name="Ucast_Macs_Local" title="Unicast MACs (local)">
 688     <p>
 689       Mapping of unicast MAC addresses to tunnels (physical
 690       locators). This table is written by the HSC, so it contains the
 691       MAC addresses that have been learned on physical ports by a
 692       VTEP.
 693     </p>
 694
 695     <column name="MAC">
 696       A MAC address that has been learned by the VTEP.
 697     </column>
 698
 699     <column name="logical_switch">
 700       The Logical switch to which this mapping applies.
 701     </column>
 702
 703     <column name="locator">
 704       The physical locator to be used to reach this MAC address. In
 705       this table, the physical locator will be one of the tunnel IP
 706       addresses of the appropriate VTEP.
 707     </column>
 708
 709     <column name="ipaddr">
 710       The IP address to which this MAC corresponds. Optional field for
 711       the purpose of ARP supression.
 712     </column>
 713
 714   </table>
 715
 716  <table name="Ucast_Macs_Remote" title="Unicast MACs (remote)">
 717     <p>
 718       Mapping of unicast MAC addresses to tunnels (physical
 719       locators). This table is written by the NVC, so it contains the
 720       MAC addresses that the NVC has learned. These include VM MAC
 721       addresses, in which case the physical locators will be
 722       hypervisor IP addresses. The NVC will also report MACs that it
 723       has learned from other HSCs in the network, in which case the
 724       physical locators will be tunnel IP addresses of the
 725       corresponding VTEPs.
 726     </p>
 727
 728     <column name="MAC">
 729       A MAC address that has been learned by the NVC.
 730     </column>
 731
 732     <column name="logical_switch">
 733       The Logical switch to which this mapping applies.
 734     </column>
 735
 736     <column name="locator">
 737       The physical locator to be used to reach this MAC address. In
 738       this table, the physical locator will be either a hypervisor IP
 739       address or a tunnel IP addresses of another VTEP.
 740     </column>
 741
 742     <column name="ipaddr">
 743       The IP address to which this MAC corresponds. Optional field for
 744       the purpose of ARP supression.
 745     </column>
 746
 747   </table>
 748
 749   <table name="Mcast_Macs_Local" title="Multicast MACs (local)">
 750     <p>
 751       Mapping of multicast MAC addresses to tunnels (physical
 752       locators). This table is written by the HSC, so it contains the
 753       MAC addresses that have been learned on physical ports by a
 754       VTEP. These may be learned by IGMP snooping, for example. This
 755       table also specifies how to handle unknown unicast and broadcast packets.
 756     </p>
 757
 758     <column name="MAC">
 759       <p>
 760         A MAC address that has been learned by the VTEP.
 761       </p>
 762       <p>
 763         The keyword <code>unknown-dst</code> is used as a special
 764         ``Ethernet address'' that indicates the locations to which
 765         packets in a logical switch whose destination addresses do not
 766         otherwise appear in <ref table="Ucast_Macs_Local"/> (for
 767         unicast addresses) or <ref table="Mcast_Macs_Local"/> (for
 768         multicast addresses) should be sent.
 769       </p>
 770     </column>
 771
 772     <column name="logical_switch">
 773       The Logical switch to which this mapping applies.
 774     </column>
 775
 776     <column name="locator_set">
 777       The physical locator set to be used to reach this MAC address. In
 778       this table, the physical locator set will be contain one or more tunnel IP
 779       addresses of the appropriate VTEP(s).
 780     </column>
 781
 782     <column name="ipaddr">
 783       The IP address to which this MAC corresponds. Optional field for
 784       the purpose of ARP supression.
 785     </column>
 786   </table>
 787
 788   <table name="Mcast_Macs_Remote" title="Multicast MACs (remote)">
 789     <p>
 790       Mapping of multicast MAC addresses to tunnels (physical
 791       locators). This table is written by the NVC, so it contains the
 792       MAC addresses that the NVC has learned. This
 793       table also specifies how to handle unknown unicast and broadcast
 794       packets.
 795     </p>
 796     <p>
 797       Multicast packet replication may be handled by a service node,
 798       in which case the physical locators will be IP addresses of
 799       service nodes. If the VTEP supports replication onto multiple
 800       tunnels, then this may be used to replicate directly onto
 801       VTEP-hypervisor tunnels.
 802     </p>
 803
 804     <column name="MAC">
 805       <p>
 806         A MAC address that has been learned by the NVC.
 807       </p>
 808       <p>
 809         The keyword <code>unknown-dst</code> is used as a special
 810         ``Ethernet address'' that indicates the locations to which
 811         packets in a logical switch whose destination addresses do not
 812         otherwise appear in <ref table="Ucast_Macs_Remote"/> (for
 813         unicast addresses) or <ref table="Mcast_Macs_Remote"/> (for
 814         multicast addresses) should be sent.
 815       </p>
 816     </column>
 817
 818     <column name="logical_switch">
 819       The Logical switch to which this mapping applies.
 820     </column>
 821
 822     <column name="locator_set">
 823       The physical locator set to be used to reach this MAC address. In
 824       this table, the physical locator set will be either a service node IP
 825       address or a set of tunnel IP addresses of hypervisors (and
 826       potentially other VTEPs).
 827     </column>
 828
 829     <column name="ipaddr">
 830       The IP address to which this MAC corresponds. Optional field for
 831       the purpose of ARP supression.
 832     </column>
 833
 834   </table>
 835
 836   <table name="Logical_Router" title="A logical L3 router.">
 837     <p>
 838       A logical router, or VRF. A logical router may be connected to one or more
 839       logical switches. Subnet addresses and interface addresses may be configured on the
 840       interfaces.
 841     </p>
 842
 843     <column name="switch_binding">
 844       Maps from an IPv4 or IPv6 address prefix in CIDR notation to a
 845       logical switch. Multiple prefixes may map to the same switch. By
 846       writing a 32-bit (or 128-bit for v6) address with a /N prefix
 847       length, both the router's interface address and the subnet
 848       prefix can be configured. For example, 192.68.1.1/24 creates a
 849       /24 subnet for the logical switch attached to the interface and
 850       assigns the address 192.68.1.1 to the router interface.
 851     </column>
 852
 853     <column name="static_routes">
 854       One or more static routes, mapping IP prefixes to next hop IP addresses.
 855     </column>
 856
 857     <group title="Identification">
 858       <column name="name">
 859         Symbolic name for the logical router.
 860       </column>
 861
 862       <column name="description">
 863         An extended description for the logical router.
 864       </column>
 865     </group>
 866   </table>
 867
 868   <table name="Arp_Sources_Local" title="ARP source addresses for logical routers">
 869     <p>
 870       MAC address to be used when a VTEP issues ARP requests on behalf
 871       of a logical router.
 872     </p>
 873
 874     <p>
 875       A distributed logical router is implemented by a set of VTEPs
 876       (both hardware VTEPs and vswitches). In order for a given VTEP
 877       to populate the local ARP cache for a logical router, it issues
 878       ARP requests with a source MAC address that is unique to the VTEP. A
 879       single per-VTEP MAC can be re-used across all logical
 880       networks. This table contains the MACs that are used by the
 881       VTEPs of a given HSC. The table provides the mapping from MAC to
 882       physical locator for each VTEP so that replies to the ARP
 883       requests can be sent back to the correct VTEP using the
 884       appropriate physical locator.
 885     </p>
 886
 887     <column name="src_mac">
 888       The source MAC to be used by a given VTEP.
 889     </column>
 890
 891     <column name="locator">
 892       The <ref table="Physical_Locator"/> to use for replies to ARP
 893       requests from this MAC address.
 894     </column>
 895   </table>
 896
 897   <table name="Arp_Sources_Remote" title="ARP source addresses for logical routers">
 898     <p>
 899       MAC address to be used when a remote VTEP issues ARP requests on behalf
 900       of a logical router.
 901     </p>
 902
 903     <p>
 904       This table is the remote counterpart of <ref
 905       table="Arp_sources_local"/>. The NVC writes this table to notify
 906       the HSC of the MACs that will be used by remote VTEPs when they
 907       issue ARP requests on behalf of a distributed logical router.
 908     </p>
 909
 910     <column name="src_mac">
 911       The source MAC to be used by a given VTEP.
 912     </column>
 913
 914     <column name="locator">
 915       The <ref table="Physical_Locator"/> to use for replies to ARP
 916       requests from this MAC address.
 917     </column>
 918   </table>
 919
 920   <table name="Physical_Locator_Set">
 921     <p>
 922       A set of one or more <ref table="Physical_Locator"/>s.
 923     </p>
 924
 925     <p>
 926       This table exists only because OVSDB does not have a way to
 927       express the type ``map from string to one or more <ref
 928       table="Physical_Locator"/> records.''
 929     </p>
 930
 931     <column name="locators"/>
 932   </table>
 933
 934   <table name="Physical_Locator">
 935     <p>
 936       Identifies an endpoint to which logical switch traffic may be
 937       encapsulated and forwarded.
 938     </p>
 939
 940     <p>
 941       For the <code>vxlan_over_ipv4</code> encapsulation, the only
 942       encapsulation defined so far, all endpoints associated with a given <ref
 943       table="Logical_Switch"/> must use a common tunnel key, which is carried
 944       in the <ref table="Logical_Switch" column="tunnel_key"/> column of <ref
 945       table="Logical_Switch"/>.
 946     </p>
 947
 948     <p>
 949       For some encapsulations yet to be defined, we expect <ref
 950       table="Physical_Locator"/> to identify both an endpoint and a tunnel key.
 951       When the first such encapsulation is defined, we expect to add a
 952       ``tunnel_key'' column to <ref table="Physical_Locator"/> to allow the
 953       tunnel key to be defined.
 954     </p>
 955
 956     <p>
 957       See the ``Per Logical-Switch Tunnel Key'' section in the <ref
 958       table="Logical_Switch"/> table for further discussion of the model.
 959     </p>
 960
 961     <column name="encapsulation_type">
 962       The type of tunneling encapsulation.
 963     </column>
 964
 965     <column name="dst_ip">
 966       <p>
 967         For <code>vxlan_over_ipv4</code> encapsulation, the IPv4 address of the
 968         VXLAN tunnel endpoint.
 969       </p>
 970
 971       <p>
 972         We expect that this column could be used for IPv4 or IPv6 addresses in
 973         encapsulations to be introduced later.
 974       </p>
 975     </column>
 976
 977   </table>
 978
 979 </database>