Network Drivers

This document describes the network driver model, primarily from a system administrator’s standpoint, though there are some details useful for developers writing tools which interact with the API as well.

Overview

There are two classes of network-related drivers: network allocators and switches. Switches are straightforward to understand; they provide support for a particular hardware switch. Network allocators are a bit more abstract.

HaaS networks may be backed by various underlying isolation technologies (currently the only network allocator shipped with HaaS uses 802.1q VLANs, but there may be more, e.g. VXLANs in the future). A network allocator manages the details of mapping networks created by HaaS to these underlying technologies. For example, the vlan_pool allocator maps each network to a unique VLAN id.

Drivers are implemented as extensions, and must be added to the [extensions] section of haas.cfg. You must supply exactly one network allocator driver, and one or more switches. For example::

...
[extensions]
haas.ext.network_allocators.vlan_pool =
haas.ext.switches.dell =
haas.ext.switches.nexus =

Some drivers may also need driver specific options, which go in a section with the same name as the extension, e.g.::

[haas.ext.network_allocators.vlan_pool]
vlans = 300-500, 700-750

Network allocator drivers

The only network allocator shipped with HaaS that is of interest to users (there are others useful for development purposes) is the VLAN allocator. The name of the extension is haas.ext.network_allocators.vlan_pool, and it requires a single extension-specific config option, vlans, which is a comma separated list of VLAN ids and/or ranges of VLAN ids. Networks created within HaaS will use VLANs specified in the configuration file. An example::

...

[extensions]
haas.ext.network_allocators.vlan_pool =
...

[haas.ext.network_allocators.vlan_pool]
vlans = 300, 500-700, 800-950
...

Once HaaS has been started, removing VLANs from this list is not supported. You may add additional VLANs, but you will have to re-run haas-admin db create.

Security

It is VERY IMPORTANT that you be sure to configure your switches to guard against VLAN hopping attacks:

https://en.wikipedia.org/wiki/VLAN_hopping

Doing so is not difficult, and it is critical for security.

Switch drivers

At present, all switch drivers shipped with HaaS require that the VLAN pool allocator is in use. There are two switch drivers shipped with HaaS:

  • haas.ext.switches.dell, which provides a driver for the Dell Powerconnect 5500 series switches.
  • haas.ext.switches.nexus, which provides a driver for some Cisco Nexus switches. Only the 3500 and 5500 have been tested, though it is possible that other models will work as well.

Neither driver requires any extension-specific config options. Per the information in rest_api.md, the details of certain API calls are driver-dependant, below are the details for each of these switches.

Powerconnect driver

switch_register

To register a Dell Powerconnect switch, the "type" field of the request body must have a value of::

http://schema.massopencloud.org/haas/v0/switches/powerconnect55xx

In addition, it requires three extra fields: "username", "hostname", and "password", which provide the necessary information to connect to the switch via telnet ("hostname" may also be an IP address). SSH support is planned, but even so we do not recommend allowing connectivity to a switch’s management interface from an untrusted network.

switch_register_port

Port names must be of the same form accepted by the switch’s console interface, e.g. gi1/0/5. Be very careful when specifying these, as they are not validated by HaaS (this will be fixed in future versions).

Nexus driver

switch_register

The type field for the Nexus driver has the value::

http://schema.massopencloud.org/haas/v0/switches/nexus

The nexus driver requires the same additional fields as the powerconnect driver, plus an additional field “dummy_vlan”, which should be a JSON number corresponding to an unused VLAN id on the switch. This VLAN should be deactivated (and thus no traffic should flow across it ever). This exists to get around an implementation problem related to disabling the native VLAN.

For example, if you’ve chosen VLAN id 2222 to use as the dummy vlan, on the switch’s console, run:

# config terminal
# no vlan 2222

The body of the api call request can then look like:

{
    "type": "http://schema.massopencloud.org/haas/v0/switches/nexus",
    "username": "MyUser",
    "password": "secret",
    "hostname": "mynexus.example.com",
    "dummy_vlan": 2222
}

switch_register_port

Like the powerconnect driver, the Nexus driver accepts port names of the same format accepted by the underlying switch, in this case (e.g.) ethernet 1/42. The same concerns about validation apply.

Brocade driver

switch_register

The type field for the Brocade NOS driver has the value:

http://schema.massopencloud.org/haas/v0/switches/brocade

In addition to type, the brocade driver requires three additional fields hostname, username, password, and interface_type. interface_type refers to the type and speed of the ports on the switch, ex. “TenGigabitEthernet”, “FortyGigabitEthernet”. If you have multiple types of ports on the same switch, register the switch multiple times with different parameters for interface_type.

The body of the api call request will look like:

{
    "type": "http://schema.massopencloud.org/haas/v0/switches/brocade",
    "username": "MyUser",
    "password": "secret",
    "hostname": "mybrocade.example.com",
    "interface_type": "TenGigabitEthernet"
}

switch_register_port

The brocade driver accepts interface names the same way they would be accepted in the console of the switch, ex. 101/0/10.

Using multiple switches

Networks managed by HaaS may span multiple switches. No special configuration of HaaS itself is required; just register each switch as normal and ensure that all VLANs in the allocator’s vlans option are trunked to every managed switch.