Troubleshooting Guide

This guide describes common issues you might run into when running Cockpit and provides easy, step-by-step instructions to fix them.

---

1. Problem: Host shows as "Disconnected" 🛑

What it looks like: A physical server running Vapor appears as disconnected (grayed out) in the Cockpit dashboard, and its performance charts stop updating.

• 💡 Analogy: Smart TV Connection Loss Think of this like your home smart TV losing connection. Is the TV unplugged from the wall? Is the home internet router offline? Or did the TV log-out of your streaming service?

How to Fix It (Step-by-Step):

1. Check the Network Line: Ensure the Cockpit server can reach the Vapor host. Open a terminal on your Cockpit server and verify you can communicate with the Vapor node on network ports 7770 (used for standard commands) and 7770 (used for live updates).
2. Verify the Vapor Service is Running: Log into the disconnected server directly and run this command to see if the Vapor program is turned on:

   systemctl status vapor.service

   • If it is stopped, turn it back on: systemctl start vapor.service.
3. Verify your Login Token: Cockpit uses a security password (token) to talk to Vapor. If this token has expired, Cockpit will be locked out. Log into the Vapor host UI, generate a new API token, and update the host's settings in your Cockpit dashboard.

---

2. Problem: Security Certificate Errors 🔒

What it looks like: You see SSL/TLS security alerts, or you get error messages when attempting to perform a live migration of a VM between servers.

• 💡 Analogy: The Expired ID Badge When Server A tries to migrate a VM to Server B, Server B demands to see Server A's ID card (its TLS certificate). If the card is expired or issued by an untrusted source, Server B blocks the VM transfer.

How to Fix It (Step-by-Step):

1. Check the Virtualization Service: Log into the physical server and make sure the virtualization tool (libvirtd) is running:

   systemctl status libvirtd

2. Generate Fresh Certificates: You can force Cockpit/Vapor to rebuild fresh security credentials on both nodes by running this command on the physical server:

   # Request the server to renew its virtualization security badges
   curl -sk -X POST https://localhost:7770/api/v1/system/tls/libvirt/setup

3. Establish Trust: Ensure that both physical servers are registered in Cockpit so Cockpit can share the trusted certificates between them automatically.

---

3. Problem: "Split-Brain" Server Conflict (Lock Conflict) 🤯

What it looks like: Your physical server keeps jumping back and forth between connected and disconnected every few seconds.

• 💡 Analogy: Two People Grabbing the Same Telephone Receiver If you are running two Cockpit management servers for backup, they might both try to manage the same physical server at the exact same time. They keep pulling the line back and forth, causing a connection loop.

How to Fix It (Step-by-Step):

1. Identify the Lock Holder: Check the database to see which Cockpit instance currently holds the manager license for that host by running this database query:

   -- View who holds the active checkout cards
   SELECT pid, classid, objid FROM pg_locks WHERE locktype = 'advisory';

2. Reset the Connection:
   • Stop the Cockpit program on both management servers.
   • Start Server #1 first, wait a few seconds for it to claim the hosts cleanly.
   • Start Server #2. It will see that Server #1 is active and will wait quietly as a standby.