Deployment Overview of Cockpit with KVM on Server¶

This document provides the technical deployment overview for the KVM management environment using the Cockpit web interface. The installation includes virtualization components, a web-based management console, and automated SSL certificate provisioning via Certbot.

Prerequisites and Basic Requirements¶

The following requirements must be met for a successful deployment:

Operating System: Ubuntu (specifically versions 24.04 or newer are supported with specific module handling).
Privileges: Root or sudo access is required for package installation and service management.
Network Ports:
80/tcp: Used by Certbot for standalone SSL certificate acquisition.
443/tcp: Standard HTTPS port for web traffic.
9227/tcp (or Cockpit default): Web management interface access.

FQDN of the final panel on the hostkey.in domain¶

The web management interface is accessible via a specific Fully Qualified Domain Name (FQDN) generated based on the server ID.

Parameter	Value
Prefix	`kvm`
Domain	`hostkey.in`
Full template	`kvm{Server_ID}.hostkey.in`

Application installation process¶

The application is installed using a combination of system package management and configuration scripts:

System Package Installation: The core virtualization and management stack is installed via the apt package manager. This includes:
KVM/QEMU (qemu-kvm, libvirt-daemon-system, libvirt-clients).
Virtualization utilities (bridge-utils, virtinst).
Cockpit web interface and machine management modules (cockpit, cockpit-machines).
SSL/TLS tools (certbot) and Python dependencies.
Virtualization Modules: On Ubuntu 24.04+, the qemu-system-modules-spice package is installed to ensure compatibility with Cockpit Machines.
Security Configuration: For modern Ubuntu versions, the system is configured to allow root login for the Cockpit interface by modifying /etc/cockpit/disallowed-users.
SSL Provisioning: Certbot is used in standalone mode to obtain Let's Encrypt certificates for the server's FQDN. Once obtained, the certificates are moved to /etc/cockpit/ws-certs.d/ and configured with appropriate ownership (root:cockpit-ws) and permissions (640).
Additional Tools: The tracer utility is installed via pip3.

Access Rights and Security¶

Firewall/Access: Cockpit access is secured via SSL certificates obtained from Let's Encrypt.
User Restrictions: Root login to the web interface is explicitly enabled by removing the root user from the disallowed list in /etc/cockpit/disallowed-users.
Service Hardening: The libvirtd and cockpit.socket services are configured to start automatically on system boot.

Docker Containers and Their Deployment¶

The deployment utilizes a Docker container for managing Nginx and SSL certificate renewals via the jonasal/nginx-certbot image.

Container Name	Image	Ports	Volumes	Environment Variables	Restart Policy
`nginx`	`jonasal/nginx-certbot:latest`	Host Network Mode	`- nginx_secrets:/etc/letsencrypt` `- /data/nginx/user_conf.d:/etc/nginx/user_conf.d`	`[email protected]`	`unless-stopped`

Custom Scripts and Additional Setup¶

The installation performs several non-standard configuration steps to ensure the environment is ready for use:

Hostname Configuration: The system hostname is set to the generated FQDN, and a corresponding entry is added to /etc/hosts.
Certificate Integration: A custom script copies the Let's Encrypt fullchain.pem and privkey.pem into the Cockpit certificate directory (/etc/cockpit/ws-certs.d/) with the required .crt and .key extensions to allow the web interface to use the SSL certificates.
Port Management: Before running Certbot, any existing services (like Nginx or Apache) or Docker containers occupying ports 80 or 443 are stopped to prevent conflicts during certificate acquisition.

Application Update Instructions¶

To update the management environment:

System Packages: Run apt update && apt upgrade to update KVM, Cockpit, and other system dependencies.

Docker Containers: To update the Nginx/Certbot container, execute:

docker compose -f /root/nginx/compose.yml pull
docker compose -f /root/nginx/compose.yml up -d

Location of configuration files and data¶

Cockpit Certificates: /etc/cockpit/ws-certs.d/
Let's Encrypt Data: /etc/letsencrypt/live/
Nginx Configuration: /data/nginx/user_conf.d/
Docker Compose (Nginx): /root/nginx/compose.yml

Available ports for connection¶

443: HTTPS access via Nginx proxy.
9227 (Default Cockpit): Direct web management interface.

Starting and Stopping the application¶

The following commands are used to manage the core services:

Start/Restart Cockpit:
```
systemctl restart cockpit.socket
```
Start/Restart Libvirt:
```
systemctl restart libvirtd
```

Manage Nginx Container:

cd /root/nginx && docker compose up -d
docker compose down

Proxy Servers¶

The deployment uses an Nginx container (via jonasal/nginx-certbot) acting as a reverse proxy. It is configured to route traffic from the external interface to the local services, ensuring that SSL termination is handled correctly and certificates are automatically renewed.