4. Experimental Commands

There are experimental commands in SPP controller. It might not work for some cases properly because it is not well tested currently.

4.1. topo

Output network topology in several formats. Support four types of output.

  • Terminal
  • Browser (websocket server is required)
  • Text (dot, json, yaml)
  • Image file (jpg, png, bmp)

This command uses graphviz for generating topology file. You can also generate a dot formatted file or image files supported by graphviz.

Here is an example for installing required tools for topo term command to output in a terminal.

$ sudo apt install graphviz \
  imagemagick \
  libsixel-bin

MacOS is also supported optionally for using topo runs on a remote host. In this case, iTerm2 and imgcat are required as described in the next section.

To output in browser with topo http command, install required packages by using requirements.txt as described in install SPP, or only for them as follwoing.

$ pip3 install tornado \
  websocket-client

4.1.1. Output to Terminal

Output an image of network configuration in terminal.

spp > topo term

There are few terminal applications supporting to output image with topo. You can use mlterm, xterm or other terminals supported by img2sixel. You can also use iTerm2 on MacOS. If you use iTerm2, you need to downloada a shell script imgcat from iTerm2’s displaying support site and save this script as src/controller/3rd_party/imgcat with permission 775. topo command tries to img2sixel first, then imgcat in the 3rd_party directory.

../_images/topo_term_exp.svg

Fig. 4.8 topo term example

4.1.2. Output to Browser

Output an image of network configuration in browser.

spp > topo http

topo term is useful to understand network configuration intuitively. However, it should be executed on a node running SPP controller. You cannnot see the image if you login remote node via ssh and running SPP controller on remote.

Websocket server is launched from src/controller/websocket/spp_ws.py to accept client messages. You should start it before using topo term command. Then, open url shown in the terminal (default is http://127.0.0.1:8989).

Browser and SPP controller behave as clients, but have different roles. Browser behaves as a viwer and SPP controller behaves as a udpater. If you update network configuration and run topo http command, SPP controller sends a message containing network configuration as DOT language format. Once the message is accepted, websocket server sends it to viewer clients immediately.

4.1.3. Output to File

Output a text or image of network configuration to a file.

spp > topo [FILE_NAME] [FILE_TYPE]

You do not need to specify FILE_TYPE because topo is able to decide file type from FILE_NAME. It is optional. This is a list of supported file type.

  • dot
  • js (or json)
  • yml (or yaml)
  • jpg
  • png
  • bmp

To generate a DOT file network.dot, run topo command with file name.

# generate DOT file
spp > topo network.dot
Create topology: 'network.dot'
# show contents of the file
spp > cat network.dot
digraph spp{
newrank=true;
node[shape="rectangle", style="filled"];
...

To generate a jpg image, run topo with the name network.jpg.

spp > topo network.jpg
spp > ls
...  network.jpg  ...

4.2. topo_subgraph

topo_subgraph is a supplemental command for managing subgraphs for topo.

spp > topo_subgraph VERB LABEL RES_ID1,RES_ID2,...

Each of options are:

  • VERB: add or del
  • LABEL: Arbitrary text, such as guest_vm1 or container1
  • RES_ID: Series of Resource ID consists of type and ID such as vhost:1. Each of resource IDs are separated with , or ;.

Subgraph is a group of object defined in dot language. Grouping objects helps your understanding relationship or hierarchy of each of objects. It is used for grouping resources on VM or container to be more understandable.

For example, if you create two vhost interfaces for a guest VM and patch them to physical ports, topo term shows a network configuration as following.

../_images/topo_subg_before.svg

Fig. 4.9 Before using topo_subgraph

Two of vhost interfaces are placed outside of Host while the guest VM runs on Host. However, vhost:1 and vhost:2 should be placed inside Host actually. It is required to use subgraph!

To include guest VM and its resources inside the Host, use topo_subgraph with options. In this case, add subgraph guest_vm and includes resoures vhost:1 and vhost:2 into the subgraph.

spp > topo_subgraph add guest_vm vhost:1,vhost:2
../_images/topo_subg_after.svg

Fig. 4.10 After using topo_subgraph

All of registered subgraphs are listed by using topo_subgraph with no options.

spp > topo_subgraph
label: guest_vm subgraph: "vhost:1,vhost:2"

If guest VM is shut down and subgraph is not needed anymore, delete subgraph guest_vm.

spp > topo_subgraph del guest_vm

4.3. load_cmd

Load command plugin dynamically while running SPP controller.

spp > load_cmd [CMD_NAME]

CLI of SPP controller is implemented with Shell class which is derived from Python standard library Cmd. It means that subcommands of SPP controller must be implemented as a member method named as do_xxx. For instance, status subcommand is implemented as do_status method.

load_cmd is for providing a way to define user specific command as a plugin. Plugin file must be placed in spp/src/controller/command and command name must be the same as file name. In addition, do_xxx method must be defined which is called from SPP controller.

For example, hello sample plugin is defined as spp/src/controller/command/hello.py and do_hello is defined in this plugin. Comment for do_hello is used as help message for hello command.

def do_hello(self, name):
    """Say hello to given user

    spp > hello alice
    Hello, alice!
    """

    if name == '':
        print('name is required!')
    else:
        hl = Hello(name)
        hl.say()

hello is loaded and called as following.

spp > load_cmd hello
Module 'command.hello' loaded.
spp > hello alice
Hello, alice!