jellyfin-srfPlay/PROXY_SETUP_GUIDE.md

Proxy Configuration Guide for SRF Play Plugin

This guide explains how to configure the Jellyfin SRF Play plugin to route all API traffic through a proxy or alternate gateway.

Overview

The SRF Play plugin now supports proxy configuration directly in the plugin settings. This allows you to:

• Route traffic through a specific gateway or proxy server
• Use authentication if your proxy requires it
• Bypass geo-restrictions or network policies
• Route only SRF-related traffic without affecting other Jellyfin operations

Supported Proxy Types

The plugin supports:

• HTTP proxies: http://proxy.example.com:8080
• HTTPS proxies: https://proxy.example.com:8443
• SOCKS5 proxies: socks5://proxy.example.com:1080

Configuration Steps

1. Access Plugin Settings

1. Open Jellyfin Dashboard
2. Navigate to Dashboard → Plugins → SRF Play
3. Scroll down to the Proxy Settings section

2. Configure Proxy

Fill in the following fields:

Use Proxy

• Enable this checkbox to route all SRF API requests through the proxy

Proxy Address

• Enter your proxy server address with protocol and port
• Examples:
  • http://192.168.1.100:8080
  • http://proxy.example.com:3128
  • socks5://127.0.0.1:1080

Proxy Username (Optional)

• Enter username if your proxy requires authentication
• Leave empty if no authentication is needed

Proxy Password (Optional)

• Enter password if your proxy requires authentication
• Leave empty if no authentication is needed

3. Save Configuration

1. Click Save button
2. Restart Jellyfin to apply changes (recommended)

Examples

Example 1: Simple HTTP Proxy (No Authentication)

Use Proxy: ✓ Enabled
Proxy Address: http://192.168.1.1:8080
Proxy Username: (empty)
Proxy Password: (empty)

Example 2: Authenticated HTTP Proxy

Use Proxy: ✓ Enabled
Proxy Address: http://proxy.company.com:3128
Proxy Username: myusername
Proxy Password: mypassword

Example 3: SOCKS5 Proxy

Use Proxy: ✓ Enabled
Proxy Address: socks5://127.0.0.1:1080
Proxy Username: (empty)
Proxy Password: (empty)

Setting Up a Transparent Proxy Gateway on Ubuntu

If you want to create your own transparent proxy gateway on Ubuntu, here are some options:

Option A: Squid Proxy

Install and configure Squid as a transparent proxy:

# Install Squid
sudo apt update
sudo apt install squid

# Edit configuration
sudo nano /etc/squid/squid.conf

# Add these lines:
http_port 3128
acl localnet src 192.168.1.0/24
http_access allow localnet

# Restart Squid
sudo systemctl restart squid

Then in plugin settings:

Proxy Address: http://192.168.1.1:3128

Option B: SSH Tunnel (SOCKS5)

Create a SOCKS5 proxy through SSH:

# On your local machine
ssh -D 1080 -N user@remote-gateway-server

Then in plugin settings:

Proxy Address: socks5://127.0.0.1:1080

Option C: Dante SOCKS Server

Install Dante for a dedicated SOCKS5 server:

sudo apt install dante-server

# Configure in /etc/danted.conf
sudo systemctl restart danted

Troubleshooting

Plugin Not Connecting Through Proxy

1. Check proxy address format: Ensure it includes the protocol (http://, socks5://, etc.)
2. Verify proxy is running: Test connectivity to the proxy from your Jellyfin server
3. Check Jellyfin logs: Look for proxy-related errors in Dashboard → Logs
4. Firewall rules: Ensure your firewall allows outbound connections to the proxy

Authentication Errors

1. Verify username and password are correct
2. Check if your proxy requires domain authentication (DOMAIN\username)
3. Some proxies may require specific authentication methods not supported by .NET HttpClient

DNS Resolution

• The plugin resolves domain names before sending requests through the proxy
• If you need DNS resolution through the proxy, you may need to use a VPN or network-level routing instead

Affected Domains

When proxy is enabled, all requests to these domains will be routed through the proxy:

• il.srgssr.ch - SRF Integration Layer API
• www.srf.ch - SRF Play v3 API (German)
• www.rts.ch - RTS Play v3 API (French)
• www.rsi.ch - RSI Play v3 API (Italian)
• www.rtr.ch - RTR Play v3 API (Romansh)
• www.swi.ch - SWI Play v3 API (International)

Viewing Logs

To verify the proxy is being used:

1. Go to Dashboard → Logs
2. Look for entries containing "Proxy configured"
3. Example log entry:

   Proxy configured: http://192.168.1.1:8080 (Authentication: False)
   

Security Notes

• Proxy credentials are stored in Jellyfin's plugin configuration
• Use HTTPS for the proxy connection when possible to encrypt traffic
• Consider using a VPN for more secure routing if dealing with sensitive content
• Regularly update your proxy server and Jellyfin to patch security vulnerabilities

Alternative: Network-Level Routing

If you prefer network-level routing instead of application proxy, see the setup-srf-routing.sh script for IP-based routing tables (requires root access and is more complex).

Support

If you encounter issues:

1. Check Jellyfin logs for detailed error messages
2. Verify proxy connectivity with curl --proxy http://proxy:port https://il.srgssr.ch
3. Open an issue on the GitHub repository with logs and configuration details