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 ​

toml
[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:

text
# Scrapers
203.0.113.0/24
198.51.100.7

# A noisy network
2001:db8:dead::/48
toml
[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 ​

toml
[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:

toml
[access]
geoip_database = "/etc/quikcast/GeoLite2-Country.mmdb"

Allow or block certain players ​

toml
[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:

toml
[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:

toml
[access]
listeners_per_ip = 4        # across every mount

[mounts.access]
listeners_per_ip = 1        # on this mount

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

toml
[[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.

toml
[[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.