HomelabNJ

Fixing a Black PBS Console Behind Nginx Proxy Manager

Robert A. Williams

·

Fixing a Black PBS Console Behind Nginx Proxy Manager

The Proxmox Backup Server web UI has a built-in Shell — click it and you get a terminal in the browser, no SSH required. Except mine opened to a black rectangle. Cursor, no prompt, nothing. Here’s the five-minute version of a debug that could have been an hour of poking at the wrong box.

The symptom

PBS web UI → Administration → Shell → a black terminal that never produces output. Not an error dialog, not a spinner. Just black.

The instinct is to blame PBS. That instinct is wrong, and chasing it is how you lose an evening.

How the console actually works

Clicking Shell kicks off a two-step dance:

  1. A POST to …/nodes/<node>/termproxy, which spins up a termproxy process on the server that allocates a PTY and runs /bin/login.
  2. A WebSocket to …/nodes/<node>/vncwebsocket, which bridges that PTY to the xterm.js terminal in your browser.

A black screen means step 2 never completed: the terminal canvas painted, but no data ever flowed. The backend confirms it — the proxy log shows nothing:

journalctl -u proxmox-backup-proxy --since "-3 min" --no-pager
# -- No entries --

No termproxy activity at all. So the request to start the console never reached the backend in a usable form.

The actual cause

PBS here sits behind Nginx Proxy Manager. NPM, by default, does not forward the WebSocket Upgrade and Connection headers. The POST to termproxy sails through fine (plain HTTPS), but the WebSocket upgrade gets stripped — so the bridge never connects, and you stare at black.

The decisive test that proves it’s the proxy and not PBS: hit the box directly, bypassing NPM.

# Works directly by IP+port, black through the proxy hostname => it's the proxy
curl -sI https://192.0.2.1:8007/

If the console works on the direct URL but not the proxied hostname, you’ve found it.

The fix

In Nginx Proxy Manager: Hosts → Proxy Hosts → edit the PBS host → Details tab → toggle “Websockets Support” ON → Save.

That one switch tells NPM to pass the Upgrade/Connection headers the console needs. Reload the PBS Shell and a prompt appears.

Why this generalizes

This isn’t a PBS quirk — it’s a Proxmox-console-behind-a-proxy quirk. The same black screen hits PVE’s noVNC/xterm/SPICE consoles too, for the same reason. If any Proxmox console goes black through a reverse proxy, check WebSocket forwarding first:

  • NPM: the “Websockets Support” toggle on the host.
  • Raw nginx: proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection "upgrade"; on the location.
  • Cloudflare: WebSockets are on by default — but a tunnel/ingress in front can still drop them.

The tell is always the same: terminal canvas loads, no data arrives, backend logs show no console process. That trio means the transport, not the server.