Running LexiVirt, from zero

LexiVirt turns ordinary Linux servers into a place to run virtual machines. A virtual machine (VM) is a complete computer — its own CPU, memory, disk and operating system — that exists as software on top of a real machine. One physical server can run many of them, isolated from each other.

You get a web dashboard where you create a VM, give it CPU, memory and disk, boot it from an operating-system installer, and open its screen in your browser. If you have used VirtualBox on a laptop, it is the same idea built for servers: the machines run on hardware you own, several servers are managed from one browser tab, and there is no licence fee and nothing phoning home.

What it is not: it is not a cloud account, and there is no LexiVirt server holding your data. Everything runs on machines you own, and it keeps working with the internet unplugged.

There are only three moving parts. Understanding which is which makes everything else obvious.

Management console

The web interface you log into. It stores your user accounts, the list of compute nodes and the audit log in a small database. It does not run virtual machines — it only gives orders. The app itself listens on 127.0.0.1:9070 and is published to the network by nginx on port 9443 over HTTPS.

Compute node

A physical server that actually runs the VMs. Each one runs the agent: a small API on port 9071 that the console commands. The agent drives KVM through libvirt, creates the disk images, defines the machines and starts them.

The cluster secret

One shared credential between the console and every agent, generated when you install the management server. The console sends it on every request to a node; an agent rejects anything else. It is stored at /etc/lexivirt/agent.secret (readable by root only) on each machine.

The installer must run as root, so run it with sudo. It installs every dependency, generates its own credentials and TLS certificate, opens the firewall ports it needs, offers to download operating-system install images, and prints a full walkthrough when it finishes.

One server (start here)

Console and hypervisor on the same machine:

# everything on this one server
curl -sSL https://lexi-cloud.com/i/YOUR-KEY | sudo bash -s -- all

Separate console and compute nodes

On the machine that will host the dashboard:

curl -sSL https://lexi-cloud.com/i/YOUR-KEY | sudo bash -s -- manager

It prints the cluster secret and its own address at the end. Then, on every server that should run VMs:

curl -sSL https://lexi-cloud.com/install.sh | sudo bash -s -- \
     agent <cluster-secret> https://<console-ip>:9443

Run it without any questions

# choose the OS images up front, skip every prompt
LEXIVIRT_ISOS="debian alpine" \
  curl -sSL https://lexi-cloud.com/i/YOUR-KEY | sudo bash -s -- all

# other options: "none", "all", or any of: debian alpine ubuntu alma

Your sign-in details

Choosing a different password at install time

Pass it to the installer and the account is created with that instead — nothing is printed and nothing needs changing afterwards:

curl -sSL https://lexi-cloud.com/i/YOUR-KEY \
  | sudo LEXIVIRT_ADMIN_PASSWORD='your-password-here' bash -s -- manager

If lexi is not accepted

Then this console is not a fresh install and its admin password is something else. These two commands cover where it can be:

# The password this console was actually installed with
sudo grep LEXIVIRT_ADMIN_PASSWORD /etc/systemd/system/lexivirt-console.service

# Upgraded from 1.0.x, where the old shared LexiVirt@2026 was rotated away
# Format is:  username <TAB> new-password
sudo cat /root/lexivirt/data/rotated_passwords.txt

Open https://<your-server>:9443 and sign in as admin.

Straight away

1. Change the admin password — Settings → Change Password. Minimum 10 characters.
2. Do not expose port 9443 to the open internet. Put it behind a VPN, or restrict it to your own address range in the firewall. It is a control panel for your entire infrastructure.
3. Create a separate account for yourself under Users, with the operator role, and keep admin for administration only.

An ISO is a single file containing an operating system's installer — the exact contents of an install DVD. A new VM boots from one the first time, just like putting a disc in a physical machine, and you click through the OS installer as normal.

The installer offers to download a few for you into /var/lib/lexivirt/isos, verifying each against the publisher's own checksum. You can also upload your own from the console: ISOs → Upload. Large files are sliced up by your browser and sent in pieces, so multi-gigabyte desktop images work fine.

