What you can learn

A topology costs a few lines of text and a few seconds. Nothing on your machine is touched. When you have broken it beyond repair you type del all and build it again.

Nothing here is a simulation

A lan is an Open vSwitch bridge. A kvm guest has its own kernel. A cnt guest is a real container with a real network stack. The routing daemons are the ones a carrier runs, and they do not know they are in a demo. When OSPF reconverges after you cut a cable, that is OSPF reconverging.

The daemons, the kernels and the frames are those of real machines: a configuration works or fails in cloonix for the reason it does on them, the timing of the hardware aside (What cloonix is not, below).

The loop

Every demo leaves the network running when it ends, so the topology it built is there to be changed, broken and captured after the last line of the script.

1. Run it cloonix cli nemo demo 2. Look dump drawing 3. Break it unplug, cnf A2B 4. Capture cnf sniff=, sniff 5. Explain two wires, one packet change one line of the script and run it again

The demos are chosen for failure modes where the symptom names a different layer than the cause. Stop OSPF in the dns demo and name resolution stops: the symptom is DNS, the cause is routing. Leave out the discard route in frrmix and every BGP session comes up, reports itself established, and carries nothing.

The one habit: catch the packet

A counter inside a guest reports what that guest believes; a capture reports what crossed the wire. Cloonix puts a sniffer on any capturable interface and hands back only what matches a filter — and the filter is applied on the server, so what does not match never crosses the wire to you.

an interface eth=1, green cloonix-ovs-snf one copy, many readers the filter applied here webshark, in the browser wireshark dissectors, no Qt cloonix cli <net> sniff ... --dump  --bytes  --line cloonix cli nemo cnf gwA eth1 sniff=on    then    cloonix cli nemo sniff gwA eth1 --dump udp port 51820

Two subscriptions with the same filter, one on each side of a tunnel or a translation, is the standard way here of showing that something was encrypted, dropped or rewritten. The grammar is a subset of tcpdump's, and its limits are part of what it shows: below IP it knows arp alone, so a demo about EAPOL or batman OGMs says so and captures unfiltered rather than inventing a filter that cannot exist.

The demos

Subject areas, then one python file per demo: demos/<area>/<demo>.py. The docstring at the top of each one says what the software is and what the demo does with it, then the topology as ascii art, then the packet to catch; its first line is what the Demo panel of the canvas shows beside the name. The chapters of the user book give every demo its history, its network and its commands, area by area.

A course through it

Twelve packages, each a few demos on one subject, ordered so that a package uses only what the ones before it showed. On every step: run the demo, read the canvas and its Comments panel, catch the packet, break one thing and repair it. The chapter Learning with cloonix of the user book gives each package its steps, its packet and its break.

0 first net 1 cloonix items 2 one wire 3 addresses 4 routing 5 tunnels 6 the edge 7 services 8 failover 9 overlays 10 wifi 11 other guests on every step 1 run the demo 2 read the canvas and the Comments panel 3 catch the packet with sniff 4 break one thing, watch, repair
packagedemoswhat it shows
0The first networkcloonix/cnt.py cloonix/kvm.pyadd, plug, ssh, sniff, del all
1The cloonix itemscloonix/a2b.py snf.py nat.py c2c.py nginx.py mount.py limit.py systemd.py cntwifi.py kvmwifi.py cntkvmwifi.pya shaped wire, the capture, the way out, three nets joined, the way in, mounts and caps, an init, the radios
2One wireswitching/vlan.py stp.py802.1Q tags, a loop and spanning tree
3Addresses, names, timeaddress/dhcp.py ipv6.py dns.py unbound.py knot.py ntp.pya relay, an address made from an advertisement, udp 53 and tcp 53, udp 123
4Routingrouting/frrspider.py frrspider_bgp.py frrmix.py bird.py isis.py babel.py batman.pyOSPF, BGP, redistribution, a second daemon, IS-IS, rerouting, a layer 2 mesh in the kernel
5Encryption and tunnelssecurity/tls.py wg.py openvpn.py tinc.py ipsec.pyhttps beside http, then what the middle wire shows before and after a tunnel
6The edgesecurity/nftables.py suricata.py ebpf.py radius.py arp.pyfilter, inspect, drop in the kernel, authenticate, and arp poisoning
7Servicesservices/proxy.py squid.py smtp.py mqtt.py asterisk.pyproxies, mail, publish and subscribe, a phone call
8Staying upavailability/vrrp.py cluster.pyan address that moves, a service that fails over
9Overlays and the real networkswitching/vxlan.py ovn.py cloonix/phy.py realnet.py watching/perf.pya layer 2 net over a routed core, Geneve, a real interface taken in, a cloonix inside a kvm, where the throughput goes
10Wifiwifi/cnt_*.py kvm_*.py cntkvm_*.pyan open air, WPA2, WPA3, a bridge, roaming, a mesh, a home box, a login per user, a listener
11Other guestsfreebsd.py windows.py cisco.pya BSD with the agent, a windows desktop, a router on its console

What cloonix is not

It emulates a network, not hardware. Forwarding at line rate, ASIC behaviour, optics, anything where the timing of the silicon is the subject — those are outside it. An a2b shapes a cable enough to show what TCP does about a bad line; it is not a channel model. The wifi radios are mac80211_hwsim: the 802.11 state machine is real, association and EAPOL are real, the propagation is not.

Get started Read the documentation