==============================================================================
                               v53-01
==============================================================================
                               GENERAL
==============================================================================
Cloonix is an AGPLv3 software that constitutes a tool to create networks of kvm
virtual machines or crun containers. It provides a graphical interactive canvas
showing the topology for your network, it is a virtualisation hypervisor.

The network connecting the virtual machines and containers is created through
the use of the openvswitch software running inside a linux net namespace
so that your host is isolated from cloonix network configuration.

Building of the binaries is done in a virtual debian trixie, all the necessary
files and libraries are included into the tool to make it self-sufficient.

Cloonix provides 2 supports for installation: cloonix-bundle or cloonix-toy,
both are tar.gz files that contains all and need no outside libraries.

To install the bundle, you must have the root privileges but to install the
toy, you only need to be an unpriviledged a user on a linux machine.

3 brandtypes of virtualizations run in cloonix: kvm, zip or cvm, the kvm is the
only real virtualization run with qemu-kvm, both the zip and cvm are container
types run with crun, a C implementation of the Open Container Initiative.

Qemu-kvm uses .qcow2 files, zip uses zip files and cvm uses directories as
root file-systems.
 
See clownix.net for a documentation.
http://clownix.net/doc_stored/build-53/html/index.html doc.

==============================================================================
LAST VERSION v53-01 NEWS:
This is a first shot at embedding open source https://github.com/Raizo62/vwifi 
into the cloonix blob, adding glue to have a seamless creation of wifi type
interfaces wlan0, wireless interfaces based on the mac80211_hwsim module.
==============================================================================

==============================================================================
                          BUNDLE INSTALLATION
==============================================================================
The bundle way for installation is based on cloonix-bundle-53.tar.gz, it
copies binary files to /usr/libexec/cloonix/cloonfs directory of your host,
puts bash scripts in /usr/bin/cloonix_xxx and uses /var/lib/cloonix as
work zone.

With this choice, root privileges are necessary for installation and
as there are cloonix actions that are related to namespaces or networks,
some binaries have the suid root permissions to run with higher privileges.

1) Download software and installation:
--------------------------------------

wget http://clownix.net/downloads/cloonix-53/cloonix-bundle-53.tar.gz
tar xvf cloonix-bundle-53.tar.gz
cd cloonix-bundle-53
sudo ./install_cloonfs

(To uninstall:   sudo rm -f /usr/bin/cloonix_*
                 sudo rm -rf /usr/libexec/cloonix
                 sudo rm -rf /var/lib/cloonix)


2) Download virtual machines and containers:
------------------------------------------

mkdir -p /var/lib/cloonix/bulk
cd /var/lib/cloonix/bulk

qcow2 (virtual machine for qemu-kvm):
wget http://clownix.net/downloads/cloonix-53/bulk/trixie.qcow2.gz
gunzip trixie.qcow2.gz

zip (container for crun):
wget http://clownix.net/downloads/cloonix-53/bulk/trixie.zip

cvm (container for crun):
wget http://clownix.net/downloads/cloonix-53/bulk/trixie.tar.gz
tar xvf trixie.tar.gz


3) Download demo script files for conventionnal eth networks:
-------------------------------------------------------------

wget http://clownix.net/downloads/cloonix-53/demos/eth_kvm.sh
wget http://clownix.net/downloads/cloonix-53/demos/eth_zip.sh
wget http://clownix.net/downloads/cloonix-53/demos/eth_cvm.sh

4) Download demo script files for experimental wireless:
--------------------------------------------------------

wget http://clownix.net/downloads/cloonix-53/demos/wpa_kvm.sh
wget http://clownix.net/downloads/cloonix-53/demos/wpa_zip.sh
wget http://clownix.net/downloads/cloonix-53/demos/wpa_cvm.sh

==============================================================================

==============================================================================
                          TOY INSTALLATION
==============================================================================
The cloonix-toy needs no privileges either at install or at run.
This is a user land application, it only needs a linux distribution to be run.
------------------------------------------------------------------------------

1) Download:
------------
wget http://clownix.net/downloads/cloonix-53/cloonix-toy-53.tar.gz

2) Extract the directory:
-------------------------
tar zxvf cloonix-toy-53.tar.gz

3) Call the setup.sh script to adapt the tool to its env:
---------------------------------------------------------
cd cloonix-toy-53
./setup.sh

4) A little help is provides at setup end, first call gui provider:
-------------------------------------------------------------------
./nemocmd canvas

5) Dump the possible demos availlable:
--------------------------------------
./nemocmd demo

6) Call a demo:
---------------
./nemocmd demo frrline

7) Kill all:
------------
./nemocmd stop 


NOTE:
=====
For the cloonix to be able to use the qcow2 files, devices /dev/kvm,
/dev/vhost-net, /dev/net/tun, vhost-vsock, vsock must have read/write
access by the user launching the demonstration.
For the cloonix to be able to use the wifi emulation, the module
mac80211_hwsim must be inserted in the kernel.

-----------------------------------------------------------------------------


==============================================================================
                         NOTES FOR THE CANVAS GUI
==============================================================================

cloonix_gui nemo gives the canvas gui, on this canvas a double-click or a right
click when above no object gives the canvas menu.

A double-click on a blue machine gives a shell, a double-click on the green
interface (small peripheral circle) gives a wireshark spy, a right-click on
the blue machine gives a menu from which you can choose a spice desktop (only
for kvm based virtuals).

The crun containers zip or cvm are smaller, a double-click in the blue zone
gives a shell, right-click on the container gives a menu from which you can
pick a remote console.

==============================================================================

==============================================================================
                            DISTANT WEB GUI:
==============================================================================
Default value for the web gui is off, to set it on:

In the bundled install:
cloonix_cli nemo cnf web on

In the extractor install:
./nemocmd web_on

Xvfb creates a virtual framebuffer on a defined DISPLAY,
this display can be seen through its X11 socket at /tmp/.X11-unix/.
Then on this display, wm2 is launched, it is a very small windows manager.
When the wm2 representation gets to be visible in your browser,
click on the main mouse button, and choose the only choice which is "cloonix".
x11vnc carries the equivalent of a desktop to the vnc server and
finaly websockify puts this desktop inside a web browser.

For nemo the http link for the browser is:

   http://<ip_of_server>:54521

Note that the 54521 port can be changed in:

  /usr/libexec/cloonix/cloonfs/etc/cloonix.cfg

-----------------------------------------------------------------------------