OVSDB library

Path: os_ken.lib.ovs

Similar to the OVSDB Manager library, this library enables your application to speak the OVSDB protocol (RFC7047), but differ from the OVSDB Manager library, this library will initiate connections from controller side as ovs-vsctl command does. Please make sure that your devices are listening on either the Unix domain socket or TCP/SSL port before calling the APIs of this library.

# Show current configuration
$ ovs-vsctl get-manager

# Set TCP listen address
$ ovs-vsctl set-manager "ptcp:6640"

See manpage of ovs-vsctl command for more details.

Basic Usage

  1. Instantiate os_ken.lib.ovs.vsctl.VSCtl.

  2. Construct commands with os_ken.lib.ovs.vsctl.VSCtlCommand. The syntax is almost the same as ovs-vsctl command.

  3. Execute commands via os_ken.lib.ovs.vsctl.VSCtl.run_command.

Example

from os_ken.lib.ovs import vsctl

OVSDB_ADDR = 'tcp:127.0.0.1:6640'
ovs_vsctl = vsctl.VSCtl(OVSDB_ADDR)

# Equivalent to
# $ ovs-vsctl show
command = vsctl.VSCtlCommand('show')
ovs_vsctl.run_command([command])
print(command)
# >>> VSCtlCommand(args=[],command='show',options=[],result='830d781f-c3c8-4b4f-837e-106e1b33d058\n    ovs_version: "2.8.90"\n')

# Equivalent to
# $ ovs-vsctl list Port s1-eth1
command = vsctl.VSCtlCommand('list', ('Port', 's1-eth1'))
ovs_vsctl.run_command([command])
print(command)
# >>> VSCtlCommand(args=('Port', 's1-eth1'),command='list',options=[],result=[<ovs.db.idl.Row object at 0x7f525fb682e8>])
print(command.result[0].name)
# >>> s1-eth1

API Reference

os_ken.lib.ovs.vsctl

ovs-vsctl command like library to speak OVSDB protocol

class os_ken.lib.ovs.vsctl.VSCtl(remote)

A class to describe an Open vSwitch instance.

remote specifies the address of the OVS instance. os_ken.lib.ovs.vsctl.valid_ovsdb_addr is a convenient function to validate this address.

run_command(commands, timeout_sec=None, exception=None)

Executes the given commands and sends OVSDB messages.

commands must be a list of os_ken.lib.ovs.vsctl.VSCtlCommand.

If timeout_sec is specified, raises exception after the given timeout [sec]. Additionally, if exception is specified, this function will wraps exception using the given exception class.

Retruns None but fills result attribute for each command instance.

class os_ken.lib.ovs.vsctl.VSCtlCommand(command, args=None, options=None)

Class to describe artgumens similar to those of ovs-vsctl command.

command specifies the command of ovs-vsctl.

args specifies a list or tuple of arguments for the given command.

options specifies a list or tuple of options for the given command. Please note that NOT all options of ovs-vsctl are supported. For example, --id option is not yet supported. This class supports the followings.

Option

Description

--may-exist

Does nothing when the given port already exists. The supported commands are add-port and add-bond.

--fake-iface

Creates a port as a fake interface. The supported command is add-bond.

--must-exist

Raises exception if the given port does not exist. The supported command is del-port.

--with-iface

Takes effect to the interface which has the same name. The supported command is del-port.

--if-exists

Ignores exception when not found. The supported command is get.

os_ken.lib.ovs.vsctl.valid_ovsdb_addr(addr)

Returns True if the given addr is valid OVSDB server address, otherwise False.

The valid formats are:

  • unix:file

  • tcp:ip:port

  • ssl:ip:port

If ip is IPv6 address, wrap ip with brackets (e.g., ssl:[::1]:6640).

Parameters:

addr -- str value of OVSDB server address.

Returns:

True if valid, otherwise False.

os_ken.lib.ovs.bridge

Wrapper utility library of os_ken.lib.ovs.vsctl

class os_ken.lib.ovs.bridge.OVSBridge(CONF, datapath_id, ovsdb_addr, timeout=None, exception=None, br_name=None)

Class to provide wrapper utilities of os_ken.lib.ovs.vsctl.VSCtl

CONF is a instance of oslo_config.cfg.ConfigOpts. Mostly self.CONF is sufficient to instantiate this class from your OSKen application.

datapath_id specifies Datapath ID of the target OVS instance.

ovsdb_addr specifies the address of the OVS instance. Automatically validated when you call init() method. Refer to os_ken.lib.ovs.vsctl.valid_ovsdb_addr for the format of this address.

if timeout is omitted, CONF.ovsdb_timeout will be used as the default value.

Usage of timeout and exception is the same with timeout_sec and exception of os_ken.lib.ovs.vsctl.VSCtl.run_command.

add_bond(name, ifaces, bond_mode=None, lacp=None)

Creates a bonded port.

Parameters:
  • name -- Port name to be created

  • ifaces -- List of interfaces containing at least 2 interfaces

  • bond_mode -- Bonding mode (active-backup, balance-tcp or balance-slb)

  • lacp -- LACP mode (active, passive or off)

add_db_attribute(table, record, column, value, key=None)

Adds ('key'=)'value' into 'column' in 'record' in 'table'.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl add TBL REC COL [KEY=]VALUE
add_gre_port(name, remote_ip, local_ip=None, key=None, ofport=None)

Creates a GRE tunnel port.

See the description of add_tunnel_port().

add_tunnel_port(name, tunnel_type, remote_ip, local_ip=None, key=None, ofport=None)

Creates a tunnel port.

Parameters:
  • name -- Port name to be created

  • tunnel_type -- Type of tunnel (gre or vxlan)

  • remote_ip -- Remote IP address of tunnel

  • local_ip -- Local IP address of tunnel

  • key -- Key of GRE or VNI of VxLAN

  • ofport -- Requested OpenFlow port number

add_vxlan_port(name, remote_ip, local_ip=None, key=None, ofport=None)

Creates a VxLAN tunnel port.

See the description of add_tunnel_port().

clear_db_attribute(table, record, column)

Clears values from 'column' in 'record' in 'table'.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl clear TBL REC COL
db_get_map(table, record, column)

Gets dict type value of 'column' in 'record' in 'table'.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl get TBL REC COL
db_get_val(table, record, column)

Gets values of 'column' in 'record' in 'table'.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl get TBL REC COL
del_controller()

Deletes the configured OpenFlow controller address.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl del-controller <bridge>
del_port(port_name)

Deletes a port on OVS instance.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl del-port <bridge> <port>
del_qos(port_name)

Deletes the Qos rule on the given port.

delete_port(port_name)

Deletes a port on the OVS instance.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl --if-exists del-port <bridge> <port>
find_db_attributes(table, *conditions)

Lists records satisfying 'conditions' in 'table'.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl find TBL CONDITION...

Note

Currently, only '=' condition is supported. To support other condition is TODO.

get_controller()

Gets the configured OpenFlow controller address.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl get-controller <bridge>
get_datapath_id()

Gets Datapath ID of OVS instance.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl get Bridge <bridge> datapath_id
get_db_attribute(table, record, column, key=None)

Gets values of 'column' in 'record' in 'table'.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl get TBL REC COL[:KEY]
get_ofport(port_name)

Gets the OpenFlow port number.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl get Interface <port> ofport
get_port_name_list()

Gets a list of all ports on OVS instance.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl list-ports <bridge>
get_vif_ports()

Returns a VIF object for each VIF port

init()

Validates the given ovsdb_addr and connects to OVS instance.

If failed to connect to OVS instance or the given datapath_id does not match with the Datapath ID of the connected OVS instance, raises os_ken.lib.ovs.bridge.OVSBridgeNotFound exception.

list_db_attributes(table, record=None)

Lists 'record' (or all records) in 'table'.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl list TBL [REC]
remove_db_attribute(table, record, column, value, key=None)

Removes ('key'=)'value' into 'column' in 'record' in 'table'.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl remove TBL REC COL [KEY=]VALUE
run_command(commands)

Executes the given commands and sends OVSDB messages.

commands must be a list of os_ken.lib.ovs.vsctl.VSCtlCommand.

The given timeout and exception when instantiation will be used to call os_ken.lib.ovs.vsctl.VSCtl.run_command.

set_controller(controllers)

Sets the OpenFlow controller address.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl set-controller <bridge> <target>...
set_db_attribute(table, record, column, value, key=None)

Sets 'value' into 'column' in 'record' in 'table'.

This method is corresponding to the following ovs-vsctl command:

$ ovs-vsctl set TBL REC COL[:KEY]=VALUE
set_qos(port_name, type='linux-htb', max_rate=None, queues=None)

Sets a Qos rule and creates Queues on the given port.

exception os_ken.lib.ovs.bridge.OVSBridgeNotFound(msg=None, **kwargs)