Network Configuration (Hub Admin Guide)

Guide for hub administrators configuring network settings for Phlix server deployments.

Port Forwarding

Phlix Media Server supports automatic port forwarding via UPnP-IGD and NAT-PMP to enable direct client connections without relay tunnel.

Enabling Automatic Port Forwarding

In config/port-forward.php:

<?php
return [
    'port_forwarding' => [
        'auto' => true,         // Set to false to disable
        'port' => 8096,        // Must match server.port in config/server.php
        'upnp_enabled' => true, // Set to false to skip UPnP
    ],
];

Or via environment variables:

PHLIX_PORT_FORWARD_AUTO=1
PHLIX_EXTERNAL_PORT=8096
PHLIX_UPNP_ENABLED=1

The shipped default does not match the port the server listens on

config/port-forward.php defaults port to 32400 (PHLIX_EXTERNAL_PORT), and PortForwardService uses that single value as both the external and the internal port of the mapping — the router is told to forward WAN 32400 to <server-lan-ip>:32400. phlix-server listens on 8096 (config/server.php server.port, which has no environment override).

Left at the defaults, the mapping therefore points at a port nothing is bound to, direct access fails, and the hostname candidates the server advertises to the Hub (http://<lan-ip>:32400, http://phlix.local:32400, …) are unreachable. Set port / PHLIX_EXTERNAL_PORT to the server's actual listen port, as shown above.

Checking Server Connectivity

To verify a server's network accessibility:

php scripts/port-forward.php status
php scripts/port-forward.php info

These commands show:

• Current port forwarding status
• Local and public IP addresses
• Port accessibility (open/filtered/blocked)
• UPnP IGD discovery result
• Hostname candidates for client connections

Relay Tunnel as Fallback

When automatic port forwarding fails or is unavailable, the relay tunnel provides connectivity:

PHLIX_RELAY_ENABLED=1
PHLIX_RELAY_HUB_URL=wss://hub.example.com/api/v1/servers/{id}/relay

See docs/dev/relay-protocol.md for relay tunnel protocol details.

Network Requirements

Outbound

Destination	Port	Protocol	Purpose
stun.l.google.com	19302	UDP	STUN public IP discovery
Your Phlix Hub URL	443	TCP	Hub heartbeat and relay

Inbound

Port	Protocol	Purpose
8096	TCP	Media streaming and web portal (direct access) — server.port, and the value port_forwarding.port must be set to
8097	TCP	SyncPlay WebSocket (only if clients connect to SyncPlay directly rather than through the Hub relay)

Firewall Configuration

If your server is behind a firewall, ensure:

1. Inbound TCP 8096 — Media streaming and web portal access (or whatever server.port is set to on that host)
2. Outbound UDP 19302 — STUN binding requests
3. Outbound TCP 443 — Hub API and relay tunnel

UFW Example

ufw allow 8096/tcp comment 'Phlix Media Server'
ufw allow out 19302/udp comment 'STUN'
ufw allow out 443/tcp comment 'Phlix Hub'

firewalld Example

firewall-cmd --permanent --add-port=8096/tcp
firewall-cmd --permanent --add-port=19302/udp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --reload

Multi-Server Setups

Each server instance requires its own port forwarding rule and unique external port. Because the external and internal ports of the mapping are the same value, each instance must also listen on that port — change server.port in that instance's config/server.php to match:

// Server 1 — config/server.php 'port' => 8096
'port_forwarding' => ['port' => 8096]

// Server 2 — config/server.php 'port' => 8098
'port_forwarding' => ['port' => 8098]

(8097 is taken by the SyncPlay WebSocket worker.)

Clients connect to http://<server-public-ip>:<port> directly.

See Also

• docs/hub/remote-access.md — End-user guide for setting up direct access
• docs/dev/relay-protocol.md — Relay tunnel protocol reference
• php scripts/port-forward.php help — Port forwarding CLI commands