Kathara: container based network emulation for teaching and prototyping

Every emulated device is a container

Kathara is a lightweight network emulation system based on Docker containers, and the mechanism is described in three short paragraphs.

Each network device is emulated by a container. Virtual network devices are interconnected by virtual layer 2 LANs. Each container can potentially run a different Docker image, with built-in images including Quagga, FRRouting, Bind, P4 and OpenVSwitch, and you can also use your own container images.

So the topology is a set of containers with virtual interfaces wired into virtual L2 segments. A router is a container running a routing daemon image, a DNS server is a container running Bind, and the L2 fabric is provided by virtual devices rather than by real switches.

The name comes from the Greek, and the project describes itself as the spiritual successor of Netkit, which it calls notorious. The consequence of that lineage is compatibility: it is cross-compatible with Netkit and inherits its language and features. For anyone who learned network labs on Netkit, the scenario files and the command vocabulary are the same.

The stated uses are interactive demos and lessons, testing production networks in a sandbox environment, and developing new network protocols. The topic tags name the protocol and platform surface the project covers, including BGP, OSPF, RIP, DNS, P4 language, software defined networking, network function virtualization, Netkit, Kubernetes and Docker.

The project is developed by the Roma Tre Computer Networks and Security Research Group, the licence is GPL-3.0, and the primary language is Python.

A scenario is a directory, not a file format

The concept the documentation leans on is the network scenario, and it is described as a directory containing a file with the network topology and, for each device, files and folders containing the configuration of that device.

That is a deliberate choice and it has a practical effect. A scenario is a directory tree of text files, which means it can be committed to a repository, reviewed in a pull request, copied between machines and taught in a course without a special tool. The alternative, a single binary or proprietary file, would make the same scenario harder to inspect and impossible to diff meaningfully.

The quick example shows the layout in use. You download and unpack a scenario, a Small Internet lab with a DNS and web server, then change into the scenario directory and start it.

kathara lstart

Kathara reads the configuration of the scenario from lab.conf and from the various *.startup files, and starts the devices, opening terminal windows so you can interact with them. When you are done experimenting, you clean it up the same way.

kathara lclean

So the pair of commands is the whole lifecycle of a lab. There is no separate teardown manifest, no state file to reason about, and the scenario directory is the single source of truth for what gets started.

The documentation also points to a PDF of the network topology for the same lab, which is a nice detail: the topology is available as a diagram for the people who do not want to read the configuration files, and as configuration for the people who will.

The same scenario runs on Docker or on Kubernetes

Kathara emulates network scenarios using either Docker or Kubernetes as the backend virtualization system, and the Kubernetes route has its own name, Megalos, and its own documentation.

The distinction is about scale. The Docker backend is the simple case: one container per device, virtual interfaces, virtual LANs, done. Megalos exists because that does not scale to large topologies, and the publications list makes the trajectory clear. There is a NOMS 2018 paper on Kathara as a container-based framework for network function virtualization and software defined networks, a NOMS 2020 paper on Megalos as a scalable architecture for the virtualization of network scenarios, a second NOMS 2020 paper on Kathara as a lightweight network emulation system which received a Best Demo Paper Award, a 2021 Future Internet Journal paper on Megalos for the virtualization of large network scenarios, and a NOMS 2022 paper on Sibyl, a framework for evaluating routing protocol implementations in fat-trees.

So the project has a research pedigree, and the architecture is published rather than improvised.

For a user, the practical question is which backend to pick. Docker is the default and the one the quick example uses. Kubernetes is for the cases where a scenario has to run across many machines, and the wiki page for Megalos is where to read about it.

The Python API is the third way in. The documentation points at a Python APIs Tutorial and a Kathara API Docs page, and the topic tags include p4language, which suggests the API is used for driving the emulation programmatically rather than only from the command line.

The dependency list explains what the tool has to talk to

The pyproject.toml is short and revealing, because the dependencies are exactly the interfaces a network emulation tool needs to touch.

There is docker at version 7.0.0 or newer, and kubernetes at 23.3.0 or newer, which are the two backends. pyroute2 is there, and that is the library for talking to the Linux kernel network interfaces directly, which is how the virtual devices and LANs get created. rich is the terminal rendering library, and it is what gives the command line its output.

Then there are the platform-specific entries, and they say a lot about what the tool does for the user. libtmux is required on macOS and Linux, and appscript on macOS, which together are how the tool opens a terminal window per emulated device so you can log into it. On Windows there is pypiwin32 and windows-curses instead, since tmux and AppleScript are not there.

The rest is ordinary. requests for HTTP calls, fs for filesystem operations, chardet for encoding detection, binaryornot for detecting binary files, and setuptools held below version 81.

The Python requirement is 3.10 or newer, and the classifiers cover 3.10 to 3.13. The package is built with setuptools under a src/ layout, with a legacy setup.py still present alongside the pyproject, and the test extra is pytest.

Reading that dependency list tells you the shape of the tool better than the feature list does. It is a Python program that talks to Docker or Kubernetes, to the kernel network stack, and to your terminal emulator, and the last of those is why the tool feels like a lab rather than a config generator.

Where Kathara is the wrong tool

The first wrong-tool case is a large topology on a single host. Every device is a container and every virtual interface and LAN is a kernel object, so the resource cost grows with the number of devices. The Megalos architecture and the 2021 paper on the virtualization of large network scenarios exist because the Docker backend does not solve that problem, and a large scenario on a laptop is exactly the case the project points at Kubernetes for.

The second case is a network security or protocol exercise that needs a real network rather than an emulated one. Kathara gives you virtual L2 LANs between containers. It does not give you the physical characteristics of a real link, and it is not a traffic generator or a link emulator, so anything about real hardware behaviour is out of scope.

The third case is a team that needs the tooling to be a product rather than a lab tool. The documentation frames the tool around demos, lessons, sandbox testing and protocol development, and the artifacts are scenario directories and command line tools. There is no service contract, no multi tenancy and no scheduled execution model described in the visible documentation.

There is a compatibility question to check as well. The project inherits Netkit's language and features, which is the reason to use it if you already know Netkit, and a reason to be careful if you do not, because the inherited vocabulary assumes a Netkit mental model.

On maintenance, the version is 3.8.3 and the last push was on 2026-10-15, with releases 3.8.3 from 2026-04-09, 3.8.1 from 2026-03-19 and 3.8.0 from 2025-07-29. The project is developed by a university research group with a GPL-3.0 licence, which is the right licence for something published by an academic group and reused in teaching, and it also means that a company embedding it in a product has to think about the copyleft obligations.

Editorial conclusion

Kathara suits a networking course or a protocol experiment where the topology must be reproducible and inspectable, because a scenario is a directory of configuration files that can live in version control and be started with one command. It does not suit a production network emulation load, since a scenario of any size is a set of containers, and Megalos exists precisely because the Docker backend does not scale to large topologies. Before adopting, read the scenario format rather than the API, and check that the device images you need exist in the Docker Images repository, since the set of built-in images is what determines how far the emulation can go.

Frequently asked questions

Official sources

1. KatharaFramework/Kathara on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases