From e27718b406c6083d1769543887448510f2175ce1 Mon Sep 17 00:00:00 2001 From: enricobuehler Date: Sat, 4 Jul 2026 22:37:45 +0000 Subject: [PATCH] packaging: ship firewalld services on rpm + deb too, share from packaging/linux MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirror the Arch firewalld service definitions into the RPM spec and the Debian host package so every Linux packager installs them, and move the two XML files to the shared packaging/linux/ home (alongside the .desktop files both the PKGBUILD and deb scripts already source there) so there's one source of truth instead of three drifting copies. - rpm: install punktfunk-{gamestream,native}.xml to /usr/lib/firewalld/services/, list them in %files host, and print the firewalld enable command in %post (gated on firewall-cmd). Fedora/RHEL run firewalld by default, so this is where it matters most; Bazzite inherits it via the sysext built from the package /usr. - deb: install both XMLs in build-deb.sh and add the same firewalld-gated hint to the postinst. Debian/Ubuntu ship no active firewall, so it's a no-op unless the admin runs firewalld. - PKGBUILD + arch README updated to the packaging/linux/ path. - Firewall docs (bazzite README now leads with --add-service; debian README gains a firewalld block) point at the shipped services; XML comments made distro-neutral. Never auto-enabled — packages don't touch the admin's firewall. Co-Authored-By: Claude Opus 4.8 (1M context) --- packaging/arch/PKGBUILD | 4 ++-- packaging/arch/README.md | 5 ++-- packaging/bazzite/README.md | 23 +++++++++++++++---- packaging/debian/README.md | 15 +++++++++++- packaging/debian/build-deb.sh | 13 +++++++++++ .../{arch => linux}/punktfunk-gamestream.xml | 6 ++--- .../{arch => linux}/punktfunk-native.xml | 7 +++--- packaging/rpm/punktfunk.spec | 15 ++++++++++++ 8 files changed, 72 insertions(+), 16 deletions(-) rename packaging/{arch => linux}/punktfunk-gamestream.xml (84%) rename packaging/{arch => linux}/punktfunk-native.xml (76%) diff --git a/packaging/arch/PKGBUILD b/packaging/arch/PKGBUILD index 1ae1a29..75ae477 100644 --- a/packaging/arch/PKGBUILD +++ b/packaging/arch/PKGBUILD @@ -138,9 +138,9 @@ package_punktfunk-host() { # 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" \ + install -Dm0644 "$R/packaging/linux/punktfunk-gamestream.xml" \ "$pkgdir/usr/lib/firewalld/services/punktfunk-gamestream.xml" - install -Dm0644 "$R/packaging/arch/punktfunk-native.xml" \ + install -Dm0644 "$R/packaging/linux/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" diff --git a/packaging/arch/README.md b/packaging/arch/README.md index 79be89d..fd6d549 100644 --- a/packaging/arch/README.md +++ b/packaging/arch/README.md @@ -206,7 +206,8 @@ udp dport { 47998-48010, 5353 } accept - `punktfunk-host.install` / `punktfunk-client.install` — pacman scriptlets (udev reload + sysctl + 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). +- The firewalld service definitions (`punktfunk-gamestream.xml` / `punktfunk-native.xml`) are shared + across all Linux packaging and live in [`../linux/`](../linux/); the host package installs them 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/bazzite/README.md b/packaging/bazzite/README.md index f189df2..fe48e1b 100644 --- a/packaging/bazzite/README.md +++ b/packaging/bazzite/README.md @@ -321,10 +321,23 @@ journalctl --user -u punktfunk-host -f ## 6. Firewall -> ⚠️ **There is no firewall script or firewall doc in the repo.** The ports below are derived -> directly from the code constants (`crates/punktfunk-host/src/gamestream/mod.rs`, `mgmt.rs`) and -> the GameStream-host port-map (`design/gamestream-host-plan.md`). Treat the `firewall-cmd` lines as recommended-but-verified, -> not a checked-in script. +Bazzite runs **firewalld**, so the ports must be opened. The `punktfunk-host` package installs +firewalld **service definitions** (`/usr/lib/firewalld/services/punktfunk-gamestream.xml` and +`punktfunk-native.xml`), so enabling is one command — reload first so firewalld picks up the +definition, add the service, reload to apply: + +```sh +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` (both planes). The +per-port breakdown below is for reference (or for opening ports by hand); the ports are the code +constants (`crates/punktfunk-host/src/gamestream/mod.rs`, `mgmt.rs`) and the GameStream-host port-map +(`design/gamestream-host-plan.md`). **GameStream / Moonlight ports** (fixed; Moonlight derives them from the HTTP base). These only apply when the host runs `serve --gamestream` (the bundled unit's default); on a bare-`serve` native-only @@ -344,7 +357,7 @@ host you don't open them: default**, so you do **not** open it in the firewall unless you deliberately move it off loopback with `--mgmt-bind IP:PORT` (which also requires `--mgmt-token`). Leave it closed for a normal setup. -Open the GameStream ports with `firewalld` (Bazzite uses firewalld): +To open the GameStream ports by hand instead of the service (equivalent): ```sh sudo firewall-cmd --permanent --add-port=47984/tcp \ diff --git a/packaging/debian/README.md b/packaging/debian/README.md index 2f5a069..3cfd5c9 100644 --- a/packaging/debian/README.md +++ b/packaging/debian/README.md @@ -52,7 +52,20 @@ journalctl --user -u punktfunk-web-init | sed -n 's/.*password generated: //p' ## Firewall -Open the ports the host listens on. The **native `punktfunk/1`** plane: +**Debian ships no firewall and Ubuntu's `ufw` is installed-but-inactive by default**, so out of the +box there is nothing to open. If you run one, open the ports the host listens on. + +If you use **firewalld**, the `punktfunk-host` package installs service definitions to +`/usr/lib/firewalld/services/` (not auto-enabled), so it's one command: + +```sh +sudo firewall-cmd --reload # load the installed definition +sudo firewall-cmd --permanent --add-service=punktfunk-native # the default native host +# --add-service=punktfunk-gamestream # …add for Moonlight compat +sudo firewall-cmd --reload +``` + +Otherwise 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 diff --git a/packaging/debian/build-deb.sh b/packaging/debian/build-deb.sh index d1795bf..6de0588 100755 --- a/packaging/debian/build-deb.sh +++ b/packaging/debian/build-deb.sh @@ -80,6 +80,13 @@ install -Dm0644 scripts/host.env.example "$SHAREDIR/host.env.example" install -Dm0644 packaging/bazzite/host.env "$SHAREDIR/host.env.bazzite" install -Dm0644 packaging/kde/host.env "$SHAREDIR/host.env.kde" install -Dm0644 api/openapi.json "$SHAREDIR/openapi.json" +# firewalld service definitions (shared across all Linux packaging). NOT auto-enabled — the postinst +# only prints the enable command when firewalld is present. Debian/Ubuntu ship no active firewall +# (Ubuntu's ufw is installed-but-inactive), so these are a no-op unless the admin runs firewalld. +install -Dm0644 packaging/linux/punktfunk-gamestream.xml \ + "$STAGE/usr/lib/firewalld/services/punktfunk-gamestream.xml" +install -Dm0644 packaging/linux/punktfunk-native.xml \ + "$STAGE/usr/lib/firewalld/services/punktfunk-native.xml" install -Dm0644 LICENSE-MIT "$DOCDIR/LICENSE-MIT" install -Dm0644 LICENSE-APACHE "$DOCDIR/LICENSE-APACHE" install -Dm0644 README.md "$DOCDIR/README.md" @@ -186,6 +193,12 @@ if [ "$1" = "configure" ]; then echo " sudo usermod -aG input \"\$USER\" # then re-login" echo "Config: mkdir -p ~/.config/punktfunk && cp /usr/share/punktfunk-host/host.env.example ~/.config/punktfunk/host.env" echo "Enable: systemctl --user enable --now punktfunk-host" + # Debian/Ubuntu ship no active firewall; only hint firewalld users (ufw users: see README). + if command -v firewall-cmd >/dev/null 2>&1; then + echo "Firewall (firewalld detected): sudo firewall-cmd --reload &&" + echo " sudo firewall-cmd --permanent --add-service=punktfunk-gamestream && sudo firewall-cmd --reload" + echo " (use punktfunk-native for the native-only host)" + fi fi exit 0 EOF diff --git a/packaging/arch/punktfunk-gamestream.xml b/packaging/linux/punktfunk-gamestream.xml similarity index 84% rename from packaging/arch/punktfunk-gamestream.xml rename to packaging/linux/punktfunk-gamestream.xml index b9489aa..95bca45 100644 --- a/packaging/arch/punktfunk-gamestream.xml +++ b/packaging/linux/punktfunk-gamestream.xml @@ -4,9 +4,9 @@ Installed to /usr/lib/firewalld/services/ by the punktfunk-host package. It is NOT enabled automatically: an Arch package never touches the admin's running firewall. Stock Arch ships no - firewall (these ports are already open); on a firewalld spin such as CachyOS, enable it once with - firewall-cmd (add-service=punktfunk-gamestream, then reload). Exact commands: the packaging/arch - README, Firewall section. + firewall (these ports are already open); Fedora/RHEL and CachyOS enable firewalld by default, so + enable it once with firewall-cmd (add-service=punktfunk-gamestream, then reload). Exact commands: + your distro's install guide, or the per-distro packaging README (Firewall section). Needed only when the host runs GameStream/Moonlight compat (serve with the gamestream flag). The mgmt REST API (TCP 47990) stays on loopback by default and is deliberately not opened here. diff --git a/packaging/arch/punktfunk-native.xml b/packaging/linux/punktfunk-native.xml similarity index 76% rename from packaging/arch/punktfunk-native.xml rename to packaging/linux/punktfunk-native.xml index 880951d..d481f6f 100644 --- a/packaging/arch/punktfunk-native.xml +++ b/packaging/linux/punktfunk-native.xml @@ -4,9 +4,10 @@ punktfunk1-host subcommand). Installed to /usr/lib/firewalld/services/ by the punktfunk-host package. NOT enabled automatically - (an Arch package never touches the admin's firewall). Stock Arch has no firewall; on a firewalld - spin such as CachyOS, enable it once with firewall-cmd (add-service=punktfunk-native, then reload). - Exact commands: the packaging/arch README, Firewall section. + (packages never touch the admin's firewall). Stock Arch/Debian ship no active firewall; Fedora/RHEL + and CachyOS enable firewalld by default, so enable it once with firewall-cmd + (add-service=punktfunk-native, then reload). Exact commands: your distro's install guide, or the + per-distro packaging README (Firewall section). The media DATA plane binds an EPHEMERAL UDP port (0.0.0.0:0) chosen per session and reported to the client, so there is no fixed data port to open. On a restrictive firewall you must also allow the diff --git a/packaging/rpm/punktfunk.spec b/packaging/rpm/punktfunk.spec index b000db8..0e9af11 100644 --- a/packaging/rpm/punktfunk.spec +++ b/packaging/rpm/punktfunk.spec @@ -259,6 +259,13 @@ install -Dm0755 packaging/bazzite/kde-desktop-setup.sh %{buildroot}%{_datadir}/% install -Dm0644 packaging/bazzite/gamescope-headless-session \ %{buildroot}/etc/gamescope-session-plus/sessions.d/steam install -Dm0644 api/openapi.json %{buildroot}%{_datadir}/%{name}/openapi.json +# firewalld service definitions (shared across all Linux packaging). Fedora/RHEL enable firewalld by +# default, so these matter here; NOT auto-enabled — %post prints the enable command. Owned by the +# firewalld package's dir; we drop only the files (same pattern as the sysctl.d file above). +install -Dm0644 packaging/linux/punktfunk-gamestream.xml \ + %{buildroot}%{_prefix}/lib/firewalld/services/punktfunk-gamestream.xml +install -Dm0644 packaging/linux/punktfunk-native.xml \ + %{buildroot}%{_prefix}/lib/firewalld/services/punktfunk-native.xml %if %{with web} # --- web console subpackage (punktfunk-web) --- @@ -289,6 +296,8 @@ install -Dm0644 web/web.env.example %{buildroot}%{_datadir}/punkt %{_bindir}/punktfunk-tray %{_udevrulesdir}/60-punktfunk.rules %{_prefix}/lib/sysctl.d/99-punktfunk-net.conf +%{_prefix}/lib/firewalld/services/punktfunk-gamestream.xml +%{_prefix}/lib/firewalld/services/punktfunk-native.xml %{_userunitdir}/punktfunk-host.service %{_userunitdir}/punktfunk-kde-session.service %{_datadir}/applications/io.unom.Punktfunk.Host.desktop @@ -340,6 +349,12 @@ sysctl -p %{_prefix}/lib/sysctl.d/99-punktfunk-net.conf >/dev/null 2>&1 || : echo "punktfunk installed. Add yourself to the 'input' group (sudo usermod -aG input \$USER)" echo "then enable the host: systemctl --user enable --now punktfunk-host" echo "Config: cp %{_datadir}/%{name}/host.env.bazzite ~/.config/punktfunk/host.env" +# Fedora/RHEL run firewalld by default — point the way to the installed service definitions. +if command -v firewall-cmd >/dev/null 2>&1; then + echo "Firewall (firewalld): sudo firewall-cmd --reload &&" + echo " sudo firewall-cmd --permanent --add-service=punktfunk-gamestream && sudo firewall-cmd --reload" + echo " (use punktfunk-native for the native-only host)" +fi %if %{with web} %post web