DCUI — Direct Console User Interface

Terminal TUIHost ConsoleKeyboard Driven

The Direct Console User Interface (DCUI) is the text-based terminal management interface for PiVirt hypervisor hosts. Built in Go using the Bubble Tea TUI framework, the DCUI is displayed on physical video outputs, IPMI/iLO/iDRAC virtual KVM consoles, serial terminals, and via the Webterm browser gateway.

---

Accessing the DCUI

Direct Host Screen / IPMI

On a bare-metal server, the DCUI launches automatically on TTY1 upon system boot.

# If starting manually from a root shell
sudo appliance

Webterm Browser Console

When the pivirt-webterm service is active, connect to the web-based terminal:

# Open in browser
http://<host-ip>:3334/

---

Keyboard Navigation and Controls

The DCUI is operated entirely via keyboard navigation:

Key / Shortcut	Action
<F2>	Customize System / View Logs (prompts for PAM login)
<F12>	Restart / Shut Down Host
Up / Down	Navigate menu items or form fields
Enter	Open sub-menu or confirm dialog selection
Space	Toggle checkbox options (e.g., NIC selection, DHCP toggle)
Esc	Cancel current edit or return to the previous screen
Ctrl+C	Log out from the current management session

---

Menu Structure and Capabilities

graph TD
    Home["Home Status Screen (Host IP, FQDN, CPU/RAM, Daemons)"]
    Home -->|F2 Login| SystemMenu["System Customization Menu"]
    Home -->|F12| PowerDialog["Reboot / Shutdown Dialog"]

    SystemMenu --> NetConfig["Configure Management Network"]
    SystemMenu --> Diagnostics["Troubleshooting and Diagnostics"]
    SystemMenu --> ViewLogs["View System and Component Logs"]
    SystemMenu --> Security["Security and PAM Credentials"]

    NetConfig --> NICSelect["Network Adapters (NICs)"]
    NetConfig --> IPConfig["IPv4 / IPv6 Configuration"]
    NetConfig --> DNSConfig["DNS Resolvers and Search Domains"]
    NetConfig --> VLANConfig["OVS and VLAN Tagging"]

    Diagnostics --> PingTest["Test Management Network (Ping)"]
    Diagnostics --> RestartDaemons["Restart Management Daemons"]

---

Operational Runbooks

1. Initial Management Network Setup

1. Press <F2> on the main screen and enter administrative PAM credentials (root / admin).
2. Select Configure Management Network and press Enter.
3. Select Network Adapters to choose the primary physical uplink port.
4. Select IPv4 Configuration:
   • Toggle Use static IPv4 address.
   • Input the IP Address, Subnet Mask, and Default Gateway.
5. Select DNS Configuration to specify upstream resolvers (e.g. 1.1.1.1, 8.8.8.8).
6. Press Esc to save changes and select Yes to apply and restart the management network stack.

---

2. Testing Network Connectivity

To quickly verify host networking from within the DCUI without dropping to a bash prompt:

1. From the System Customization Menu, select Troubleshooting and Diagnostics.
2. Select Test Management Network.
3. The DCUI performs automated tests against:
   • Default Gateway ping
   • Upstream DNS server reachable
   • Local FQDN reverse lookup resolution
4. Review the pass/fail indicators displayed on the screen.

---

3. Restarting Management Daemons

If pivirtd, agent, or iscsiman require a restart:

1. In the Troubleshooting and Diagnostics menu, select Restart Management Agents.
2. Press Enter to initiate a graceful reload of the systemd services.
3. Observe live service restart status indicators directly within the TUI.

---

Related Documentation

PiVirt Appliance Overview

Learn about the underlying architecture, PAM authentication, and Webterm.
View Appliance Overview

pivirtd Daemon CLI

Direct hypervisor daemon CLI and socket operations.
View pivirtd CLI

pvcli Reference

Full cluster and VM management CLI tool.
View pvcli Reference

Troubleshooting Guide

Host diagnostic trees, network debugging, and disk locks.
View Troubleshooting