-YangIDE Installation Guide
+YANG IDE Installation Guide
==========================
Overview
--------
-The YangIDE project provides an Eclipse plugin for viewing and editing
+The YANG IDE project provides an Eclipse plugin for viewing and editing
Yang model files. When you create a "Yang Project" using the plugin,
it creates a small Maven project with a POM file (pom.xml) that
references the appropriate OpenDaylight dependencies, along with a
sample Yang model file (acme-system.yang).
-Pre Requisites for Installing YangIDE
+Pre Requisites for Installing YANG IDE
-------------------------------------
-* YangIDE has the same hardware requirements as the Eclipse IDE, which
+* YANG IDE has the same hardware requirements as the Eclipse IDE, which
is about the same as the hardware requirements for Java 7.
* At least Java 7 is required to run Eclipse (also an obvious
- requirement), but Java 8 will be required if you're building an
+ requirement), but Java 8 will be required if you are building an
application using OpenDaylight, and Java 8 is recommended anyway.
Preparing for Installation
--------------------------
As soon as at least Java 7 (Java 8 preferred) and Eclipse are
-installed, and Eclipse is running, you can install YangIDE.
+installed, and Eclipse is running, you can install YANG IDE.
You can find the Oracle Java installer at
http://www.oracle.com/technetwork/java/javase/downloads/index.html .
the correct platform (for instance, 32-bit or 64-bit).
-Installing YangIDE
+Installing YANG IDE
------------------
-The YangIDE plugin can be installed by using the public update site URL
+The YANG IDE plugin can be installed by using the public update site URL
provided, which is http://abc.def .
While in Eclipse, select "Help" from the menu bar and select "Install
New Software ...". On the resulting "Install" dialog, click the
"Add..." button. In that dialog, enter the update site URL as
-specified above and give it a name of "YangIDE". Select the provided
+specified above and give it a name of "YANG IDE". Select the provided
plugin and approve the license.
Eclipse will prompt you to restart Eclipse. Do that.
Installation is complete at this point.
+Network Connections
+^^^^^^^^^^^^^^^^^^^
+
+If the installation failed with an indication that it could not reach
+the internet, then your work computer may be behind a firewall.
+You will need to go to the "Network Connections" section of the Eclipse
+preferences (Menubar: "Window"->"Preferences"->"General"->"Network
+Connections").
+
+Before you make these changes, you will need to know the host and port
+of your outbound proxy server.
+
+On the "Network Connections" page, you should select "Manual" in the
+"Active Provider" dropdown, then edit the "HTTP" and "HTTPS" rows in
+the table, setting the host and port of the outbound proxy server.
+
+If the proxy server requires authentication, turn on the "Requires
+Authentication" checkbox and enter the required userid and password
+fields. If you do not know whether your proxy server requires
+authentication, it probably does not.
+
Verifying your Installation
---------------------------
option and click "Next".
On the "New Yang Project" dialog, you may see a wizard page titled
-"Specify YANG Code Generators Parameters". Don't change anything on
+"Specify YANG Code Generators Parameters". Do not change anything on
that page and click "Next".
On the next wizard page, with the title "Select project name and
of the project.
In that resulting list, there are only two entries that you will ever
-care about. One is "src/main/yang", which is where you'll store the
-Yang model files, and the "pom.xml" file, which is where you'll enter
-dependencies for Yang model files to import. If you won't be
-importing any Yang model files, or you'll only be importing other Yang
-model files in your own project, then you'll never have to do anything
+care about. One is "src/main/yang", which is where you will store the
+Yang model files, and the "pom.xml" file, which is where you will enter
+dependencies for Yang model files to import. If you will not be
+importing any Yang model files, or you will only be importing other Yang
+model files in your own project, then you will never have to do anything
with the "pom.xml" file.
Click the arrow to the left of the "src/main/yang" entry to expand that.
up, you can ask questions on the #eclipse IRC channel, or post
questions on the "Newcomers" forum at http://www.eclipse.org/forums/ .
-If Java and Eclipse seem to be fine, but the YangIDE is having
+If Java and Eclipse seem to be fine, but the YANG IDE is having
problems, ask questions on the "yangide-dev" mailing list.
Post Installation Configuration
-------------------------------
-No post-installation steps are required.
+Setting Proxy Used For Maven
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If your work computer sits behind a firewall, you will have had to put
+information about your firewall in the "Network Connections" section
+of the Eclipse preferences. That would have allowed you to at least
+obtain the plugin and install it into Eclipse.
+
+Much of the functionality of YANG IDE uses Maven internally. You do
+not need to be a Maven expert to use this functionality, but you will
+need to add a few more lines of configuration so that Maven can get
+through the firewall. Maven, even when running inside Eclipse, as it
+is when you are using YANG IDE, does not use the Eclipse "Network
+Connection" settings to reach the internet. You have to set the proxy
+server information in a different place for Maven.
+
+Maven looks for a file at ``$HOME/.m2/settings.xml`` (Linux) or
+``%HOME%\.m2\settings.xml`` (Windows). If the ``.m2`` folder does not
+exist, you will need to create it. If the "settings.xml" file does not
+exist, you should create it with the following contents::
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
+ <proxies>
+ <proxy>
+ <id>proxy</id>
+ <active>true</active>
+ <protocol>http</protocol>
+ <host>FULLY QUALIFIED NAME OF PROXY HOST</host>
+ <port>PROXY PORT</port>
+ </proxy>
+ <proxy>
+ <id>proxy2</id>
+ <active>true</active>
+ <protocol>https</protocol>
+ <host>FULLY QUALIFIED NAME OF PROXY HOST</host>
+ <port>PROXY PORT</port>
+ </proxy>
+ </proxies>
+ </settings>
+
+Replace "FULLY QUALIFIED NAME OF PROXY HOST" and "PROXY PORT" with the
+host and port of your proxy server.
+
+If the "settings.xml" file already existed, then you will need to edit
+it, inserting the "proxies" element from the above sample at an
+appropriate place.
Upgrading From a Previous Release
---------------------------------
-If you already had the "Yang IDE" plugin from "Xored", you'll need to
+If you already had the "YANG IDE" plugin from "Xored", you will need to
uninstall that plugin before you install this one.
-Uninstalling YangIDE
+Uninstalling YANG IDE
--------------------
-Uninstalling the YangIDE plugin is the same as uninstalling any other Eclipse plugin.
+Uninstalling the YANG IDE plugin is the same as uninstalling any other Eclipse plugin.
Click on the "Help" menu item and select "Installation Details". That
list will have all the plugins you have installed (or that came with
-the distribution). To uninstall YangIDE, you'll need to select four
+the distribution). To uninstall YANG IDE, you will need to select four
entries from that list:
* "m2e connector for YANG"
-Subproject commit c2402c3ea906e374bdc63c34b3e09ecc60010bee
+Subproject commit 1b9a451b5aac36e28c535880d597360bf0069d3b
-Subproject commit 9f2b2bb08b3f1b8ab10d7ce7a2230b30907cc1b1
+Subproject commit 3d45b3c71137a3271f97e8c5db80fd98954e8087
-Subproject commit 95e5da9408659f1886fede230413205cf8cadbaf
+Subproject commit 92be8239cf3dbd22807afacc841021a733283bb6
include::opflex/agent-ovs-user.adoc[]
+include::ovsdb/odl-ovsdb-netvirt-user-guide.adoc[]
+
include::bgpcep/odl-bgpcep-pcep-all-user.adoc[PCEP]
include::packetcable/packetcable-user.adoc[PacketCable PCMM - CMTS Management]
--- /dev/null
+=== NetVirt
+
+The OVSDB NetVirt project delivers two major pieces of functionality:
+
+. The OVSDB Southbound Protocol, and
+. NetVirt, a network virtualization solution.
+
+The following diagram shows the system-level architecture of OVSDB NetVirt in
+an OpenStack-based solution.
+
+.OVSDB NetVirt Architecture
+image::ovsdb/ovsdb-netvirt-architecture.jpg[align="center",width=250]
+
+NetVirt is a network virtualization solution that is a Neutron service provider, and therefore supports
+the OpenStack Neutron Networking API and extensions.
+
+The OVSDB component implements the OVSDB protocol (RFC 7047), as well as
+plugins to support OVSDB Schemas, such as the Open_vSwitch database schema and
+the hardware_vtep database schema.
+
+NetVirt has MDSAL-based interfaces with Neutron on the northbound side, and
+OVSDB and OpenFlow plugins on the southbound side.
+
+OVSDB NetVirt currently supports Open vSwitch virtual switches
+via OpenFlow and OVSDB. Work is underway to support hardware gateways.
+
+NetVirt services are enabled by installing the odl-ovsdb-openstack feature using the following command:
+
+ feature:install odl-ovsdb-openstack
+
+To enable NetVirt's distributed Layer 3 routing services, the following line must be uncommented in the etc/custom.properties
+file in the OpenDaylight distribution prior to starting karaf:
+
+ ovsdb.l3.fwd.enabled=yes
+
+To start the OpenDaylight controller, run the following application in your distribution:
+
+ bin/karaf
+
+More details about using NetVirt with OpenStack can be found in the following places:
+
+. The "OpenDaylight and OpenStack" guide, and
+. https://wiki.opendaylight.org/view/OVSDB_Integration:Main#Getting_Started_with_OpenDaylight_OVSDB_Plugin_Network_Virtualization[Getting Started with OpenDaylight OVSDB Plugin Network Virtualization]
+
+Some additional details about using OpenStack Security Groups and the Data Plane Development Kit (DPDK) are provided below.
+
+include::odl-ovsdb-security-groups.adoc[]
+
+include::odl-ovs-dpdk-user-guide.adoc[]
--- /dev/null
+==== Using OVS with DPDK hosts and OVSDB NetVirt
+
+The Data Plane Development Kit (http://dpdk.org/[DPDK]) is a userspace set
+of libraries and drivers designed for fast packet processing. The userspace
+datapath variant of OVS can be built with DPDK enabled to provide the
+performance features of DPDK to Open vSwitch (OVS). In the 2.4.0 version of OVS, the
+Open_vSwtich table schema was enhanced to include the lists 'datapath-types' and
+'interface-types'. When the OVS with DPDK variant of OVS is running, the
+'inteface-types' list will include DPDK interface types such as 'dpdk' and 'dpdkvhostuser'.
+The OVSDB Southbound Plugin includes this information in the OVSDB YANG model
+in the MD-SAL, so when a specific OVS host is running OVS with DPDK, it is possible
+for NetVirt to detect that information by checking that DPDK interface types are
+included in the list of supported interface types.
+
+For example, query the operational MD-SAL for OVSDB nodes:
+
+HTTP GET:
+
+ http://{{CONTROLLER-IP}}:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/
+
+Result Body:
+
+ {
+ "topology": [
+ {
+ "topology-id": "ovsdb:1",
+ "node": [
+ < content edited out >
+ {
+ "node-id": "ovsdb://uuid/f9b58b6d-04db-459a-b914-fff82b738aec",
+ < content edited out >
+ "ovsdb:interface-type-entry": [
+ {
+ "interface-type": "ovsdb:interface-type-ipsec-gre"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-internal"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-system"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-patch"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-dpdkvhostuser"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-dpdk"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-dpdkr"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-vxlan"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-lisp"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-geneve"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-gre"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-tap"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-stt"
+ }
+ ],
+ < content edited out >
+ "ovsdb:datapath-type-entry": [
+ {
+ "datapath-type": "ovsdb:datapath-type-netdev"
+ },
+ {
+ "datapath-type": "ovsdb:datapath-type-system"
+ }
+ ],
+ < content edited out >
+ },
+ < content edited out >
+ ]
+ }
+ ]
+ }
+
+This example illustrates the output of an OVS with DPDK host because
+the list of interface types includes types supported by DPDK.
+
+Bridges on OVS with DPDK hosts need to be created with the 'netdev' datapath type
+and DPDK specific ports need to be created with the appropriate interface type.
+The OpenDaylight OVSDB Southbound Plugin supports these attributes.
+
+The OpenDaylight NetVirt application checks whether the OVS host is using OVS with DPDK
+when creating the bridges that are expected to be present on the host, e.g. 'br-int'.
+
+Following are some tips for supporting hosts using OVS with DPDK when using NetVirt as the Neutron service
+provider and 'devstack' to deploy Openstack.
+
+In addition to the 'networking-odl' ML2 plugin, enable the 'networking-odl-dpdk' plugin in 'local.conf'.
+
+ For working with Openstack Liberty
+ enable_plugin networking-odl https://github.com/FedericoRessi/networking-odl integration/liberty
+ enable_plugin networking-ovs-dpdk https://github.com/openstack/networking-ovs-dpdk stable/liberty
+
+ For working with Openstack Mitaka (or later) branch
+ enable_plugin networking-odl https://github.com/openstack/networking-odl
+ enable_plugin networking-ovs-dpdk https://github.com/openstack/networking-ovs-dpdk
+
+The order of these plugin lines is important. The 'networking-odl' plugin will install and
+setup 'openvswitch'. The 'networking-ovs-dpdk' plugin will install OVS with DPDK. Note, the 'networking-ovs-dpdk'
+plugin is only being used here to setup OVS with DPDK. The 'networking-odl' plugin will be used as the Neutron ML2 driver.
+
+For VXLAN tenant network support, the NetVirt application interacts with OVS with DPDK host in the same way as OVS hosts
+using the kernel datapath by creating VXLAN ports on 'br-int' to communicate with other tunnel endpoints. The IP address
+for the local tunnel endpoint may be configured in the 'local.conf' file. For example:
+
+ ODL_LOCAL_IP=192.100.200.10
+
+NetVirt will use this information to configure the VXLAN port on 'br-int'. On a host with the OVS kernel datapath, it
+is expected that there will be a networking interface configured with this IP address. On an OVS with DPDK host, an OVS
+bridge is created and a DPDK port is added to the bridge. The local tunnel endpoint address is then assigned to the
+bridge port of the bridge. So, for example, if the physical network interface is associated with 'eth0' on the host,
+a bridge named 'br-eth0' could be created. The DPDK port, such as 'dpdk0' (per the naming conventions of OVS with DPDK), is
+added to bridge 'br-eth0'. The local tunnel endpoint address is assigned to the network interface 'br-eth0' which is
+attached to bridge 'br-eth0'. All of this setup is not done by NetVirt. The 'networking-ovs-dpdk' can be made to
+perform this setup by putting configuration like the following in 'local.conf'.
+
+ ODL_LOCAL_IP=192.168.200.9
+ ODL_PROVIDER_MAPPINGS=physnet1:eth0,physnet2:eht1
+ OVS_DPDK_PORT_MAPPINGS=eth0:br-eth0,eth1:br-ex
+ OVS_BRIDGE_MAPPINGS=physnet1:br-eth0,physnet2:br-ex
+
+The above settings associate the host networking interface 'eth0' with bridge 'br-eth0'. The 'networking-ovs-dpdk' plugin
+will determine the DPDK port name associated with 'eth0' and add it to the bridge 'br-eth0'. If using the NetVirt L3 support,
+these settings will enable setup of the 'br-ex' bridge and attach the DPDK port associated with network interface 'eth1' to it.
+
+The following settings are included in 'local.conf' to specify specific attributes associated with OVS with DPDK. These are
+used by the 'networking-ovs-dpdk' plugin to configure OVS with DPDK.
+
+ OVS_DATAPATH_TYPE=netdev
+ OVS_NUM_HUGEPAGES=8192
+ OVS_DPDK_MEM_SEGMENTS=8192
+ OVS_HUGEPAGE_MOUNT_PAGESIZE=2M
+ OVS_DPDK_RTE_LIBRTE_VHOST=y
+ OVS_DPDK_MODE=compute
+
+Once the stack is up and running virtual machines may be deployed on OVS with DPDK hosts. The 'networking-odl' plugin handles
+ensuring that 'dpdkvhostuser' interfaces are utilized by Nova instead of the default 'tap' interface. The 'dpdkvhostuser' interface
+provides the best performance for VMs on OVS with DPDK hosts.
+
+A Nova flavor is created for VMs that may be deployed on OVS with DPDK hosts.
+
+ nova flavor-create largepage-flavor 1002 1024 4 1
+ nova flavor-key 1002 set "hw:mem_page_size=large"
+
+Then, just specify the flavor when creating a VM.
+
+ nova boot --flavor largepage-flavor --image cirros-0.3.4-x86_64-uec --nic net-id=<NET ID VALUE> vm-name
--- /dev/null
+==== OVSDB Hardware VTEP SouthBound Plugin
+
+===== Overview
+
+Hwvtepsouthbound plugin is used to configure a hardware VTEP which
+implements hardware ovsdb schema. This page will show how to use
+RESTConf API of hwvtepsouthbound. There are two ways to connect to ODL:
+
+.user initiates connection, and
+.switch initiates connection.
+
+Both will be introduced respectively.
+
+===== User Initiates Connection
+
+====== Prerequisite
+
+Configure the hwvtep device/node to listen for the tcp connection in
+passive mode. In addition, management IP and tunnel source IP are also
+configured. After all this configuration is done, a physical switch is
+created automatically by the hwvtep node.
+
+====== Connect to a hwvtep device/node
+
+Send below Restconf request if you want to initiate the connection to a
+hwvtep node from the controller, where listening IP and port of hwvtep
+device/node are provided.
+
+REST API: POST
+http://odl:8181/restconf/config/network-topology:network-topology/topology/hwvtep:1/
+
+ {
+ "network-topology:node": [
+ {
+ "node-id": "hwvtep://192.168.1.115:6640",
+ "hwvtep:connection-info":
+ {
+ "hwvtep:remote-port": 6640,
+ "hwvtep:remote-ip": "192.168.1.115"
+ }
+ }
+ ]
+ }
+
+Please replace 'odl' in the URL with the IP address of your OpendayLight
+controller and change '192.168.1.115' to your hwvtep node IP.
+
+**NOTE**: The format of node-id is fixed. It will be one of the two:
+
+User initiates connection from ODL:
+
+ hwvtep://ip:port
+
+Switch initiates connection:
+
+ hwvtep://uuid/<uuid of switch>
+
+The reason for using UUID is that we can distinguish between multiple
+switches if they are behind a NAT.
+
+After this request is completed successfully, we can get the physical
+switch from the operational data store.
+
+REST API: GET
+http://odl:8181/restconf/operational/network-topology:network-topology/topology/hwvtep:1/node/hwvtep:%2F%2F192.168.1.115:6640
+
+There is no body in this request.
+
+The response of the request is:
+
+ {
+ "node": [
+ {
+ "node-id": "hwvtep://192.168.1.115:6640",
+ "hwvtep:switches": [
+ {
+ "switch-ref": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='hwvtep:1']/network-topology:node[network-topology:node-id='hwvtep://192.168.1.115:6640/physicalswitch/br0']"
+ }
+ ],
+ "hwvtep:connection-info": {
+ "local-ip": "192.168.92.145",
+ "local-port": 47802,
+ "remote-port": 6640,
+ "remote-ip": "192.168.1.115"
+ }
+ },
+ {
+ "node-id": "hwvtep://192.168.1.115:6640/physicalswitch/br0",
+ "hwvtep:management-ips": [
+ {
+ "management-ips-key": "192.168.1.115"
+ }
+ ],
+ "hwvtep:physical-switch-uuid": "37eb5abd-a6a3-4aba-9952-a4d301bdf371",
+ "hwvtep:managed-by": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='hwvtep:1']/network-topology:node[network-topology:node-id='hwvtep://192.168.1.115:6640']",
+ "hwvtep:hwvtep-node-description": "",
+ "hwvtep:tunnel-ips": [
+ {
+ "tunnel-ips-key": "192.168.1.115"
+ }
+ ],
+ "hwvtep:hwvtep-node-name": "br0"
+ }
+ ]
+ }
+
+If there is a physical switch which has already been created by manual
+configuration, we can get the node-id of the physical switch from this
+response, which is presented in “swith-ref”. If the switch does not
+exist, we need to create the physical switch. Currently, most hwvtep
+devices do not support running multiple switches.
+
+====== Create a physical switch
+
+REST API: POST
+http://odl:8181/restconf/config/network-topology:network-topology/topology/hwvtep:1/
+
+request body:
+
+ {
+ "network-topology:node": [
+ {
+ "node-id": "hwvtep://192.168.1.115:6640/physicalswitch/br0",
+ "hwvtep-node-name": "ps0",
+ "hwvtep-node-description": "",
+ "management-ips": [
+ {
+ "management-ips-key": "192.168.1.115"
+ }
+ ],
+ "tunnel-ips": [
+ {
+ "tunnel-ips-key": "192.168.1.115"
+ }
+ ],
+ "managed-by": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='hwvtep:1']/network-topology:node[network-topology:node-id='hwvtep://192.168.1.115:6640']"
+ }
+ ]
+ }
+
+Note: "managed-by" must provided by user. We can get its value after the
+step 'Connect to a hwvtep device/node' since the node-id of hwvtep
+device is provided by user. "managed-by" is a reference typed of
+instance identifier. Though the instance identifier is a little
+complicated for RestConf, the primary user of hwvtepsouthbound plugin
+will be provider-type code such as NetVirt and the instance identifier
+is much easier to write code for.
+
+====== Create a logical switch
+
+Creating a logical switch is effectively creating a logical network. For
+VxLAN, it is a tunnel network with the same VNI.
+
+REST API: POST
+http://odl:8181/restconf/config/network-topology:network-topology/topology/hwvtep:1/node/hwvtep:%2F%2F192.168.1.115:6640
+
+request body:
+
+ {
+ "logical-switches": [
+ {
+ "hwvtep-node-name": "ls0",
+ "hwvtep-node-description": "",
+ "tunnel-key": "10000"
+ }
+ ]
+ }
+
+====== Create a physical locator
+
+After the VXLAN network is ready, we will add VTEPs to it. A VTEP is
+described by a physical locator.
+
+REST API: POST
+http://odl:8181/restconf/config/network-topology:network-topology/topology/hwvtep:1/node/hwvtep:%2F%2F192.168.1.115:6640
+
+request body:
+
+ {
+ "termination-point": [
+ {
+ "tp-id": "vxlan_over_ipv4:192.168.0.116",
+ "encapsulation-type": "encapsulation-type-vxlan-over-ipv4",
+ "dst-ip": "192.168.0.116"
+ }
+ ]
+ }
+
+The "tp-id" of locator is "\{encapsualation-type}: \{dst-ip}".
+
+Note: As far as we know, the OVSDB database does not allow the insertion
+of a new locator alone. So, no locator is inserted after this request is
+sent. We will trigger off the creation until other entity refer to it,
+such as remote-mcast-macs.
+
+====== Create a remote-mcast-macs entry
+
+After adding a physical locator to a logical switch, we need to create a
+remote-mcast-macs entry to handle unknown traffic.
+
+REST API: POST
+http://odl:8181/restconf/config/network-topology:network-topology/topology/hwvtep:1/node/hwvtep:%2F%2F192.168.1.115:6640
+
+request body:
+
+ {
+ "remote-mcast-macs": [
+ {
+ "mac-entry-key": "00:00:00:00:00:00",
+ "logical-switch-ref": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='hwvtep:1']/network-topology:node[network-topology:node-id='hwvtep://192.168.1.115:6640']/hwvtep:logical-switches[hwvtep:hwvtep-node-name='ls0']",
+ "locator-set": [
+ {
+ "locator-ref": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='hwvtep:1']/network-topology:node[network-topology:node-id='hwvtep://219.141.189.115:6640']/network-topology:termination-point[network-topology:tp-id='vxlan_over_ipv4:192.168.0.116']"
+ }
+ ]
+ }
+ ]
+ }
+
+The physical locator 'vxlan_over_ipv4:192.168.0.116' is just created in
+"Create a physical locator". It should be noted that list "locator-set"
+is immutable, that is, we must provide a set of "locator-ref" as a
+whole.
+
+Note: "00:00:00:00:00:00" stands for "unknown-dst" since the type of
+mac-entry-key is yang:mac and does not accept "unknown-dst".
+
+====== Create a physical port
+
+Now we add a physical port into the physical switch
+"hwvtep://192.168.1.115:6640/physicalswitch/br0". The port is attached
+with a physical server or an L2 network and with the vlan 100.
+
+REST API: POST
+http://odl:8181/restconf/config/network-topology:network-topology/topology/hwvtep:1/node/hwvtep:%2F%2F192.168.1.115:6640%2Fphysicalswitch%2Fbr0
+
+ {
+ "network-topology:termination-point": [
+ {
+ "tp-id": "port0",
+ "hwvtep-node-name": "port0",
+ "hwvtep-node-description": "",
+ "vlan-bindings": [
+ {
+ "vlan-id-key": "100",
+ "logical-switch-ref": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='hwvtep:1']/network-topology:node[network-topology:node-id='hwvtep://192.168.1.115:6640']/hwvtep:logical-switches[hwvtep:hwvtep-node-name='ls0']"
+ }
+ ]
+ }
+ ]
+ }
+
+At this point, we have completed the basic configuration.
+
+Typically, hwvtep devices learn local MAC addresses automatically. But
+they also support getting MAC address entries from ODL.
+
+====== Create a local-mcast-macs entry
+
+It is similar to 'Create a remote-mcast-macs entry'.
+
+====== Create a remote-ucast-macs
+
+REST API: POST
+http://odl:8181/restconf/config/network-topology:network-topology/topology/hwvtep:1/node/hwvtep:%2F%2F192.168.1.115:6640
+
+ request body:
+
+ {
+ "remote-ucast-macs": [
+ {
+ "mac-entry-key": "11:11:11:11:11:11",
+ "logical-switch-ref": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='hwvtep:1']/network-topology:node[network-topology:node-id='hwvtep://192.168.1.115:6640']/hwvtep:logical-switches[hwvtep:hwvtep-node-name='ls0']",
+ "ipaddr": "1.1.1.1",
+ "locator-ref": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='hwvtep:1']/network-topology:node[network-topology:node-id='hwvtep://192.168.1.115:6640']/network-topology:termination-point[network-topology:tp-id='vxlan_over_ipv4:192.168.0.116']"
+ }
+ ]
+ }
+
+====== Create a local-ucast-macs entry
+
+This is similar to 'Create a remote-ucast-macs'.
+
+===== Switch Initiates Connection
+
+We do not need to connect to a hwvtep device/node when the switch
+initiates the connection. After switches connect to ODL successfully, we
+get the node-id's of switches by reading the operational data store.
+Once the node-id of a hwvtep device is received, the remaining steps are
+the same as when the user initiates the connection.
+
+===== References
+
+https://wiki.opendaylight.org/view/User_talk:Pzhang
--- /dev/null
+== OVSDB NetVirt
+
+include::odl-netvirt-user-guide.adoc[]
+
+include::odl-ovsdb-plugins-user-guide.adoc[]
--- /dev/null
+=== OVSDB Plugins
+
+==== Overview and Architecture
+
+There are currently two OVSDB Southbound plugins:
+
+* odl-ovsdb-southbound: Implements the OVSDB Open_vSwitch database schema.
+
+* odl-ovsdb-hwvtepsouthbound: Implements the OVSDB hardware_vtep database schema.
+
+These plugins are normally installed and used automatically by higher level applications such as
+odl-ovsdb-openstack; however, they can also be installed separately and used via their REST APIs
+as is described in the following sections.
+
+include::odl-ovsdb-southbound-user-guide.adoc[]
+
+include::odl-ovsdb-hwvtep-southbound-user-guide.adoc[]
--- /dev/null
+[[security-groups]]
+==== Security groups
+
+The security group in openstack helps to filter packets based on
+policies configured. The current implementation in openstack uses
+iptables to realize security groups. In Opendaylight instead of iptable
+rules, ovs flows are used. This will remove the many layers of
+bridges/ports required in iptable implementation.
+
+The current rules are applied on the basis of the following attributes:
+ingress/egress, protocol, port range, and prefix. In the pipeline, table
+40 is used for egress acl and table 90 for ingress acl rules.
+
+[[stateful-implementation]]
+===== Stateful Implementation
+
+The security group is implemented in two modes, stateful and stateless.
+Stateful can be enabled by setting false to true in
+etc/opendaylight/karaf/netvirt-impl-default-config.xml
+
+The stateful implementation uses the conntrack capabilities of ovs and
+tracks an existing connection. This mode requires OVS2.5 and linux
+kernel 4.3. The ovs which is integrated with netfilter framework tracks
+the connection using the five tuple(layer-3 protocol, source address,
+destination address, layer-4 protocol, layer-4 key). The connection
+state is independent of the upper level state of connection oriented
+protocols like TCP, and even connectionless protocols like UDP will have
+a pseudo state. With this implementation OVS sends the packet to the
+netfilter framework to know whether there is an entry for to the
+connection. netfilter will return the packet to OVS with the appropriate
+flag set. Below are the states we are interested in:
+
+ -trk - The packet was never send to netfilter framework
+
+ +trk+est - It is already known and connection which was allowed previously,
+ pass it to the next table.
+
+ +trk+new - This is a new connection. So if there is a specific rule in the
+ table which allows this traffic with a commit action an entry will be made
+ in the netfilter framework. If there is no specific rule to allow this
+ traffic the packet will be dropped.
+
+So, by default, a packet is be dropped unless there is a rule to allow
+the packet.
+
+[[stateless-implementation]]
+===== Stateless Implementation
+
+The stateless mode is for OVS 2.4 and below where connection tracking is
+not supported. Here we have pseudo-connection tracking using the TCP SYN
+flag. Other than TCP packets, all protocol packets is allowed by
+default. For TCP packets, the SYN packets will be dropped by default
+unless there is a specific rule which allows TCP SYN packets to a
+particular port.
+
+[[fixed-rules]]
+===== Fixed Rules
+
+The SecurityGroup are associated with the vm port when the vm is
+spawned. By default a set of rules are applied to the vm port referred
+to as fixed security group rule. This includes the DHCP rules the ARP
+rule and the conntrack rules. The conntrack rules will be inserted only
+in the stateful mode.
+
+[[dhcp-rules]]
+====== DHCP rules
+
+The DHCP rules added to the vm port when a vm is spawned. The fixed DHCP
+rules are
+
+* Allow DHCP server traffic ingress.
+
+ cookie=0x0, duration=36.848s, table=90, n_packets=2, n_bytes=717,
+ priority=61006,udp,dl_src=fa:16:3e:a1:f9:d0,
+ tp_src=67,tp_dst=68 actions=goto_table:100
+
+ cookie=0x0, duration=36.566s, table=90, n_packets=0, n_bytes=0,
+ priority=61006,udp6,dl_src=fa:16:3e:a1:f9:d0,
+ tp_src=547,tp_dst=546 actions=goto_table:100
+
+* Allow DHCP client traffic egress.
+
+ cookie=0x0, duration=2165.596s, table=40, n_packets=2, n_bytes=674,
+ priority=61012,udp,tp_src=68,tp_dst=67 actions=goto_table:50
+
+ cookie=0x0, duration=2165.513s, table=40, n_packets=0, n_bytes=0,
+ priority=61012,udp6,tp_src=546,tp_dst=547 actions=goto_table:50
+
+* Prevent DHCP server traffic from the vm port.(DHCP Spoofing)
+
+ cookie=0x0, duration=34.711s, table=40, n_packets=0, n_bytes=0,
+ priority=61011,udp,in_port=2,tp_src=67,tp_dst=68 actions=drop
+
+ cookie=0x0, duration=34.519s, table=40, n_packets=0, n_bytes=0,
+ priority=61011,udp6,in_port=2,tp_src=547,tp_dst=546 actions=drop
+
+[[arp-rules]]
+====== Arp rules
+
+The default arp rules allows the arp traffic to go in and out of the vm
+port.
+
+ cookie=0x0, duration=35.015s, table=40, n_packets=10, n_bytes=420,
+ priority=61010,arp,arp_sha=fa:16:3e:93:88:60 actions=goto_table:50
+
+ cookie=0x0, duration=35.582s, table=90, n_packets=1, n_bytes=42,
+ priority=61010,arp,arp_tha=fa:16:3e:93:88:60 actions=goto_table:100
+
+[[conntrack-rules]]
+====== Conntrack rules
+
+These rules are inserted only in stateful mode. The conntrack rules use
+the netfilter framework to track packets. The below rules are added to
+leverage it.
+
+* If a packet is not tracked(connection state –trk) it is send it to the
+netfilter for tracking
+* If the packet is already tracked (netfilter filter returns connection
+state +trk,+est) and if the connection is established, then allow the
+packet to go through the pipeline.
+* The third rule is the default drop rule which will drop the packet, if
+the packet is tracked and new(netfilter filter returns connection state
++trk,+new). This rule has lower priority than the custom rules which
+shall be added.
+
+ cookie=0x0, duration=35.015s table=40,priority=61021,in_port=3,
+ ct_state=-trk,action=ct"("table=0")"
+
+ cookie=0x0, duration=35.015s table=40,priority=61020,in_port=3,
+ ct_state=+trk+est,action=goto_table:50
+
+ cookie=0x0, duration=35.015s table=40,priority=36002,in_port=3,
+ ct_state=+new,actions=drop
+
+ cookie=0x0, duration=35.015s table=90,priority=61022,
+ dl_dst=fa:16:3e:0d:8d:21,ct_state=+trk+est,action=goto_table:100
+
+ cookie=0x0, duration=35.015s table=90,priority=61021,
+ dl_dst=fa:16:3e:0d:8d:21,ct_state=-trk,action=ct"("table=0")"
+
+ cookie=0x0, duration=35.015s table=90,priority=36002,
+ dl_dst=fa:16:3e:0d:8d:21,ct_state=+new,actions=drop
+
+[[tcp-syn-rule]]
+====== TCP SYN Rule
+
+This rule is inserted in stateless mode only. This rule will drop TCP
+SYN packet by default
+
+[[custom-security-groups]]
+===== Custom Security Groups
+
+ User can add security groups in openstack via command line or UI. When we associate this security group with a vm the flows related to each security group will be added in the related tables. A preconfigured security group called the default security group is available in neutron db.
+
+[[stateful]]
+====== Stateful
+
+If connection tracking is enabled the match will have connection state
+and the action will have commit along with goto. The commit will send
+the packet to the netfilter framework to cache the entry. After a
+commit, for the next packet of this connection netfilter will return
++trk+est and the packet will match the fixed conntrack rule and get
+forwarded to next table.
+
+ cookie=0x0, duration=202.516s, table=40, n_packets=0, n_bytes=0,
+ priority=61007,ct_state=+new+trk,icmp,dl_src=fa:16:3e:ee:a5:ec,
+ nw_dst=0.0.0.0/24,icmp_type=2,icmp_code=4 actions=ct(commit),goto_table:50
+
+ cookie=0x0, duration=60.701s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,ct_state=+new+trk,udp,dl_dst=fa:16:3e:22:59:2f,
+ nw_src=10.100.5.3,tp_dst=2222 actions=ct(commit),goto_table:100
+
+ cookie=0x0, duration=58.988s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,ct_state=+new+trk,tcp,dl_dst=fa:16:3e:22:59:2f,
+ nw_src=10.100.5.3,tp_dst=1111 actions=ct(commit),goto_table:100
+
+[[stateless]]
+====== Stateless
+
+If the mode is stateless the match will have only the parameter
+specified in the security rule and a goto in the action. The ct_state
+and commit action will be missing.
+
+ cookie=0x0, duration=13211.171s, table=40, n_packets=0, n_bytes=0,
+ priority=61007,icmp,dl_src=fa:16:3e:93:88:60,nw_dst=0.0.0.0/24,
+ icmp_type=2,icmp_code=4 actions=goto_table:50
+
+ cookie=0x0, duration=199.674s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,udp,dl_dst=fa:16:3e:dc:49:ff,nw_src=10.100.5.3,tp_dst=2222
+ actions=goto_table:100
+
+ cookie=0x0, duration=199.780s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,tcp,dl_dst=fa:16:3e:93:88:60,nw_src=10.100.5.4,tp_dst=3333
+ actions=goto_table:100
+
+[[tcpudp-port-range]]
+====== TCP/UDP Port Range
+
+The TCP/UDP port range is supported with the help of port mask. This
+will dramatically reduce the number of flows required to cover a port
+range. The below 7 rules can cover a port range from 333 to 777.
+
+ cookie=0x0, duration=56.129s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,udp,dl_dst=fa:16:3e:f9:2c:42,nw_src=0.0.0.0/24,
+ tp_dst=0x200/0xff00 actions=goto_table:100
+
+ cookie=0x0, duration=55.805s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,udp,dl_dst=fa:16:3e:f9:2c:42,nw_src=0.0.0.0/24,
+ tp_dst=0x160/0xffe0 actions=goto_table:100
+
+ cookie=0x0, duration=55.587s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,udp,dl_dst=fa:16:3e:f9:2c:42,nw_src=0.0.0.0/24,
+ tp_dst=0x300/0xfff8 actions=goto_table:100
+
+ cookie=0x0, duration=55.437s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,udp,dl_dst=fa:16:3e:f9:2c:42,nw_src=0.0.0.0/24,
+ tp_dst=0x150/0xfff0 actions=goto_table:100
+
+ cookie=0x0, duration=55.282s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,udp,dl_dst=fa:16:3e:f9:2c:42,nw_src=0.0.0.0/24,
+ tp_dst=0x14e/0xfffe actions=goto_table:100
+
+ cookie=0x0, duration=54.063s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,udp,dl_dst=fa:16:3e:f9:2c:42,nw_src=0.0.0.0/24,
+ tp_dst=0x308/0xfffe actions=goto_table:100
+
+ cookie=0x0, duration=55.130s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,udp,dl_dst=fa:16:3e:f9:2c:42,nw_src=0.0.0.0/24,
+ tp_dst=333 actions=goto_table:100
+
+[[cidrremote-security-group]]
+===== CIDR/Remote Security Group
+
+ When adding a security group we can select the rule to applicable to a
+ set of CIDR or to a set of VMs which has a particular security group
+ associated with it.
+
+If CIDR is selected there will be only one flow rule added allowing the
+traffic from/to the IP’s belonging to that CIDR.
+
+ cookie=0x0, duration=202.516s, table=40, n_packets=0, n_bytes=0,
+ priority=61007,ct_state=+new+trk,icmp,dl_src=fa:16:3e:ee:a5:ec,
+ nw_dst=0.0.0.0/24,icmp_type=2,icmp_code=4 actions=ct(commit),goto_table:50
+
+If a remote security group is selected a flow will be inserted for every
+vm which has that security group associated.
+
+ cookie=0x0, duration=60.701s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,ct_state=+new+trk,udp,dl_dst=fa:16:3e:22:59:2f,
+ nw_src=10.100.5.3,tp_dst=2222 actions=ct(commit),goto_table:100
+
+ cookie=0x0, duration=58.988s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,ct_state=+new+trk,tcp,dl_dst=fa:16:3e:22:59:2f,
+ nw_src=10.100.5.3,tp_dst=1111 actions=ct(commit),goto_table:100
+
+[[rules-supported-in-odl]]
+===== Rules supported in ODL
+
+The following rules are supported in the current implementation. The
+direction (ingress/egress) is always expected.
+
+.Table Supported Rules
+|====
+|Protocol |Port Range |IP Prefix |Remote Security Group supported
+|Any |Any |Any |Yes
+|TCP |1 - 65535 |0.0.0.0/0 |Yes
+|UDP |1 - 65535 |0.0.0.0/0 |Yes
+|ICMP |Any |0.0.0.0/0 |Yes
+|====
+
+Note : IPV6 and port-range feature is not supported as of today
--- /dev/null
+==== OVSDB Southbound Plugin
+
+The OVSDB Southbound Plugin provides support for managing OVS hosts
+via an OVSDB model in the MD-SAL which maps to important tables and
+attributes present in the Open_vSwitch schema. The OVSDB Southbound Plugin
+is able to connect actively or passively to OVS hosts and operate
+as the OVSDB manager of the OVS host. Using the OVSDB protocol it is able
+to manage the OVS database (OVSDB) on the OVS host as defined by the Open_vSwitch schema.
+
+===== OVSDB YANG Model
+
+The OVSDB Southbound Plugin provides a YANG model which is based on the
+abstract
+https://github.com/opendaylight/yangtools/blob/stable/beryllium/yang/yang-parser-impl/src/test/resources/ietf/network-topology%402013-10-21.yang[network topology model].
+
+The details of the OVSDB YANG model are defined in the
+https://github.com/opendaylight/ovsdb/blob/stable/beryllium/southbound/southbound-api/src/main/yang/ovsdb.yang[ovsdb.yang] file.
+
+The OVSDB YANG model defines three augmentations:
+
+*ovsdb-node-augmentation*::
+This augments the network-topology node and maps primarily to the Open_vSwitch table of
+the OVSDB schema. The ovsdb-node-augmentation is a representation of the OVS host. It contains the following attributes.
+ * *connection-info* - holds the local and remote IP address and TCP port numbers for the OpenDaylight to OVSDB node connections
+ * *db-version* - version of the OVSDB database
+ * *ovs-version* - version of OVS
+ * *list managed-node-entry* - a list of references to ovsdb-bridge-augmentation nodes, which are the OVS bridges managed by this OVSDB node
+ * *list datapath-type-entry* - a list of the datapath types supported by the OVSDB node (e.g. 'system', 'netdev') - depends on newer OVS versions
+ * *list interface-type-entry* - a list of the interface types supported by the OVSDB node (e.g. 'internal', 'vxlan', 'gre', 'dpdk', etc.) - depends on newer OVS verions
+ * *list openvswitch-external-ids* - a list of the key/value pairs in the Open_vSwitch table external_ids column
+ * *list openvswitch-other-config* - a list of the key/value pairs in the Open_vSwitch table other_config column
+ * *list managery-entry* - list of manager information entries and connection status
+ * *list qos-entries* - list of QoS entries present in the QoS table
+ * *list queues* - list of queue entries present in the queue table
+*ovsdb-bridge-augmentation*::
+This augments the network-topology node and maps to an specific bridge in the OVSDB
+bridge table of the associated OVSDB node. It contains the following attributes.
+ * *bridge-uuid* - UUID of the OVSDB bridge
+ * *bridge-name* - name of the OVSDB bridge
+ * *bridge-openflow-node-ref* - a reference (instance-identifier) of the OpenFlow node associated with this bridge
+ * *list protocol-entry* - the version of OpenFlow protocol to use with the OpenFlow controller
+ * *list controller-entry* - a list of controller-uuid and is-connected status of the OpenFlow controllers associated with this bridge
+ * *datapath-id* - the datapath ID associated with this bridge on the OVSDB node
+ * *datapath-type* - the datapath type of this bridge
+ * *fail-mode* - the OVSDB fail mode setting of this bridge
+ * *flow-node* - a reference to the flow node corresponding to this bridge
+ * *managed-by* - a reference to the ovsdb-node-augmentation (OVSDB node) that is managing this bridge
+ * *list bridge-external-ids* - a list of the key/value pairs in the bridge table external_ids column for this bridge
+ * *list bridge-other-configs* - a list of the key/value pairs in the bridge table other_config column for this bridge
+*ovsdb-termination-point-augmentation*::
+This augments the topology termination point model. The OVSDB Southbound
+Plugin uses this model to represent both the OVSDB port and OVSDB interface for
+a given port/interface in the OVSDB schema. It contains the following
+attributes.
+ * *port-uuid* - UUID of an OVSDB port row
+ * *interface-uuid* - UUID of an OVSDB interface row
+ * *name* - name of the port and interface
+ * *interface-type* - the interface type
+ * *list options* - a list of port options
+ * *ofport* - the OpenFlow port number of the interface
+ * *ofport_request* - the requested OpenFlow port number for the interface
+ * *vlan-tag* - the VLAN tag value
+ * *list trunks* - list of VLAN tag values for trunk mode
+ * *vlan-mode* - the VLAN mode (e.g. access, native-tagged, native-untagged, trunk)
+ * *list port-external-ids* - a list of the key/value pairs in the port table external_ids column for this port
+ * *list interface-external-ids* - a list of the key/value pairs in the interface table external_ids interface for this interface
+ * *list port-other-configs* - a list of the key/value pairs in the port table other_config column for this port
+ * *list interface-other-configs* - a list of the key/value pairs in the interface table other_config column for this interface
+ * *list inteface-lldp* - LLDP Auto Attach configuration for the interface
+ * *qos* - UUID of the QoS entry in the QoS table assigned to this port
+
+===== Getting Started
+
+To install the OVSDB Southbound Plugin, use the following command at the Karaf console:
+
+ feature:install odl-ovsdb-southbound-impl-ui
+
+After installing the OVSDB Southbound Plugin, and before any OVSDB topology nodes have been created,
+the OVSDB topology will appear as follows in the configuration and operational MD-SAL.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/
+ or
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/
+
+Result Body:
+
+ {
+ "topology": [
+ {
+ "topology-id": "ovsdb:1"
+ }
+ ]
+ }
+
+Where
+
+'<controller-ip>' is the IP address of the OpenDaylight controller
+
+===== OpenDaylight as the OVSDB Manager
+
+An OVS host is a system which is running the OVS software and is capable of being managed
+by an OVSDB manager. The OVSDB Southbound Plugin is capable of connecting to
+an OVS host and operating as an OVSDB manager. Depending on the configuration of the
+OVS host, the connection of OpenDaylight to the OVS host will be active or passive.
+
+===== Active Connection to OVS Hosts
+
+An active connection is when the OVSDB Southbound Plugin initiates the connection to
+an OVS host. This happens when the OVS host is configured to listen for the
+connection (i.e. the OVSDB Southbound Plugin is active the the OVS host is passive).
+The OVS host is configured with the following command:
+
+ sudo ovs-vsctl set-manager ptcp:6640
+
+This configures the OVS host to listen on TCP port 6640.
+
+The OVSDB Southbound Plugin can be configured via the configuration MD-SAL to
+actively connect to an OVS host.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1
+
+Body:
+
+ {
+ "network-topology:node": [
+ {
+ "node-id": "ovsdb://HOST1",
+ "connection-info": {
+ "ovsdb:remote-port": "6640",
+ "ovsdb:remote-ip": "<ovs-host-ip>"
+ }
+ }
+ ]
+ }
+
+Where
+
+'<ovs-host-ip>' is the IP address of the OVS Host
+
+
+Note that the configuration assigns a 'node-id' of "ovsdb://HOST1" to the OVSDB node.
+This 'node-id' will be used as the identifier for this OVSDB node in the MD-SAL.
+
+Query the configuration MD-SAL for the OVSDB topology.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/
+
+Result Body:
+
+ {
+ "topology": [
+ {
+ "topology-id": "ovsdb:1",
+ "node": [
+ {
+ "node-id": "ovsdb://HOST1",
+ "ovsdb:connection-info": {
+ "remote-ip": "<ovs-host-ip>",
+ "remote-port": 6640
+ }
+ }
+ ]
+ }
+ ]
+ }
+
+As a result of the OVSDB node configuration being added to the configuration MD-SAL, the OVSDB
+Southbound Plugin will attempt to connect with the specified OVS host. If the connection is
+successful, the plugin will connect to the OVS host as an OVSDB manager, query the schemas and
+databases supported by the OVS host, and register to monitor changes made to the OVSDB tables
+on the OVS host. It will also set an external id key and value in the external-ids column
+of the Open_vSwtich table of the OVS host which identifies the MD-SAL instance identifier
+of the OVSDB node. This ensures that the OVSDB node will use the same 'node-id' in both the
+configuration and operational MD-SAL.
+
+ "opendaylight-iid" = "instance identifier of OVSDB node in the MD-SAL"
+
+When the OVS host sends the OVSDB Southbound Plugin the first update message after the monitoring has
+been established, the plugin will populate the operational MD-SAL with the information it
+receives from the OVS host.
+
+Query the operational MD-SAL for the OVSDB topology.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/
+
+Result Body:
+
+ {
+ "topology": [
+ {
+ "topology-id": "ovsdb:1",
+ "node": [
+ {
+ "node-id": "ovsdb://HOST1",
+ "ovsdb:openvswitch-external-ids": [
+ {
+ "external-id-key": "opendaylight-iid",
+ "external-id-value": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb://HOST1']"
+ }
+ ],
+ "ovsdb:connection-info": {
+ "local-ip": "<controller-ip>",
+ "remote-port": 6640,
+ "remote-ip": "<ovs-host-ip>",
+ "local-port": 39042
+ },
+ "ovsdb:ovs-version": "2.3.1-git4750c96",
+ "ovsdb:manager-entry": [
+ {
+ "target": "ptcp:6640",
+ "connected": true,
+ "number_of_connections": 1
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+
+
+To disconnect an active connection, just delete the configuration MD-SAL entry.
+
+HTTP DELETE:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1
+
+Note in the above example, that '/' characters which are part of the 'node-id' are specified in hexadecimal format as "%2F".
+
+===== Passive Connection to OVS Hosts
+
+A passive connection is when the OVS host initiates the connection to
+the OVSDB Southbound Plugin. This happens when the OVS host is configured to connect
+to the OVSDB Southbound Plugin.
+The OVS host is configured with the following command:
+
+ sudo ovs-vsctl set-manager tcp:<controller-ip>:6640
+
+The OVSDB Southbound Plugin is configured to listen for OVSDB connections
+on TCP port 6640. This value can be changed by editing the "./karaf/target/assembly/etc/custom.properties"
+file and changing the value of the "ovsdb.listenPort" attribute.
+
+When a passive connection is made, the OVSDB node will appear first in the operational MD-SAL.
+If the Open_vSwitch table does not contain an external-ids value of 'opendaylight-iid', then
+the 'node-id' of the new OVSDB node will be created in the format:
+
+ "ovsdb://uuid/<actual UUID value>"
+
+If there an 'opendaylight-iid' value was already present in the external-ids column, then the
+instance identifier defined there will be used to create the 'node-id' instead.
+
+Query the operational MD-SAL for an OVSDB node after a passive connection.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/
+
+Result Body:
+
+ {
+ "topology": [
+ {
+ "topology-id": "ovsdb:1",
+ "node": [
+ {
+ "node-id": "ovsdb://uuid/163724f4-6a70-428a-a8a0-63b2a21f12dd",
+ "ovsdb:openvswitch-external-ids": [
+ {
+ "external-id-key": "system-id",
+ "external-id-value": "ecf160af-e78c-4f6b-a005-83a6baa5c979"
+ }
+ ],
+ "ovsdb:connection-info": {
+ "local-ip": "<controller-ip>",
+ "remote-port": 46731,
+ "remote-ip": "<ovs-host-ip>",
+ "local-port": 6640
+ },
+ "ovsdb:ovs-version": "2.3.1-git4750c96",
+ "ovsdb:manager-entry": [
+ {
+ "target": "tcp:10.11.21.7:6640",
+ "connected": true,
+ "number_of_connections": 1
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+
+Take note of the 'node-id' that was created in this case.
+
+===== Manage Bridges
+
+The OVSDB Southbound Plugin can be used to manage bridges on an OVS host.
+
+This example shows how to add a bridge to the OVSDB node 'ovsdb://HOST1'.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1%2Fbridge%2Fbrtest
+
+Body:
+
+ {
+ "network-topology:node": [
+ {
+ "node-id": "ovsdb://HOST1/bridge/brtest",
+ "ovsdb:bridge-name": "brtest",
+ "ovsdb:protocol-entry": [
+ {
+ "protocol": "ovsdb:ovsdb-bridge-protocol-openflow-13"
+ }
+ ],
+ "ovsdb:managed-by": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb://HOST1']"
+ }
+ ]
+ }
+
+Notice that the 'ovsdb:managed-by' attribute is specified in the command. This indicates the association of the new bridge node with its OVSDB node.
+
+Bridges can be updated. In the following example, OpenDaylight is configured to be the OpenFlow controller for the bridge.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1%2Fbridge%2Fbrtest
+
+Body:
+
+ {
+ "network-topology:node": [
+ {
+ "node-id": "ovsdb://HOST1/bridge/brtest",
+ "ovsdb:bridge-name": "brtest",
+ "ovsdb:controller-entry": [
+ {
+ "target": "tcp:<controller-ip>:6653"
+ }
+ ],
+ "ovsdb:managed-by": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb://HOST1']"
+ }
+ ]
+ }
+
+If the OpenDaylight OpenFlow Plugin is installed, then checking on the OVS host will show that OpenDaylight has successfully connected as the controller for the bridge.
+
+ $ sudo ovs-vsctl show
+ Manager "ptcp:6640"
+ is_connected: true
+ Bridge brtest
+ Controller "tcp:<controller-ip>:6653"
+ is_connected: true
+ Port brtest
+ Interface brtest
+ type: internal
+ ovs_version: "2.3.1-git4750c96"
+
+Query the operational MD-SAL to see how the bridge appears.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1%2Fbridge%2Fbrtest/
+
+Result Body:
+
+ {
+ "node": [
+ {
+ "node-id": "ovsdb://HOST1/bridge/brtest",
+ "ovsdb:bridge-name": "brtest",
+ "ovsdb:datapath-type": "ovsdb:datapath-type-system",
+ "ovsdb:datapath-id": "00:00:da:e9:0c:08:2d:45",
+ "ovsdb:managed-by": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb://HOST1']",
+ "ovsdb:bridge-external-ids": [
+ {
+ "bridge-external-id-key": "opendaylight-iid",
+ "bridge-external-id-value": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb://HOST1/bridge/brtest']"
+ }
+ ],
+ "ovsdb:protocol-entry": [
+ {
+ "protocol": "ovsdb:ovsdb-bridge-protocol-openflow-13"
+ }
+ ],
+ "ovsdb:bridge-uuid": "080ce9da-101e-452d-94cd-ee8bef8a4b69",
+ "ovsdb:controller-entry": [
+ {
+ "target": "tcp:10.11.21.7:6653",
+ "is-connected": true,
+ "controller-uuid": "c39b1262-0876-4613-8bfd-c67eec1a991b"
+ }
+ ],
+ "termination-point": [
+ {
+ "tp-id": "brtest",
+ "ovsdb:port-uuid": "c808ae8d-7af2-4323-83c1-e397696dc9c8",
+ "ovsdb:ofport": 65534,
+ "ovsdb:interface-type": "ovsdb:interface-type-internal",
+ "ovsdb:interface-uuid": "49e9417f-4479-4ede-8faf-7c873b8c0413",
+ "ovsdb:name": "brtest"
+ }
+ ]
+ }
+ ]
+ }
+
+Notice that just like with the OVSDB node, an 'opendaylight-iid' has been added to the external-ids column of the bridge since it was created via the configuration MD-SAL.
+
+
+A bridge node may be deleted as well.
+
+HTTP DELETE:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1%2Fbridge%2Fbrtest
+
+===== Manage Ports
+
+Similarly, ports may be managed by the OVSDB Southbound Plugin.
+
+This example illustrates how a port and various attributes may be created on a bridge.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1%2Fbridge%2Fbrtest/termination-point/testport/
+
+Body:
+
+ {
+ "network-topology:termination-point": [
+ {
+ "ovsdb:options": [
+ {
+ "ovsdb:option": "remote_ip",
+ "ovsdb:value" : "10.10.14.11"
+ }
+ ],
+ "ovsdb:name": "testport",
+ "ovsdb:interface-type": "ovsdb:interface-type-vxlan",
+ "tp-id": "testport",
+ "vlan-tag": "1",
+ "trunks": [
+ {
+ "trunk": "5"
+ }
+ ],
+ "vlan-mode":"access"
+ }
+ ]
+ }
+
+
+Ports can be updated - add another VLAN trunk.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1%2Fbridge%2Fbrtest/termination-point/testport/
+
+Body:
+
+ {
+ "network-topology:termination-point": [
+ {
+ "ovsdb:name": "testport",
+ "tp-id": "testport",
+ "trunks": [
+ {
+ "trunk": "5"
+ },
+ {
+ "trunk": "500"
+ }
+ ]
+ }
+ ]
+ }
+
+Query the operational MD-SAL for the port.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1%2Fbridge%2Fbrtest/termination-point/testport/
+
+Result Body:
+
+ {
+ "termination-point": [
+ {
+ "tp-id": "testport",
+ "ovsdb:port-uuid": "b1262110-2a4f-4442-b0df-84faf145488d",
+ "ovsdb:options": [
+ {
+ "option": "remote_ip",
+ "value": "10.10.14.11"
+ }
+ ],
+ "ovsdb:port-external-ids": [
+ {
+ "external-id-key": "opendaylight-iid",
+ "external-id-value": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb://HOST1/bridge/brtest']/network-topology:termination-point[network-topology:tp-id='testport']"
+ }
+ ],
+ "ovsdb:interface-type": "ovsdb:interface-type-vxlan",
+ "ovsdb:trunks": [
+ {
+ "trunk": 5
+ },
+ {
+ "trunk": 500
+ }
+ ],
+ "ovsdb:vlan-mode": "access",
+ "ovsdb:vlan-tag": 1,
+ "ovsdb:interface-uuid": "7cec653b-f407-45a8-baec-7eb36b6791c9",
+ "ovsdb:name": "testport",
+ "ovsdb:ofport": 1
+ }
+ ]
+ }
+
+Remember that the OVSDB YANG model includes both OVSDB port and interface table attributes in the termination-point augmentation.
+Both kinds of attributes can be seen in the examples above. Again, note the creation of an 'opendaylight-iid' value in the external-ids column of the port table.
+
+Delete a port.
+
+HTTP DELETE:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1%2Fbridge%2Fbrtest2/termination-point/testport/
+
+
+
+
+===== Overview of QoS and Queue
+The OVSDB Southbound Plugin provides the capability of managing the QoS
+and Queue tables on an OVS host with OpenDaylight configured
+as the OVSDB manager.
+
+====== QoS and Queue Tables in OVSDB
+The OVSDB includes a QoS and Queue table. Unlike most of the other tables
+in the OVSDB, except the Open_vSwitch table, the QoS and Queue tables are
+"root set" tables, which means that entries, or rows, in these tables are
+not automatically deleted if they can not be reached directly or indirectly
+from the Open_vSwitch table. This means that QoS entries can exist and be
+managed independently of whether or not they are referenced in a Port entry.
+Similarly, Queue entries can be managed independently of whether or not they are
+referenced by a QoS entry.
+
+
+====== Modelling of QoS and Queue Tables in OpenDaylight MD-SAL
+
+Since the QoS and Queue tables are "root set" tables, they are modeled
+in the OpenDaylight MD-SAL as lists which are part of the attributes
+of the OVSDB node model.
+
+The MD-SAL QoS and Queue models have an additonal identifier attribute per
+entry (e.g. "qos-id" or "queue-id") which is not present
+in the OVSDB schema. This identifier is used by the MD-SAL as a key for referencing
+the entry. If the entry is created originally from the
+configuration MD-SAL, then the value of the identifier is whatever is specified
+by the configuration. If the entry is created on the OVSDB node and received
+by OpenDaylight in an operational update, then the id will be created in
+the following format.
+
+ "queue-id": "queue://<UUID>"
+ "qos-id": "qos://<UUID>"
+
+The UUID in the above identifiers is the actual UUID of the entry in the
+OVSDB database.
+
+When the QoS or Queue entry is created by the configuration MD-SAL, the
+identifier will be configured as part of the external-ids column of the
+entry. This will ensure that the corresponding entry that is created
+in the operational MD-SAL uses the same identifier.
+
+ "queues-external-ids": [
+ {
+ "queues-external-id-key": "opendaylight-queue-id",
+ "queues-external-id-value": "QUEUE-1"
+ }
+ ]
+
+See more in the examples that follow in this section.
+
+The QoS schema in OVSDB currently defines two types of QoS entries.
+
+* linux-htb
+* linux-hfsc
+
+These QoS types are defined in the QoS model. Additional types will
+need to be added to the model in order to be supported. See the examples
+that folow for how the QoS type is specified in the model.
+
+QoS entries can be configured with addtional attritubes such as "max-rate".
+These are configured via the 'other-config' column of the QoS entry. Refer
+to OVSDB schema (in the reference section below) for all of the relevant
+attributes that can be configured. The examples in the rest of this section
+will demonstrate how the other-config column may be configured.
+
+Similarly, the Queue entries may be configured with additional attributes
+via the other-config column.
+
+===== Managing QoS and Queues via Configuration MD-SAL
+This section will show some examples on how to manage QoS and
+Queue entries via the configuration MD-SAL. The examples will
+be illustrated by using RESTCONF (see
+https://github.com/opendaylight/ovsdb/blob/stable/beryllium/resources/commons/Qos-and-Queue-Collection.json.postman_collection[QoS and Queue Postman Collection] ).
+
+A pre-requisite for managing QoS and Queue entries is that the
+OVS host must be present in the configuration MD-SAL.
+
+For the following examples, the following OVS host is configured.
+
+HTTP POST:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/
+
+Body:
+
+ {
+ "node": [
+ {
+ "node-id": "ovsdb:HOST1",
+ "connection-info": {
+ "ovsdb:remote-ip": "<ovs-host-ip>",
+ "ovsdb:remote-port": "<ovs-host-ovsdb-port>"
+ }
+ }
+ ]
+ }
+
+Where
+
+* '<controller-ip>' is the IP address of the OpenDaylight controller
+* '<ovs-host-ip>' is the IP address of the OVS host
+* '<ovs-host-ovsdb-port>' is the TCP port of the OVSDB server on the OVS host (e.g. 6640)
+
+This command creates an OVSDB node with the node-id "ovsdb:HOST1". This OVSDB node will be used in the following
+examples.
+
+QoS and Queue entries can be created and managed without a port, but ultimately, QoS entries are
+associated with a port in order to use them. For the following examples a test bridge and port will
+be created.
+
+Create the test bridge.
+
+HTTP PUT
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1%2Fbridge%2Fbr-test
+
+Body:
+
+ {
+ "network-topology:node": [
+ {
+ "node-id": "ovsdb:HOST1/bridge/br-test",
+ "ovsdb:bridge-name": "br-test",
+ "ovsdb:managed-by": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb:HOST1']"
+ }
+ ]
+ }
+
+Create the test port (which is modeled as a termination point in the OpenDaylight MD-SAL).
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1%2Fbridge%2Fbr-test/termination-point/testport/
+
+Body:
+
+ {
+ "network-topology:termination-point": [
+ {
+ "ovsdb:name": "testport",
+ "tp-id": "testport"
+ }
+ ]
+ }
+
+If all of the previous steps were successful, a query of the operational MD-SAL should look something like the following results. This indicates that the configuration commands have been successfully instantiated on the OVS host.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1%2Fbridge%2Fbr-test
+
+Result Body:
+
+ {
+ "node": [
+ {
+ "node-id": "ovsdb:HOST1/bridge/br-test",
+ "ovsdb:bridge-name": "br-test",
+ "ovsdb:datapath-type": "ovsdb:datapath-type-system",
+ "ovsdb:managed-by": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb:HOST1']",
+ "ovsdb:datapath-id": "00:00:8e:5d:22:3d:09:49",
+ "ovsdb:bridge-external-ids": [
+ {
+ "bridge-external-id-key": "opendaylight-iid",
+ "bridge-external-id-value": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb:HOST1/bridge/br-test']"
+ }
+ ],
+ "ovsdb:bridge-uuid": "3d225d8d-d060-4909-93ef-6f4db58ef7cc",
+ "termination-point": [
+ {
+ "tp-id": "br=-est",
+ "ovsdb:port-uuid": "f85f7aa7-4956-40e4-9c94-e6ca2d5cd254",
+ "ovsdb:ofport": 65534,
+ "ovsdb:interface-type": "ovsdb:interface-type-internal",
+ "ovsdb:interface-uuid": "29ff3692-6ed4-4ad7-a077-1edc277ecb1a",
+ "ovsdb:name": "br-test"
+ },
+ {
+ "tp-id": "testport",
+ "ovsdb:port-uuid": "aa79a8e2-147f-403a-9fa9-6ee5ec276f08",
+ "ovsdb:port-external-ids": [
+ {
+ "external-id-key": "opendaylight-iid",
+ "external-id-value": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb:HOST1/bridge/br-test']/network-topology:termination-point[network-topology:tp-id='testport']"
+ }
+ ],
+ "ovsdb:interface-uuid": "e96f282e-882c-41dd-a870-80e6b29136ac",
+ "ovsdb:name": "testport"
+ }
+ ]
+ }
+ ]
+ }
+
+====== Create Queue
+Create a new Queue in the configuration MD-SAL.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1/ovsdb:queues/QUEUE-1/
+
+Body:
+
+ {
+ "ovsdb:queues": [
+ {
+ "queue-id": "QUEUE-1",
+ "dscp": 25,
+ "queues-other-config": [
+ {
+ "queue-other-config-key": "max-rate",
+ "queue-other-config-value": "3600000"
+ }
+ ]
+ }
+ ]
+ }
+
+
+====== Query Queue
+Now query the operational MD-SAL for the Queue entry.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1/ovsdb:queues/QUEUE-1/
+
+Result Body:
+
+ {
+ "ovsdb:queues": [
+ {
+ "queue-id": "QUEUE-1",
+ "queues-other-config": [
+ {
+ "queue-other-config-key": "max-rate",
+ "queue-other-config-value": "3600000"
+ }
+ ],
+ "queues-external-ids": [
+ {
+ "queues-external-id-key": "opendaylight-queue-id",
+ "queues-external-id-value": "QUEUE-1"
+ }
+ ],
+ "queue-uuid": "83640357-3596-4877-9527-b472aa854d69",
+ "dscp": 25
+ }
+ ]
+ }
+
+====== Create QoS
+
+Create a QoS entry. Note that the UUID of the Queue entry, obtained by querying the operational MD-SAL of the Queue entry, is
+specified in the queue-list of the QoS entry. Queue entries may be added to the QoS entry at the creation of the QoS entry, or
+by a subsequent update to the QoS entry.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1/ovsdb:qos-entries/QOS-1/
+
+Body:
+
+ {
+ "ovsdb:qos-entries": [
+ {
+ "qos-id": "QOS-1",
+ "qos-type": "ovsdb:qos-type-linux-htb",
+ "qos-other-config": [
+ {
+ "other-config-key": "max-rate",
+ "other-config-value": "4400000"
+ }
+ ],
+ "queue-list": [
+ {
+ "queue-number": "0",
+ "queue-uuid": "83640357-3596-4877-9527-b472aa854d69"
+ }
+ ]
+ }
+ ]
+ }
+
+====== Query QoS
+
+Query the operational MD-SAL for the QoS entry.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1/ovsdb:qos-entries/QOS-1/
+
+Result Body:
+
+ {
+ "ovsdb:qos-entries": [
+ {
+ "qos-id": "QOS-1",
+ "qos-other-config": [
+ {
+ "other-config-key": "max-rate",
+ "other-config-value": "4400000"
+ }
+ ],
+ "queue-list": [
+ {
+ "queue-number": 0,
+ "queue-uuid": "83640357-3596-4877-9527-b472aa854d69"
+ }
+ ],
+ "qos-type": "ovsdb:qos-type-linux-htb",
+ "qos-external-ids": [
+ {
+ "qos-external-id-key": "opendaylight-qos-id",
+ "qos-external-id-value": "QOS-1"
+ }
+ ],
+ "qos-uuid": "90ba9c60-3aac-499d-9be7-555f19a6bb31"
+ }
+ ]
+ }
+
+====== Add QoS to a Port
+Update the termination point entry to include the UUID of the QoS entry, obtained by querying the operational MD-SAL, to associate a QoS entry with a port.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1%2Fbridge%2Fbr-test/termination-point/testport/
+
+Body:
+
+ {
+ "network-topology:termination-point": [
+ {
+ "ovsdb:name": "testport",
+ "tp-id": "testport",
+ "qos": "90ba9c60-3aac-499d-9be7-555f19a6bb31"
+ }
+ ]
+ }
+
+====== Query the Port
+Query the operational MD-SAL to see how the QoS entry appears in the termination point model.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1%2Fbridge%2Fbr-test/termination-point/testport/
+
+Result Body:
+
+ {
+ "termination-point": [
+ {
+ "tp-id": "testport",
+ "ovsdb:port-uuid": "aa79a8e2-147f-403a-9fa9-6ee5ec276f08",
+ "ovsdb:port-external-ids": [
+ {
+ "external-id-key": "opendaylight-iid",
+ "external-id-value": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb:HOST1/bridge/br-test']/network-topology:termination-point[network-topology:tp-id='testport']"
+ }
+ ],
+ "ovsdb:qos": "90ba9c60-3aac-499d-9be7-555f19a6bb31",
+ "ovsdb:interface-uuid": "e96f282e-882c-41dd-a870-80e6b29136ac",
+ "ovsdb:name": "testport"
+ }
+ ]
+ }
+
+
+====== Query the OVSDB Node
+Query the operational MD-SAL for the OVS host to see how the QoS and Queue entries appear as lists in the OVS node model.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1/
+
+Result Body (edited to only show information relevant to the QoS and Queue entries):
+
+ {
+ "node": [
+ {
+ "node-id": "ovsdb:HOST1",
+ <content edited out>
+ "ovsdb:queues": [
+ {
+ "queue-id": "QUEUE-1",
+ "queues-other-config": [
+ {
+ "queue-other-config-key": "max-rate",
+ "queue-other-config-value": "3600000"
+ }
+ ],
+ "queues-external-ids": [
+ {
+ "queues-external-id-key": "opendaylight-queue-id",
+ "queues-external-id-value": "QUEUE-1"
+ }
+ ],
+ "queue-uuid": "83640357-3596-4877-9527-b472aa854d69",
+ "dscp": 25
+ }
+ ],
+ "ovsdb:qos-entries": [
+ {
+ "qos-id": "QOS-1",
+ "qos-other-config": [
+ {
+ "other-config-key": "max-rate",
+ "other-config-value": "4400000"
+ }
+ ],
+ "queue-list": [
+ {
+ "queue-number": 0,
+ "queue-uuid": "83640357-3596-4877-9527-b472aa854d69"
+ }
+ ],
+ "qos-type": "ovsdb:qos-type-linux-htb",
+ "qos-external-ids": [
+ {
+ "qos-external-id-key": "opendaylight-qos-id",
+ "qos-external-id-value": "QOS-1"
+ }
+ ],
+ "qos-uuid": "90ba9c60-3aac-499d-9be7-555f19a6bb31"
+ }
+ ]
+ <content edited out>
+ }
+ ]
+ }
+
+
+====== Remove QoS from a Port
+This example removes a QoS entry from the termination point and associated port. Note that this is a PUT command on the termination point with the
+QoS attribute absent. Other attributes of the termination point should be included in the body of the command so that they are not inadvertantly removed.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1%2Fbridge%2Fbr-test/termination-point/testport/
+
+Body:
+
+ {
+ "network-topology:termination-point": [
+ {
+ "ovsdb:name": "testport",
+ "tp-id": "testport"
+ }
+ ]
+ }
+
+====== Remove a Queue from QoS
+
+This example removes the specific Queue entry from the queue list in the QoS entry. The queue entry is specified by the queue number, which is "0" in this example.
+
+HTTP DELETE:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1/ovsdb:qos-entries/QOS-1/queue-list/0/
+
+====== Remove Queue
+Once all references to a specific queue entry have been removed from QoS entries, the Queue itself can be removed.
+
+HTTP DELETE:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1/ovsdb:queues/QUEUE-1/
+
+====== Remove QoS
+The QoS entry may be removed when it is no longer referenced by any ports.
+
+HTTP DELETE:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1/ovsdb:qos-entries/QOS-1/
+
+
+===== References
+http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf[Openvswitch schema]
+
+https://github.com/opendaylight/ovsdb/blob/stable/beryllium/resources/commons[OVSDB and Netvirt Postman Collection]
+
-== YangIDE User Guide
-Refer to this template to identify the required sections and information
-that you should provide for a User Guide. The user guide should contain
-configuration, administration, management, using, and troubleshooting
-sections for the feature.
+== YANG IDE User Guide
=== Overview
-Provide an overview of the feature and the use case. Also include the
-audience who will use the feature. For example, audience can be the
-network administrator, cloud administrator, network engineer, system
-administrators, and so on.
-
-=== YangIDE Architecture
-Provide information about feature components and how they work together.
-Also include information about how the feature integrates with
-OpenDaylight. An architecture diagram could help.
-
-=== Configuring YangIDE
-
-Describe how to configure the feature or the project after installation.
-Configuration information could include day-one activities for a project
-such as configuring users, configuring clients/servers and so on.
-
-=== Administering or Managing YangIDE
-Include related command reference or operations that you could perform
-using the feature. For example viewing network statistics, monitoring
-the network, generating reports, and so on.
-
-NOTE: Ensure that you create a step procedure whenever required and
-avoid concepts.
-
-For example:
-
-.To configure L2switch components perform the following steps.
-. Step 1:
-. Step 2:
-. Step 3:
-
-=== Tutorials
-<optional>
-If there is only one tutorial, you skip the "Tutorials" section and
-instead just lead with the single tutorial's name.
-
-==== <Tutorial Name>
-Ensure that the title starts with a gerund. For example using,
-monitoring, creating, and so on.
-
-===== Overview
-An overview of the use case.
-
-===== Prerequisites
-Provide any prerequisite information, assumed knowledge, or environment
-required to execute the use case.
-
-===== Target Environment
-Include any topology requirement for the use case. Ideally, provide
-visual (abstract) layout of network diagrams and any other useful visual
-aides.
-
-===== Instructions
-Use case could be a set of configuration procedures. Including
-screenshots to help demonstrate what is happening is especially useful.
-Ensure that you specify them separately. For example:
-
-. *Setting up the VM*
-To set up a VM perform the following steps.
-.. Step 1
-.. Step 2
-.. Step 3
-
-. *Installing the feature*
-To install the feature perform the following steps.
-.. Step 1
-.. Step 2
-.. Step 3
-
-. *Configuring the environment*
-To configure the system perform the following steps.
-.. Step 1
-.. Step 2
-.. Step 3
+
+The YANG IDE project provides an Eclipse plugin that is used to create,
+view, and edit Yang model files. It currently supports version 1.0 of
+the Yang specification.
+
+The YANG IDE project uses components from the OpenDaylight project for
+parsing and verifying Yang model files. The "yangtools" parser in
+OpenDaylight is generally used for generating Java code associated
+with Yang models. If you are just using the YANG IDE to view and edit
+Yang models, you do not need to know any more about this.
+
+Although the YANG IDE plugin is used in Eclipse, it is not necessary to
+be familiar with the Java programming language to use it effectively.
+
+The YANG IDE also uses the Maven build tool, but you do not have to be
+a Maven expert to use it, or even know that much about it. Very
+little configuration of Maven files will have to be done by you. In
+fact, about the only thing you will likely ever need to change can be
+done entirely in the Eclipse GUI forms, without even seeing the
+internal structure of the Maven POM file (Project Object Model).
+
+The YANG IDE plugin provides features that are similar to other
+programming language plugins in the Eclipse ecosystem.
+
+For instance, you will find support for the following:
+
+* Immediate "as-you-type" display of syntactic and semantic errors
+* Intelligent completion of language tokens, limited to only choices
+valid in the current scope and namespace
+* Consistent (and customizable) color-coding of syntactic and semantic symbols
+* Provides access to remote Yang models by specifying dependency on
+Maven artifact containing models (or by manual inclusion in project)
+* One-click navigation to referenced symbols in external files
+* Mouse hovers display descriptions of referenced components
+* Tools for refactoring or renaming components respect namespaces
+* Code templates can be entered for common conventions
+
+Forthcoming sections of this manual will step through how to utilize
+these features.
+
+=== Creating a Yang Project
+
+After the plugin is installed, the next thing you have to do is create
+a Yang Project. This is done from the "File" menu, selecting "New",
+and navigating to the "Yang" section and selecting "YANG Project", and
+then clicking "Next" for more items to configure.
+
+Some shortcuts for these steps are the following:
+
+* Typically, the key sequence "Ctrl+n" (press "n" while holding down
+one of the "ctrl" keys) is bound to the "new" function
+* In the "New" wizard dialog, the initial focus is in the filter
+field, where you can enter "yang" to limit the choices to only the
+functions provided by the YANG IDE plugin
+* On the "New" wizard dialog, instead of clicking the "Next" button
+with your mouse, you can press "Alt+n" (you will see a hint for this
+with the "N" being underlined)
+
+==== First Yang Project Wizard Page
+
+After the "Next" button is pressed, it goes to the first wizard page
+that is specific to creating Yang projects. you will see a subtitle on
+this page of "YANG Tools Configuration". In almost all cases, you
+should be able to click "Next" again on this page to go to the next
+wizard page.
+
+However, some information about the fields on this page would be helpful.
+
+You will see the following labeled fields and sections:
+
+===== Yang Files Root Directory
+
+This defaults to "src/main/yang". Except when creating your first
+Yang file, you, you do not even have to know this, as Eclipse presents
+the same interface to view your Yang files no matter what you set
+this to.
+
+===== Source Code Generators
+
+If you do not know what this is, you do not need to know about it. The
+"yangtools" Yang parser from OpenDaylight uses a "code generator"
+component to generate specific kinds of Java classes from the Yang
+models. Again, if you do not need to work with the generated Java
+code, you do not need to change this.
+
+===== Create Example YANG File
+
+This is likely the only field you will ever have any reason to change.
+If this checkbox is set, when the YANG IDE creates the Yang project,
+it will create a sample "acme-system.yang" file which you can view and
+edit to demonstrate the features of the tool to yourself. If you
+do not need this file, then either delete it from the project or
+uncheck the checkbox to prevent its creation.
+
+When done with the fields on this page, click the "Next" button to go
+to the next wizard page.
+
+==== Second Yang Project Wizard Page
+
+This page has a subtitle of "New Maven project". There are several
+fields on this page, but you will only ever have to see and change the
+setting of the first field, the "Create a simple project" checkbox.
+You should always set this ON to avoid the selection of a Maven
+archetype, which is something you do not need to do for creating a
+Yang project.
+
+Click "Next" at the bottom of the page to move to the next wizard page.
+
+==== Third Yang Project Wizard Page
+
+This also has a subtitle of "New Maven project", but with different
+fields to set. You will likely only ever set the first two fields,
+and completely ignore everything else.
+
+The first field is labeled "Group id" in the "Artifact" section. It
+really does not matter what you set this to, but it does have to be set
+to something. For consistency, you might set this to the name or
+nickname of your organization. Otherwise, there are no constraints on
+the value of this field.
+
+The second field is labeled "Artifact id". The value of this field
+will be used as the name of the project you create, so you will have
+to think about what you want the project to be called. Also note that
+this name has to be unique in the Eclipse workspace. You cannot have
+two projects with the same name.
+
+After you have set this field, you will notice that the "Next" button is
+insensitive, but now the "Finish" button is sensitive. You can click
+"Finish" now (or use the keyboard shortcut of "Alt+f"), and the Yang
+IDE will finally create your project.
+
+=== Creating a Yang File
+
+Now that you have created your project, it is time to create your first Yang file.
+
+When you created the Yang project, you might have noticed the other
+option next to "YANG Project", which was "YANG File". That is what
+you will select now. Click "Next" to go to the first wizard page.
+
+==== First Yang File Wizard Page
+
+This wizard page lets you specify where the new file will be located, and its name.
+
+You have to select the particular project you want the file to go
+into, and it needs to go into the "src/main/yang" folder (or a
+different location if you changed that field when creating the
+project).
+
+You then enter the desired name of the file in the "File name". The
+file name should have no spaces or "special characters" in it. You
+can specify a ".yang" extent if you want. If you do not specify an
+extent, the YANG IDE will create it with the ".yang" extent.
+
+Click "Next" to go to the next wizard page.
+
+==== Second Yang File Wizard Page
+
+On this wizard page, you set some metadata about the module that is
+used to initialize the contents of the Yang file.
+
+It has the following fields:
+
+===== Module Name
+
+This will default to the "base name" of the file name you created.
+For instance, if the file name you created was "network-setup.yang",
+this field will default to "network-setup". You should leave this
+value as is. There is no good reason to define a model with a name
+different from the file name.
+
+===== Namespace
+
+This defaults to "urn:opendaylight:xxx", where "xxx" is the "base
+name" of the file name you created. You should put a lot of thought
+into designing a namespace naming scheme that is used throughout your
+organization. It is quite common for this namespace value to look like
+a "http" URL, but note that that is just a convention, and will not
+necessarily imply that there is a web page residing at that HTTP
+address.
+
+===== Prefix
+
+This defaults to the "base name" of the file name you created. It
+mostly does not technically matter what you set this to, as long as
+it is not empty. Conventionally, it should be a "nickname" that is
+used to refer to the given namespace in an abbreviated form, when
+referenced in an "import" statement in another Yang model file.
+
+===== Revision
+
+This has to be a date value in the form of "yyyy-mm-dd", representing
+the last modified date of this Yang model. The value will default to
+the current date.
+
+===== Revision Description
+
+This is just human-readable text, which will go into the "description"
+field underneath the Yang "revision" field, which will describe what
+went into this revision.
+
+When all the fields have the content you want, click the "Finish"
+button to set the YANG IDE create the file in the specified location.
+It will then present the new file in the editor view for additional
+modifications.
+
+=== Accessing Artifacts for Yang Model Imports
+
+You might be working on Yang models that are "abstract" or are
+intended to be imported by other Yang models. You might also, and
+more likely, be working on Yang models that import other "abstract"
+Yang models.
+
+Assuming you are in that latter more common group, you need to consider
+for yourself, and for your organization, how you are going to get
+access to those models that you import.
+
+You could use a very simple and primitive approach of somehow
+obtaining those models from some source as plain files and just
+copying them into the "src/main/yang" folder of your project. For a
+simple demo or a "one-off" very short project, that might be
+sufficient.
+
+A more robust and maintainable approach would be to reference
+"coordinates" of the artifacts containing Yang models to import. When
+you specify unique coordinates associated with that artifact, the Yang
+IDE can retrieve the artifact in the background and make it available
+for your "import" statements.
+
+Those "coordinates" that I speak of refer to the Maven concepts of
+"group id", "artifact id", and "version". you may remember "group id"
+and "artifact id" from the wizard page for creating a Yang project.
+It is the same idea. If you ever produce Yang model artifacts that
+other people are going to import, you will want to think more about what
+you set those values to when you created the project.
+
+For example, the OpenDaylight project produces several importable
+artifacts that you can specify to get access to common Yang models.
+
+==== Turning on Indexing for Maven Repositories
+
+Before we talk about how to add dependencies to Maven artifacts with
+Yang models for import, I need to explain how to make it easier to
+find those artifacts.
+
+In the Yang project that you have created, the "pom.xml" file (also
+called a "POM file") is the file that Maven uses to specify
+dependencies. We will talk about that in a minute, but first we need to
+talk about "repositories". These are where artifacts are stored.
+
+We are going to have Eclipse show us the "Maven Repositories" view.
+In the main menu, select "Window" and then "Show View", and then
+"Other". Like in the "New" dialog, you can enter "maven" in the
+filter field to limit the list to views with "maven" in the name.
+Click on the "Maven Repositories" entry and click OK.
+
+This will usually create the view in the bottom panel of the window.
+
+The view presents an outline view of four principal elements:
+
+* Local Repositories
+* Global Repositories
+* Project Repositories
+* Custom Repositories
+
+For this purpose, the only section you care about is "Project
+Repositories", being the repositories that are only specified in the
+POM for the project. There should be a "right-pointing arrow" icon on
+the line. Click that to expand the entry.
+
+You should see two entries there:
+
+* opendaylight-release
+* opendaylight-snapshot
+
+You will also see internet URLs associated with each of those repositories.
+
+For this purpose, you only care about the first one. Right-click on
+that entry and select "Full Index Enabled". The first time you do
+this on the first project you create, it will spend several minutes
+walking the entire tree of artifacts available at that repository and
+"indexing" all of those components. When this is done, searching for
+available artifacts in that repository will go very quickly.
+
+=== Adding Dependencies Containing Yang Models
+
+Double-click the "pom.xml" file in your project. Instead of just
+bringing up the view of an XML file (although you can see that if you
+like), it presents a GUI form editor with a handful of tabs.
+
+The first tab, "Overview", shows things like the "Group Id", "Artifact
+Id", and "Version", which represents the "Maven coordinate" of your
+project, which I have mentioned before.
+
+Now click on the "Dependencies" tab. You will now see two list
+components, labeled "Dependencies" and "Dependency Management". You
+only care about the "Dependencies" section.
+
+In the "Dependencies" section, you should see one dependency for an
+artifact called "yang-binding". This artifact is part of
+OpenDaylight, but you do not need to know anything about it.
+
+Now click the "Add" button.
+
+This brings up a dialog titled "Select Dependency". It has three
+fields at the top labeled "Group Id", "Artifact Id", and "Version",
+with a "Scope" dropdown. You will never have a need to change the
+"Scope" dropdown, so ignore it. Despite the fact that you will need to
+get values into these fields, in general usage, you will never have to
+manually enter values into them, but you will see values being inserted
+into these fields by the next steps I describe.
+
+Below those fields is a field labeled "Enter groupId, artifactId ...".
+This is effectively a "filter field", like on the "New" dialog, but
+instead of limiting the list from a short list of choices, the value
+you enter there will be matched against all of the artifacts that were
+indexed in the "opendaylight-release" repository (and others). It
+will match the string you enter as a substring of any groupId or
+artifactId.
+
+For all of the entries that match that substring, it will list an
+entry showing the groupId and artifactId, with an expansion arrow. If
+you open it by clicking on the arrow, you will see individual entries
+corresponding to each available version of that artifact, along with
+some metadata about the artifacts between square brackets, mostly
+indicating what "type" of artifact is.
+
+For your purposes, you only ever want to use "bundle" or "jar" artifacts.
+
+Let us consider an example that many people will probably be using.
+
+In the filter field, enter "ietf-yang-types". Depending on what
+versions are available, you should see a small handful of "groupId,
+artifactId" entries there. One of them should be groupId
+"org.opendaylight.mdsal.model" and artifactId "ietf-yang-types".
+Click on the expansion arrow to open that.
+
+What you will see at this point depends on what versions are
+available. You will likely want to select the newest one (most likely
+top of the list) that is also either a "bundle" or "jar" type
+artifact.
+
+If you click on that resulting version entry, you should notice at
+this point that the "Group Id", "Artifact Id", and "Version" fields at
+the top of the dialog are now filled in with the values corresponding
+to this artifact and version.
+
+If this is the version that you want, click OK and this artifact will
+be added to the dependencies in the POM.
+
+This will now make the Yang models found in that artifact available in
+"import" statements in Yang models, not to mention the completion
+choices for that "import" statement.
Code Review / docs.git / commitdiff
