Get started

Ten minutes, no root, nothing left behind if you delete the directory afterwards.

1. Check the host

Linux, x86-64. For containers that is all. For virtual machines your account must read and write three devices:

getfacl /dev/kvm /dev/vhost-net /dev/net/tun
sudo setfacl -m u:${USER}:rw /dev/kvm /dev/vhost-net /dev/net/tun

A container runs no init unless you ask for one, so the usual topology needs nothing here. If you do ask — startup_env=CLOONIX_WITH_SYSTEMD=1 — each systemd wants about five inotify instances, counted per user, and the default of 128 runs out near the twenty-fourth container. There is no error anywhere: the container starts and dies. Raise the limit first:

sudo sysctl -w fs.inotify.max_user_instances=8192

2. Take the toy

The toy is a tarball that carries cloonix inside its own container. Extract it as your normal user:

tar xf cloonix-toy-100.tar.gz
cd cloonix-toy-100
./setup.sh nemo

setup.sh writes a command script named after the network you chose — ./nemocmd — and reports what the machine can and cannot do. A line saying wifi emulation is unavailable is not fatal; it tells you in advance which demos will not run.

3. Start it

./nemocmd start

Then open the canvas:

https://127.0.0.1:4444

From another machine, https://<ip>:4444. The certificate is self-signed: accept the warning once. The page then asks for a user and a password:

They are not secret: the user is the name of the network, the password its cloonix_passwd, the name of the network followed by clown; for the network nemo: user nemo, password nemoclown. Both are in the configuration, where they can be changed:

/usr/libexec/cloonix/cloonfs/etc/cloonix.cfg                   the bundle
<toy directory>/rootfs/cloonix/cloonfs/etc/cloonix.cfg         the toy

4. Make something

Right-click the empty canvas to create a machine, a container or a lan, or play one of the demos from the Demo button of the header:

./nemocmd demo               # list what is available
./nemocmd demo security/wg.py      # a wireguard tunnel, and a wire that goes blank

A demo is a python programme taking the name of the network as its only argument. It runs on the machine you typed on and drives the server across the network, so the server needs no interpreter. What each one shows.

Then double-click a node for a root shell, or a green interface dot for a packet capture.

5. Stop it

./nemocmd cloonix cli nemo del all   # destroy every object, keep the server
./nemocmd stop                   # stop the server and the container

The bundle instead

Use the bundle when the machine is a shared server and several people run their own networks on it. It installs once, as root:

tar xf cloonix-bundle-100.tar.gz
cd cloonix-bundle-100
sudo ./install_cloonfs

That puts the run-time under /usr/libexec/cloonix, one command cloonix in /usr/bin, the demos in /usr/share/cloonix, and copies the certificate of the tarball into /usr/share/cloonix/cert for the secure web port. Then:

cloonix start nemo                        # start a network, in a terminal of its own
cloonix cli nemo add cnt c1 eth=1 trixie  # a container with one port
cloonix cli nemo ssh c1                   # a root shell inside it

Guest images

A machine needs a root file-system in /var/lib/cloonix/bulk, which the toy reads on the host too; every demo asks for one, trixie for the plain containers. Download it, or build it:

cd vm_create/cnt_kvm
./doitall.sh --cnt trixie      # a container image
./doitall.sh --kvm trixie      # a qemu image

The demos of demos/ ask for one image per subject — frr, asterisk, wireguard and the rest. Those are built next door, and that driver takes the demo name:

cd vm_create/cnt_kvm_demo
./doitall.sh frr               # the image the frr demos need
./doitall.sh --all             # every image every demo needs

From another machine

When something does not work