Appliance & DCUI Overview

Terminal UIHost ConsolePAM Security

PiVirt Appliance (pilab-cloud/virt-appliance) is a dedicated host management interface designed for direct physical, virtual, or out-of-band console access on PiVirt hypervisor nodes. It features the Direct Console User Interface (DCUI) powered by Bubble Tea, system-level PAM authentication, host network orchestration, and the Webterm browser terminal gateway.

---

Architecture Overview

PiVirt Appliance compiles into two coordinated binaries:

graph TD
    subgraph Access["Management Access Channels"]
        Monitor["Physical Monitor / IPMI KVM"] -->|TTY Console| Appliance["appliance (DCUI TUI)<br/>Bubble Tea + PAM"]
        Browser["Web Browser (Admin)"] -->|WebSocket (:3334)| Webterm["webterm Gateway<br/>PTY Bridge"]
        Webterm -->|PTY / stdin-stdout| Appliance
    end

    subgraph Host["Host Operating System"]
        Appliance -->|PAM /etc/pam.d/pivirt-appliance| PAM["Linux PAM Auth"]
        Appliance -->|OVS / iproute2 / resolvconf| Network["Host Network Stack"]
        Appliance -->|Systemd / D-Bus| Services["pivirtd / agent Daemons"]
        Appliance -->|Viper / File I/O| Config["/etc/pivirt/appliance.toml"]
    end

---

Core Capabilities

Direct Console UI (DCUI)

Modern, responsive Terminal User Interface (TUI) built with Bubble Tea and Lip Gloss, providing intuitive keyboard navigation on host monitors and serial consoles.

PAM System Authentication

Authenticates operators directly against Linux Pluggable Authentication Modules (/etc/pam.d/pivirt-appliance) with unix password validation and session restrictions.

Network Configurator

Interactive setup for Open vSwitch (OVS) bridges, physical NIC assignment, static IP vs DHCP configurations, VLAN tags, and DNS name resolvers.

Webterm Browser Gateway

Embedded WebSocket terminal gateway that launches the DCUI inside a virtual PTY and streams ANSI terminal output directly to web browsers.

System Diagnostics

Built-in network diagnostic utilities (ping, traceroute, ARP tables), kernel resource monitoring, and direct service restart runbooks.

Persistent Host Settings

Zero-drift configuration management backed by Viper, writing validated settings to /etc/pivirt/appliance.toml.

---

Component Binaries

1. appliance (Direct Console UI)

The primary binary executed upon console login or system boot.

• Framework: Bubble Tea (Elm architecture / Model-View-Update pattern)
• Styling: Lip Gloss themes with high-contrast color palettes
• Execution: Runs directly on physical TTYs, virtual consoles, or PTY sessions
• Privilege Separation: Executes necessary configuration scripts via the built-in system configurator

2. webterm (WebSocket Terminal Gateway)

A lightweight Go daemon providing browser-based access to the DCUI console without requiring SSH keys.

• Port: Listens on 127.0.0.1:3334
• Protocol: WebSockets over HTTP/2 (/demo/pivirt/ws)
• PTY Bridge: Allocates pseudo-terminals and attaches appliance sessions securely

---

PAM Authentication & Security

PiVirt Appliance uses Linux PAM for secure authentication against system user accounts:

/etc/pam.d/pivirt-appliance

auth      required   pam_unix.so nullok
auth      required   pam_nologin.so
account   required   pam_unix.so
session   required   pam_limits.so
session   required   pam_unix.so

1. System Credentials: Validates standard administrative credentials (e.g. root or admin).
2. Access Restrictions: Honors /etc/nologin to prevent console access during maintenance windows.
3. Audit Trails: Logs all successful logins and failed authentication attempts to /var/log/secure and appliance.log.

---

Configuration (appliance.toml)

Host appliance settings are persisted in /etc/pivirt/appliance.toml:

[server]
listen_addr = "127.0.0.1:3334"
log_level = "info"
log_file = "/var/log/pivirt/appliance.log"

[network]
interface = "ovs-br0"
management_ip = "192.168.1.10/24"
gateway = "192.168.1.1"
dns_servers = ["1.1.1.1", "8.8.8.8"]

[security]
pam_service = "pivirt-appliance"
session_timeout_minutes = 15

[theme]
palette = "default" # options: default, high-contrast, dark

---

Installation & Packaging

PiVirt Appliance packages are built with GoReleaser and NFPM into native .deb and .rpm packages:

Debian / Ubuntu (.deb)

# Install PiVirt Appliance package
sudo dpkg -i pivirt-appliance_amd64.deb

# Verify PAM configuration
ls -la /etc/pam.d/pivirt-appliance

# Launch DCUI manually
sudo appliance

RHEL / Rocky Linux (.rpm)

# Install RPM package
sudo rpm -Uvh pivirt-appliance.x86_64.rpm

# Start and enable webterm service
sudo systemctl enable --now pivirt-webterm

Build from Source

# Clone repository
git clone https://github.com/pilab-cloud/virt-appliance.git
cd virt-appliance

# Build both appliance and webterm binaries
make build

# Run unit tests
make test

---

Related Documentation

DCUI Operator Guide

Keyboard controls, menu navigation, and network setup runbooks.
View DCUI CLI Guide

pivirtd Daemon

The hypervisor daemon managed and monitored through the Appliance.
View pivirtd Overview

Host Deployment Runbook

Bare metal provisioning and initial host bootstrapping.
View Deployment Guide

Troubleshooting Guide

Diagnostic workflows for networking, disk locking, and services.
View Troubleshooting