Deployment Overview of KVM with web management via Cockpit on Server¶

Prerequisites and Basic Requirements¶

The deployment requires a Linux server running Ubuntu with root privileges. The system must have internet access to download packages and obtain SSL certificates. The following components are installed and configured as part of the deployment:

Operating System: Ubuntu
Privileges: Root access is required for installation and configuration.
Domain: The server must be accessible via the hostkey.in zone.
Ports: Ports 80 and 443 must be available for Let's Encrypt validation and HTTPS traffic.
Services: libvirtd and cockpit.socket must be enabled and running.

FQDN of the Final Panel¶

The fully qualified domain name (FQDN) for accessing the KVM web management interface follows the format:

kvm<Server ID>.hostkey.in

The system automatically configures the hostname and updates /etc/hosts to resolve this FQDN to 127.0.1.1.

File and Directory Structure¶

The deployment utilizes the following directories for configuration, data, and certificates:

/etc/cockpit/ws-certs.d/: Stores the SSL certificate and private key for Cockpit.
/etc/letsencrypt/live/<fqdn>/: Contains the Let's Encrypt certificate files (fullchain.pem and privkey.pem).
/root/nginx/: Contains the Docker Compose configuration for the Nginx proxy.
/data/nginx/user_conf.d/: Stores custom Nginx configuration files for the specific server instance.
/data/nginx/nginx-certbot.env: Environment file for the Nginx-Certbot container.

Application Installation Process¶

The application stack is installed using the native package manager and Docker. The process includes the following steps:

Package Installation: The system installs qemu-kvm, libvirt-daemon-system, libvirt-clients, bridge-utils, virtinst, cockpit, cockpit-machines, certbot, and pip.
Service Activation: The libvirtd and cockpit.socket services are started and enabled to run on boot.
Port Preparation: Existing web servers (Nginx, Apache) and Docker containers occupying ports 80 and 443 are stopped to allow Let's Encrypt validation.
Certificate Acquisition: Let's Encrypt certificates are obtained for the generated FQDN using the certbot standalone mode.
Certificate Integration: The obtained certificates are copied to the Cockpit certificate directory and permissions are set.
Proxy Deployment: A Docker container running jonasal/nginx-certbot:latest is deployed to handle reverse proxying and SSL termination.

Access Rights and Security¶

Security is enforced through service isolation and certificate management:

Firewall: Ports 80 and 443 are utilized for external access. Internal services communicate via localhost.
Users: The Cockpit service runs under the root user with specific group permissions for the cockpit-ws group.
Restrictions: The libvirtd service manages virtual machine access, while Cockpit provides the web interface.
Certificate Permissions: SSL certificate files in /etc/cockpit/ws-certs.d/ are set to 640 permissions with ownership root:cockpit-ws.

Docker Containers and Their Deployment¶

The reverse proxy is deployed using Docker Compose. The container configuration is defined in /root/nginx/compose.yml.

Image: jonasal/nginx-certbot:latest
Restart Policy: unless-stopped
Network Mode: host
Volumes:
nginx_secrets (external) mounted to /etc/letsencrypt
/data/nginx/user_conf.d mounted to /etc/nginx/user_conf.d
Environment:
CERTBOT_EMAIL: [email protected]
Additional environment variables are loaded from /data/nginx/nginx-certbot.env

The container is started using the command:

docker compose up -d

executed from the /root/nginx directory.

Proxy Servers¶

Nginx is deployed as a Docker container to act as a reverse proxy for the Cockpit web interface.

Proxy Target: The Nginx configuration forwards requests to http://127.0.0.1:3000.
SSL/TLS: SSL termination is handled by the Nginx container using Let's Encrypt certificates.
Configuration Location: Custom proxy rules are stored in /data/nginx/user_conf.d/kvm<Server ID>.hostkey.in.conf.
Certbot Integration: The Nginx container includes Certbot for automatic certificate renewal.

Permission Settings¶

File and directory permissions are configured as follows:

/root/nginx/: 0755 (Owner: root, Group: root)
/root/nginx/compose.yml: 0644 (Owner: root, Group: root)
/etc/cockpit/ws-certs.d/: 0755 (Owner: root, Group: root)
/etc/cockpit/ws-certs.d/*.crt and *.key: 0640 (Owner: root, Group: cockpit-ws)

Location of Configuration Files and Data¶

Key configuration files and data locations include:

Nginx Compose: /root/nginx/compose.yml
Nginx Custom Config: /data/nginx/user_conf.d/kvm<Server ID>.hostkey.in.conf
Cockpit Certificates: /etc/cockpit/ws-certs.d/kvm<Server ID>.hostkey.in.crt and .key
Let's Encrypt Certificates: /etc/letsencrypt/live/kvm<Server ID>.hostkey.in/
Environment Variables: /data/nginx/nginx-certbot.env

Available Ports for Connection¶

The following ports are configured for the application:

Port	Protocol	Description
443	TCP	HTTPS access to the Cockpit web interface via Nginx proxy.
80	TCP	HTTP for Let's Encrypt validation and redirection.
3000	TCP	Internal Cockpit service port (localhost only).

Starting, Stopping, and Updating¶

Service management commands for the deployed components:

Cockpit Service:
Start: systemctl start cockpit.socket
Stop: systemctl stop cockpit.socket
Restart: systemctl restart cockpit
Enable: systemctl enable cockpit.socket
Libvirt Service:
Start: systemctl start libvirtd
Stop: systemctl stop libvirtd
Restart: systemctl restart libvirtd
Enable: systemctl enable libvirtd
Nginx Proxy Container:
Start/Restart: docker compose up -d (from /root/nginx)
Stop: docker compose down (from /root/nginx)
View Logs: docker compose logs -f (from /root/nginx)