enricobuehler
185a69c806
ci / bun-nix (pull_request) Successful in 20s
ci / docs-site (pull_request) Successful in 1m5s
ci / web (pull_request) Successful in 1m10s
ci / rust-arm64 (pull_request) Successful in 1m49s
ci / rust (pull_request) Successful in 6m23s
nix / flake (pull_request) Failing after 12m37s
Two separate things had to be wrong for this, and both were. The frame's own policy locked it out. Plugin UIs moved to their own origin so a plugin cannot act as the logged-in operator, and the plugin origin names the console as the only page allowed to frame it. It built that name from the incoming request — but Nitro hands the app a synthetic request with no TLS socket, so an HTTPS console reads back as `http:`. The header said `frame-ancestors http://host:47992` while the operator was on `https://host:47992`, and the browser refused the frame outright (ERR_BLOCKED_BY_RESPONSE). Nothing on screen said so; the reason was only in devtools. The scheme now comes from the listener's own TLS state, stamped at bind time, with x-forwarded-proto winning when something in front terminated TLS for us — the one case where the browser's scheme is not ours. And the port was shut. 47993 was added to the firewall definitions, but an already-open firewall does not pick a new port up: ufw expands an app profile into rules when you allow it and keeps those, so editing the profile on upgrade changes nothing, and firewalld needs a reload. Every upgraded Linux host kept a 47992-only rule, silently. The packages now notice on upgrade and print the one command that fixes it, without touching the running firewall. The NixOS module and the container image never learned the port at all; both now open it. Also: the console no longer mounts the frame while it is still checking whether that origin is reachable. A firewalled port drops rather than refuses, so the check hangs for the browser's whole connect timeout, and mounting meanwhile is exactly the empty panel with no explanation. The card that follows now names both causes it can be — an untrusted certificate for that port, or a closed one — because from a browser the two are indistinguishable. The rule is now a pure function with tests, since its failure mode is a well-formed header that only a browser rejects. Verified on glass against home-worker-5 (.21) and its ROM Manager plugin: the frame was refused before, renders the plugin's UI after.
141 lines
7.5 KiB
Markdown
141 lines
7.5 KiB
Markdown
---
|
|
title: The Web Console
|
|
description: Enable the Punktfunk browser console, read or change its login password, arm PIN pairing, and what every page in it does.
|
|
---
|
|
|
|
The web console is the browser UI for a Punktfunk host — live status, pairing, display policy, the
|
|
game library, logs, plugins and host updates. It ships as the **`punktfunk-web`** systemd user unit
|
|
on Linux and runs under the **Punktfunk Host service** on Windows, and serves on **`https://<host-ip>:47992`**
|
|
(HTTPS with the host's own self-signed identity cert — your browser warns once; trust it and
|
|
continue). It's the surface you expose on the LAN to administer the host; the host's own management
|
|
API (47990) keeps every admin action loopback-only and off-loopback serves only read-only status +
|
|
game-library browsing to paired clients.
|
|
|
|
> New here? Read [Security & Safe Use](/docs/security) first — a streaming host is remote control of
|
|
> the machine, so keep it on a trusted LAN or VPN and require pairing.
|
|
|
|
## Two ports, not one
|
|
|
|
The console also listens on **TCP 47993**, and plugin interfaces are served from there — same host,
|
|
same certificate, **different port**.
|
|
|
|
That is a deliberate boundary rather than a second console. A plugin's interface is third-party
|
|
code, and on the console's own port the browser would treat it as part of the console: it could act
|
|
as you, with your logged-in session, against every admin action the console can reach. A different
|
|
port is a different *origin*, so the browser itself keeps the two apart — while staying the same
|
|
*site*, which is what lets your login still carry over so you don't sign in twice.
|
|
|
|
What this means in practice:
|
|
|
|
- **Open 47993 alongside 47992** on the host's firewall if you browse the console from another
|
|
device. The packaged firewall profiles already list both.
|
|
- **Trust the certificate twice.** Browsers store a self-signed certificate exception *per port*.
|
|
The first time you open a plugin, the console will notice it can't reach 47993 yet and offer a
|
|
link to open it in a tab — accept the warning there once, come back, and it works from then on.
|
|
- If a plugin's page is an empty panel, see
|
|
[A plugin's interface doesn't load](/docs/troubleshooting#a-plugins-interface-doesnt-load).
|
|
|
|
## Enable the console
|
|
|
|
- **Linux packages (apt / RPM / Bazzite):** on Ubuntu the host package is `punktfunk-host`
|
|
and on Fedora/Bazzite it's `punktfunk`; either way it *recommends* `punktfunk-web`, so your
|
|
package manager pulls the console in with the host (the Bazzite sysext image already contains
|
|
it). Enable and start it as your desktop user, then open the URL:
|
|
|
|
```sh
|
|
systemctl --user enable --now punktfunk-web
|
|
# then browse to https://<host-ip>:47992
|
|
```
|
|
|
|
- **Arch / CachyOS (pacman):** the console is an *optional* package here, and pacman never installs
|
|
optional dependencies — so install it yourself from the same repo the host came from (see
|
|
[Arch Linux](/docs/arch)), then enable it exactly as above. Take it as a full `-Syu`, never a bare
|
|
`pacman -S`, so you don't end up on a partial upgrade:
|
|
|
|
```sh
|
|
sudo pacman -Syu punktfunk-web
|
|
systemctl --user enable --now punktfunk-web
|
|
```
|
|
|
|
- **Windows host:** the installer sets up the console and its runtime; the Punktfunk Host service
|
|
runs it and automatically brings it back if it ever stops. There is nothing to enable — open
|
|
`https://<this-PC>:47992`.
|
|
|
|
- **SteamOS host:** the install script builds and starts the console as a user service for you. It
|
|
prints the URL when it finishes.
|
|
|
|
## Login password
|
|
|
|
The console is password-protected. Where that password lives and how you change it depends on the
|
|
host platform.
|
|
|
|
**Linux packages (apt / RPM / Bazzite).** On first start `punktfunk-web-init` generates a random
|
|
password and saves it to `~/.config/punktfunk/web-password` (as `PUNKTFUNK_UI_PASSWORD=…`). Read it
|
|
back from the init service's journal or straight from the file:
|
|
|
|
```sh
|
|
journalctl --user -u punktfunk-web-init | sed -n 's/.*password generated: //p'
|
|
sed -n 's/^PUNKTFUNK_UI_PASSWORD=//p' ~/.config/punktfunk/web-password
|
|
```
|
|
|
|
To set your own, edit that file (`PUNKTFUNK_UI_PASSWORD=<your-password>`) and restart the console:
|
|
`systemctl --user restart punktfunk-web`.
|
|
|
|
**SteamOS host.** Same idea, but the install script writes the generated password to
|
|
`~/.config/punktfunk/web.env` and prints it at the end of the install run:
|
|
|
|
```sh
|
|
sed -n 's/^PUNKTFUNK_UI_PASSWORD=//p' ~/.config/punktfunk/web.env
|
|
```
|
|
|
|
Edit that file and `systemctl --user restart punktfunk-web` to change it.
|
|
|
|
**Windows host.** You choose the password during install — a secure random default is pre-filled and
|
|
shown again on the installer's final page. It's stored in `%ProgramData%\punktfunk\web-password` (as
|
|
`PUNKTFUNK_UI_PASSWORD=…`), readable only by Administrators and SYSTEM. To change it, edit the file
|
|
and restart the Punktfunk Host service (which runs the console) in an **elevated** PowerShell:
|
|
|
|
```powershell
|
|
notepad "$env:ProgramData\punktfunk\web-password" # set PUNKTFUNK_UI_PASSWORD=<your-password>
|
|
punktfunk-host service restart
|
|
```
|
|
|
|
Forgot it? See [Forgot your Password?](/docs/forgot-password).
|
|
|
|
## Arm pairing
|
|
|
|
The host **requires PIN pairing** by default (secure on a LAN). To connect the first time, open the
|
|
console, log in, then open **Pairing** in the sidebar and click **Pair a device**. The host shows a
|
|
one-time 4-digit PIN — enter it on your [client](/docs/clients) to pair. If the device already tried
|
|
to connect it appears under **Waiting for approval** instead; approving it pairs it immediately, no
|
|
PIN needed. See [Pairing & Trust](/docs/pairing) for the full trust model and how to approve or
|
|
remove devices later.
|
|
|
|
## What's in it
|
|
|
|
Nine destinations in the sidebar (a **More** tab on a phone holds the last five):
|
|
|
|
- **Dashboard** — live status: whether video and audio are streaming, the active sessions with
|
|
their codec, resolution, frame rate and bitrate, which games are running, and how many clients
|
|
are paired. Buttons here stop a session or ask the encoder for a fresh keyframe.
|
|
- **Host** — this host's identity (hostname, OS, local IP, version, unique id), the codecs it
|
|
advertises, its ports, the **Updates** card (see [Updating the Host](/docs/updating)), the
|
|
**GPUs** card — Automatic, or prefer one GPU for capture and encode, applied to the next session
|
|
— and the compositor backends it found.
|
|
- **Virtual displays** — the policy for the display each session gets, and the Streamed screen
|
|
picker. See [Virtual displays](/docs/virtual-displays).
|
|
- **Library** — the games every client sees: turn a launcher source on or off, add or edit a custom
|
|
title with its own art and launch command. See [Your game library](/docs/game-library).
|
|
- **Performance** — arm a capture, run a session, stop it, and read the recording back as
|
|
per-stage latency, throughput and health graphs.
|
|
- **Logs** — the host's recent log stream *and your plugins'*: follow it live, filter by level or
|
|
producer, search it, and download or share it for a bug report. Plugin lines are tagged
|
|
`plugin:<name>` and the **Host / Plugins** switch isolates either side.
|
|
- **Pairing** — arm a PIN, approve or deny devices waiting for approval, and unpair a device. A
|
|
second PIN box for [Moonlight/GameStream](/docs/moonlight) clients appears only when this host
|
|
runs the GameStream plane.
|
|
- **Plugins** — the plugin store's **Browse**, **Installed** and **Sources** tabs plus the plugin
|
|
runner switch; an installed plugin with a UI gets its own entry below. See
|
|
[Plugins](/docs/plugins).
|
|
- **Settings** — the console's language, and **Sign out**.
|