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

Prerequisites and Basic Requirements¶

To deploy KVM with web management via Cockpit, the following system requirements and privileges are necessary:

• Operating System: Ubuntu (compatible with apt package manager).
• Privileges: Root access or sudo privileges are required to install system packages, manage services, and configure network settings.
• Domain Configuration: A fully qualified domain name (FQDN) must be configured for the server, constructed from the prefix, server ID, and zone (e.g., prefixserverid.zone).
• Network Ports:
• Port 80 and 443 must be available for Let's Encrypt certificate validation and HTTPS traffic.
• Port 9090 is used by the Cockpit web interface.
• Existing Services: Any existing web servers (Nginx, Apache) or Docker containers occupying ports 80 and 443 must be stopped to allow certificate issuance.

File and Directory Structure¶

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

• /etc/cockpit/ws-certs.d/: Stores the SSL certificate and private key files used by the Cockpit service.
• /etc/letsencrypt/live/: Contains the Let's Encrypt certificates issued for the domain.
• /root/nginx/: Contains the Docker Compose configuration file for the Nginx proxy.
• /data/nginx/user_conf.d/: Stores custom Nginx configuration files for specific host keys.
• /data/nginx/nginx-certbot.env: Environment file containing configuration variables for the Nginx-Certbot container.
• /etc/hosts: Updated to include the server's FQDN mapping to 127.0.1.1.

Application Installation Process¶

The installation process involves setting up the KVM virtualization stack, the Cockpit web interface, and the necessary dependencies:

1. Package Installation: The following packages are installed using the apt package manager:

   • qemu-kvm: Core KVM virtualization support.
   • libvirt-daemon-system and libvirt-clients: Libvirt daemon and client tools.
   • bridge-utils: Utilities for managing network bridges.
   • virtinst: Command-line tool for creating virtual machines.
   • cockpit and cockpit-machines: Web-based management interface and machine management plugin.
   • certbot: Tool for obtaining and renewing SSL certificates.
   • pip: Python package installer.

2. Service Initialization:

   • The libvirtd service is started and enabled to run on boot.
   • The cockpit.socket service is started and enabled to run on boot.

3. Hostname Configuration:

   • The system hostname is set to the generated FQDN.
   • The /etc/hosts file is updated to map 127.0.1.1 to the FQDN and its short name.

4. Certificate Acquisition:

   • Let's Encrypt certificates are obtained using the certbot tool in standalone mode for the specified FQDN.
   • The certificate and private key are copied to /etc/cockpit/ws-certs.d/ with the extensions .crt and .key respectively.

5. Additional Tools:

   • The tracer Python package is installed via pip3.

Access Rights and Security¶

Security configurations are applied to ensure secure access to the management interface:

• SSL/TLS Encryption: The Cockpit interface is secured using Let's Encrypt certificates. The certificate chain (fullchain.pem) and private key (privkey.pem) are deployed to the Cockpit certificate directory.
• File Permissions:
• The certificate files in /etc/cockpit/ws-certs.d/ are owned by root:cockpit-ws.
• File permissions are set to 640 to restrict access to the private key and certificate.
• Port Management:
• Ports 80 and 443 are temporarily freed by stopping existing web servers and Docker containers to allow certbot to validate domain ownership.
• The Nginx proxy container runs in host network mode to manage traffic on these ports.

Docker Containers and Their Deployment¶

A Docker container is deployed to manage SSL certificates and act as a reverse proxy using Docker Compose:

• Container Image: jonasal/nginx-certbot:latest
• Deployment Method: Docker Compose
• Configuration File: /root/nginx/compose.yml
• Network Mode: host
• Volumes:
• nginx_secrets: An external volume mounted to /etc/letsencrypt inside the container.
• /data/nginx/user_conf.d: Mounted to /etc/nginx/user_conf.d inside the container for custom configurations.
• Environment:
• CERTBOT_EMAIL: Set to [email protected].
• Additional environment variables are loaded from /data/nginx/nginx-certbot.env.
• Restart Policy: unless-stopped

The container is started using the command docker compose up -d executed from the /root/nginx directory.

Proxy Servers¶

The Nginx proxy is configured to handle traffic for the KVM management interface:

• Proxy Target: Traffic is proxied to http://127.0.0.1:3000.
• Configuration Location: Custom proxy settings are stored in /data/nginx/user_conf.d/ with filenames following the pattern {prefix}{server_id}.hostkey.in.conf.
• Location Block: The proxy_pass directive is inserted into the location / block of the configuration file.
• SSL Termination: The Nginx container handles SSL termination using the certificates managed by Certbot.

Starting, Stopping, and Updating¶

The following commands and procedures are used to manage the services:

• Libvirt Service:
• Start: systemctl start libvirtd
• Enable on boot: systemctl enable libvirtd
• Cockpit Service:
• Start: systemctl start cockpit.socket
• Enable on boot: systemctl enable cockpit.socket
• Restart (after certificate update): systemctl restart cockpit
• Docker Proxy:
• Start/Update: docker compose up -d (executed from /root/nginx)
• Stop: docker compose down (executed from /root/nginx)
• Certificate Renewal:
• Certificates are managed by the certbot tool within the Docker container or via standalone execution for initial setup.