What the installer can fetch for you

# pick exactly what you want
LEXIVIRT_ISOS="ubuntu2404 debian12" sudo bash install.sh all

# or a group: all (~19 GB) | linux (~8 GB) | windows | none
LEXIVIRT_ISOS=linux sudo bash install.sh all

Filenames are resolved from each publisher's own directory listing, so a point release never breaks the download. Every Linux image is checked against the publisher's SHA256 and deleted if it does not match. The installer refuses to start a download that would not fit on the disk.

Windows guests

1. Nodes — check at least one node is online and says KVM enabled. If it says "No KVM", virtualization is off in that server's BIOS or the libvirt Python binding is missing.
2. ISOs — check an install image is listed.
3. Virtual Machines → Create VM, and fill in:

LexiVirt chooses an online, KVM-capable node for you and starts the machine immediately. There is no node picker — placement is automatic.

4. Click the screen icon on the VM to open its console, and work through the operating system's installer exactly as you would on real hardware.
5. When the OS is installed, stop the VM and start it again — it will boot from its own disk.

The screen icon opens the machine's actual video output in a browser tab, with keyboard and mouse attached — the equivalent of standing in front of it with a monitor plugged in. It works before any operating system is installed, which is exactly why you need it for the initial install, and it keeps working when the guest's own networking is broken.

• Ctrl+Alt+Del — sends the key combination to the guest, not to your own machine.
• Clipboard — pastes text into the guest (useful because typing into a console is otherwise character by character).
• Fullscreen — for graphical installers.

Each extra server adds its CPU cores, memory and disk to the pool. New VMs are placed automatically across whichever nodes are online and KVM-capable.

1. Get the cluster secret from the console machine:

   sudo cat /etc/lexivirt/agent.secret

2. On the new server:

   LEXIVIRT_MANAGER_IP=<console-ip> \
   curl -sSL https://lexi-cloud.com/install.sh | sudo bash -s -- \
        agent <cluster-secret> https://<console-ip>:9443

3. In the console: Nodes → Add Node. Enter a name, the new server's IP, port 9071, and leave the secret blank — the cluster secret is already configured.

If the node does not come up

Every VM gets one virtual network card, attached to the node's built-in NAT network. In practice that means:

• VMs get an address automatically, in 192.168.122.0/24.
• VMs can reach the internet and your LAN.
• VMs on the same node can reach each other.
• Nothing outside can start a connection in to a VM. This is a real security property, not a limitation to work around casually.
• VMs on different nodes cannot reach each other directly — each node has its own separate 192.168.122.0/24.

Finding a VM's address

The console shows it once the guest has requested one. From the node itself:

sudo virsh net-dhcp-leases default

Publishing a service running in a VM

To let the outside world reach, say, a web server inside a VM, forward a port on the node:

# node's port 8080 → VM 192.168.122.42, port 80
sudo iptables -t nat -A PREROUTING -p tcp --dport 8080 \
     -j DNAT --to-destination 192.168.122.42:80
sudo iptables -A FORWARD -p tcp -d 192.168.122.42 --dport 80 -j ACCEPT

# iptables rules do not survive a reboot on their own:
sudo apt install iptables-persistent   # Debian/Ubuntu
sudo netfilter-persistent save

What a VLAN actually is

A VLAN (Virtual LAN, standard IEEE 802.1Q) splits one physical network into several separate logical networks. It works by adding a small tag — a number from 1 to 4094 — to each Ethernet frame. Switches keep tagged traffic apart: two machines plugged into the same switch but assigned different VLAN tags simply cannot see each other, as if they were on different cables entirely.

The vocabulary you will meet on a switch:

• Access port — carries exactly one VLAN, untagged. The device plugged in knows nothing about VLANs; the switch adds and strips the tag. This is what an ordinary PC port is.
• Trunk port — carries many VLANs at once, tagged. This is how you connect a switch to another switch, or to a server that needs to be on several networks over one cable.
• Native / untagged VLAN — on a trunk, the one VLAN whose frames travel without a tag.
• VLAN ID / PVID — the number itself. 1 is usually the default; 4095 is reserved.

