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
19 Read the OVSDB User Guide before you begin development.
21 OpenDaylight OVSDB southbound plugin architecture and design
22 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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/>`__.
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/
37 Overview of OpenDaylight Controller architecture
38 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
46 | The bundles can be placed in the following broad categories:
48 - Network Service Functional Modules (Examples: Topology Manager,
49 Inventory Manager, Forwarding Rules Manager,and others)
51 - NorthBound API Modules (Examples: Topology APIs, Bridge Domain APIs,
52 Neutron APIs, Connection Manager APIs, and others)
54 - Service Abstraction Layer(SAL)- (Inventory Services, DataPath
55 Services, Topology Services, Network Config, and others)
57 - SouthBound Plugins (OpenFlow Plugin, OVSDB Plugin, OpenDove Plugin,
60 - Application Modules (Simple Forwarding, Load Balancer)
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
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.
75 OVSDB southbound plugin
76 ~~~~~~~~~~~~~~~~~~~~~~~
78 | The `Open vSwitch Database Management
79 Protocol-draft-02 <http://tools.ietf.org/html/draft-pfaff-ovsdb-proto-02>`__
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:
93 - Connection Service - Based on Netty
95 - Network Configuration Service
97 - Bidirectional JSON-RPC Library
99 - OVSDB Schema definitions and Object mappers
101 - Overlay Tunnel management
103 - OVSDB to OpenFlow plugin mapping service
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:
116 - Connection to a specified element given IP-address, L4-port, and
117 other connectivity options (such as authentication,…)
119 - Disconnection from an element
121 - Handling Cluster Mode change notifications to support the
122 OpenDaylight Clustering/High-Availability feature
124 Network Configuration Service
125 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
134 - The new network virtualization protocol plugins such as OVSDB
137 - The traditional management protocols such as SNMP or any others in
140 The above definition, and more information on Network Configuration
141 Services, is available at :
142 https://wiki.opendaylight.org/view/OpenDaylight_Controller:NetworkConfigurationServices
144 Bidirectional JSON-RPC library
145 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
151 | The main responsibilities of this Library are:
153 - Demarshal and marshal JSON Strings to JSON objects
155 - Demarshal and marshal JSON Strings from and to the Network Element.
157 OVSDB Schema definitions and Object mappers
158 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
168 | On the demarshaling side the mapping logic differentiates the Request
169 and Response messages as follows :
171 - Request messages are mapped by its "method"
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:
178 .. figure:: ./images/ConfigurationService-example1.png
179 :alt: End-to-end handling of a Create Bridge request
181 End-to-end handling of a Create Bridge request
183 .. figure:: ./images/MonitorResponse.png
184 :alt: End-to-end handling of a monitor response
186 End-to-end handling of a monitor response
188 Overlay tunnel management
189 ^^^^^^^^^^^^^^^^^^^^^^^^^
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.
202 OVSDB to OpenFlow plugin mapping service
203 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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:
215 {OVSDB_NODE + BRIDGE_IDENTFIER} <---> {OF_NODE}.
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).
226 Schema independent library
227 ^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
238 - openvswitch : Schema wrapper that represents
239 http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf
241 - hardwarevtep: Schema wrapper that represents
242 http://openvswitch.org/docs/vtep.5.pdf
244 OVSDB Library Developer Guide
245 -----------------------------
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.
255 The main responsibilities of OVSDB library include:
257 - Manage connections to peers
259 - Marshal and unmarshal JSON Strings to JSON objects.
261 - Marshal and unmarshal JSON Strings from and to the Network Element.
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.
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.
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>`__.
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.
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.
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:
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``
333 OVSDB protocol transactions
334 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
336 The OVSDB protocol defines the RPC transaction methods in RFC 7047. The
337 following RPC methods are supported in OVSDB protocol:
349 - Update notification
351 - Monitor cancellation
355 - Locked notification
357 - Stolen notification
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:
374 - Locked notification
376 - Stolen notification
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.
388 OVSDB database operations
389 ~~~~~~~~~~~~~~~~~~~~~~~~~
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.
399 The TransactionBuilder class provides the following methods to help
402 - getOperations(): Get the list of operations in this transaction.
404 - add(): Add data operation to this transaction.
406 - build(): Return the list of operations in this transaction. This is
407 the same as the getOperations() method.
409 - execute(): Send the JSON RPC transaction to peer.
411 - getDatabaseSchema(): Get the database schema of this transaction.
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:
416 1. Statically import parameter "op" in Operations.java
418 ``import static org.opendaylight.ovsdb.lib.operations.Operations.op;``
420 2. Obtain transaction builder through transacBuilder() method in
423 ``TransactionBuilder transactionBuilder = ovsdbClient.transactionBuilder(dbSchema);``
425 3. Add operations to transaction builder:
427 ``transactionBuilder.add(op.insert(schema, row));``
429 4. Send transaction to peer and get JSON RPC response:
431 ``operationResults = transactionBuilder.execute().get();``
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:
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).”
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.
453 Reference Documentation
454 ~~~~~~~~~~~~~~~~~~~~~~~
456 RFC 7047 The Open vSwitch Databse Management Protocol
457 https://tools.ietf.org/html/rfc7047
459 OVSDB MD-SAL Southbound Plugin Developer Guide
460 ----------------------------------------------
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
471 OVSDB MD-SAL Southbound Plugin Architecture and Operation
472 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
474 The architecture and operation of the OVSDB MD-SAL Southbound plugin is
475 illustrated in the following set of diagrams.
477 Connecting to an OVSDB Node
478 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
486 Active OVSDB Node Manager Workflow
487 ''''''''''''''''''''''''''''''''''
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
498 ovs-vsctl set-manager ptcp:6640
500 The following diagram illustrates the sequence of events which occur
501 when OpenDaylight initiates an active OVSDB manager connection to an
504 .. figure:: ./images/ovsdb-sb-active-connection.jpg
505 :alt: Active OVSDB Manager Connection
507 Active OVSDB Manager Connection
510 Create an OVSDB node by using RESTCONF or an OpenDaylight plugin.
511 The OVSDB node is listed under the OVSDB topology node.
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.
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).
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
533 The OVSDB Southbound provider requests the schema and databases
534 which are supported by the OVSDB node.
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
542 Passive OVSDB Node Manager Workflow
543 '''''''''''''''''''''''''''''''''''
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:
553 ovs-vsctl set-manager tcp:<IP address>:6640
555 The following diagram illustrates the sequence of events which occur
556 when an OVSDB node connects to OpenDaylight.
558 .. figure:: ./images/ovsdb-sb-passive-connection.jpg
559 :alt: Passive OVSDB Manager Connection
561 Passive OVSDB Manager Connection
564 The OVSDB node initiates a connection to OpenDaylight.
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
573 The OVSDB Southbound provider requests the schema and databases
574 which are supported by the OVSDB node.
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.
582 OVSDB Node ID in the Southbound Operational MD-SAL
583 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
595 $ ovs-vsctl list open_vswitch
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']"}
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.
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.
613 "node-id": "ovsdb://uuid/b8dc0bfb-d22b-4938-a2e8-b0084d7bd8c1"
615 The *opendaylight-iid* entry can be removed from the Open\_vSwitch table
616 using the following command.
620 $ sudo ovs-vsctl remove open_vswitch . external-id "opendaylight-iid"
622 OVSDB Changes by using OVSDB Southbound Config MD-SAL
623 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
631 .. figure:: ./images/ovsdb-sb-config-crud.jpg
632 :alt: OVSDB Changes by using the Southbound Config MD-SAL
634 OVSDB Changes by using the Southbound Config MD-SAL
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.
642 The OVSDB Southbound provider receives notification of the changes
643 made to the OVSDB Southbound Config MD-SAL data store.
646 As appropriate, OVSDB transactions are constructed and transmitted
647 to the OVSDB node to update the OVSDB database on the OVSDB node.
650 The OVSDB node sends update messages to the OVSDB Southbound
651 provider to indicate the changes made to the OVSDB nodes database.
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.
658 Detecting changes in OVSDB coming from outside OpenDaylight
659 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
666 .. figure:: ./images/ovsdb-sb-oper-crud.jpg
667 :alt: OVSDB Changes made directly on the OVSDB node
669 OVSDB Changes made directly on the OVSDB node
672 Changes are made to the OVSDB node outside of OpenDaylight (e.g.
676 The OVSDB node constructs update messages to inform OpenDaylight of
677 the changes made to its databases.
680 The OVSDB Southbound provider maps the OVSDB database changes to
681 corresponding changes in the OVSDB Southbound operational MD-SAL
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>`__.
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>`__
695 There are three augmentations:
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
702 - **connection-info** - holds the local and remote IP address and
703 TCP port numbers for the OpenDaylight to OVSDB node connections
705 - **db-version** - version of the OVSDB database
707 - **ovs-version** - version of OVS
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
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
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
721 - **list openvswitch-external-ids** - a list of the key/value pairs
722 in the Open\_vSwitch table external\_ids column
724 - **list openvswitch-other-config** - a list of the key/value pairs
725 in the Open\_vSwitch table other\_config column
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.
732 - **bridge-uuid** - UUID of the OVSDB bridge
734 - **bridge-name** - name of the OVSDB bridge
736 - **bridge-openflow-node-ref** - a reference (instance-identifier)
737 of the OpenFlow node associated with this bridge
739 - **list protocol-entry** - the version of OpenFlow protocol to use
740 with the OpenFlow controller
742 - **list controller-entry** - a list of controller-uuid and
743 is-connected status of the OpenFlow controllers associated with
746 - **datapath-id** - the datapath ID associated with this bridge on
749 - **datapath-type** - the datapath type of this bridge
751 - **fail-mode** - the OVSDB fail mode setting of this bridge
753 - **flow-node** - a reference to the flow node corresponding to
756 - **managed-by** - a reference to the ovsdb-node-augmentation
757 (OVSDB node) that is managing this bridge
759 - **list bridge-external-ids** - a list of the key/value pairs in
760 the bridge table external\_ids column for this bridge
762 - **list bridge-other-configs** - a list of the key/value pairs in
763 the bridge table other\_config column for this bridge
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.
771 - **port-uuid** - UUID of an OVSDB port row
773 - **interface-uuid** - UUID of an OVSDB interface row
775 - **name** - name of the port
777 - **interface-type** - the interface type
779 - **list options** - a list of port options
781 - **ofport** - the OpenFlow port number of the interface
783 - **ofport\_request** - the requested OpenFlow port number for the
786 - **vlan-tag** - the VLAN tag value
788 - **list trunks** - list of VLAN tag values for trunk mode
790 - **vlan-mode** - the VLAN mode (e.g. access, native-tagged,
791 native-untagged, trunk)
793 - **list port-external-ids** - a list of the key/value pairs in the
794 port table external\_ids column for this port
796 - **list interface-external-ids** - a list of the key/value pairs
797 in the interface table external\_ids interface for this interface
799 - **list port-other-configs** - a list of the key/value pairs in
800 the port table other\_config column for this port
802 - **list interface-other-configs** - a list of the key/value pairs
803 in the interface table other\_config column for this interface
805 Examples of OVSDB Southbound MD-SAL API
806 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
808 Connect to an OVSDB Node
809 ^^^^^^^^^^^^^^^^^^^^^^^^
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.
817 POST http://<host>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/
818 Content-Type: application/json
822 "node-id": "ovsdb:HOST1",
824 "ovsdb:remote-ip": "10.11.12.1",
825 "ovsdb:remote-port": 6640
831 Query the OVSDB Southbound Configuration MD-SAL
832 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
840 GET http://<host>:8080/restconf/config/network-topology:network-topology/topology/ovsdb:1/
841 Application/json data in the reply
845 "topology-id": "ovsdb:1",
848 "node-id": "ovsdb:HOST1",
849 "ovsdb:connection-info": {
851 "remote-ip": "10.11.12.1"
859 Reference Documentation
860 ~~~~~~~~~~~~~~~~~~~~~~~
863 schema <http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf>`__
865 OVSDB Hardware VTEP Developer Guide
866 -----------------------------------
873 OVSDB Hardware VTEP Architecture
874 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~