Lightweight libvirt/QEMU topology runner with cloud-init user provisioning and automatic networking.
- YAML-described topologies (networks and nodes)
- Libvirt/QEMU VMs with COW overlays
- Automatic tap/bridge setup per network
- Cloud-init ISO auto-generated (user
netsim, SSH key from~/.ssh/id_rsa.pub) - SSH port-forwarding per node (2200 + node index)
- Image caching and auto-download
- Linux with KVM and bridge support
- libvirt daemon running
- Packages (Ubuntu/Debian):
sudo apt-get install -y \ libvirt-daemon-system libvirt-clients libvirt-dev \ qemu-system-x86 \ python3-libvirt \ genisoimage \ bridge-utils \ swtpm
- Python 3.9+
- SSH key at
~/.ssh/id_rsa.pub(generate withssh-keygen -t rsa -N "" -f ~/.ssh/id_rsaif missing)
poetry install
source .venv/bin/activate
sudo ./setup-user-mode.sh # adds you to libvirt/kvm and configures sudoers for ip commands
# log out/in for group changes# Start an example topology (creates bridges/taps, cloud-init ISO, boots VMs)
netsim start examples/two_node_iperf/two_node_iperf.yaml
# Show connection info (SSH ports, status)
netsim connect examples/two_node_iperf/two_node_iperf.yaml
# SSH to node1 (mgmt port 2200)
ssh -p 2200 netsim@localhost
# Stop / resume
netsim stop examples/two_node_iperf/two_node_iperf.yaml
netsim start examples/two_node_iperf/two_node_iperf.yaml
# Destroy (remove VMs, taps, bridges)
netsim destroy examples/two_node_iperf/two_node_iperf.yaml- Networks: name, subnet, mtu
- Nodes: name, image (path or {name,url,checksum}), memory, vcpus, networks (list of network names to connect)
- Interfaces: auto-allocated at start time. First network = eth0 (management), additional networks = eth1, eth2, etc.
- IPs: auto-allocated from each subnet starting at .10 (gateway is .1)
- Example: see
examples/two_node_iperf/two_node_iperf.yaml
- A cached ISO is generated at
~/.netsim/cloud-init/cloud-init-netsim.iso - Creates user
netsimwith SSH key from~/.ssh/id_rsa.pub - Attached as SATA CD-ROM to each VM automatically
netsim start <topology.yaml>netsim stop <topology.yaml>netsim status <topology.yaml>netsim connect <topology.yaml>netsim destroy <topology.yaml>netsim image list|download|remove|clear
netsim.testkit is a pytest plugin that turns a topology into fixtures: booted
VMs, SSH access, netplan-configured interfaces, and .deb installation. Install
it with the extra, then opt in from your project's rootdir conftest.py:
pip install 'netsim[testkit] @ git+ssh://git@github.com/pdmorrow/netsim.git@v0.2.0'# conftest.py
pytest_plugins = ["netsim.testkit.plugin"]A suite is a directory holding its topology, named after it — a test in
tests/mysuite/ loads tests/mysuite/mysuite.yaml. From there the fixtures
topology, nodes, node_interfaces, configure_node_interfaces and
install_user_packages are available, along with the options --package-dir,
--feature, --pause-on-failure and --tpm. Inherit BaseTopologyTests to
pick up the standard allocation, interface and connectivity assertions.
A minimal suite is three files:
# tests/mysuite/mysuite.yaml
name: "mysuite"
version: "1.0"
networks:
- name: "net1"
subnet: "10.1.1.0/24"
nodes:
- name: "alice"
image:
name: "debian-13-genericcloud"
url: "https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2"
checksum: "<sha512>"
networks: ["net1"]
- name: "bob"
image:
name: "debian-13-genericcloud"
url: "https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2"
checksum: "<sha512>"
networks: ["net1"]# tests/mysuite/__init__.py (empty — makes the suite a package)# tests/mysuite/test_mysuite.py
from netsim.testkit.base import BaseTopologyTests
class TestMySuite(BaseTopologyTests):
def test_alice_can_ping_bob(
self, configure_node_interfaces, node_interfaces, nodes
):
bob_ip = node_interfaces["bob"]["net1"].get_ip_address()
nodes["alice"].ssh_command(f"ping -c 3 {bob_ip}", timeout=10)Run it with make test-suite SUITE=mysuite. examples/two_node_iperf/ is the
smallest complete example in this repo, and shows package installation and
richer assertions on top of the same pattern.
Run one suite at a time — a suite tree is a single package, so pytest sets up the package-scoped topology once and a second suite in the same session would reuse the first one's VMs:
make test-suite SUITE=two_node_iperf # one suite
make test # all of them, one pytest run each- Permission errors / Operation not permitted: ensure
setup-user-mode.shran, re-login; checkidforlibvirtandkvmgroups; verify/etc/sudoers.d/netsimexists. - Libvirt connection errors:
sudo systemctl start libvirtd; setNETSIM_LIBVIRT_URIif using system libvirt. - Missing tools:
genisoimage,python3-libvirt, andqemu-system-x86must be installed.
- Image management: docs/IMAGE_MANAGEMENT.md