# OVSDB library

Path: `ryu.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 `ryu.lib.ovs.vsctl.VSCtl`.
2. Construct commands with `ryu.lib.ovs.vsctl.VSCtlCommand`. The syntax is almost the same as ovs-vsctl command.
3. Execute commands via `ryu.lib.ovs.vsctl.VSCtl.run_command`.

### Example

    from ryu.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

### ryu.lib.ovs.vsctl

`ovs-vsctl` command like library to speak OVSDB protocol

class `ryu.lib.ovs.vsctl.``VSCtl`(remote)

  A class to describe an Open vSwitch instance.

  `remote` specifies the address of the OVS instance. `ryu.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 `ryu.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 `ryu.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`.

`ryu.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.

### ryu.lib.ovs.bridge

Wrapper utility library of `ryu.lib.ovs.vsctl`

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

  Class to provide wrapper utilities of `ryu.lib.ovs.vsctl.VSCtl`

  `CONF` is a instance of `oslo_config.cfg.ConfigOpts`. Mostly `self.CONF` is sufficient to instantiate this class from your Ryu 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 `ryu.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 `ryu.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 `ryu.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 `ryu.lib.ovs.vsctl.VSCtlCommand`.

    The given `timeout` and `exception` when instantiation will be used to call `ryu.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 `ryu.lib.ovs.bridge.``OVSBridgeNotFound`(msg=None, **kwargs)