Qeneth

String together QEMU VMs with UDP sockets using graphviz(7), mustache(1) and duct tape.

               .--------.
    Graph ---> |        |      .---------------------.
               | qeneth | ---> | qemu-system-${ARCH} |-.
Templates ---> |        |      '---------------------' |-.
               '--------'        `---------------------' |
                                   `---------------------'

qeneth starts from an undirected graphviz(7) Graph of "record nodes". The graph is analyzed, annotated with information, and split into per-node YAML documents. Finally, these documents are filtered through one or more mustache(1) Templates to create executable scripts. Typically the generated script will launch an instance of qemu-system-${ARCH}, but it could be anything.

Some basic process monitoring is available, but the executables can also be run manually or through some other process monitor.

Installation

Clone the repository and place the absolute path to qeneth is in your $PATH. A few tools are required to run, on Debian based systems like Ubuntu or Linux Mint:

~$ sudo apt install e2fsprogs graphviz ruby-mustache squashfs-tools \
        qemu-system-x86 qemu-utils

Basic completion support for Bash is available. Copy or symlink qeneth-complete.sh to /etc/bash_completion.d to enable it.

Tutorial

This tutorial makes use of one of the bundled Infix NOS templates. We start by creating our tutorial directory where all files related to our network project will be stored. Then we download a pre-built Infix image into it:

~$ mkdir tutorial
~$ cd tutorial/
~/tutorial$ wget -q https://github.com/kernelkit/infix/releases/download/latest/infix-x86_64.tar.gz
~/tutorial$ tar xf infix-x86_64.tar.gz infix-x86_64/infix-x86_64.img
~/tutorial$ mv infix-x86_64/infix-x86_64.img .
~/tutorial$ rm -rf infix-x86_64/ infix-x86_64.tar.gz

Next, let's setup our topology, edit ~/tutorial/topology.dot.in:

graph "tutorial" {
    node [shape=record];
    qn_template="infix-x86_64";
    qn_append="quiet";
    qn_mem="512M";
    qn_oui="00:a0:85";

    server [label="server   | { <e1> e1 | <e2> e2 }", qn_basemac="02:de:ad:00:00:00"];
    client1 [label="client1 | { <eth1> eth1 }"];
    client2 [label="client2 | { <eth1> eth1 }"];

    server:eth0 -- client1:eth0 [qn_tailmac="02:de:ad:12:34:56", qn_headmac="08:00:20:c0:ff:ee"];
    server:eth1 -- client2:eth0;
}

The two clients in this example connect to the server, which has two interfaces named e1 and e2. We name all <interfaces> (called "ports" in graphviz) and put the same label on them. The name is used in all qemu script generation and the label is "only" used when generating a graph. Use your favorite graphviz(7) layout engine to visualize it. Here we've used neato -Tpng topology.dot.in -otopology.png:

• qn-append is what is appended to the kernel command line
• qn_mem overrides the template's default RAM size for all nodes
• qn_oui sets a default MAC OUI prefix for all nodes
• qn_basemac changes the base MAC used for all connections on one node
• qn_tailmac and qn_headmac overrides the MAC address for a specific interface on a link

Note: the names headmac and tailmac refer to the head and tail end of the edge in the graph. Even though we do not use directed edges the left side is called the tail and the right is head.

Everything we need is now in place - so we can generate the scripts and all support files:

~/tutorial$ qeneth generate
Info: Generating topology
Info: Generating node YAML
Info: Generating executables
~/tutorial$ ls
client1         client2         infix-x86_64.img  server.yaml   topology.dot.in
client1.mactab  client2.mactab  server            topology.dot
client1.yaml    client2.yaml    server.mactab

Finally, we can start our network:

~/tutorial$ qeneth start
Info: Launching server
Info: Launching client1
Info: Launching client2
~/tutorial$ qeneth status
NODE           PID  CNSOL  MONTR
server     2811526  10000  10001
client1    2811527  10010  10011
client2    2811528  10020  10021

Attach to the different nodes with qeneth console NODE. Use Ctrl-] to get to the telnet> prompt, quit with 'q' followed by enter:

~/tutorial$ qeneth console server
Trying 127.0.0.1...
Connected to localhost.

Infix by KernelKit (console)
server login: root
Note: use help, show, and setup commands to set up and diagnose the system.
root@server:~# ip -br link
lo               UNKNOWN        00:00:00:00:00:00 <LOOPBACK,UP,LOWER_UP>
eth0             UP             02:00:00:00:02:00 <BROADCAST,MULTICAST,UP,LOWER_UP>
eth1             UP             02:00:00:00:02:01 <BROADCAST,MULTICAST,UP,LOWER_UP>
root@server:~#
telnet> Connection closed.
~/tutorial$

When we are done, we stop all the nodes:

~/tutorial$ qeneth stop
Info: Stopping server
Info: Stopping client1
Info: Stopping client2

Host Interaction

In addition to VM-to-VM communication, a Qeneth network can also be connected to the host system. This is done by connecting a VM port to a port on a node named host. Every port on host will show up as a TAP interface.

Let's look at an example topology (~/host-net/topology.dot.in):

graph "host-net" {
        node [shape=record];
        qn_template="infix-x86_64-classic";

        host   [label="host  | { <tap-infix> tap-infix }"];
        infix  [label="infix | { <eth0> eth0 | <eth1> eth1 }"];

        host:"tap-infix" -- infix:eth0;
}

After generating and starting the network, a new TAP interface (tap-infix) is created, which is connected to eth0 inside the VM infix:

~/host-net$ qeneth generate && qeneth start
Info: Generating topology
Info: Generating node YAML
gvpr: warning: Using value of uninitialized edge attribute "qn_headport" of "host--infix"
Info: Generating executables
Info: Launching infix
~/host-net$ ip -br link | grep tap-infix
tap-infix        DOWN           ce:fe:82:f8:cd:19 <BROADCAST,MULTICAST>
~/host-net$ ip addr add 10.10.10.1/24 dev tap-infix
~/host-net$ qeneth console infix
Trying 127.0.0.1...
Connected to localhost.

Infix by KernelKit (console)
infix login: root
Note: use help, show, and setup commands to set up and diagnose the system.
root@infix:~# ip addr add 10.10.10.2/24 dev eth0
root@infix:~# ping -c 3 10.10.10.1
PING 10.10.10.1 (10.10.10.1): 56 data bytes
64 bytes from 10.10.10.1: seq=0 ttl=64 time=0.241 ms
64 bytes from 10.10.10.1: seq=1 ttl=64 time=0.474 ms
64 bytes from 10.10.10.1: seq=2 ttl=64 time=0.504 ms

--- 10.10.10.1 ping statistics ---
3 packets transmitted, 3 packets received, 0% packet loss
round-trip min/avg/max = 0.241/0.406/0.504 ms
root@infix:~#
telnet> q
Connection closed.