Skip to content

Module Kathara

Jump to bottom
sat edited this page Aug 15, 2026 · 7 revisions

Module: Kathara

This page describes the Kathara module for dot2net.

What is Kathara?

Kathara is a container-based network emulator built for teaching. A lab is a directory: a lab.conf naming the devices and the shared media they sit on, and a directory or a startup file per device.

What dot2net Generates

module:
  - kathara
output/
├── kathara/                # the lab directory
│   ├── lab.conf
│   ├── r1.startup
│   └── kathara.sh          # with module_config.kathara.generate_scripts
└── r1/etc/frr/frr.conf     # the node's own files, shared with the other platforms

lab.conf names each device's image, the directories mounted into it, and which collision domain each of its interfaces sits on:

LAB_NAME="ospf_simple"
r1[image]="quay.io/frrouting/frr:8.5.4"
r1[volume]="../r1/etc/frr|/etc/frr"
r1[0]="conn0"

A collision domain is a shared medium, which is what dot2net calls a switch node — the deploy: platform node that containerlab emits as a bridge and TiNET as a switches: entry. It is named after the node and gets no line of its own, since nothing is deployed for it. A link between two ordinary devices gets a domain of its own.

Why the lab sits in a directory of its own

Kathara reads a directory named after a device, next to lab.conf, as files to copy into that device once it has started. The nodes' generated files sit at the output root under exactly such names, so a lab.conf beside them would set that copying off: a second delivery nobody asked for, running after the device is up. One level down, the convention finds nothing.

Mounts are directories: mount_dirs

Kathara mounts directories and refuses single files. What is mounted is therefore a directory, and mounting one replaces what the image had there — dot2net cannot see inside an image to know whether that is safe. So the topology says which directories it is willing to take over:

module_config:
  kathara:
    mount_dirs: [/etc/frr]

This is a statement, not a restatement of the paths: dot2net supplies everything the software needs in /etc/frr.

A file to be mounted from a directory that was not named is reported, with both ways out — name the directory, or give the file provide: copy, which places it once the device is up. A directory named here that no file is generated into is reported too: taking over a directory of a device's filesystem is not a thing to do by accident, and a name that matches nothing is nearly always a misspelling.

What Kathara cannot express

Why
Interfaces named by the topology Kathara derives an interface's name from its index in lab.conf, so the interfaces it lists are eth0, eth1, ... One named anything else is rejected. This applies only to the interfaces Kathara puts there — those with deploy: link. A device the node's own configuration builds (deploy: logical: a bridge, a tunnel end) never gets a line in lab.conf, so Kathara has no say in its name and the topology keeps whatever it chose.
A hole in a device's interface indexes Kathara rejects the lab. Automatic naming hands the numbers to the wired interfaces first, so it cannot leave one; a hole means the topology named its interfaces itself and skipped a number.
Device names outside [a-z0-9_]{1,30} Kathara's own rule, checked here so the message can name the topology's node.

A lab across machines: network_plugin

A topology declaring worker groups gets a lab.conf per machine, the same as containerlab and TiNET. Joining the machines is a step outside the lab, and on Kathara it needs one change to Kathara's own settings.

Kathara builds a collision domain with a VDE driver by default (network_plugin: kathara/katharanp_vde), and a VDE domain puts no bridge on the host — so there is nothing on the machine for a VXLAN, or any other cross-machine link, to attach to. Setting network_plugin to kathara/katharanp builds collision domains as Linux bridges instead, which appear on the host as kt-<id> and can be joined the way containerlab's bridges are.

This is Kathara's setting, not something dot2net writes: nothing in the generated files chooses a plugin, and a lab on a single machine runs on either. Verified on a two-machine lab.

Required Parameters

Parameter Meaning
image The device's image. Without one Kathara starts its own base image, which is rarely what a topology means.

Options

module_config:
  kathara:
    mount_dirs: [/etc/frr]      # directories dot2net supplies entirely
    generate_scripts: true      # write kathara/kathara.sh

Running the Lab

The lab is the kathara/ directory, so Kathara is run from inside it:

dot2net build -c input.yaml input.dot

cd kathara
sudo kathara lstart --noterminals
sudo kathara lclean

With an entry script

module_config.kathara.generate_scripts: true (off by default) writes kathara/kathara.sh:

sudo ./kathara/kathara.sh deploy
sudo ./kathara/kathara.sh exec r1 vtysh -c "show ip ospf neighbor"
sudo ./kathara/kathara.sh destroy      # teardown, collect, then lclean

It knows where its files are and how to reach a device, which matters here: Kathara reads its files from the directory it runs in, and kathara exec cannot pass a command containing -c. A topology that collects files or has teardown commands needs the script for them to happen. See Command Reference.

See Also

Clone this wiki locally