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. First put the images it will use in /var/lib/cloonix/bulk of the host: setup.sh gives the toy that directory only if it exists when setup.sh runs, and a bulk made afterwards is not seen by the toy:

sudo mkdir -p /var/lib/cloonix/bulk
sudo chown ${USER}: /var/lib/cloonix/bulk
cd /var/lib/cloonix/bulk
wget https://clownix.net/downloads/cnt_bulk/trixie.tar.gz
cd

Then extract the toy as your normal user:

tar xf cloonix-toy.tar.gz
cd cloonix-toy
./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: it lists the demos by package, plays the one picked, shows each cloonix command in its log and tells the steps in its History. 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

Delete all, in the header of the canvas, destroys every object and keeps the server; then:

./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.tar.gz
cd cloonix-bundle
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, when the directory was there before its ./setup.sh; 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