Tutorial¶
Audience¶
This tutorial is written for users familiar with traditional virtual machine workflows — selecting an OS image (ISO or QCOW2), allocating CPU / RAM / disk, configuring networking, and installing or booting an operating system.
Onteon VM Stack provides the same capabilities on top of a local
single-node Onteon Stack (also known as a demo cluster). Instead of a GUI or a
Vagrantfile, the onteon-cli command-line tool is used to create, configure,
start, stop and snapshot QEMU virtual machines.
This tutorial covers the minimum Onteon vocabulary needed to:
- Launch pre-built VMs (Ubuntu, CentOS, Gentoo) with zero configuration — they come with embedded disk images and sensible defaults.
- Create a generic QEMU VM, download an ISO from the internet, and install an operating system from scratch.
Terminology Mapping¶
| Familiar concept | Onteon equivalent |
|---|---|
| VirtualBox / VMware | QEMU system emulator |
| Vagrant box / VM template | Application (app) — a packaged QEMU microservice |
vagrant up |
onteon-cli onm create instance + start instance |
vagrant ssh |
SSH through port forwarding (or SPICE) |
vagrant halt |
onteon-cli onm stop instance |
vagrant destroy |
onteon-cli onm delete instance |
| Vagrant Cloud / box registry | OCC (Onteon Control Center) — app registry |
| Hypervisor host | ONM (Onteon Node Manager) — runs the VMs |
Prerequisites¶
- A Linux machine with KVM support.
- Root access (the installer runs system-wide services).
- A machine without an existing Onteen OCC/ONM installation (the stack includes its own).
1. Install the Onteon VM Stack¶
The installer deploys a complete single-node Onteon demo cluster (Onteon Control Center with Onteon Node Manager) and pre-loads the QEMU microservice applications.
./install.bash \
--occ-ip-address "127.0.0.1" \
--occ-node-id "localhost" \
--occ-node-name "localhost" \
--onm-ip-address "127.0.0.1" \
--onm-node-id "localhost" \
--onm-node-name "localhost" \
--installation-dir "/var/lib/onteon" \
--install-qemu
After the script finishes, verify the CLI is available:
Check that both Onteon Stack components started:
Set up auth tokens:
onteon-cli config set \
--auth-token "a9f3c2e8b47d6a1f09ce5d24b8a7e3f2" \
--refresh-token "7e4a9c2f1b8d0e6c5a3f9d2b4e7a1c8c"
Get the overview of the local stack environment:
The output should resemble:
127.0.0.1:7019 (7019)
|
127.0.0.1 (8030)
|
falcon-db-core-onm-microservice-1.9.0-9393ddb
nginx-inner-1.3.10-89ef9e276c778df84fc760b5
nginx-edge-1.3.10-0ef5f1479808100f7fe54c49
qemu-centos-1.0.1-qemu-centos-app
qemu-ubuntu-1.0.1-qemu-ubuntu-app
qemu-gentoo-1.0.1-qemu-gentoo-app
qemu-1.0.1-qemu-generic-app
Note
If You get a "connection refused"-type error from the above command instead or do not see the application names in the graph, then it means that Onteon components have not yet started. On a system with 4 CPU cores (or more) and 8 GB of RAM (or more) it should take up to 2 minutes to start. On systems that have less resources or are busy with other tasks (have high system load) it might take up to 5 minutes.
2. Connect and Explore¶
The Onteon Stack runs on localhost by default (Onteon Control Center (OCC) on
port 7020 and Onteon Node Manager (ONM) on port 8030).
The simplest way to connect:
The Onteon Node Manager (ONM) with IP address of 127.0.0.1 should be listed
in the return output of above command. If it is not listed it means that the
local Onteon Node Manager has not connected yet, please retry it a few times,
up to a minute, after that time it should the available on the list. It is also
possible that in special network setups the ONM might come up with a different
IP other than 127.0.0.1 - in such cases We can just use that IP, as reported
in onteon-cli occ get node-managers instead of 127.0.0.1.
Set the localhost ONM as the default:
List the pre-loaded applications (the "VM templates"):
The output should resemble:
nginx-inner 1.3.10 89ef9e276c778df84fc760b5 embedded native DATE-TIME CREATED
nginx-edge 1.3.10 0ef5f1479808100f7fe54c49 embedded native DATE-TIME CREATED
qemu-centos 1.0.1 qemu-centos-app embedded native DATE-TIME CREATED
qemu-gentoo 1.0.1 qemu-gentoo-app embedded native DATE-TIME CREATED
qemu-ubuntu 1.0.1 qemu-ubuntu-app embedded native DATE-TIME CREATED
qemu 1.0.1 qemu-generic-app embedded native DATE-TIME CREATED
The first three are pre-built VMs with embedded disk images.
The last one (qemu) is a generic QEMU microservice without
a pre-loaded image — it is used in section 7 to boot from a
downloaded ISO.
3. Your First VM: CentOS¶
3.1 Create an instance¶
An "instance" is a concrete virtual machine created from an "application template" (generally referred to as application in Onteon terms). Create one from the CentOS app:
3.2 Start the instance¶
This clones the embedded QCOW2 disk image, resizes it to the default 20 GB, and boots the VM with QEMU + KVM.
After the VM starts You can get the info about it via the app's info command:
You should see this or similar message in the processOutput:
[INFO 12:01:43] VM_OS_TYPE : unknown
[INFO 12:01:43] VM_BOOT_UEFI : FALSE
[INFO 12:01:43] VM_DISK_SIZE : 20
[INFO 12:01:43] VM_CPUS : 2
[INFO 12:01:43] VM_RAM : 2048
[INFO 12:01:43] VM_SPICE : TRUE
[INFO 12:01:43] VM_SPICE_PORT : 15900
[INFO 12:01:43] VM_MONITOR_PORT : 10000
[INFO 12:01:43] VM_NET_USER_NIC : TRUE
[INFO 12:01:44] VM_NET_PORT_MAP : 12200:22,18000:80
[INFO 12:01:44] VM_NET_BR : FALSE
[INFO 12:01:44] VM_NET_BR_AUTO : TRUE
[INFO 12:01:44] VM_NET_BR_IFACE : ont-vmbr-0
[INFO 12:01:44] VM_NET_BR_IP : 70.70.70.1
[INFO 12:01:44] VM_NET_BR_MASK : 24
3.3 Connect via SPICE (graphical console)¶
The VM starts with SPICE enabled by default on port 15900
(or the next available port). Connect with remote-viewer:
The CentOS VM's console will be displayed. Log in with the
default credentials baked into the image (user: root, password: onteon).
Tip
Onteon VM images have those credentials combinations:
- user:
root, password:onteon - user:
root, password: (none) --- optionally - user:
onteon, password:onteon--- optionally
Warning
The remote-viewer tool has to be installed specifically on the client
system You are connecting from. It acts similarly to a SSH client or a web
browser.
On Ubuntu the remote-viewer executable is a part of the virt-viewer
package. See the Ubuntu's
help on remote-viewer.
3.4 Connect via SSH (port forwarding)¶
The VM also sets up user-mode networking with port forwarding.
By default the host port 12200 is forwarded to the VM's port 22.
Connect with SSH:
3.5 Stop the VM¶
The instance transitions back to the CREATED state — the disk
is preserved and can be started again later.
4. More Pre-Built VMs¶
Ubuntu¶
Ubuntu uses BIOS boot, like CentOS. The workflow is identical:
onteon-cli onm create instance qemu-ubuntu-app qemu-ubuntu-instance
onteon-cli onm start instance qemu-ubuntu-app qemu-ubuntu-instance
SPICE port will auto-increment if 15900 is taken.
Gentoo (UEFI)¶
Gentoo boots with UEFI instead of BIOS. The lifecycle is otherwise the same:
onteon-cli onm create instance qemu-gentoo-app qemu-gentoo-instance
onteon-cli onm start instance qemu-gentoo-app qemu-gentoo-instance
5. VM Lifecycle Basics¶
| Action | Command |
|---|---|
| List instances | onteon-cli onm get instances |
| Start | onteon-cli onm start instance <app-id> <instance-id> |
| Stop | onteon-cli onm stop instance <app-id> <instance-id> |
| Terminate | onteon-cli onm terminate instance <app-id> <instance-id> |
| Delete | onteon-cli onm delete instance (--permanently) <app-id> <instance-id> |
Note
Command stop performs a clean shutdown; terminate sends an immediate
kill signal to the QEMU microservice process.
6. Snapshots¶
Snapshots allow saving and restoring the VM disk state.
Offline snapshot (VM stopped)¶
onteon-cli onm exec instance qemu-centos-app qemu-centos-instance \
snapshot-disk "create snapshot-1"
List snapshots:
Restore a snapshot:
onteon-cli onm exec instance qemu-centos-app qemu-centos-instance \
snapshot-disk "apply snapshot-1"
Delete selected snapshot:
onteon-cli onm exec instance qemu-centos-app qemu-centos-instance \
snapshot-disk "delete snapshot-1"
Live snapshot (VM running)¶
And afterwards stop, restore and start:
onteon-cli onm exec instance qemu-centos-app qemu-centos-instance \
snapshot-disk "apply snapshot-2"
Both commands forward to qemu-img snapshot under the hood.
Delete the disk (all snapshots gone)¶
Use delete-disk with care — it removes the disk image and all its
snapshots. This deletes all storage of a particular VM. It will basically reset
the VM to blank slate after instance start.
7. Custom VM from an ISO¶
This section covers the common scenario of booting a VM from an installer ISO and installing an operating system from scratch.
The qemu (generic) microservice has no embedded disk image.
On start, the microservice:
- creates a blank QCOW2 disk,
- waits for a boot ISO to appear,
- boots the VM from the ISO to enable OS installation.
7.1 Create an instance of the generic QEMU app¶
7.2 Download an ISO¶
Use the download-image command before starting the instance.
For example, to download the CentOS Server 24.04 ISO:
onteon-cli onm exec instance qemu-generic-app qemu-generic-instance \
download-image \
" --set-image-type iso --set-image-download-url https://releases.centos.com/24.04.4/centos-24.04.4-live-server-amd64.iso"
Warning
The command may throw a timeout (The response status is not OK, given:
504,) because Onteon requests have max life time of 2 minutes. In that
case observe whether the file
/var/lib/onteon/onteon-node-manager/store/qemu/qemu-generic-app.iso is
present. If that file exists and grows then it means that the command is
still running - wait for the ISO to reach the desired size. If it does not
exist or the file is stuck at incorrect size, then the download failed.
The ISO is saved to the microservice's store and linked for discovery by the
start script (in directory /var/lib/onteon/onteon-node-manager/store/qemu).
7.3 Boot the VM and install¶
Now start the instance:
QEMU boots from the ISO. Connect via SPICE:
The CentOS Server installer will be displayed. Proceed with the standard installation steps — partition the blank disk, install the OS, and reboot.
7.4 After installation¶
Once the OS is installed and the installer requests a reboot, the instance can be stopped:
The ISO is no longer needed for subsequent boots. When the instance is started again, QEMU will boot from the installed disk (the QCOW2 image) instead of the ISO:
8. Tuning Resources¶
You can change CPU, RAM, disk size, and other settings before
or after creating an instance using the write-conf command.
Note
From this section we return to the CentOS VM. Be sure to stop it first.
CPU and RAM¶
onteon-cli onm exec instance qemu-centos-app qemu-centos-instance \
write-conf " --vm-cpus 4 --vm-ram 4096"
(RAM is specified in megabytes — 4096 = 4 GB.)
Disk size¶
Disk size is applied when the image is first cloned or created. To request a larger disk, set it before the first start:
Note
For "disk size set" to actually see it take effect You will have to delete the VM disk first. Currently there is no way to resize the disk of instance after it has been started (only before the 1st start). However it is possible to use raw Linux commands to achieve this.
Boot mode¶
onteon-cli onm exec instance qemu-centos-app qemu-centos-instance \
write-conf " --vm-boot-uefi TRUE"
SPICE on/off¶
All write-conf options¶
| Option | Values | Description |
|---|---|---|
--vm-os-type |
freeform text | OS type (e.g. "linux", "windows") |
--vm-boot-uefi |
TRUE / FALSE | UEFI firmware (default: FALSE) |
--vm-disk-size |
integer (GB) | QCOW2 disk size |
--vm-cpus |
integer | Number of CPU cores |
--vm-ram |
integer (MB) | Amount of RAM |
--vm-spice |
TRUE / FALSE | Enable SPICE graphical console |
--vm-spice-port |
integer | SPICE port number |
--vm-net-user-nic |
TRUE / FALSE | User-mode networking (NAT) |
--vm-net-port-map |
HOST:VM,... |
Port forwarding rules |
--vm-net-br |
TRUE / FALSE | Bridged networking |
--vm-net-br-auto |
TRUE / FALSE | Auto-create the bridge |
--vm-net-br-iface |
string | Bridge interface name |
--vm-net-br-ip |
IP address | Bridge IP address |
--vm-net-br-mask |
integer | Bridge netmask (e.g. 24) |
9. Networking¶
Default: user-mode (NAT)¶
By default, each VM is configured with user-mode networking. The VM can reach the internet, and the host can reach the VM through explicit port maps.
Default port map:
The port map can be customised with write-conf:
onteon-cli onm exec instance qemu-centos-app qemu-centos-instance \
write-conf " --vm-net-port-map 2222:22,8080:80"
Private bridge¶
A private bridge allows for those communication types:
- Virtual Machine to Virtual Machine,
- Virtual Machine to host,
- host to Virtual Machine.
But it disallows the Virtual Machine to Internet communication.
Warning
Keep in mind that all the above communication can only occur over the
specified IP address associated with a private bridge interface. So for
example if there is a service that runs only on localhost (127.0.0.1),
then the VM (with private bridge IP set to 70.70.70.1) will not be able
to see it.
Configure the VM to use a private bridge so VMs can communicate with each other and with the host:
onteon-cli onm exec instance qemu-centos-app qemu-centos-instance \
write-conf " --vm-net-br TRUE --vm-net-br-auto TRUE --vm-net-br-ip 70.70.70.1 --vm-net-br-mask 24"
When above command success You should see in processOutput the following:
VM_NET_BR="TRUE"
VM_NET_BR_AUTO="TRUE"
VM_NET_BR_IFACE="ont-vmbr-0"
VM_NET_BR_IP="70.70.70.1"
VM_NET_BR_MASK="24"
The bridge is created automatically on the host, and the VM gets a network device of type TAP attached to it.
Private device on VM¶
After above steps succeed the bridge is set up on the host, but not yet on the VM. On the VM side one needs to configure the newly created interface and set a static IP and mask.
After VM boots You should see this in the onteon-cli output:
[DEBUG 11:22:02] VM_NET_BR is: TRUE
[DEBUG 11:22:02] VM_NET_BR is enabled
[DEBUG 11:22:02] VM_NET_BR_AUTO is: TRUE
[DEBUG 11:22:02] VM_NET_BR_AUTO is enabled
[DEBUG 11:22:02] Device ont-vmbr-0 does not exist, creating it
[INFO 11:22:02] Creating the bridge device: ont-vmbr-0
[DEBUG 11:22:02] Exe: /usr/bin/sudo /usr/sbin/ip link add ont-vmbr-0 type bridge
[INFO 11:22:02] Stopping the network device: ont-vmbr-0
[DEBUG 11:22:02] Exe: /usr/bin/sudo /usr/sbin/ip link set ont-vmbr-0 down
[INFO 11:22:02] Adding IP 70.70.70.1/24 to device: ont-vmbr-0
[DEBUG 11:22:02] Exe: /usr/bin/sudo /usr/sbin/ip addr add 70.70.70.1/24 dev ont-vmbr-0
[DEBUG 11:22:02] Device ont-vmbr-0 already has address
[INFO 11:22:02] Starting the network device: ont-vmbr-0
And if You execute ip --color a on the host you should see info similar to:
ont-vmbr-0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue
state UP group default qlen 1000
inet 70.70.70.1/24 scope global ont-vmbr-0
ont-vmtap-0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel
master ont-vmbr-0
state UP group default qlen 1000
Log into the CentOS VM via SPICE. Then, execute the following:
Warning
Remember, you are doing this and next steps in this subsection on the virtual machine. If you do this on your host it will surely break.
From the above command You should see one or two network interfaces in addition
to the lo loopback (local-only) device. If there are two it means that both
user-mode networking and bridge are enabled, in such case the bridge device
should be the second. The devices should have names starting with enp0s but
it may look different on other operating systems.
Afterwards execute:
If the above commands succeeded you can now SSH from the host to the VM:
You should see:
Warning: Permanently added '70.70.70.111' (ED25519) to the list of known hosts.
root@70.70.70.111's password:
root@vm:~#
Full LAN bridge¶
To place the VM directly on the local network (receiving its own IP from the
LAN's DHCP server), create a bridge on the host manually and attach it to the
physical NIC. You will have to turn off br-auto (--vm-net-br-auto FALSE)
and pass the name of the new bridge that You also connect a Ethernet interface
to (for example: --vm-net-br-iface lan-br).
onteon-cli onm exec instance qemu-centos-app qemu-centos-instance \
write-conf " --vm-net-br TRUE --vm-net-br-auto FALSE --vm-net-br-iface lan-br --vm-net-br-ip 80.80.80.1 --vm-net-br-mask 24"
10. Downloading QCOW2 Images Directly¶
Instead of installing from an ISO, a ready-to-use QCOW2 image can be downloaded directly. This avoids the installation step.
onteon-cli onm exec instance qemu-generic-app qemu-generic-instance \
download-image \
" --set-image-type qcow2 --set-image-download-url https://example.com/some-image.qcow2"
The QCOW2 replaces the blank disk. On the next start, the VM boots directly into the downloaded OS.
11. Configuration File Reference¶
For persistent CLI configuration, the file lives at
~/.config/tech.onteon.cli/onteon/onteon-cli/config.yaml.
You can also override settings via environment variables
(OCLI_OCC_ADDRESSES, OCLI_ONM_IP, etc.) or CLI flags.
See the full Onteon-CLI Onboarding guide for all configuration options.
Next Steps¶
- Run the full command tree with
onteon-cli commands getto explore all available subcommands. - Set up a private or LAN bridge to experiment with VM-to-VM communication.
- Use the
snapshot-diskandsnapshot-livecommands to create restore points during OS installation or testing.