# 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:

```bash
# 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:

```bash
# 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:

```bash
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