4. Experimental Commands¶

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 gfor generating topology file. You can also generate a dot formatted file or image files supported by graphviz.

Here is a list of required tools for topo term command to output in terminal. MacOS is also supported optionally for which SPP controller runs on a remote host.

• graphviz
• imagemagick
• libsixel-bin (for Ubuntu)
• iTerm2 and imgcat (for MacOS)

To output in browser with topo http command, install packages for websocket with pip or pip3.

• 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 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 have to get a shell script imgcat from iTerm2’s displaying support site and save this script as spp/src/controller/3rd_party/imgcat.

Fig. 4.1 topo term example

spp > topo http

spp > topo [FILE_NAME] [FILE_TYPE]

# 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"];
...

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.

Fig. 4.2 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

Fig. 4.3 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. topo_resize¶

topo_resize is a supplemental command for changing the size of images displayed on the terminal with topo.

topo displays an image generated from graphviz with default size. However, it is too small or large for some environments because it depends on the resolution actually.

To check default size, run topo_resize with no arguments. It shows current size of the image.

# shows current size
spp > topo_resize
60%

You can resize it with percentage

# resize with percentage
spp > topo_resize 80%
80%

or ratio.

# resize with ratio
spp > topo_resize 0.8
80%

4.4. 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!