Skip to content

feat: add PLEX_MANUAL_PORT env var for manual Remote Access port mapping - #171

Open
jonfen wants to merge 1 commit into
plexinc:masterfrom
jonfen:feat/manual-port-mapping-env
Open

feat: add PLEX_MANUAL_PORT env var for manual Remote Access port mapping#171
jonfen wants to merge 1 commit into
plexinc:masterfrom
jonfen:feat/manual-port-mapping-env

Conversation

@jonfen

@jonfen jonfen commented Jul 27, 2026

Copy link
Copy Markdown

Summary

  • Adds a PLEX_MANUAL_PORT environment variable that sets ManualPortMappingMode=1 and ManualPortMappingPort=<value> in Preferences.xml, equivalent to enabling Remote Access > Manually specify public port in the server settings.
  • Implemented in 40-plex-first-run directly alongside the existing ADVERTISE_IP / ALLOWED_NETWORKS handling, using the same setPref helper and the same first-run semantics.
  • Documents the new variable in the README parameters list, and extends the Bridge-networking note (which already explains that automatic port mapping cannot work there) to point at it.

(Note: this repository has issues disabled, so the problem report below is included here rather than as a linked issue.)

Problem

When Plex Media Server runs behind a router/firewall that does not offer UPnP/NAT-PMP (most business-grade firewalls, and effectively any Bridge-networking deployment, where the README notes the server is "essentially behind two routers"), automatic port mapping can never succeed. Unless the user manually enables Settings > Remote Access > Manually specify public port in the web UI, the server never publishes a direct WAN connection to plex.tv — even when a correct port-forward for 32400 is already in place and working.

The failure mode is silent and easy to misdiagnose: remote clients can complete their small candidate-test connections against the forwarded port, but the candidate list plex.tv serves them contains no direct WAN URI, so every remote stream falls back to the bandwidth-limited relay (~2 Mbps). Users see "speed issues" while their firewall shows the forwarded port open and passing traffic.

Confirmed on plexinc/pms-docker:latest (PMS 1.43.3): with a static DNAT for 32400 in place, /myplex/account showed mappingState="mapped" but publicPort="0", and the plex.tv resources list had only LAN, custom, and relay candidates. Setting ManualPortMappingMode=1 + ManualPortMappingPort=32400 immediately produced the https://<wan-ip-dashes>.<hash>.plex.direct:32400 candidate and remote clients switched from relayed="1" to relayed="0".

Today the only fix is a manual, non-declarative GUI step that is lost if Preferences.xml is rebuilt. The container already maps ADVERTISE_IP and ALLOWED_NETWORKS onto Preferences.xml, and this image is the deployment shape where automatic mapping is most likely to be impossible, so this belongs alongside them.

Test plan

  • Verified on a live deployment (PMS 1.43.3, bridge networking, firewall without UPnP, static 32400 DNAT): applying these two preferences flipped /myplex/account from publicPort="0" to publicPort="32400", added the direct plex.direct:32400 WAN candidate to the plex.tv resources list, and remote clients switched from relayed="1" to relayed="0".
  • Fresh-container first run with -e PLEX_MANUAL_PORT=32400 writes both attributes to a clean Preferences.xml.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant