Skip to content

Module Kathara

Jump to bottom
sat edited this page Aug 12, 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 scenario 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 scenario Kathara derives an interface's name from its index in lab.conf, so a device's interfaces are eth0, eth1, ... An interface class asking for another prefix is rejected.
A hole in a device's interface indexes Kathara rejects the lab. dot2net names the case rather than emitting it.
Device names outside [a-z0-9_]{1,30} Kathara's own rule, checked here so the message can name the scenario's node.
Nodes placed on more than one machine A lab.conf describes one machine. A scenario declaring worker groups is rejected.

Required Parameters

Parameter Meaning
image The device's image. Without one Kathara starts its own base image, which is rarely what a scenario 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 scenario that collects files or has teardown commands needs the script for them to happen. See Command Reference.

See Also

Clone this wiki locally