Datacentres use VLANs to keep, say, storage traffic, management traffic and customer traffic apart while sharing the same physical wiring, and to stop a compromised machine in one segment from seeing another.

If you genuinely need bridged or VLAN-tagged guests

This is a host networking task on the node, configured with your distribution's normal tools. Once a bridge exists on the host, libvirt can attach machines to it directly.

A plain bridge puts VMs straight onto your physical LAN, so they get addresses from your normal DHCP server and are reachable like any other machine — no NAT, no port forwarding:

# Debian/Ubuntu, /etc/netplan/01-bridge.yaml
network:
  version: 2
  ethernets:
    eno1: {dhcp4: no}
  bridges:
    br0:
      interfaces: [eno1]
      dhcp4: yes

A VLAN-tagged bridge puts VMs onto one specific VLAN — here, VLAN 100:

network:
  version: 2
  ethernets:
    eno1: {dhcp4: no}
  vlans:
    eno1.100:
      id: 100
      link: eno1
  bridges:
    br-vlan100:
      interfaces: [eno1.100]
      dhcp4: no

Then, in the console, go to Networks → Create Network, choose Bridged and give it br-vlan100. Pick that network when you create a VM and the guest lands on VLAN 100. No hand-editing of XML, and a resize will not undo it — the console preserves a VM's network when it redefines the domain.

• Passwords must be at least 10 characters, for every account and however it is set.
• The built-in admin account cannot be deleted or demoted, so you can never lock yourself out.
• Deactivating an account stops it signing in immediately.
• Every meaningful action — sign-ins, VM creation and deletion, node changes, ISO uploads — is recorded in Audit Logs with the user, the time and the source address.

The installer opens these with ufw or firewalld, whichever is active. Pass LEXIVIRT_MANAGER_IP when installing a node and the rules are restricted to that one console address.

Where the secrets live

Updates

The dashboard shows a badge when a newer version is published. Settings → Apply Update downloads it over verified TLS, checks its checksum before running anything, applies it and restarts the service. Your database, VMs and ISOs are left untouched. If the restart fails you are told so explicitly, along with the command to finish it by hand.

Back these up — they cannot be regenerated

Everyday commands

# on the console machine
systemctl status lexivirt-console
journalctl -u lexivirt-console -f
systemctl restart lexivirt-console

# on a compute node
systemctl status lexivirt-agent
journalctl -u lexivirt-agent -f
virsh list --all                 # what the hypervisor itself sees
virsh net-dhcp-leases default    # which VM got which address

Common problems

Virtual machine (VM), guest

A complete computer that exists as software: its own CPU, memory, disk and operating system, running on top of a real machine. "Guest" is the same thing, named from the host's point of view.

Host, compute node

The real, physical server that a VM runs on. In LexiVirt a host with the agent installed is called a node.

Hypervisor

The software layer that lets one machine run several VMs, handing each a slice of the real hardware. LexiVirt uses KVM.

KVM (Kernel-based Virtual Machine)

Virtualization built into the Linux kernel. It requires CPU support (Intel VT-x or AMD-V), which is why it must be enabled in the BIOS. With it, guest code runs at very close to native speed.

QEMU

The program that emulates all the parts of a computer that are not the CPU — disks, network cards, screen, keyboard. QEMU plus KVM is the pairing that actually runs each VM.

libvirt

The standard management layer above QEMU/KVM. It stores each machine's definition as an XML document and provides the interface for starting, stopping and editing it. The virsh command is its command-line client.

Domain

libvirt's word for a virtual machine. If a tool talks about a "domain", it means a VM.

Agent

LexiVirt's small service on each compute node. It receives instructions from the console and carries them out through libvirt. It has no interface of its own.

Management console

The web dashboard. Holds accounts, the node list and the audit log; runs no VMs itself.

