Recommended Settings

Copy-paste ready configuration that balances bot protection with zero false positives for real MAG/STB users. These values are the defaults when you enable firewall features in the dashboard.

Quick reference

IP Rate Limiting

Scope	Req/s	Burst	Why
Global default	50	100	Covers all paths — generous for normal browsing
`/c`	20	60	Multiple MAG boxes behind NAT (~6 devices surfing). Burst covers multi-device boot storms
`/player_api.php`	20	40	Auth + channel list. Burst on app launch, then idle
`/get.php`	2	5	M3U playlist download — 50MB+ payload. Real apps fetch 1-2x/day, bots hammer it
`/xmltv.php`	1	3	EPG XML download — even larger than playlist, fetched once per day
`/panel_api.php`	5	10	Admin/reseller API — high-privilege, lock it down

MAC Protection

Setting	Value	Why
Requests/sec	3	One device channel-surfing peaks at 2-3/s
Burst	20	Portal boot fires 8-15 requests in ~2s
Max MACs per IP	25	Covers CGNAT/hotels. Bots blow past this in seconds
Window	600s (10 min)	Catches slow-drip MAC cycling bots
Ban duration	15 min	Short enough to self-heal false positives
Require MAC	off	Third-party players (TiviMate, Smarters) don't send it

Auto-Ban

Setting	Value	Why
Threshold	100	Violations in window before ban
Window	60s	1 minute sliding window
Ban duration	30 min	Longer than MAC ban — catches heavier abuse

How the layers work together

Each layer catches a different type of attack. A request passes through them in order — the first match blocks it:

Attack pattern	What catches it
100 req/s from 1 IP	IP rate limit (20/s cap on `/c`)
15 req/s, 1 IP, 1 MAC	MAC rate limit (3/s per MAC)
2 req/s, 1 IP, cycling 100 MACs	MAC-per-IP tracking (>25 unique = ban)
2 req/s, many IPs, reusing same MAC	Per-MAC rate limit (3/s total across all IPs)
Repeated rate limit violations	Auto-ban (100 hits in 60s = 30 min ban)
VPN / datacenter IP	VPN detection (blocked instantly)
Real user, 1 MAC, 1-2 req/s	Passes everything

Full JSON config

{
  "firewall": {
    "enabled": true,
    "block_vpn_proxy": true,
    "whitelist": [],
    "rate_limits": {
      "requests_per_second": 50,
      "burst": 100,
      "paths": [
        { "pattern": "/c", "requests_per_second": 20, "burst": 60 },
        { "pattern": "/player_api.php", "requests_per_second": 20, "burst": 40 },
        { "pattern": "/get.php", "requests_per_second": 2, "burst": 5 },
        { "pattern": "/xmltv.php", "requests_per_second": 1, "burst": 3 },
        { "pattern": "/panel_api.php", "requests_per_second": 5, "burst": 10 }
      ]
    },
    "auto_ban": {
      "enabled": true,
      "threshold": 100,
      "window_seconds": 60,
      "ban_duration_minutes": 30
    },
    "mac_protection": {
      "enabled": true,
      "paths": ["/c"],
      "requests_per_second": 3,
      "burst": 20,
      "max_macs_per_ip": 25,
      "mac_window_seconds": 600,
      "ban_duration_minutes": 15,
      "require_mac": false
    }
  }
}

Paths you should NOT rate limit

Some endpoints look like they need protection but actually break if you throttle them — they don't behave like normal request/response traffic.

Path	Why not
`/play`, `/live/`, `/movie/`, `/series/`, `/timeshift/`	Streaming endpoints. One stream = one long-lived connection. Rate limits do nothing — a user makes 1 request and holds it for hours.
`/hls/`, `.m3u8`, `.ts`	HLS segments. Bursty by design (4-10 segments/minute per stream). The global 50/s default handles this fine.
`/logo/`, `/picons/`, `/channel_logos/`	High volume but each file is tiny. Global default is enough.
`/images/`	Already redirected to your CDN via `image_url`.
`/health`, `/status`, `/metrics`	Internal endpoints — should be whitelisted, not rate limited.

What rate limiting cannot fix

Rate limits are one tool. Some abuse patterns look identical to legitimate traffic from the proxy's perspective and need different defenses:

Problem	Why rate limits miss it	Real solution
Account sharing	50 viewers of one paid account each make 1 request and hold it. Each looks like a normal user.	Per-username concurrent stream counter — needs session tracking, separate feature.
HLS segment scraping	Bots pulling `.ts` segments to re-encode/mirror look identical to a real player.	Token/referer validation on stream URLs — separate feature.
EPG / catalog scraping	Even at 1 req/s, a patient bot still gets the full EPG eventually.	User-Agent filtering, returning smaller catalogs to suspicious clients, or watermarking the data.
Network-layer DDoS	The proxy rate limiter only runs after the request reaches it. SYN floods exhaust upstream resources first.	Cloudflare / upstream DDoS protection — handled outside this app.
Bandwidth exhaustion via `/get.php`	Even at 2 req/s, a 50MB playlist × 2 = 100MB/s out of your bandwidth.	Smaller catalogs, CDN caching, or returning 304 Not Modified more aggressively.

These are real features worth building if abuse on those vectors becomes a problem. For most deployments, the rate limit + MAC protection + VPN detection combo above blocks 95% of bot traffic.

When to adjust

See the tuning sections in each feature's docs:

Recommended Settings

On this page