From c2bc72a8e9deac9282ea78a79ae2b62618f47a34 Mon Sep 17 00:00:00 2001 From: enricobuehler Date: Sun, 5 Jul 2026 16:52:35 +0000 Subject: [PATCH] fix(packaging): correct CachyOS firewall to ufw + ship ufw openers + web-console opener MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CachyOS ships ufw enabled by default (firewalld is not installed) — verified live on the .21 box — but the docs and shipped firewall openers claimed "CachyOS enables firewalld by default". Correct that everywhere and ship a ufw application profile (the one-liner analogue of the firewalld service files): - packaging/linux/punktfunk.ufw (new): [punktfunk-native], [punktfunk-gamestream], [punktfunk-web] profiles, installed to /etc/ufw/applications.d/punktfunk by the Arch (CachyOS) and .deb host packages. `sudo ufw allow punktfunk-native`. - packaging/linux/punktfunk-web.xml (new): firewalld service for the optional web console (TCP 47992), installed by the host package on arch/deb/rpm. Neither the native nor gamestream opener covered 47992, so a firewalld/ufw host that enabled punktfunk-web could not reach the console over the LAN. - Fix the "CachyOS enables firewalld" claim in arch.md, arch/README.md, debian/README.md, both firewalld service .xml comments, and the pacman scriptlet; firewalld now attributed to the spins that use it (EndeavourOS, Fedora/RHEL). - Docs present both one-liners (ufw + firewalld) whichever firewall you run, plus a console-opener step; postinst/scriptlet hints detect ufw as well as firewalld. The native data plane stays hole-punched (ephemeral UDP, no fixed port) — its openers correctly open only 9777/udp + mDNS; the stale "open a UDP range" note is replaced with the accurate outbound-UDP explanation. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs-site/content/docs/arch.md | 40 +++++++++----- packaging/arch/PKGBUILD | 16 ++++-- packaging/arch/README.md | 66 ++++++++++++++---------- packaging/arch/punktfunk-host.install | 21 +++++--- packaging/debian/README.md | 32 +++++++----- packaging/debian/build-deb.sh | 21 +++++--- packaging/linux/punktfunk-gamestream.xml | 7 +-- packaging/linux/punktfunk-native.xml | 5 +- packaging/linux/punktfunk-web.xml | 20 +++++++ packaging/linux/punktfunk.ufw | 38 ++++++++++++++ packaging/rpm/punktfunk.spec | 4 ++ 11 files changed, 197 insertions(+), 73 deletions(-) create mode 100644 packaging/linux/punktfunk-web.xml create mode 100644 packaging/linux/punktfunk.ufw diff --git a/docs-site/content/docs/arch.md b/docs-site/content/docs/arch.md index 11c8b11..a8a0497 100644 --- a/docs-site/content/docs/arch.md +++ b/docs-site/content/docs/arch.md @@ -109,28 +109,40 @@ To set your own, edit that file and `systemctl --user restart punktfunk-web`. Fo ## 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. +enables `ufw` by default** (firewalld is not installed), and some other spins (e.g. EndeavourOS) +enable **`firewalld`** — an Arch package never opens ports for you, so on those 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: +The `punktfunk-host` package installs openers for **both**, so it's a one-liner whichever you run: ```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 +# ufw — CachyOS (and Ubuntu, once you enable ufw): +sudo ufw allow punktfunk-native # the secure native host (the default) +sudo ufw allow punktfunk-gamestream # …also this if you run `serve --gamestream` (Moonlight) + +# firewalld — Fedora-like spins (EndeavourOS, …): +sudo firewall-cmd --reload # load the installed definition +sudo firewall-cmd --permanent --add-service=punktfunk-native 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. +The media **data plane** uses an *ephemeral* UDP port that the client opens with a hole-punch — the +host streams back out through the path the client opened, so there's **nothing fixed to open** as +long as the firewall allows outbound UDP (the default for both ufw and firewalld). + +Enabled the **web console** (`punktfunk-web`, above) and want to reach it from your phone or another +machine? It's not opened by the streaming rules — open its port too, the same one-liner way: + +```sh +sudo ufw allow punktfunk-web # ufw +sudo firewall-cmd --permanent --add-service=punktfunk-web && sudo firewall-cmd --reload # firewalld +``` + +That opens **TCP 47992** (HTTPS, login-gated). The mgmt API (47990) stays loopback-only and is never +opened. Full port lists (`nftables`, explicit ports) are in +[`packaging/arch/README.md`](https://git.unom.io/unom/punktfunk/src/branch/main/packaging/arch/README.md#firewall). ## 6. Connect a client diff --git a/packaging/arch/PKGBUILD b/packaging/arch/PKGBUILD index 75ae477..d26cfc5 100644 --- a/packaging/arch/PKGBUILD +++ b/packaging/arch/PKGBUILD @@ -134,14 +134,22 @@ 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. + # Firewall openers — NOT auto-enabled (an Arch package never touches the admin's running firewall). + # Stock Arch ships no firewall; CachyOS ships ufw; some spins (EndeavourOS) enable firewalld — so we + # install BOTH a ufw application profile and firewalld service definitions, and the one for whatever + # firewall you actually run is a one-liner. See README.md → Firewall. + # ufw: sudo ufw allow punktfunk-native (or punktfunk-gamestream) + # firewalld: sudo firewall-cmd --reload && sudo firewall-cmd --permanent --add-service=punktfunk-native && sudo firewall-cmd --reload + install -Dm0644 "$R/packaging/linux/punktfunk.ufw" \ + "$pkgdir/etc/ufw/applications.d/punktfunk" install -Dm0644 "$R/packaging/linux/punktfunk-gamestream.xml" \ "$pkgdir/usr/lib/firewalld/services/punktfunk-gamestream.xml" install -Dm0644 "$R/packaging/linux/punktfunk-native.xml" \ "$pkgdir/usr/lib/firewalld/services/punktfunk-native.xml" + # Web console opener (TCP 47992) — only meaningful with the optional punktfunk-web package; opened + # deliberately (see README.md → Firewall). ufw's equivalent is the punktfunk-web profile above. + install -Dm0644 "$R/packaging/linux/punktfunk-web.xml" \ + "$pkgdir/usr/lib/firewalld/services/punktfunk-web.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" diff --git a/packaging/arch/README.md b/packaging/arch/README.md index fd6d549..eadb6b5 100644 --- a/packaging/arch/README.md +++ b/packaging/arch/README.md @@ -139,33 +139,45 @@ so it's a much lighter sysext than the host. **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. +admin's running firewall. **CachyOS is the common case** — it ships `ufw` enabled by default (not +firewalld), so out of the box the host is unreachable until you allow it. Some other spins (e.g. +EndeavourOS) enable `firewalld` instead. -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: +The `punktfunk-host` package ships openers for **both** — a ufw application profile +(`/etc/ufw/applications.d/punktfunk`) and firewalld service definitions +(`/usr/lib/firewalld/services/`) — so enabling is one command whichever you run: ```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 +# ufw (CachyOS, and Ubuntu once you enable ufw) — reads the profile at once, no reload needed: +sudo ufw allow punktfunk-native # the native-only host (the default) +sudo ufw allow punktfunk-gamestream # …or add this for the Moonlight/GameStream host + +# firewalld (EndeavourOS and other Fedora-like spins): +sudo firewall-cmd --reload # pick up the installed def +sudo firewall-cmd --permanent --add-service=punktfunk-native +# --add-service=punktfunk-gamestream # …for the Moonlight 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`). +both planes). The **data plane is an *ephemeral* UDP port** the client opens with a hole-punch, so +there is no fixed data port in either service — the host streams back out through the path the +client opened, which any firewall that allows outbound UDP (the default) passes. 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: +If you installed the **web console** (`punktfunk-web`) and want it reachable from another device, +open its port with the matching one-liner — `sudo ufw allow punktfunk-web` or `sudo firewall-cmd +--permanent --add-service=punktfunk-web && sudo firewall-cmd --reload` — which opens **TCP 47992** +(HTTPS, login-gated). The mgmt API (47990) stays loopback-only. + +Prefer explicit rules (or a firewall the shipped profiles don't cover)? 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 - open. For a restrictive firewall you'd need to allow a UDP range (the repo does not pin one). +- **Data plane: an *ephemeral* UDP port** the client hole-punches — nothing to open inbound as long + as outbound UDP is allowed (the host streams back out through the client-opened path). And the **GameStream / Moonlight** ports (fixed) — only needed if you run the host with `serve --gamestream` (opt-in, trusted LAN only); bare `serve` is native-only and doesn't open these: @@ -181,14 +193,14 @@ And the **GameStream / Moonlight** ports (fixed) — only needed if you run the The mgmt 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`). -With `ufw`: +With `ufw` (explicit ports, instead of the shipped `punktfunk-native`/`punktfunk-gamestream` profile): ```sh sudo ufw allow 9777/udp # punktfunk/1 control plane sudo ufw allow 47984/tcp && sudo ufw allow 47989/tcp && sudo ufw allow 48010/tcp -sudo ufw allow 47998:48010/udp -sudo ufw allow 5353/udp -# plus the ephemeral punktfunk/1 data port — open a UDP range you reserve for it. +sudo ufw allow 47998,47999,48000/udp # GameStream video/control/audio +sudo ufw allow 5353/udp # mDNS discovery +# The punktfunk/1 data plane is an ephemeral UDP port the host hole-punches — nothing to open here. ``` With raw `nftables` (add to your `inet filter input` chain): @@ -196,18 +208,20 @@ With raw `nftables` (add to your `inet filter input` chain): ``` udp dport 9777 accept # punktfunk/1 control plane tcp dport { 47984, 47989, 48010 } accept -udp dport { 47998-48010, 5353 } accept -# plus the ephemeral punktfunk/1 data port (a reserved UDP range). +udp dport { 47998-48000, 5353 } accept # GameStream video/control/audio + mDNS +# The punktfunk/1 data plane is an ephemeral UDP port the host hole-punches — a stateful chain that +# accepts ct state established,related (as this one should) passes the return with nothing extra. ``` ## Files - `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, incl. the firewalld enable command when firewalld is present), mirror the RPM + first-run hint, incl. the ufw/firewalld enable command for whichever is present), mirror the RPM `%post` / deb postinst. -- 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). +- The firewall openers are shared across all Linux packaging and live in [`../linux/`](../linux/): + the ufw application profile (`punktfunk.ufw` → `/etc/ufw/applications.d/punktfunk`) and the + firewalld service definitions (`punktfunk-native.xml` / `punktfunk-gamestream.xml` / + `punktfunk-web.xml` → `/usr/lib/firewalld/services/`). None 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-host.install b/packaging/arch/punktfunk-host.install index 3277160..ba7883d 100644 --- a/packaging/arch/punktfunk-host.install +++ b/packaging/arch/punktfunk-host.install @@ -17,15 +17,24 @@ 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. + # Firewall: stock Arch ships none (ports already open); CachyOS ships ufw; some spins (EndeavourOS) + # enable firewalld. We install a ufw app profile AND firewalld service definitions but never touch + # the running firewall — just point the way for whichever is active. + if command -v ufw >/dev/null 2>&1; then + cat <<'MSG' + + 4. ufw is installed — open the streaming ports once (native-only host shown; add + 'punktfunk-gamestream' as well for Moonlight compat): + sudo ufw allow punktfunk-native +MSG + fi 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 + 4. firewalld is active — open the streaming ports once (native-only host shown; add + 'punktfunk-gamestream' as well for Moonlight compat): + sudo firewall-cmd --reload # load the new service def + sudo firewall-cmd --permanent --add-service=punktfunk-native sudo firewall-cmd --reload MSG fi diff --git a/packaging/debian/README.md b/packaging/debian/README.md index 3cfd5c9..b69b284 100644 --- a/packaging/debian/README.md +++ b/packaging/debian/README.md @@ -53,23 +53,31 @@ journalctl --user -u punktfunk-web-init | sed -n 's/.*password generated: //p' ## Firewall **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: +box there is nothing to open. If you turn one on, the `punktfunk-host` package ships a one-liner +opener for both **ufw** and **firewalld** (neither auto-enabled): ```sh +# ufw (Ubuntu) — profile at /etc/ufw/applications.d/punktfunk, read at once (no reload): +sudo ufw allow punktfunk-native # the default native host +sudo ufw allow punktfunk-gamestream # …add for Moonlight compat + +# firewalld — service definitions at /usr/lib/firewalld/services/: sudo firewall-cmd --reload # load the installed definition -sudo firewall-cmd --permanent --add-service=punktfunk-native # the default native host +sudo firewall-cmd --permanent --add-service=punktfunk-native # --add-service=punktfunk-gamestream # …add for Moonlight compat sudo firewall-cmd --reload ``` -Otherwise open the ports directly. The **native `punktfunk/1`** plane: +If you installed the **web console** (`punktfunk-web`) and want it reachable from another device, +open its port with the matching one-liner — `sudo ufw allow punktfunk-web` or `sudo firewall-cmd +--permanent --add-service=punktfunk-web && sudo firewall-cmd --reload` — which opens **TCP 47992** +(HTTPS, login-gated). The mgmt API (47990) stays loopback-only. + +Prefer explicit rules? 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 - open. For a restrictive firewall you'd need to allow a UDP range (the repo does not pin one). +- **Data plane: an *ephemeral* UDP port** the client hole-punches — nothing to open inbound as long + as outbound UDP is allowed (the host streams back out through the client-opened path). And the **GameStream / Moonlight** ports (fixed) — only needed if you run the host with `serve --gamestream` (opt-in, trusted LAN only); bare `serve` is native-only and doesn't open these: @@ -85,14 +93,14 @@ And the **GameStream / Moonlight** ports (fixed) — only needed if you run the The mgmt 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`). -With `ufw`: +With `ufw` (explicit ports, instead of the shipped profile): ```sh sudo ufw allow 9777/udp # punktfunk/1 control plane sudo ufw allow 47984/tcp && sudo ufw allow 47989/tcp && sudo ufw allow 48010/tcp -sudo ufw allow 47998:48010/udp -sudo ufw allow 5353/udp -# plus the ephemeral punktfunk/1 data port — open a UDP range you reserve for it. +sudo ufw allow 47998,47999,48000/udp # GameStream video/control/audio +sudo ufw allow 5353/udp # mDNS discovery +# The punktfunk/1 data plane is an ephemeral UDP port the host hole-punches — nothing to open here. ``` With raw `nftables` (add to your `inet filter input` chain): diff --git a/packaging/debian/build-deb.sh b/packaging/debian/build-deb.sh index 6de0588..61a34d0 100755 --- a/packaging/debian/build-deb.sh +++ b/packaging/debian/build-deb.sh @@ -80,13 +80,19 @@ 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. +# Firewall openers (shared across all Linux packaging), NOT auto-enabled — the postinst prints the +# enable command for whichever firewall is present. Debian ships none and Ubuntu's ufw is +# installed-but-inactive, so these are a no-op until the admin turns a firewall on. +install -Dm0644 packaging/linux/punktfunk.ufw \ + "$STAGE/etc/ufw/applications.d/punktfunk" 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" +# Web console opener (TCP 47992) — only meaningful with the optional punktfunk-web package; opened +# deliberately (see README.md → Firewall). ufw's equivalent is the punktfunk-web profile above. +install -Dm0644 packaging/linux/punktfunk-web.xml \ + "$STAGE/usr/lib/firewalld/services/punktfunk-web.xml" install -Dm0644 LICENSE-MIT "$DOCDIR/LICENSE-MIT" install -Dm0644 LICENSE-APACHE "$DOCDIR/LICENSE-APACHE" install -Dm0644 README.md "$DOCDIR/README.md" @@ -193,11 +199,14 @@ 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). + # Debian ships no active firewall and Ubuntu's ufw is inactive by default; hint whichever is present. + if command -v ufw >/dev/null 2>&1; then + echo "Firewall (ufw detected): sudo ufw allow punktfunk-native (or punktfunk-gamestream for Moonlight)" + fi 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)" + echo " sudo firewall-cmd --permanent --add-service=punktfunk-native && sudo firewall-cmd --reload" + echo " (use punktfunk-gamestream for the Moonlight-compat host)" fi fi exit 0 diff --git a/packaging/linux/punktfunk-gamestream.xml b/packaging/linux/punktfunk-gamestream.xml index 95bca45..0c82d9c 100644 --- a/packaging/linux/punktfunk-gamestream.xml +++ b/packaging/linux/punktfunk-gamestream.xml @@ -4,9 +4,10 @@ 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); 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). + firewall (these ports are already open); Fedora/RHEL and some Arch spins (EndeavourOS) enable + firewalld by default, so enable it once with firewall-cmd (add-service=punktfunk-gamestream, then + reload). CachyOS and Ubuntu use ufw instead — the package also ships a ufw application profile + (punktfunk.ufw). Exact commands: your distro's install guide, or the per-distro packaging README. 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/linux/punktfunk-native.xml b/packaging/linux/punktfunk-native.xml index d481f6f..5709fd6 100644 --- a/packaging/linux/punktfunk-native.xml +++ b/packaging/linux/punktfunk-native.xml @@ -5,8 +5,9 @@ Installed to /usr/lib/firewalld/services/ by the punktfunk-host package. NOT enabled automatically (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 + and some Arch spins (EndeavourOS) enable firewalld by default, so enable it once with firewall-cmd + (add-service=punktfunk-native, then reload). CachyOS and Ubuntu use ufw instead — the package also + ships a ufw application profile (punktfunk.ufw). 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 diff --git a/packaging/linux/punktfunk-web.xml b/packaging/linux/punktfunk-web.xml new file mode 100644 index 0000000..6e9cc08 --- /dev/null +++ b/packaging/linux/punktfunk-web.xml @@ -0,0 +1,20 @@ + + + + Punktfunk web console + The optional punktfunk management web console (device pairing, status, GPU selection, performance graphs) over HTTPS. Open only if you run the punktfunk-web package and want the console reachable from other devices on the LAN. + + diff --git a/packaging/linux/punktfunk.ufw b/packaging/linux/punktfunk.ufw new file mode 100644 index 0000000..73804cc --- /dev/null +++ b/packaging/linux/punktfunk.ufw @@ -0,0 +1,38 @@ +# ufw application profile for the punktfunk host — installed to +# /etc/ufw/applications.d/punktfunk by the .deb and the Arch/CachyOS package. +# +# This is the ufw analogue of the firewalld service definitions +# (punktfunk-native.xml / punktfunk-gamestream.xml): it turns opening the host's +# ports into a one-liner on the distros that use ufw instead of firewalld +# (CachyOS ships ufw enabled; Debian/Ubuntu ship it installed-but-inactive). ufw +# reads this directory on every command, so no reload is needed after the +# package drops the file — just: +# +# sudo ufw allow punktfunk-native # the secure native punktfunk/1 host (the default) +# sudo ufw allow punktfunk-gamestream # add GameStream/Moonlight compat (opt-in) +# sudo ufw allow punktfunk-web # reach the web console from the LAN (if punktfunk-web is installed) +# sudo ufw app info punktfunk-native # show what a profile opens +# +# Same port map as the firewalld services. The punktfunk/1 DATA plane is an +# ephemeral UDP port chosen per session and is NOT listed here: the host +# hole-punches, so a deny-inbound firewall still works (it just adds ~2.5 s at +# session start). To open a fixed one instead, run the host with +# `serve --data-port 9778` and `sudo ufw allow 9778/udp`. + +[punktfunk-native] +title=punktfunk host (native punktfunk/1) +description=punktfunk/1 native streaming: QUIC control plane + mDNS auto-discovery +ports=9777/udp|5353/udp + +[punktfunk-gamestream] +title=punktfunk host (GameStream/Moonlight) +description=GameStream/Moonlight compatibility ports (opt-in, trusted LAN only) +ports=47984,47989,48010/tcp|47998:48010/udp|5353/udp + +# The optional web console (the separate punktfunk-web package). Open only if you installed it and +# want to reach it from another device — it binds all interfaces on TCP 47992 (HTTPS, login-gated). +# The mgmt API (47990) is loopback-only and is deliberately not covered here. +[punktfunk-web] +title=punktfunk web console +description=The optional punktfunk management web console (HTTPS, login-gated) reachable from the LAN +ports=47992/tcp diff --git a/packaging/rpm/punktfunk.spec b/packaging/rpm/punktfunk.spec index 0e9af11..7ac03fd 100644 --- a/packaging/rpm/punktfunk.spec +++ b/packaging/rpm/punktfunk.spec @@ -266,6 +266,9 @@ 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 +# Web console opener (TCP 47992) — only meaningful with the web subpackage, opened deliberately. +install -Dm0644 packaging/linux/punktfunk-web.xml \ + %{buildroot}%{_prefix}/lib/firewalld/services/punktfunk-web.xml %if %{with web} # --- web console subpackage (punktfunk-web) --- @@ -298,6 +301,7 @@ install -Dm0644 web/web.env.example %{buildroot}%{_datadir}/punkt %{_prefix}/lib/sysctl.d/99-punktfunk-net.conf %{_prefix}/lib/firewalld/services/punktfunk-gamestream.xml %{_prefix}/lib/firewalld/services/punktfunk-native.xml +%{_prefix}/lib/firewalld/services/punktfunk-web.xml %{_userunitdir}/punktfunk-host.service %{_userunitdir}/punktfunk-kde-session.service %{_datadir}/applications/io.unom.Punktfunk.Host.desktop