Cluster secret

The shared credential between the console and every agent. Sent as the x-agent-token header on every request to a node; without it a node refuses everything.

vCPU

A virtual processor core presented to a guest. Several vCPUs share the host's real cores; handing out more vCPUs in total than the host physically has is called overcommit and is normal practice.

RAM / memory

Memory assigned to a VM. Unlike CPU it is genuinely reserved while the machine runs, so the VMs on a host must not add up to more than the host has.

qcow2

QEMU's disk-image format. A VM's whole disk is one .qcow2 file on the node. It is thin-provisioned: a 100 GB disk containing 3 GB of data occupies about 3 GB. It also supports snapshots.

Thin provisioning

Allocating space on paper and consuming it only as it is really used. Convenient, but it lets you promise more disk than you own — watch the node's free space.

ISO

A single file containing an operating system's installer, byte for byte the contents of an install DVD. A new VM boots from one to get its OS installed.

Snapshot

A point-in-time copy of a VM's disk you can roll back to. Useful before a risky change. It is not a backup — it lives on the same disk as the original, so it dies with it.

VNC

The protocol that carries a machine's screen, keyboard and mouse over the network. Each VM in LexiVirt has its own VNC server with a randomly generated password; the console proxies it into your browser.

noVNC

The JavaScript VNC client that renders that screen inside a browser tab, so nothing has to be installed locally.

WebSocket

A network connection that stays open in both directions inside an ordinary HTTPS session. It is what lets the VM console and the live dashboard charts stream continuously through the same port as the rest of the site.

NAT (Network Address Translation)

Letting many machines share one address by rewriting outgoing traffic to look as if it came from the host. The default for LexiVirt guests: they can reach out, nothing can start a connection in.

Bridge (virbr0, br0)

A virtual network switch inside the host. virbr0 is libvirt's NAT bridge; a bridge you make yourself over a physical card puts guests directly onto your real LAN.

VLAN (802.1Q)

A tag numbered 1–4094 added to Ethernet frames that splits one physical network into several isolated logical ones. Machines with different tags cannot see each other even on the same wire. LexiVirt does not tag VLANs itself, but it can attach guests to a VLAN-tagged host bridge through a bridged network — see section 11.

Trunk / access port

Switch terminology. An access port carries one VLAN untagged; a trunk carries several, tagged, over one cable.

CIDR (e.g. 192.168.122.0/24)

A way to write a range of addresses. The number after the slash is how many leading bits are fixed: /24 fixes the first three numbers, leaving 254 usable addresses.

Gateway

The address traffic is sent to when its destination is outside the local network. For LexiVirt guests it is 192.168.122.1, the node itself.

DHCP

The service that hands a machine an address automatically when it joins a network. libvirt runs one for the NAT network, which is why new VMs get an address without being told one.

Port forwarding (DNAT)

A firewall rule that sends traffic arriving on a port of the host onward to a specific VM, so a service inside a NATed VM can be reached from outside.

MAC address

The hardware address of a network card, virtual ones included. libvirt generates one per VM; it is how DHCP recognises the same machine each time.

systemd unit / service

How Linux starts and supervises background programs. lexivirt-console and lexivirt-agent are units; systemctl controls them and journalctl shows their logs.

nginx, reverse proxy

The web server sitting in front of the console. It terminates HTTPS on port 9443 and forwards plain HTTP to the app on loopback, which is why the app itself is never exposed.

TLS / SSL, self-signed certificate

The encryption behind HTTPS. A certificate normally proves who you are connecting to; a self-signed one encrypts the traffic but nobody vouches for it, which is why the browser warns.

Session token (JWT)

The signed proof of who you are, issued at sign-in and stored in a cookie your browser cannot read from JavaScript. It expires after 24 hours.

Audit log

The record of who did what and when — sign-ins, VM creation and deletion, node changes, uploads.

Overcommit

Assigning more of a resource than physically exists. Safe and routine with vCPUs; dangerous with memory.