Limit who can listen
By default anyone can play your streams. Narrow that with rules on IP address, country and player (User-Agent). Rules are optional, are checked before a listener connects, and never affect encoders (they have a separate rule set). A refused listener gets a plain 403 Forbidden that never says which rule matched.
How rules combine
- A listener must pass every category you configure: IP, User-Agent and country.
- A deny rule always wins over an allow rule.
- A non-empty allow list means "only these". An empty list means "no restriction".
- Global rules (
[access]) and per-mount rules ([mounts.access]) both apply. A mount can only add restrictions, never relax the global ones.
Block addresses
[access]
ip_deny = ["203.0.113.0/24", "198.51.100.7", "2001:db8:dead::/48"]Entries can be single addresses or CIDR ranges, IPv4 or IPv6.
Long blocklists in a file
Keep a growing list out of your config. Put one address or range per line:
# Scrapers
203.0.113.0/24
198.51.100.7
# A noisy network
2001:db8:dead::/48[access]
ip_deny_file = "lists/blocked.txt"Blank lines and # comments are ignored. Edit the file, then send the server a reload (kill -HUP) to apply it without a restart. You can combine inline entries and a file; the limit is 10,000 distinct rules together.
An empty allow file is an error
ip_allow_file with no rules would mean "allow everyone", so Quikcast refuses to start (or reload) instead of silently opening the stream. An empty ip_deny_file is fine.
Allow only certain countries
[access]
countries_allow = ["GH", "NG"]Use two-letter ISO country codes. countries_deny works the same way in reverse. A country database is built into Quikcast, so this works with no extra setup. Addresses whose country is unknown (for example private network addresses) fail an allow list but pass a deny list.
Testing from your own machine
127.0.0.1 and other private addresses have no country, so they are refused by countries_allow. Test from a real network, or temporarily use an IP rule instead.
To use your own MaxMind-format database instead of the built-in one:
[access]
geoip_database = "/etc/quikcast/GeoLite2-Country.mmdb"Allow or block certain players
[access]
user_agent_deny = ["substring:python-requests", "prefix:curl/"]
user_agent_allow = []Rules start with how to match: exact:, prefix: or substring:, followed by the text. Matching is case-sensitive.
User-Agent is easy to fake
Use it to keep out known bad tools, not as security. Anyone can change what their player says it is.
Block whole networks
Hosting providers and scrapers change addresses constantly but stay in one network. Block them by ASN (autonomous system number) using the ASN database built into Quikcast:
[access]
asns_deny = [16509, 14061]asns_allow works in reverse, and a mount can add its own lists. The built-in database is a snapshot refreshed with each release. For fresher data, or your own, point asn_database at a MaxMind-format file with autonomous_system_number records, such as GeoLite2-ASN; it replaces the built-in one. Unknown and private addresses pass a deny list and fail an allow list.
Limit connections per address
One address can otherwise hold as many listener slots as it likes. Cap it:
[access]
listeners_per_ip = 4 # across every mount
[mounts.access]
listeners_per_ip = 1 # on this mountExtra connections get 429 Too Many Requests. IPv6 addresses share one budget per /64. This needs correct proxy settings or every listener looks like the proxy. It applies to continuous streams, not HLS.
Ban an address while it is running
For an abuser you want gone now, without editing a file or reloading, use the management API: POST /api/bans?ip=203.0.113.7&ttl_seconds=3600&kick=true refuses the address and disconnects its listeners. Bans expire by themselves, are held in memory, and are lost on restart. For a permanent block use ip_deny_file.
Different rules per stream
Put the same fields under a mount:
[[mounts]]
path = "/members.mp3"
secret_file = "secrets/members-source"
[mounts.access]
ip_allow = ["10.0.0.0/8", "192.168.0.0/16"]This stream is only reachable from the private network, while other mounts stay public (subject to any global rules).
Limit who can broadcast
Separately from listeners, you can restrict which addresses may connect an encoder to a mount. The password is still required.
[[mounts]]
path = "/radio.mp3"
secret_file = "secrets/radio-source"
[mounts.source_access]
ip_allow = ["203.0.113.10"]source_access accepts only IP lists (ip_allow, ip_allow_file, ip_deny, ip_deny_file).
Behind a proxy? Tell Quikcast
Rules look at the listener's address. Behind a proxy that is the proxy's address, so rules would hit the wrong machine. Configure trusted_proxies as described in HTTPS and proxies.
Check what is applied
With [management] enabled, /api/server and /api/mounts show the active rule counts, and the metrics include counters for each kind of denial (see Metrics). For a closer look, set log_filter = "quikcast=debug" to log the reason for each rejection.