WebVirtMgr Installation Guide

This guide describes the installation and configuration of WebVirtMgr (WebVirtCloud), a web-based KVM management interface that can manage multiple KVM servers from a centralized location.

WebVirtMgr is better installed on a dedicated machine (physical or virtual) separate from the KVM hypervisor servers. This approach allows:

• Centralized management of multiple KVM servers
• Better security isolation
• Independent scaling and maintenance
• Reduced resource consumption on hypervisor hosts

• Ubuntu 24.04 server (can be virtual)
• Minimum 2 GB RAM, 2 CPU cores, 20 GB storage
• Network access to KVM servers you want to manage
• SSH access to target KVM servers

Update the system:

sudo apt update && sudo apt upgrade
sudo reboot

Install essential packages:

sudo apt install \
    curl \
    wget \
    git \
    htop \
    vim \
    ufw \
    software-properties-common \
    apt-transport-https \
    ca-certificates \
    gnupg \
    lsb-release

Install required system packages:

sudo apt install git libvirt-dev libxml2-dev libxslt1-dev \
libxslt1-dev zlib1g-dev libffi-dev libssl-dev supervisor gcc \
pkg-config libsasl2-dev libssl-dev libldap2-dev

Install Python and modules:

sudo apt install python3 python3-pip python3-venv

Get WebVirtCloud source code:

cd ~/
git clone https://github.com/retspen/webvirtcloud.git

Create settings.py from template and set secret key:

cd webvirtcloud
cp webvirtcloud/settings.py.template webvirtcloud/settings.py
SECRET=$(python3 conf/runit/secret_generator.py)
sed -i "s|SECRET_KEY = \"\"|SECRET_KEY = \"$SECRET\"|" webvirtcloud/settings.py

Configure WebVirtCloud:

vim webvirtcloud/settings.py

Update the CSRF trusted origins with your server’s hostname/IP:

CSRF_TRUSTED_ORIGINS = ['http://localhost','http://webvirtmgr.example.com']

Replace webvirtmgr.example.com with your actual hostname or IP address.

Move WebVirtCloud to system directory:

cd ~/
sudo mv ./webvirtcloud /srv
sudo chown -R www-data:www-data /srv/webvirtcloud

Create virtual environment for WebVirtCloud:

cd /srv/webvirtcloud
sudo mkdir -p /var/www/.cache/
sudo chown -R www-data:www-data /var/www/.cache
sudo -u www-data python3 -m venv venv
sudo -u www-data /srv/webvirtcloud/venv/bin/pip install setuptools
sudo -u www-data /srv/webvirtcloud/venv/bin/pip install -r conf/requirements.txt

Initialize database migrations and static files:

sudo -u www-data /srv/webvirtcloud/venv/bin/python manage.py migrate
sudo -u www-data /srv/webvirtcloud/venv/bin/python manage.py collectstatic --noinput

Install Nginx web server:

sudo apt install nginx
sudo systemctl enable --now nginx
systemctl status nginx

Copy WebVirtCloud nginx configuration:

sudo cp /srv/webvirtcloud/conf/nginx/webvirtcloud.conf /etc/nginx/sites-available

Configure the default nginx site to listen on port 8080:

sudo vim /etc/nginx/sites-available/default

Update the listen directive:

server {
        listen 127.0.0.1:8080 default_server;
        #listen [::]:8080 default_server;

Configure WebVirtCloud nginx site:

sudo vim /etc/nginx/sites-available/webvirtcloud.conf

Update server name and logging paths:

server {
    listen 127.0.0.1:8080;

    server_name webvirtmgr.example.com;
    access_log /var/log/nginx/webvirtcloud-access_log;
    error_log /var/log/nginx/webvirtcloud-error_log;

Enable WebVirtCloud nginx configuration:

sudo ln -s /etc/nginx/sites-available/webvirtcloud.conf /etc/nginx/sites-enabled/webvirtcloud.conf

Remove default nginx configuration:

sudo rm /etc/nginx/sites-enabled/default

Test nginx configuration:

sudo nginx -t

Restart nginx:

sudo systemctl restart nginx

Copy supervisor configuration:

sudo cp /srv/webvirtcloud/conf/supervisor/webvirtcloud.conf /etc/supervisor/conf.d

Enable and start supervisor:

sudo systemctl enable supervisor
sudo systemctl restart supervisor

Check supervisor managed services:

sudo supervisorctl status

Expected output:

novncd                           RUNNING   pid 4725, uptime 0:00:07
socketiod                        RUNNING   pid 4726, uptime 0:00:07
webvirtcloud                     RUNNING   pid 4727, uptime 0:00:07

Verify the service is listening:

ss -tunelp|grep 8000

Expected output:

tcp   LISTEN 0      2048             127.0.0.1:8000      0.0.0.0:*    uid:33 ino:19338 sk:7 cgroup:/system.slice/supervisor.service <->

If you want to access WebVirtMgr through a reverse proxy (like HAProxy), configure your load balancer to forward requests to this server on port 8080.

Example HAProxy backend configuration:

backend webvirtmgr_servers
    balance roundrobin
    server webvirtmgr1 192.168.0.11:8080 check

Access WebVirtCloud installation URL at http://your-server-hostname:8080

The default login credentials are:

Username: admin
Password: admin

Important: Change the default password immediately:

1. Go to Admin → Profile → Change Password
2. Set a strong password

Add your SSH public key for secure connections to KVM servers:

1. Go to Admin → Profile → SSH keys
2. Add your public SSH key

Add local compute:

• Go to Compute → Add Compute
• Click local and set a name (e.g., “Local”)
• Save

Add remote compute:

• Go to Compute → Add Compute
• Select TCP connection type
• Fill in the details:
  • Name: Descriptive name for the KVM server
  • IP Address: KVM server IP address
  • Username: User with libvirt access (e.g., vm-admin)
  • SSH Port: 22 (default)

Prerequisites for Remote KVM Servers:

• SSH key-based authentication must be configured
• Target user must be in the libvirt group
• libvirtd service must be running on the target server

For each KVM server, configure storage pools:

1. Go to Computes → Select your KVM server → Overview
2. Go to Storages in the side menu
3. Click Add Storage
4. Fill out the form:

   Name: default
   Type: dir
   Target Path: /var/lib/libvirt/images
   

5. Click Create

Configure networks for your KVM servers:

1. Go to your compute → Networks
2. Add or configure existing networks (e.g., br0 bridge network)

• Change default admin password immediately
• Use SSH key authentication for KVM server connections
• Configure firewall rules to restrict access to WebVirtMgr
• Use HTTPS with proper SSL certificates in production
• Regularly update WebVirtCloud and dependencies

WebVirtCloud not accessible:

• Check nginx status: sudo systemctl status nginx
• Check supervisor services: sudo supervisorctl status
• Check logs: sudo tail -f /var/log/nginx/webvirtcloud-error_log

Cannot connect to KVM servers:

• Verify SSH key authentication is working
• Check if user is in libvirt group on target server
• Verify libvirtd is running on target server: systemctl status libvirtd

Permission errors:

• Ensure www-data user has proper permissions
• Check file ownership in /srv/webvirtcloud

This setup provides a centralized management interface for multiple KVM servers, making it easier to manage virtualized infrastructure across your network.