docs/ovsdb-developer-guide.rst

   1 OVSDB Developer Guide
   2 =====================
   3
   4 OVSDB Integration
   5 -----------------
   6
   7 The Open vSwitch database (OVSDB) Southbound Plugin component for
   8 OpenDaylight implements the OVSDB `RFC
   9 7047 <https://tools.ietf.org/html/rfc7047>`__ management protocol that
  10 allows the southbound configuration of switches that support OVSDB. The
  11 component comprises a library and a plugin. The OVSDB protocol uses
  12 JSON-RPC calls to manipulate a physical or virtual switch that supports
  13 OVSDB. Many vendors support OVSDB on various hardware platforms. The
  14 OpenDaylight controller uses the library project to interact with an OVS
  15 instance.
  16
  17 .. note::
  18
  19     Read the OVSDB User Guide before you begin development.
  20
  21 OpenDaylight OVSDB southbound plugin architecture and design
  22 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  23
  24 OpenVSwitch (OVS) is generally accepted as the unofficial standard for
  25 Virtual Switching in the Open hypervisor based solutions. Every other
  26 Virtual Switch implementation, properietery or otherwise, uses OVS in
  27 some form. For information on OVS, see `Open
  28 vSwitch <http://openvswitch.org/>`__.
  29
  30 In Software Defined Networking (SDN), controllers and applications
  31 interact using two channels: OpenFlow and OVSDB. OpenFlow addresses the
  32 forwarding-side of the OVS functionality. OVSDB, on the other hand,
  33 addresses the management-plane. A simple and concise overview of Open
  34 Virtual Switch Database(OVSDB) is available at:
  35 http://networkstatic.net/getting-started-ovsdb/
  36
  37 Overview of OpenDaylight Controller architecture
  38 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  39
  40 The OpenDaylight controller platform is designed as a highly modular and
  41 plugin based middleware that serves various network applications in a
  42 variety of use-cases. The modularity is achieved through the Java OSGi
  43 framework. The controller consists of many Java OSGi bundles that work
  44 together to provide the required controller functionalities.
  45
  46 | The bundles can be placed in the following broad categories:
  47
  48 -  Network Service Functional Modules (Examples: Topology Manager,
  49    Inventory Manager, Forwarding Rules Manager,and others)
  50
  51 -  NorthBound API Modules (Examples: Topology APIs, Bridge Domain APIs,
  52    Neutron APIs, Connection Manager APIs, and others)
  53
  54 -  Service Abstraction Layer(SAL)- (Inventory Services, DataPath
  55    Services, Topology Services, Network Config, and others)
  56
  57 -  SouthBound Plugins (OpenFlow Plugin, OVSDB Plugin, OpenDove Plugin,
  58    and others)
  59
  60 -  Application Modules (Simple Forwarding, Load Balancer)
  61
  62 Each layer of the Controller architecture performs specified tasks, and
  63 hence aids in modularity. While the Northbound API layer addresses all
  64 the REST-Based application needs, the SAL layer takes care of
  65 abstracting the SouthBound plugin protocol specifics from the Network
  66 Service functions.
  67
  68 Each of the SouthBound Plugins serves a different purpose, with some
  69 overlapping. For example, the OpenFlow plugin might serve the Data-Plane
  70 needs of an OVS element, while the OVSDB plugin can serve the management
  71 plane needs of the same OVS element. As the OpenFlow Plugin talks
  72 OpenFlow protocol with the OVS element, the OVSDB plugin will use OVSDB
  73 schema over JSON-RPC transport.
  74
  75 OVSDB southbound plugin
  76 ~~~~~~~~~~~~~~~~~~~~~~~
  77
  78 | The `Open vSwitch Database Management
  79   Protocol-draft-02 <http://tools.ietf.org/html/draft-pfaff-ovsdb-proto-02>`__
  80   and `Open vSwitch
  81   Manual <http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf>`__ provide
  82   theoretical information about OVSDB. The OVSDB protocol draft is
  83   generic enough to lay the groundwork on Wire Protocol and Database
  84   Operations, and the OVS Manual currently covers 13 tables leaving
  85   space for future OVS expansion, and vendor expansions on proprietary
  86   implementations. The OVSDB Protocol is a database records transport
  87   protocol using JSON RPC1.0. For information on the protocol structure,
  88   see `Getting Started with
  89   OVSDB <http://networkstatic.net/getting-started-ovsdb/>`__. The
  90   OpenDaylight OVSDB southbound plugin consists of one or more OSGi
  91   bundles addressing the following services or functionalities:
  92
  93 -  Connection Service - Based on Netty
  94
  95 -  Network Configuration Service
  96
  97 -  Bidirectional JSON-RPC Library
  98
  99 -  OVSDB Schema definitions and Object mappers
 100
 101 -  Overlay Tunnel management
 102
 103 -  OVSDB to OpenFlow plugin mapping service
 104
 105 -  Inventory Service
 106
 107 Connection service
 108 ~~~~~~~~~~~~~~~~~~
 109
 110 | One of the primary services that most southbound plugins provide in
 111   OpenDaylight a Connection Service. The service provides protocol
 112   specific connectivity to network elements, and supports the
 113   connectivity management services as specified by the OpenDaylight
 114   Connection Manager. The connectivity services include:
 115
 116 -  Connection to a specified element given IP-address, L4-port, and
 117    other connectivity options (such as authentication,…)
 118
 119 -  Disconnection from an element
 120
 121 -  Handling Cluster Mode change notifications to support the
 122    OpenDaylight Clustering/High-Availability feature
 123
 124 Network Configuration Service
 125 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 126
 127 | The goal of the OpenDaylight Network Configuration services is to
 128   provide complete management plane solutions needed to successfully
 129   install, configure, and deploy the various SDN based network services.
 130   These are generic services which can be implemented in part or full by
 131   any south-bound protocol plugin. The south-bound plugins can be either
 132   of the following:
 133
 134 -  The new network virtualization protocol plugins such as OVSDB
 135    JSON-RPC
 136
 137 -  The traditional management protocols such as SNMP or any others in
 138    the middle.
 139
 140 The above definition, and more information on Network Configuration
 141 Services, is available at :
 142 https://wiki.opendaylight.org/view/OpenDaylight_Controller:NetworkConfigurationServices
 143
 144 Bidirectional JSON-RPC library
 145 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 146
 147 The OVSDB plugin implements a Bidirectional JSON-RPC library. It is easy
 148 to design the library as a module that manages the Netty connection
 149 towards the Element.
 150
 151 | The main responsibilities of this Library are:
 152
 153 -  Demarshal and marshal JSON Strings to JSON objects
 154
 155 -  Demarshal and marshal JSON Strings from and to the Network Element.
 156
 157 OVSDB Schema definitions and Object mappers
 158 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 159
 160 The OVSDB Schema definitions and Object Mapping layer sits above the
 161 JSON-RPC library. It maps the generic JSON objects to OVSDB schema POJOs
 162 (Plain Old Java Object) and vice-versa. This layer mostly provides the
 163 Java Object definition for the corresponding OVSDB schema (13 of them)
 164 and also will provide much more friendly API abstractions on top of
 165 these object data. This helps in hiding the JSON semantics from the
 166 functional modules such as Configuration Service and Tunnel management.
 167
 168 | On the demarshaling side the mapping logic differentiates the Request
 169   and Response messages as follows :
 170
 171 -  Request messages are mapped by its "method"
 172
 173 -  | Response messages are mapped by their IDs which were originally
 174      populated by the Request message. The JSON semantics of these OVSDB
 175      schema is quite complex. The following figures summarize two of the
 176      end-to-end scenarios:
 177
 178 .. figure:: ./images/ConfigurationService-example1.png
 179    :alt: End-to-end handling of a Create Bridge request
 180
 181    End-to-end handling of a Create Bridge request
 182
 183 .. figure:: ./images/MonitorResponse.png
 184    :alt: End-to-end handling of a monitor response
 185
 186    End-to-end handling of a monitor response
 187
 188 Overlay tunnel management
 189 ^^^^^^^^^^^^^^^^^^^^^^^^^
 190
 191 Network Virtualization using OVS is achieved through Overlay Tunnels.
 192 The actual Type of the Tunnel may be GRE, VXLAN, or STT. The differences
 193 in the encapsulation and configuration decide the tunnel types.
 194 Establishing a tunnel using configuration service requires just the
 195 sending of OVSDB messages towards the ovsdb-server. However, the scaling
 196 issues that would arise on the state management at the data-plane (using
 197 OpenFlow) can get challenging. Also, this module can assist in various
 198 optimizations in the presence of Gateways. It can also help in providing
 199 Service guarantees for the VMs using these overlays with the help of
 200 underlay orchestration.
 201
 202 OVSDB to OpenFlow plugin mapping service
 203 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 204
 205 | The connect() of the ConnectionService would result in a Node that
 206   represents an ovsdb-server. The CreateBridgeDomain() Configuration on
 207   the above Node would result in creating an OVS bridge. This OVS Bridge
 208   is an OpenFlow Agent for the OpenDaylight OpenFlow plugin with its own
 209   Node represented as (example) OF\|xxxx.yyyy.zzzz. Without any help
 210   from the OVSDB plugin, the Node Mapping Service of the Controller
 211   platform would not be able to map the following:
 212
 213 ::
 214
 215     {OVSDB_NODE + BRIDGE_IDENTFIER} <---> {OF_NODE}.
 216
 217 Without such mapping, it would be extremely difficult for the
 218 applications to manage and maintain such nodes. This Mapping Service
 219 provided by the OVSDB plugin would essentially help in providing more
 220 value added services to the orchestration layers that sit atop the
 221 Northbound APIs (such as OpenStack).
 222
 223 OVSDB: New features
 224 ~~~~~~~~~~~~~~~~~~~
 225
 226 Schema independent library
 227 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 228
 229 The OVS connection is a node which can have multiple databases. Each
 230 database is represented by a schema. A single connection can have
 231 multiple schemas. OSVDB supports multiple schemas. Currently, these are
 232 two schemas available in the OVSDB, but there is no restriction on the
 233 number of schemas. Owing to the Northbound v3 API, no code changes in
 234 ODL are needed for supporting additional schemas.
 235
 236 | Schemas:
 237
 238 -  openvswitch : Schema wrapper that represents
 239    http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf
 240
 241 -  hardwarevtep: Schema wrapper that represents
 242    http://openvswitch.org/docs/vtep.5.pdf
 243
 244 OVSDB Library Developer Guide
 245 -----------------------------
 246
 247 Overview
 248 ~~~~~~~~
 249
 250 The OVSDB library manages the Netty connections to network nodes and
 251 handles bidirectional JSON-RPC messages. It not only provides OVSDB
 252 protocol functionality to OpenDaylight OVSDB plugin but also can be used
 253 as standalone JAVA library for OVSDB protocol.
 254
 255 The main responsibilities of OVSDB library include:
 256
 257 -  Manage connections to peers
 258
 259 -  Marshal and unmarshal JSON Strings to JSON objects.
 260
 261 -  Marshal and unmarshal JSON Strings from and to the Network Element.
 262
 263 Connection Service
 264 ~~~~~~~~~~~~~~~~~~
 265
 266 The OVSDB library provides connection management through the
 267 OvsdbConnection interface. The OvsdbConnection interface provides OVSDB
 268 connection management APIs which include both active and passive
 269 connections. From the library perspective, active OVSDB connections are
 270 initiated from the controller to OVS nodes while passive OVSDB
 271 connections are initiated from OVS nodes to the controller. In the
 272 active connection scenario an application needs to provide the IP
 273 address and listening port of OVS nodes to the library management API.
 274 On the other hand, the library management API only requires the info of
 275 the controller listening port in the passive connection scenario.
 276
 277 For a passive connection scenario, the library also provides a
 278 connection event listener through the OvsdbConnectionListener interface.
 279 The listener interface has connected() and disconnected() methods to
 280 notify an application when a new passive connection is established or an
 281 existing connection is terminated.
 282
 283 SSL Connection
 284 ~~~~~~~~~~~~~~
 285
 286 In addition to a regular TCP connection, the OvsdbConnection interface
 287 also provides a connection management API for an SSL connection. To
 288 start an OVSDB connection with SSL, an application will need to provide
 289 a Java SSLContext object to the management API. There are different ways
 290 to create a Java SSLContext, but in most cases a Java KeyStore with
 291 certificate and private key provided by the application is required.
 292 Detailed steps about how to create a Java SSLContext is out of the scope
 293 of this document and can be found in the Java documentation for `JAVA
 294 Class SSlContext <http://goo.gl/5svszT>`__.
 295
 296 In the active connection scenario, the library uses the given SSLContext
 297 to create a Java SSLEngine and configures the SSL engine with the client
 298 mode for SSL handshaking. Normally clients are not required to
 299 authenticate themselves.
 300
 301 In the passive connection scenario, the library uses the given
 302 SSLContext to create a Java SSLEngine which will operate in server mode
 303 for SSL handshaking. For security reasons, the SSLv3 protocol and some
 304 cipher suites are disabled. Currently the OVSDB server only supports the
 305 TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA cipher suite and the following
 306 protocols: SSLv2Hello, TLSv1, TLSv1.1, TLSv1.2.
 307
 308 The SSL engine is also configured to operate on two-way authentication
 309 mode for passive connection scenarios, i.e., the OVSDB server
 310 (controller) will authenticate clients (OVS nodes) and clients (OVS
 311 nodes) are also required to authenticate the server (controller). In the
 312 two-way authentication mode, an application should keep a trust manager
 313 to store the certificates of trusted clients and initialize a Java
 314 SSLContext with this trust manager. Thus during the SSL handshaking
 315 process the OVSDB server (controller) can use the trust manager to
 316 verify clients and only accept connection requests from trusted clients.
 317 On the other hand, users should also configure OVS nodes to authenticate
 318 the controller. Open vSwitch already supports this functionality in the
 319 ovsdb-server command with option ``--ca-cert=cacert.pem`` and
 320 ``--bootstrap-ca-cert=cacert.pem``. On the OVS node, a user can use the
 321 option ``--ca-cert=cacert.pem`` to specify a controller certificate
 322 directly and the node will only allow connections to the controller with
 323 the specified certificate. If the OVS node runs ovsdb-server with option
 324 ``--bootstrap-ca-cert=cacert.pem``, it will authenticate the controller
 325 with the specified certificate cacert.pem. If the certificate file
 326 doesn’t exist, it will attempt to obtain a certificate from the peer
 327 (controller) on its first SSL connection and save it to the named PEM
 328 file ``cacert.pem``. Here is an example of ovsdb-server with
 329 ``--bootstrap-ca-cert=cacert.pem`` option:
 330
 331 ``ovsdb-server --pidfile --detach --log-file --remote punix:/var/run/openvswitch/db.sock --remote=db:hardware_vtep,Global,managers --private-key=/etc/openvswitch/ovsclient-privkey.pem -- certificate=/etc/openvswitch/ovsclient-cert.pem --bootstrap-ca-cert=/etc/openvswitch/vswitchd.cacert``
 332
 333 OVSDB protocol transactions
 334 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 335
 336 The OVSDB protocol defines the RPC transaction methods in RFC 7047. The
 337 following RPC methods are supported in OVSDB protocol:
 338
 339 -  List databases
 340
 341 -  Get schema
 342
 343 -  Transact
 344
 345 -  Cancel
 346
 347 -  Monitor
 348
 349 -  Update notification
 350
 351 -  Monitor cancellation
 352
 353 -  Lock operations
 354
 355 -  Locked notification
 356
 357 -  Stolen notification
 358
 359 -  Echo
 360
 361 According to RFC 7047, an OVSDB server must implement all methods, and
 362 an OVSDB client is only required to implement the "Echo" method and
 363 otherwise free to implement whichever methods suit its needs. However,
 364 the OVSDB library currently doesn’t support all RPC methods. For the
 365 "Echo" method, the library can handle "Echo" messages from a peer and
 366 send a JSON response message back, but the library doesn’t support
 367 actively sending an "Echo" JSON request to a peer. Other unsupported RPC
 368 methods are listed below:
 369
 370 -  Cancel
 371
 372 -  Lock operations
 373
 374 -  Locked notification
 375
 376 -  Stolen notification
 377
 378 In the OVSDB library the RPC methods are defined in the Java interface
 379 OvsdbRPC. The library also provides a high-level interface OvsdbClient
 380 as the main interface to interact with peers through the OVSDB protocol.
 381 In the passive connection scenario, each connection will have a
 382 corresponding OvsdbClient object, and the application can obtain the
 383 OvsdbClient object through connection listener callback methods. In
 384 other words, if the application implements the OvsdbConnectionListener
 385 interface, it will get notifications of connection status changes with
 386 the corresponding OvsdbClient object of that connection.
 387
 388 OVSDB database operations
 389 ~~~~~~~~~~~~~~~~~~~~~~~~~
 390
 391 RFC 7047 also defines database operations, such as insert, delete, and
 392 update, to be performed as part of a "transact" RPC request. The OVSDB
 393 library defines the data operations in Operations.java and provides the
 394 TransactionBuilder class to help build "transact" RPC requests. To build
 395 a JSON-RPC transact request message, the application can obtain the
 396 TransactionBuilder object through a transactBuilder() method in the
 397 OvsdbClient interface.
 398
 399 The TransactionBuilder class provides the following methods to help
 400 build transactions:
 401
 402 -  getOperations(): Get the list of operations in this transaction.
 403
 404 -  add(): Add data operation to this transaction.
 405
 406 -  build(): Return the list of operations in this transaction. This is
 407    the same as the getOperations() method.
 408
 409 -  execute(): Send the JSON RPC transaction to peer.
 410
 411 -  getDatabaseSchema(): Get the database schema of this transaction.
 412
 413 If the application wants to build and send a "transact" RPC request to
 414 modify OVSDB tables on a peer, it can take the following steps:
 415
 416 1. Statically import parameter "op" in Operations.java
 417
 418    ``import static org.opendaylight.ovsdb.lib.operations.Operations.op;``
 419
 420 2. Obtain transaction builder through transacBuilder() method in
 421    OvsdbClient:
 422
 423    ``TransactionBuilder transactionBuilder = ovsdbClient.transactionBuilder(dbSchema);``
 424
 425 3. Add operations to transaction builder:
 426
 427    ``transactionBuilder.add(op.insert(schema, row));``
 428
 429 4. Send transaction to peer and get JSON RPC response:
 430
 431    ``operationResults = transactionBuilder.execute().get();``
 432
 433    .. note::
 434
 435        Although the "select" operation is supported in the OVSDB
 436        library, the library implementation is a little different from
 437        RFC 7047. In RFC 7047, section 5.2.2 describes the "select"
 438        operation as follows:
 439
 440    “The "rows" member of the result is an array of objects. Each object
 441    corresponds to a matching row, with each column specified in
 442    "columns" as a member, the column’s name as the member name, and its
 443    value as the member value. If "columns" is not specified, all the
 444    table’s columns are included (including the internally generated
 445    "\_uuid" and "\_version" columns).”
 446
 447    The OVSDB library implementation always requires the column’s name in
 448    the "columns" field of a JSON message. If the "columns" field is not
 449    specified, none of the table’s columns are included. If the
 450    application wants to get the table entry with all columns, it needs
 451    to specify all the columns’ names in the "columns" field.
 452
 453 Reference Documentation
 454 ~~~~~~~~~~~~~~~~~~~~~~~
 455
 456 RFC 7047 The Open vSwitch Databse Management Protocol
 457 https://tools.ietf.org/html/rfc7047
 458
 459 OVSDB MD-SAL Southbound Plugin Developer Guide
 460 ----------------------------------------------
 461
 462 Overview
 463 ~~~~~~~~
 464
 465 The Open vSwitch Database (OVSDB) Model Driven Service Abstraction Layer
 466 (MD-SAL) Southbound Plugin provides an MD-SAL based interface to Open
 467 vSwitch systems. This is done by augmenting the MD-SAL topology node
 468 with a YANG model which replicates some (but not all) of the Open
 469 vSwitch schema.
 470
 471 OVSDB MD-SAL Southbound Plugin Architecture and Operation
 472 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 473
 474 The architecture and operation of the OVSDB MD-SAL Southbound plugin is
 475 illustrated in the following set of diagrams.
 476
 477 Connecting to an OVSDB Node
 478 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 479
 480 An OVSDB node is a system which is running the OVS software and is
 481 capable of being managed by an OVSDB manager. The OVSDB MD-SAL
 482 Southbound plugin in OpenDaylight is capable of operating as an OVSDB
 483 manager. Depending on the configuration of the OVSDB node, the
 484 connection of the OVSDB manager can be active or passive.
 485
 486 Active OVSDB Node Manager Workflow
 487 ''''''''''''''''''''''''''''''''''
 488
 489 An active OVSDB node manager connection is made when OpenDaylight
 490 initiates the connection to the OVSDB node. In order for this to work,
 491 you must configure the OVSDB node to listen on a TCP port for the
 492 connection (i.e. OpenDaylight is active and the OVSDB node is passive).
 493 This option can be configured on the OVSDB node using the following
 494 command:
 495
 496 ::
 497
 498     ovs-vsctl set-manager ptcp:6640
 499
 500 The following diagram illustrates the sequence of events which occur
 501 when OpenDaylight initiates an active OVSDB manager connection to an
 502 OVSDB node.
 503
 504 .. figure:: ./images/ovsdb-sb-active-connection.jpg
 505    :alt: Active OVSDB Manager Connection
 506
 507    Active OVSDB Manager Connection
 508
 509 Step 1
 510     Create an OVSDB node by using RESTCONF or an OpenDaylight plugin.
 511     The OVSDB node is listed under the OVSDB topology node.
 512
 513 Step 2
 514     Add the OVSDB node to the OVSDB MD-SAL southbound configuration
 515     datastore. The OVSDB southbound provider is registered to listen for
 516     data change events on the portion of the MD-SAL topology data store
 517     which contains the OVSDB southbound topology node augmentations. The
 518     addition of an OVSDB node causes an event which is received by the
 519     OVSDB Southbound provider.
 520
 521 Step 3
 522     The OVSDB Southbound provider initiates a connection to the OVSDB
 523     node using the connection information provided in the configuration
 524     OVSDB node (i.e. IP address and TCP port number).
 525
 526 Step 4
 527     The OVSDB Southbound provider adds the OVSDB node to the OVSDB
 528     MD-SAL operational data store. The operational data store contains
 529     OVSDB node objects which represent active connections to OVSDB
 530     nodes.
 531
 532 Step 5
 533     The OVSDB Southbound provider requests the schema and databases
 534     which are supported by the OVSDB node.
 535
 536 Step 6
 537     The OVSDB Southbound provider uses the database and schema
 538     information to construct a monitor request which causes the OVSDB
 539     node to send the controller any updates made to the OVSDB databases
 540     on the OVSDB node.
 541
 542 Passive OVSDB Node Manager Workflow
 543 '''''''''''''''''''''''''''''''''''
 544
 545 A passive OVSDB node connection to OpenDaylight is made when the OVSDB
 546 node initiates the connection to OpenDaylight. In order for this to
 547 work, you must configure the OVSDB node to connect to the IP address and
 548 OVSDB port on which OpenDaylight is listening. This option can be
 549 configured on the OVSDB node using the following command:
 550
 551 ::
 552
 553     ovs-vsctl set-manager tcp:<IP address>:6640
 554
 555 The following diagram illustrates the sequence of events which occur
 556 when an OVSDB node connects to OpenDaylight.
 557
 558 .. figure:: ./images/ovsdb-sb-passive-connection.jpg
 559    :alt: Passive OVSDB Manager Connection
 560
 561    Passive OVSDB Manager Connection
 562
 563 Step 1
 564     The OVSDB node initiates a connection to OpenDaylight.
 565
 566 Step 2
 567     The OVSDB Southbound provider adds the OVSDB node to the OVSDB
 568     MD-SAL operational data store. The operational data store contains
 569     OVSDB node objects which represent active connections to OVSDB
 570     nodes.
 571
 572 Step 3
 573     The OVSDB Southbound provider requests the schema and databases
 574     which are supported by the OVSDB node.
 575
 576 Step 4
 577     The OVSDB Southbound provider uses the database and schema
 578     information to construct a monitor request which causes the OVSDB
 579     node to send back any updates which have been made to the OVSDB
 580     databases on the OVSDB node.
 581
 582 OVSDB Node ID in the Southbound Operational MD-SAL
 583 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 584
 585 When OpenDaylight initiates an active connection to an OVSDB node, it
 586 writes an external-id to the Open\_vSwitch table on the OVSDB node. The
 587 external-id is an OpenDaylight instance identifier which identifies the
 588 OVSDB topology node which has just been created. Here is an example
 589 showing the value of the *opendaylight-iid* entry in the external-ids
 590 column of the Open\_vSwitch table where the node-id of the OVSDB node is
 591 *ovsdb:HOST1*.
 592
 593 ::
 594
 595     $ ovs-vsctl list open_vswitch
 596     ...
 597     external_ids        : {opendaylight-iid="/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb:HOST1']"}
 598     ...
 599
 600 The *opendaylight-iid* entry in the external-ids column of the
 601 Open\_vSwitch table causes the OVSDB node to have same node-id in the
 602 operational MD-SAL datastore as in the configuration MD-SAL datastore.
 603 This holds true if the OVSDB node manager settings are subsequently
 604 changed so that a passive OVSDB manager connection is made.
 605
 606 If there is no *opendaylight-iid* entry in the external-ids column and a
 607 passive OVSDB manager connection is made, then the node-id of the OVSDB
 608 node in the operational MD-SAL datastore will be constructed using the
 609 UUID of the Open\_vSwitch table as follows.
 610
 611 ::
 612
 613     "node-id": "ovsdb://uuid/b8dc0bfb-d22b-4938-a2e8-b0084d7bd8c1"
 614
 615 The *opendaylight-iid* entry can be removed from the Open\_vSwitch table
 616 using the following command.
 617
 618 ::
 619
 620     $ sudo ovs-vsctl remove open_vswitch . external-id "opendaylight-iid"
 621
 622 OVSDB Changes by using OVSDB Southbound Config MD-SAL
 623 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 624
 625 After the connection has been made to an OVSDB node, you can make
 626 changes to the OVSDB node by using the OVSDB Southbound Config MD-SAL.
 627 You can make CRUD operations by using the RESTCONF interface or by a
 628 plugin using the MD-SAL APIs. The following diagram illustrates the
 629 high-level flow of events.
 630
 631 .. figure:: ./images/ovsdb-sb-config-crud.jpg
 632    :alt: OVSDB Changes by using the Southbound Config MD-SAL
 633
 634    OVSDB Changes by using the Southbound Config MD-SAL
 635
 636 Step 1
 637     A change to the OVSDB Southbound Config MD-SAL is made. Changes
 638     include adding or deleting bridges and ports, or setting attributes
 639     of OVSDB nodes, bridges or ports.
 640
 641 Step 2
 642     The OVSDB Southbound provider receives notification of the changes
 643     made to the OVSDB Southbound Config MD-SAL data store.
 644
 645 Step 3
 646     As appropriate, OVSDB transactions are constructed and transmitted
 647     to the OVSDB node to update the OVSDB database on the OVSDB node.
 648
 649 Step 4
 650     The OVSDB node sends update messages to the OVSDB Southbound
 651     provider to indicate the changes made to the OVSDB nodes database.
 652
 653 Step 5
 654     The OVSDB Southbound provider maps the changes received from the
 655     OVSDB node into corresponding changes made to the OVSDB Southbound
 656     Operational MD-SAL data store.
 657
 658 Detecting changes in OVSDB coming from outside OpenDaylight
 659 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 660
 661 Changes to the OVSDB nodes database may also occur independently of
 662 OpenDaylight. OpenDaylight also receives notifications for these events
 663 and updates the Southbound operational MD-SAL. The following diagram
 664 illustrates the sequence of events.
 665
 666 .. figure:: ./images/ovsdb-sb-oper-crud.jpg
 667    :alt: OVSDB Changes made directly on the OVSDB node
 668
 669    OVSDB Changes made directly on the OVSDB node
 670
 671 Step 1
 672     Changes are made to the OVSDB node outside of OpenDaylight (e.g.
 673     ovs-vsctl).
 674
 675 Step 2
 676     The OVSDB node constructs update messages to inform OpenDaylight of
 677     the changes made to its databases.
 678
 679 Step 3
 680     The OVSDB Southbound provider maps the OVSDB database changes to
 681     corresponding changes in the OVSDB Southbound operational MD-SAL
 682     data store.
 683
 684 OVSDB Model
 685 ^^^^^^^^^^^
 686
 687 The OVSDB Southbound MD-SAL operates using a YANG model which is based
 688 on the abstract topology node model found in the `network topology
 689 model <https://github.com/opendaylight/yangtools/blob/stable/boron/model/ietf/ietf-topology/src/main/yang/network-topology%402013-10-21.yang>`__.
 690
 691 The augmentations for the OVSDB Southbound MD-SAL are defined in the
 692 `ovsdb.yang <https://github.com/opendaylight/ovsdb/blob/stable/boron/southbound/southbound-api/src/main/yang/ovsdb.yang>`__
 693 file.
 694
 695 There are three augmentations:
 696
 697 **ovsdb-node-augmentation**
 698     This augments the topology node and maps primarily to the
 699     Open\_vSwitch table of the OVSDB schema. It contains the following
 700     attributes.
 701
 702     -  **connection-info** - holds the local and remote IP address and
 703        TCP port numbers for the OpenDaylight to OVSDB node connections
 704
 705     -  **db-version** - version of the OVSDB database
 706
 707     -  **ovs-version** - version of OVS
 708
 709     -  **list managed-node-entry** - a list of references to
 710        ovsdb-bridge-augmentation nodes, which are the OVS bridges
 711        managed by this OVSDB node
 712
 713     -  **list datapath-type-entry** - a list of the datapath types
 714        supported by the OVSDB node (e.g. *system*, *netdev*) - depends
 715        on newer OVS versions
 716
 717     -  **list interface-type-entry** - a list of the interface types
 718        supported by the OVSDB node (e.g. *internal*, *vxlan*, *gre*,
 719        *dpdk*, etc.) - depends on newer OVS verions
 720
 721     -  **list openvswitch-external-ids** - a list of the key/value pairs
 722        in the Open\_vSwitch table external\_ids column
 723
 724     -  **list openvswitch-other-config** - a list of the key/value pairs
 725        in the Open\_vSwitch table other\_config column
 726
 727 **ovsdb-bridge-augmentation**
 728     This augments the topology node and maps to an specific bridge in
 729     the OVSDB bridge table of the associated OVSDB node. It contains the
 730     following attributes.
 731
 732     -  **bridge-uuid** - UUID of the OVSDB bridge
 733
 734     -  **bridge-name** - name of the OVSDB bridge
 735
 736     -  **bridge-openflow-node-ref** - a reference (instance-identifier)
 737        of the OpenFlow node associated with this bridge
 738
 739     -  **list protocol-entry** - the version of OpenFlow protocol to use
 740        with the OpenFlow controller
 741
 742     -  **list controller-entry** - a list of controller-uuid and
 743        is-connected status of the OpenFlow controllers associated with
 744        this bridge
 745
 746     -  **datapath-id** - the datapath ID associated with this bridge on
 747        the OVSDB node
 748
 749     -  **datapath-type** - the datapath type of this bridge
 750
 751     -  **fail-mode** - the OVSDB fail mode setting of this bridge
 752
 753     -  **flow-node** - a reference to the flow node corresponding to
 754        this bridge
 755
 756     -  **managed-by** - a reference to the ovsdb-node-augmentation
 757        (OVSDB node) that is managing this bridge
 758
 759     -  **list bridge-external-ids** - a list of the key/value pairs in
 760        the bridge table external\_ids column for this bridge
 761
 762     -  **list bridge-other-configs** - a list of the key/value pairs in
 763        the bridge table other\_config column for this bridge
 764
 765 **ovsdb-termination-point-augmentation**
 766     This augments the topology termination point model. The OVSDB
 767     Southbound MD-SAL uses this model to represent both the OVSDB port
 768     and OVSDB interface for a given port/interface in the OVSDB schema.
 769     It contains the following attributes.
 770
 771     -  **port-uuid** - UUID of an OVSDB port row
 772
 773     -  **interface-uuid** - UUID of an OVSDB interface row
 774
 775     -  **name** - name of the port
 776
 777     -  **interface-type** - the interface type
 778
 779     -  **list options** - a list of port options
 780
 781     -  **ofport** - the OpenFlow port number of the interface
 782
 783     -  **ofport\_request** - the requested OpenFlow port number for the
 784        interface
 785
 786     -  **vlan-tag** - the VLAN tag value
 787
 788     -  **list trunks** - list of VLAN tag values for trunk mode
 789
 790     -  **vlan-mode** - the VLAN mode (e.g. access, native-tagged,
 791        native-untagged, trunk)
 792
 793     -  **list port-external-ids** - a list of the key/value pairs in the
 794        port table external\_ids column for this port
 795
 796     -  **list interface-external-ids** - a list of the key/value pairs
 797        in the interface table external\_ids interface for this interface
 798
 799     -  **list port-other-configs** - a list of the key/value pairs in
 800        the port table other\_config column for this port
 801
 802     -  **list interface-other-configs** - a list of the key/value pairs
 803        in the interface table other\_config column for this interface
 804
 805 Examples of OVSDB Southbound MD-SAL API
 806 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 807
 808 Connect to an OVSDB Node
 809 ^^^^^^^^^^^^^^^^^^^^^^^^
 810
 811 This example RESTCONF command adds an OVSDB node object to the OVSDB
 812 Southbound configuration data store and attempts to connect to the OVSDB
 813 host located at the IP address 10.11.12.1 on TCP port 6640.
 814
 815 ::
 816
 817     POST http://<host>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/
 818     Content-Type: application/json
 819     {
 820       "node": [
 821          {
 822            "node-id": "ovsdb:HOST1",
 823            "connection-info": {
 824              "ovsdb:remote-ip": "10.11.12.1",
 825              "ovsdb:remote-port": 6640
 826            }
 827          }
 828       ]
 829     }
 830
 831 Query the OVSDB Southbound Configuration MD-SAL
 832 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 833
 834 Following on from the previous example, if the OVSDB Southbound
 835 configuration MD-SAL is queried, the RESTCONF command and the resulting
 836 reply is similar to the following example.
 837
 838 ::
 839
 840     GET http://<host>:8080/restconf/config/network-topology:network-topology/topology/ovsdb:1/
 841     Application/json data in the reply
 842     {
 843       "topology": [
 844         {
 845           "topology-id": "ovsdb:1",
 846           "node": [
 847             {
 848               "node-id": "ovsdb:HOST1",
 849               "ovsdb:connection-info": {
 850                 "remote-port": 6640,
 851                 "remote-ip": "10.11.12.1"
 852               }
 853             }
 854           ]
 855         }
 856       ]
 857     }
 858
 859 Reference Documentation
 860 ~~~~~~~~~~~~~~~~~~~~~~~
 861
 862 `Openvswitch
 863 schema <http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf>`__
 864
 865 OVSDB Hardware VTEP Developer Guide
 866 -----------------------------------
 867
 868 Overview
 869 ~~~~~~~~
 870
 871 TBD
 872
 873 OVSDB Hardware VTEP Architecture
 874 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 875
 876 TBD