Using VLANd

Initial setup

To set up a VLANd instance, you’ll need to install the software. then configure the initial database access - see db/ for help with that.

Next, tell VLANd about all the switches that you want to use, in vland.cfg. Each switch must have a unique name defined (or an IP address if you don’t have DNS set up). VLANd also needs details of which driver to use and how to log in.

Populate the database to match your switch configuration. That’s possible by directly adding all the switches, ports and VLANs individually using the vland-admin tool manually, but it will be very long-winded and error-prone. Instead, vland-admin has a subcommand auto_import_switch which will do most of the hard work for you - run it once per switch. For sanity, check the configuration of your switches before you start. For example, if you have VLANs already defined, make sure they’re already consistent (i.e. matching tags and names). auto_import_switch will try to do the right thing for you based on what it reads from your switches, but it will fail if it can’t understand your setup.

Once you have all the ports, switches and VLANs imported or set up in the database, configure the ports appropriately:

  • any inter-switch connections should be set into trunk mode so that they will pass traffic for all VLANs. (vland-admin set_port_mode)
  • (optionally) if you plan on using the Visualisation, add trunks showing your inter-switch connections so that it can show them. (vland-admin create_trunk)
  • all other ports should be set into access mode. (vland-admin set_port_mode)
  • if you have infrastructure devices connected to your switches, it is recommended that you lock them to stop users accidentally changing configuration and breaking your infrastructure. (vland-admin lock_port)
  • if you have any multi-homed devices attached to your network, you may want to isolate some of their connected ports. (vland-admin create_vlan, vland-admin set_port_base_vlan, vland-admin restore_port_to_base_vlan)


vland-admin is a tool designed to expose the VLANd APIs to local admins. It’s basically a thin wrapper around the APIs. Using it, you can look up lots of details about the system and also make changes. Here’s a summary of the available commands; run vland-admin command --help for more details on each one.

usage: vland-admin [-h]

optional arguments:
  -h, --help            show this help message and exit

    status              Describe current system status
    statistics          Print some system statistics
    version             Describe the version of this admin interface
    vland_version       Describe the version of the running VLANd
    probe_switches      Probe all the configured switches
    auto_import_switch  Attempt to import a switch's configuration into the
                        VLANd system
    shutdown            Shut down a running VLANd
    list_all_switches   List all the existing switches in the system
    create_switch       Add a new switch to the system
    delete_switch       Remove an existing switch from the system
    show_switch         Show the details of an existing switch in the system
                        Lookup a switch ID by name
    list_all_ports      List all the existing ports in the system
    create_port         Add a new port to the system
    delete_port         Remove an existing port from the system
    show_port           Show the details of an existing port in the system
                        Lookup a port ID by switch ID and port name
                        Lookup a port ID by switch ID and port number
                        Lookup port ID(s) by switch ID
                        Lookup port ID(s) by current VLAN ID
                        Lookup port ID(s) by base vlan ID
                        Lookup port ID(s) by trunk ID
    set_port_mode       Set the mode of a port to 'trunk' or 'access'
    get_port_mode       Get the mode of a port ('trunk' or 'access')
    lock_port           Lock the settings on a port
    unlock_port         Unlock the settings on a port
                        Set the current VLAN assignment for a port
                        Get the current VLAN assignment for a port
    set_port_base_vlan  Set the base VLAN assignment for a port
    get_port_base_vlan  Get the base VLAN assignment for a port
                        Reset a port back to its base VLAN
    list_all_vlans      List all the existing VLANs in the system
    create_vlan         Add a new VLAN to the system
    delete_vlan         Remove an existing VLAN from the system
    show_vlan           Show the details of an existing VLAN in the system
    lookup_vlan_by_tag  Find the VLAN ID of an existing VLAN in the system
    show_vlan_tag       Print the VLAN tag of an existing VLAN in the system
    list_all_trunks     List all the existing trunks in the system
    create_trunk        Add a new trunk to the system, linking two ports
    delete_trunk        Remove an existing trunk from the system
    show_trunk          Show the details of an existing trunk in the system

vland-admin tips

Start by listing the various items (e.g. vland-admin list_all_ports) if you’re not sure what you’re after.

vland-admin will always want to use IDs for its APIs (to reference switches, ports, VLANs or trunks. Remember to use the lookup APIs (e.g. vland-admin lookup_port_by_switch_and_number) to work out the ID that you need before attempting to make changes.

If you’re looking to work on specific ports manually and you’re not sure of the IDs, use the Visualisation. Simply run your mouse over the various ports on the switch you’re looking at, and it will show you more details in the popup. This will likely be much quicker than calling the lookup APIs on the command line over and over.

How to use the VLANd API

There isn’t (yet!) a friendly module to expose the API. The easiest way to use things at the moment is to copy what vland-admin does:

   from Vland.ipc.ipc import VlanIpc
   ipc = VlanIpc()
   ipc.client_connect(*server*, *port*)
   msg['client_name'] = 'my-application'
   msg['type'] = *type*
   ret = ipc.client_recv_and_close()
   *decode msg*

.. index:: common API tasks

Common tasks with the API

VLANd was designed to work with LAVA, providing API access to VLANs as LAVA tests need them. LAVA’s typical setup in a VLANd-enabled test will have several test devices included, each with multiple network interfaces. The test writer will be asking for one or more VLANs to be set up.

As the test devices are configured in a typical lab, LAVA will have a switch name and a port number for each of the network interfaces. The sequence of calls in a simple test will look something like:

  • connect to VLANd via IPC
  • for each network interface used:
    • look up the switch ID from the switch name
    • lookup the port ID from the switch ID and the port number
  • create the specified VLANs
  • move ports to the VLANs as desired
  • run the test
  • return each port to its base VLAN
  • delete each of the VLANs that was created
  • disconnect from VLANd

The code to do this in LAVA is inside the LAVA dispatcher - see if you’d like to see exactly how it’s done.


It is hoped that VLANd will work reliably and do just what you need! But, like all software, it’s possible that you might encounter problems. Here are the things to try if VLANd appears to be misbehaving:

  • Check that VLANd is running.
  • Check that the postgres database server is still running. If you have restarted it, you will also need to restart VLANd.
  • Look in the VLANd logfile (/var/log/vland.log by default) for errors. If there is a back-trace at the end, you’ve found a bug.
  • Check the timestamps in the logfile to see how recent they are.
  • Run a simple vland-admin status and see if you get a response. Errors from vland-admin here will typically suggest that VLANd is not running, or something else is hogging the comms socket.
  • If API calls hang, maybe VLANd is stuck doing something else. When the command is received, it should show in the log . If not, then VLANd is definitely stuck somewhere. Try killing the VLANd process(es) and restarting, and see if things respond now.

The most common causes of VLANd problems are a missing database connection (as mentioned earlier), or a misbehaving switch. Simply restarting VLANd is normally enough to get things back up and running, but depending on the state of the switches you might need to unwind changes (VLAN creation, port moving, etc.) to put things back to normal.