From 6bc893e394ba92bdbc23f32af9634623f6d17819 Mon Sep 17 00:00:00 2001 From: enricobuehler Date: Sat, 4 Jul 2026 22:31:53 +0000 Subject: [PATCH] docs(arch): fish-safe repo setup, firewalld services, fix client label MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The pacman-repo setup step used a bash heredoc (`<<'EOF'`), which fish — the default shell on CachyOS — cannot parse ("expected a string, but found a redirection"). Replace it with a cross-shell `printf | sudo tee -a` form in both the Arch guide and packaging/arch/README.md; `$repo`/`$arch` stay literal for pacman and the output is byte-identical to the old heredoc. Firewall: stock Arch ships none (ports already open), but CachyOS enables firewalld by default and an Arch package must never touch the running firewall. Ship firewalld service definitions the host package installs to /usr/lib/firewalld/services/ (punktfunk-gamestream, punktfunk-native), not auto-enabled; the install scriptlet prints the enable command only when firewall-cmd is present. Document it in the Arch guide (new section) and README. The mgmt API (loopback) and web console ports are deliberately not opened. Also fix the "GTK4 couch/Deck client" mislabel — it's the native GTK4/libadwaita Linux client (desktop/laptop/Deck are targets; the controller-optimized launcher is one view, not its identity) — across the Arch PKGBUILD/README, Arch guide, and the Debian README. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs-site/content/docs/arch.md | 40 ++++++++++++++++----- packaging/arch/PKGBUILD | 12 +++++-- packaging/arch/README.md | 47 +++++++++++++++++++------ packaging/arch/punktfunk-gamestream.xml | 25 +++++++++++++ packaging/arch/punktfunk-host.install | 12 +++++++ packaging/arch/punktfunk-native.xml | 20 +++++++++++ packaging/debian/README.md | 2 +- 7 files changed, 136 insertions(+), 22 deletions(-) create mode 100644 packaging/arch/punktfunk-gamestream.xml create mode 100644 packaging/arch/punktfunk-native.xml diff --git a/docs-site/content/docs/arch.md b/docs-site/content/docs/arch.md index 4ad4287..11c8b11 100644 --- a/docs-site/content/docs/arch.md +++ b/docs-site/content/docs/arch.md @@ -34,12 +34,10 @@ curl -fsS https://git.unom.io/api/packages/unom/arch/repository.key \ sudo pacman-key --lsign-key E0CA04465C99C936E0B0C6510A317015A34DDD69 # Add the repo (append to /etc/pacman.conf). No SigLevel line needed — pacman's default -# verifies signed packages against the key you just trusted. -sudo tee -a /etc/pacman.conf >/dev/null <<'EOF' - -[punktfunk] -Server = https://git.unom.io/api/packages/unom/arch/$repo/$arch -EOF +# verifies signed packages against the key you just trusted. (printf, not a heredoc, so this +# works in fish too — CachyOS's default shell has no `</dev/null ``` > **Stable vs canary.** `[punktfunk]` is the **stable** channel — it moves only when a `vX.Y.Z` @@ -54,7 +52,7 @@ sudo pacman -S punktfunk-web # optional: the browser management console ( sudo usermod -aG input "$USER" # /dev/uinput access for virtual gamepads (re-login to apply) ``` -`punktfunk-client` (the GTK4 couch/Deck client) is in the same repo if this box is also a client. +`punktfunk-client` (the native GTK4 Linux client) is in the same repo if this box is also a client. The host package ships the systemd **user** units, the udev rule, the UDP socket-buffer sysctl tuning, and example configs. Updates later are just `sudo pacman -Syu`. @@ -108,7 +106,33 @@ sed -n 's/^PUNKTFUNK_UI_PASSWORD=//p' ~/.config/punktfunk/web-password To set your own, edit that file and `systemctl --user restart punktfunk-web`. Forgot it? See [Forgot your Password?](/docs/forgot-password). -## 5. Connect a client +## 5. Open the firewall (if you have one) + +**Stock Arch ships no firewall** — every port is already open, so you can skip this. But **CachyOS +enables `firewalld` by default**, and an Arch package never opens ports for you (it won't touch your +running firewall), so on CachyOS the host is unreachable until you allow it. + +The `punktfunk-host` package installs **firewalld service definitions** for exactly this, so +enabling is one command. Reload once so firewalld sees the just-installed definition, add the +service, then reload to apply: + +```sh +sudo firewall-cmd --reload +sudo firewall-cmd --permanent --add-service=punktfunk-native # the default native host +# --add-service=punktfunk-gamestream # …or add this for Moonlight compat +sudo firewall-cmd --reload +``` + +`punktfunk-native` opens the QUIC control port (UDP 9777) + mDNS discovery; add +`punktfunk-gamestream` as well if you run `serve --gamestream` (the fixed Moonlight ports + mDNS). +The media **data plane** uses an *ephemeral* UDP port per session (nothing fixed to open); a +restrictive firewall must also allow a UDP range. The web console (47992) and mgmt API (47990, +loopback-only) are **not** opened by these — reach the console from the host box, or open 47992 +yourself if you want it on the LAN. Not on firewalld? See +[`packaging/arch/README.md`](https://git.unom.io/unom/punktfunk/src/branch/main/packaging/arch/README.md#firewall) +for the `ufw`/`nftables` port lists. + +## 6. Connect a client From any [client](/docs/clients), `--discover` finds the host on the LAN. On first connect, complete the **PIN pairing** — arm it from the host's web console, which displays a 4-digit PIN to type into diff --git a/packaging/arch/PKGBUILD b/packaging/arch/PKGBUILD index da10c55..1ae1a29 100644 --- a/packaging/arch/PKGBUILD +++ b/packaging/arch/PKGBUILD @@ -1,7 +1,7 @@ # Maintainer: unom # # Arch Linux / SteamOS split package: punktfunk-host (the gaming-rig HOST, NVENC) and -# punktfunk-client (the GTK4 couch/Deck CLIENT). Mirrors the rpm subpackages +# punktfunk-client (the native GTK4/libadwaita Linux CLIENT). Mirrors the rpm subpackages # (packaging/rpm/punktfunk.spec) and the two deb build scripts. On a Steam Deck you want # `punktfunk-client` (it's what the Decky plugin launches); on a gaming rig, `punktfunk-host`. # @@ -134,13 +134,21 @@ package_punktfunk-host() { install -Dm0644 "$R/packaging/bazzite/gamescope-headless-session" \ "$pkgdir/etc/gamescope-session-plus/sessions.d/steam" install -Dm0644 "$R/api/openapi.json" "$pkgdir/usr/share/punktfunk/openapi.json" + # firewalld service definitions — NOT auto-enabled (Arch packages never touch the admin's + # firewall). Stock Arch ships none, so they're a no-op there; CachyOS et al. ship firewalld, so + # sudo firewall-cmd --reload && sudo firewall-cmd --permanent --add-service=punktfunk-gamestream && sudo firewall-cmd --reload + # (or =punktfunk-native). See README.md → Firewall. + install -Dm0644 "$R/packaging/arch/punktfunk-gamestream.xml" \ + "$pkgdir/usr/lib/firewalld/services/punktfunk-gamestream.xml" + install -Dm0644 "$R/packaging/arch/punktfunk-native.xml" \ + "$pkgdir/usr/lib/firewalld/services/punktfunk-native.xml" install -Dm0644 "$R/LICENSE-MIT" "$pkgdir/usr/share/licenses/punktfunk-host/LICENSE-MIT" install -Dm0644 "$R/LICENSE-APACHE" "$pkgdir/usr/share/licenses/punktfunk-host/LICENSE-APACHE" install -Dm0644 "$R/README.md" "$pkgdir/usr/share/doc/punktfunk-host/README.md" } package_punktfunk-client() { - pkgdesc="Low-latency desktop/game streaming CLIENT (GTK4) — the couch/Deck side" + pkgdesc="Low-latency desktop/game streaming CLIENT — native GTK4/libadwaita Linux app" # The GTK4/libadwaita client: SDL3 gamepads, FFmpeg (VAAPI) decode, PipeWire audio/mic. depends=('gtk4' 'libadwaita' 'sdl3' 'ffmpeg' 'pipewire' 'wireplumber' 'pipewire-pulse' 'opus' 'libglvnd') diff --git a/packaging/arch/README.md b/packaging/arch/README.md index e3880b8..79be89d 100644 --- a/packaging/arch/README.md +++ b/packaging/arch/README.md @@ -1,9 +1,9 @@ # punktfunk on Arch Linux / SteamOS Packaging for punktfunk on Arch and Arch-derived immutable distros. The `PKGBUILD` is a **split -package** producing **`punktfunk-host`** (the gaming-rig host) and **`punktfunk-client`** (the GTK4 -couch/Deck client) — mirrors the rpm subpackages (`packaging/rpm/punktfunk.spec`) and the deb build -scripts. On a **Steam Deck used as a client you want `punktfunk-client`** (it's what the +package** producing **`punktfunk-host`** (the gaming-rig host) and **`punktfunk-client`** (the native +GTK4/libadwaita Linux client) — mirrors the rpm subpackages (`packaging/rpm/punktfunk.spec`) and the +deb build scripts. On a **Steam Deck used as a client you want `punktfunk-client`** (it's what the [Decky plugin](../../clients/decky/) launches); on a gaming rig, `punktfunk-host`. > **Steam Deck as a HOST:** don't use this PKGBUILD — SteamOS's read-only root makes `makepkg`/sysext @@ -42,15 +42,13 @@ curl -fsS https://git.unom.io/api/packages/unom/arch/repository.key \ sudo pacman-key --lsign-key E0CA04465C99C936E0B0C6510A317015A34DDD69 # 2. Add the repo (pick ONE channel — punktfunk for releases, punktfunk-canary for main builds). -sudo tee -a /etc/pacman.conf >/dev/null <<'EOF' - -[punktfunk] -Server = https://git.unom.io/api/packages/unom/arch/$repo/$arch -EOF +# printf, not a heredoc, so this works in fish too (CachyOS's default shell has no `</dev/null # 3. Sync + install. sudo pacman -Sy punktfunk-host # gaming rig -sudo pacman -Sy punktfunk-client # couch/Deck side +sudo pacman -Sy punktfunk-client # the native GTK4 Linux client sudo pacman -Sy punktfunk-web # optional browser management console ``` @@ -139,7 +137,31 @@ so it's a much lighter sysext than the host. ## Firewall -If the host box runs a firewall, open the ports it listens on. The **native `punktfunk/1`** plane: +**Stock Arch ships no firewall** — every port is open by default, so there is nothing to do. +Spins that enable one **do not** get their ports opened for you: an Arch package never touches the +admin's running firewall. **CachyOS is the common case** — its installer turns on `firewalld` by +default, so out of the box the host is unreachable until you allow it. + +The `punktfunk-host` package ships **firewalld service definitions** (installed to +`/usr/lib/firewalld/services/`) so enabling is one command — pick the plane your host serves: + +```sh +# Reload once so firewalld picks up the just-installed service definition, add it, reload to apply. +sudo firewall-cmd --reload +sudo firewall-cmd --permanent --add-service=punktfunk-gamestream # Moonlight/GameStream host +# --add-service=punktfunk-native # …or the native-only host +sudo firewall-cmd --reload +``` + +`punktfunk-gamestream` opens the fixed Moonlight ports + mDNS; `punktfunk-native` opens the QUIC +control port (UDP 9777) + mDNS. Enable both if the host runs `serve --gamestream` (which serves +both planes). The **data plane is an *ephemeral* UDP port** negotiated per session, so there is no +fixed data port in either service; a restrictive firewall must additionally allow a UDP range (the +project does not pin one). The mgmt REST API (TCP 47990) binds to loopback by default — leave it +closed unless you move it off loopback with `--mgmt-bind IP:PORT` (which then requires +`--mgmt-token`). + +For a non-firewalld setup, open the ports directly. The **native `punktfunk/1`** plane: - **QUIC control plane: UDP 9777** (`serve --native-port N` to change). - **Data plane: an *ephemeral* UDP port** — negotiated per session, so there is no fixed port to @@ -182,6 +204,9 @@ udp dport { 47998-48010, 5353 } accept - `PKGBUILD` — split package: `punktfunk-host` + `punktfunk-client` (builds the working tree via `PF_SRCDIR`, or a git tag for AUR). - `punktfunk-host.install` / `punktfunk-client.install` — pacman scriptlets (udev reload + sysctl + - first-run hint), mirror the RPM `%post` / deb postinst. + first-run hint, incl. the firewalld enable command when firewalld is present), mirror the RPM + `%post` / deb postinst. +- `punktfunk-gamestream.xml` / `punktfunk-native.xml` — firewalld service definitions the host + package installs to `/usr/lib/firewalld/services/` (not auto-enabled; see Firewall above). - `build-sysext.sh` — wraps either built `.pkg.tar.zst` into a `systemd-sysext` `.raw` for SteamOS (derives the name from the package, so it works for host or client). diff --git a/packaging/arch/punktfunk-gamestream.xml b/packaging/arch/punktfunk-gamestream.xml new file mode 100644 index 0000000..b9489aa --- /dev/null +++ b/packaging/arch/punktfunk-gamestream.xml @@ -0,0 +1,25 @@ + + + + Punktfunk (GameStream / Moonlight) + Low-latency game-streaming host over the Moonlight-compatible GameStream protocol. Opens the fixed nvhttp (HTTPS/HTTP), RTSP, video RTP, ENet control/input and Opus audio ports, plus mDNS for auto-discovery. + + + + + + + + diff --git a/packaging/arch/punktfunk-host.install b/packaging/arch/punktfunk-host.install index 7bfbe4e..3277160 100644 --- a/packaging/arch/punktfunk-host.install +++ b/packaging/arch/punktfunk-host.install @@ -17,6 +17,18 @@ punktfunk-host installed. NOTE: encode is NVENC-only. Install 'nvidia-utils' on an NVIDIA host. An AMD Steam Deck is NOT yet supported — it needs a VAAPI (hevc_vaapi) encoder backend (see packaging/arch/README.md). MSG + # Firewall: stock Arch ships none (ports already open), but CachyOS et al. enable firewalld. We + # install firewalld service definitions but never touch the running firewall — just point the way. + if command -v firewall-cmd >/dev/null 2>&1; then + cat <<'MSG' + + 4. firewalld is active — open the streaming ports once (GameStream/Moonlight shown; use + 'punktfunk-native' instead for the native-only host): + sudo firewall-cmd --reload # load the new service def + sudo firewall-cmd --permanent --add-service=punktfunk-gamestream + sudo firewall-cmd --reload +MSG + fi } post_upgrade() { diff --git a/packaging/arch/punktfunk-native.xml b/packaging/arch/punktfunk-native.xml new file mode 100644 index 0000000..880951d --- /dev/null +++ b/packaging/arch/punktfunk-native.xml @@ -0,0 +1,20 @@ + + + + Punktfunk (native punktfunk/1) + Low-latency game-streaming host over the native punktfunk/1 protocol (QUIC control plane). Opens the default QUIC control port plus mDNS for auto-discovery. The media data plane uses an ephemeral UDP port negotiated per session, not opened here. + + + diff --git a/packaging/debian/README.md b/packaging/debian/README.md index f5e48d3..2f5a069 100644 --- a/packaging/debian/README.md +++ b/packaging/debian/README.md @@ -9,7 +9,7 @@ to a canary build — see [Release Channels](https://punktfunk.unom.io/docs/chan below subscribes to `stable`; swap `stable` → `canary` for the latest main builds. The same workflow also publishes **`punktfunk-web`** (the browser management console — pairing + -status) and **`punktfunk-client`** (the GTK4 couch/Deck client). `punktfunk-host` **Recommends** +status) and **`punktfunk-client`** (the native GTK4/libadwaita Linux client). `punktfunk-host` **Recommends** `punktfunk-web`, so a default `apt install punktfunk-host` pulls the console too (alongside the udev/sysctl bits) unless you've disabled weak deps; `punktfunk-client` is independent — install it on the box you stream *to*. (`punktfunk-probe` is the headless reference/test tool, not packaged