enricobuehlerandClaude Opus 5
d383161723
ci / rust (push) Failing after 2m31s
ci / docs-site (push) Successful in 1m22s
ci / web (push) Successful in 1m48s
docker / builders (--build-arg FEDORA_VERSION=44, ci/fedora-rpm.Dockerfile, punktfunk-fedora44-rpm, -f44) (push) Successful in 1m1s
ci / rust-arm64 (push) Successful in 2m2s
docker / builders (ci/android-ci.Dockerfile, punktfunk-android-ci) (push) Successful in 11s
docker / builders (ci/arch-ci.Dockerfile, punktfunk-arch-ci) (push) Successful in 9s
docker / builders (ci/fedora-rpm.Dockerfile, punktfunk-fedora-rpm) (push) Successful in 9s
docker / builders (ci/rust-ci-noble.Dockerfile, punktfunk-rust-ci-noble) (push) Successful in 9s
docker / builders (ci/rust-ci.Dockerfile, punktfunk-rust-ci) (push) Successful in 9s
docker / builders-arm64cross (push) Successful in 20s
docker / apps (., web/Dockerfile, punktfunk-web) (push) Canceled after 36s
docker / apps (docs-site, docs-site/Dockerfile, punktfunk-docs) (push) Canceled after 36s
docker / deploy-docs (push) Canceled after 0s
~1150 feat/fix commits landed since v0.19 and the docs drifted badly. This is a full sweep of every page against the code as shipped: ~280 verified corrections, nine new pages, and one deletion. The worst of what was wrong: the quickstart's five-minute path could not work (`serve` never started the web console, so step 3 had no PIN to read); every packaged Linux host runs `serve --gamestream` while security.md told readers to leave GameStream off; HDR was documented as Windows-only; `PUNKTFUNK_SECURE_DDA` was documented as a working knob that nothing reads; `PUNKTFUNK_INPUT_BACKEND` listed a `uinput` value that does not exist and named libei for KDE instead of kwin; README linked three pages deleted on 2026-07-05; and the rpm-ostree update command pointed at a script no package installs. Completeness: about half of what shipped since v0.19 had no page at all. New: support-matrix (what works where, from 217 verified capability cells), input (mouse/touch/pen — and the in-stream chords, so the docs finally say how to get your mouse back), client-settings, profiles-and-links, game-library, clipboard, wake-on-lan, hdr, uninstall. Updating existed but had zero inbound links. status.md is gone: its facts moved into the support matrix, its shell stays as a redirect so the public URL does not 404. roadmap.md is themes now, not a feature checklist — checkboxes are what rotted. Debian is no longer claimed. The .deb's Depends resolve against Ubuntu images, nothing in CI builds or tests Debian, and Debian 12 is below the glibc 2.39 floor. The `debian` in the repo URL is the package format. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
123 lines
5.1 KiB
Markdown
123 lines
5.1 KiB
Markdown
---
|
|
title: GNOME (Mutter)
|
|
description: Configure a Punktfunk host for GNOME — host.env, the EGL/lock traps, and a headless session.
|
|
---
|
|
|
|
Configure a host running **GNOME**. The host drives GNOME's Mutter compositor to create a per-client
|
|
virtual display over D-Bus (`RecordVirtual`), zero-copy. This page assumes the host is already
|
|
installed — see [Ubuntu](/docs/ubuntu), [Fedora](/docs/fedora), or [Arch](/docs/arch).
|
|
|
|
> 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.
|
|
|
|
## host.env
|
|
|
|
The host auto-detects the compositor from your live session on every connect, so the starter
|
|
`~/.config/punktfunk/host.env` is one line:
|
|
|
|
```ini
|
|
# ~/.config/punktfunk/host.env (keys are case-sensitive)
|
|
PUNKTFUNK_VIDEO_SOURCE=virtual
|
|
# GPU zero-copy (dmabuf → CUDA → NVENC) is ON by default; auto-falls back to CPU. Set =0 to force CPU.
|
|
```
|
|
|
|
> **Don't set `PUNKTFUNK_COMPOSITOR`, `WAYLAND_DISPLAY`, or `XDG_CURRENT_DESKTOP` here.** Pinning
|
|
> the compositor turns auto-detection **off** — per connect *and* mid-stream — so the host stops
|
|
> following session switches, and stale session values point it at dead sockets. Forcing a backend
|
|
> is a CI / dedicated-appliance posture, not desktop configuration.
|
|
|
|
You must be on a **Wayland** session (not X11), and Mutter must be **≥ 48**. See the
|
|
[Configuration reference](/docs/configuration) for every option.
|
|
|
|
## The GL/EGL userspace
|
|
|
|
On NVIDIA, gnome-shell fails to start — or the host logs **"GPU … not supported by EGL"** — when the
|
|
NVIDIA GL/EGL userspace is missing. The base driver package doesn't always pull it in. Install your
|
|
distro's NVIDIA GL/EGL userspace package — on **Ubuntu** it's `libnvidia-gl-<version>` matching
|
|
your driver; on **Fedora/Arch** it ships with the RPM Fusion / repo driver — then confirm the glvnd
|
|
vendor file exists:
|
|
|
|
```sh
|
|
ls /usr/share/glvnd/egl_vendor.d/10_nvidia.json # must exist
|
|
```
|
|
|
|
Installing the driver itself is covered on your distro's install page
|
|
([Ubuntu](/docs/ubuntu), [Fedora](/docs/fedora), [Arch](/docs/arch)).
|
|
|
|
## Do not lock the session
|
|
|
|
A **locked** GNOME session blocks screen capture — the host fails with
|
|
**"Session creation inhibited"**. On an always-on or headless host there's no one to unlock it, so
|
|
disable the lock:
|
|
|
|
```sh
|
|
gsettings set org.gnome.desktop.screensaver lock-enabled false
|
|
gsettings set org.gnome.desktop.session idle-delay 0
|
|
```
|
|
|
|
## Start the host
|
|
|
|
With `host.env` in place, start the host from **inside your GNOME session**:
|
|
|
|
```sh
|
|
systemctl --user enable --now punktfunk-host
|
|
journalctl --user -u punktfunk-host -f # watch it come up and print its identity fingerprint
|
|
```
|
|
|
|
This unit runs `serve --gamestream`, so it serves stock [Moonlight](/docs/moonlight) clients as well
|
|
as the native ones. For a native-only host, see
|
|
[What the unit starts](/docs/running-as-a-service#what-the-unit-starts).
|
|
|
|
A desktop-login host should also follow your session's lifetime, or restarting GNOME Shell leaves the
|
|
host wired to a compositor that is gone — it keeps answering, and every session after that fails at
|
|
capture. Add the drop-in from
|
|
[Restart the host with your desktop](/docs/running-as-a-service#restart-the-host-with-your-desktop).
|
|
Skip it on the headless route below.
|
|
|
|
Then bring up [The Web Console](/docs/web-console) to arm pairing and connect a
|
|
[client](/docs/clients). For an always-on box, see the [headless session](#headless-session) below.
|
|
|
|
Display scaling you set while streaming **sticks per client**: the host remembers each device's
|
|
scale and reapplies it on reconnect — see
|
|
[Persistent scaling](/docs/virtual-displays#persistent-scaling).
|
|
|
|
## HDR (GNOME 50+)
|
|
|
|
The per-client virtual display this page is about always streams **SDR** — Mutter's `RecordVirtual`
|
|
screencasts are 8-bit upstream, so there is nothing to turn on.
|
|
|
|
GNOME 50 added HDR screencast for **real monitors**, and the host can use that route — on the
|
|
GameStream/Moonlight plane only, by mirroring a monitor instead of creating one.
|
|
[HDR → Linux + GNOME](/docs/hdr#linux--gnome) has the two settings it needs, which monitor it
|
|
checks, and how it degrades when none is in HDR mode; [Check it](/docs/hdr#check-it) has the
|
|
`hdr-probe` subcommand that names the link that said no.
|
|
|
|
## Headless session
|
|
|
|
To run with no monitor and no login, keep a GNOME Wayland session up at all times and start the host
|
|
without a login. Have GDM auto-login your user:
|
|
|
|
```ini
|
|
# /etc/gdm3/custom.conf (Ubuntu) · /etc/gdm/custom.conf (Fedora)
|
|
[daemon]
|
|
AutomaticLoginEnable = true
|
|
AutomaticLogin = your-user
|
|
```
|
|
|
|
Disable the lock (see [above](#do-not-lock-the-session)), then enable the host user service and let it
|
|
linger past logout:
|
|
|
|
```sh
|
|
systemctl --user enable --now punktfunk-host
|
|
sudo loginctl enable-linger "$USER"
|
|
```
|
|
|
|
Reboot and the host comes up on the auto-login session. Full walkthrough:
|
|
[Running as a Service](/docs/running-as-a-service).
|
|
|
|
## Troubleshooting
|
|
|
|
More fixes — black screen, discovery, pairing — in [Troubleshooting](/docs/troubleshooting).
|
|
|
|
Once the host is up, bring the console up and pair — see [The Web Console](/docs/web-console).
|