Open vSwitch VDSM hook
======================

This hook enables us to create selected networks and bonds as Open vSwitch
devices.


Warning
-------

This hook is not yet ready to be used in real environment. It passes some VDSM
networks tests, but it is not able to run with oVirt Engine as a native Linux
networking replacement. See TODO below.


Installation
------------

In case of missing openvswitch package in repositories, you might install the
package manualy.

Install vdsm-hook-ovs package on a host:
yum install vdsm-hook-ovs

Configure engine for hook's custom network properties:
PROPERTIES='ovs=.*'
engine-config -s "UserDefinedNetworkCustomProperties=$PROPERTIES" --cver='3.5'
systemctl restart ovirt-engine

Don't forget to include the names of other custom network properties you may
want to use, such as 'ethtool_opts'.


Usage
-----

Setup network:
In the oVirt UI open the 'Setup Host Networks' dialog. Proceed to editing
a desired logical network's properties. Among them you will find 'ovs', set
it to 'true' or '1' to mark is as OVS Network.

Setup bonding:
In the oVirt UI open the 'Setup Host Networks' dialog. Merge two networks.
In opened 'Create New Bond' dialog select 'Bonding Mode' 'Custom' and set
it to 'ovs=True'.


Limitations
-----------

- Only one untagged network
- STP only on untagged network
- All networks are bridged
- Tested only with ifcfg configurator. OVS rollback probably won't be working
  with iproute2 or pyroute2 configurators


TODO
----

- Faster rollback:
  + Now in case of a rollback, we remove all OVS networks and bonds and then
    recreate them. This could be improved with changing just what have to
    be changed as we do in iproute2 rollback.
- Implement QoS:
  + Linux HFSC QoS is supported by OVS and could be set up via ovs-vsctl
    as described here: [1]
- Implement 'multicast_router' and 'multicast_snooping':
  + This feature is not supported by openvswitch until 2.4.0
  + We need to be able to set and get those values. It should be possible
    via 'mcast_snooping_enable' records, described here [1]
- Implement implicitBonding
- Defined multiple OVS Bridge instances:
  + Now custom network property 'ovs' is passing only True, we could change it
    to pass an integer and then create OVS network under 'ovsbr$INT'
    OVS Bridge instance.
- Fix networkTestsOVS.py dependencies:  # TO BE CHECKED
  + It is possible that this test fail would cause problems when
    vdsm-hook-ovs package is installed without vdsm-tests.
- Better OVS command logging:
  + Now we log created OVS command as one long string. It would be nice to
    split commands with new lines and add 'comment' about what was done with
    certain sub-command.
- Allow non-OVS=>OVS and OVS=>non-OVS changes:
  + Now we do not handle the situation when OVS network is changed into
    non-OVS and vice versa.
  + non-OVS=>OVS editation should be easy, we could handle it within
    a before_network_setup hook.
  + OVS=>non-OVS editation is harder, while we have to first remove non-OVS
    network and then create OVS network after_network_setup.
- Better handling of traceback and logging:
  + We need more logging.
  + Traceback sometimes provides hooking mess, but not an initial error.
- Network persistence:
  + An easy way would be to remove all OVS networks on startup (as we do in
    rollback) and then let persistence restoration to recreate it all.
- Bond does not turn UP:  # TO BE CHECKED
  + When we create OVS Bond and attach real NICs to it, it does not turn UP,
    even after `ip link set ovsbond up`
  + Check if it OK or a BUG.
- Call `sysctl enable openvswitch` on hook installation
- Implement bridgeOpts:
  + We need to implement at least some of bridgeOpts, it is not possible to be
    read the way we do it with native Linux bridges.
- Implement ports:
  + We should report NICs and VM nets attached to bridge/network in caps.
- Move needed VDSM non-libraries to vdsm/lib:
  + Now we use hacky sys.path.append('/usr/share/vdsm') to access some VDSM
    modules. They should be moved to vdsm/lib.
- When we configure dhclient over a network and then setup fails, dhclient
  is not rolled back.
- Handle dhclient return code


[1] http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf
