Open-source core
Configuration reference
Every setting in config.yml for the open-source core, with its default and its environment variable.
Lurcast reads one YAML file, config.yml by default (--config to change it). Unknown keys are an error, so a typo stops the server at startup instead of being ignored. If the file is missing, every setting takes its default.
Environment variables#
Most scalar settings can be overridden with an environment variable: LURCAST_ plus the setting's name in upper case, for example LURCAST_PORT or LURCAST_SOURCE_PASSWORD. Environment variables win over the file. The older ICECAST_... names still work as aliases.
- Booleans (
LURCAST_FALLBACK_OVERRIDE,LURCAST_RELAYS_ON_DEMAND,LURCAST_HLS) accept1,true,yes,0,falseorno. LURCAST_ALLOWED_ORIGINStakes a comma-separated list.LURCAST_BUFFER_SIZEis accepted as an alias forLURCAST_BURST_SIZE.
The tables below mark settings that have no environment variable with "file only".
CRYSTAL_WORKERS is not a Lurcast setting but is read at startup. Lurcast uses as many worker threads as the process has logical CPUs. Set CRYSTAL_WORKERS to a positive number to cap that, or to 1 for single-threaded operation.
Server and passwords#
| Setting | Default | Notes |
|---|---|---|
host |
0.0.0.0 |
Address to listen on. |
port |
8000 |
Plain HTTP port for listeners, sources, admin and API. |
hostname |
localhost |
Public host name, reported in admin statistics and authentication callbacks. |
public_url |
http://<hostname>:<port> |
Base URL of the server as listeners reach it, used in playlists, status output and the dashboard. Must be http or https. |
admin_email |
"" |
Contact address. Required when yp_urls is set. |
admin_password |
hackme |
Password for the admin account (admin endpoints and API). |
source_password |
hackme |
Password for sources, with username source. |
log_level |
info |
Log severity, for example debug, info, warn or error. |
allowed_origins |
["*"] |
CORS origins. |
Lurcast warns at startup while admin_password, source_password or relay_password is still hackme. Neither admin_password nor source_password may be empty.
Limits and buffering#
| Setting | Default | Notes |
|---|---|---|
max_listeners |
1000 |
Listeners across the whole server. |
max_sources |
10 |
Live sources across the whole server. |
max_connections_per_ip |
5 |
Sources, API and admin requests, and connections still sending headers, per address. |
max_listeners_per_ip |
unset (unlimited) | Listeners per address. |
burst_size |
65536 |
Bytes of audio sent to a newly connected listener. buffer_size is an older alias. |
queue_size |
524288 |
Most bytes queued for one slow listener before it is disconnected. |
metadata_interval |
8192 |
Bytes between ICY metadata blocks. |
timeout |
30 |
Seconds. Default for both timeouts below. |
header_timeout |
timeout |
Seconds a connection may take to send its headers. |
source_timeout |
timeout |
Seconds a source may stay silent before it is dropped. |
rate_limit |
100 |
New connections allowed per address in each window. |
rate_limit_window |
60 |
Window length in seconds. |
burst_size must not exceed queue_size. Listeners stop counting against max_connections_per_ip once their stream starts, so many players behind one NAT address can tune in; use max_listeners_per_ip to cap them separately. rate_limit applies to every connection.
A slow player never stalls the source: each listener has its own byte-bounded queue, and a listener that falls queue_size bytes behind is disconnected.
TLS#
| Setting | Default | Notes |
|---|---|---|
tls_port |
unset | Port for native TLS. |
tls_cert |
unset | PEM certificate chain. |
tls_key |
unset | PEM private key. |
Set all three together, or none. The certificate and key files must exist at startup.
tls_port: 8443
tls_cert: /etc/lurcast/fullchain.pem
tls_key: /etc/lurcast/privkey.pem
public_url: https://radio.example:8443
SHOUTcast sources#
| Setting | Default | Notes |
|---|---|---|
shoutcast_port |
unset | Dedicated port for SHOUTcast v1 and v2 (Ultravox) sources. |
shoutcast_mount |
/stream |
Mount for stream ID 1. |
shoutcast_mounts |
{} |
Map of stream ID to mount, for more streams. File only. |
uvox_cipher_key |
foobar |
Ultravox 2.1 cipher key, 1 to 16 bytes. |
port, tls_port and shoutcast_port must all be different. See Encoders and compatibility.
Mounts#
Per-mount settings go under mounts, keyed by mount path. Each value overrides the server-wide default only for that mount. The whole mounts block is file only.
webroot: /var/lib/lurcast
mounts:
/live:
burst_size: 32768
queue_size: 262144
metadata_interval: 16000
max_listeners: 500
max_listener_duration: 21600
fallback: /backup
fallback_override: true
fallback_when_full: true
/dj:
username: dj
password: turntable
intro: intro.mp3
/internal:
hidden: true
| Mount setting | Notes |
|---|---|
burst_size, queue_size, metadata_interval |
Override the server values for this mount. |
max_listeners |
Listeners on this mount. |
max_listener_duration |
Seconds a listener may stay connected. |
fallback |
Mount (or file in webroot) listeners move to when this source ends. |
fallback_override |
Move listeners back when this source returns. Defaults to the server-wide fallback_override. |
fallback_when_full |
Send new listeners to the fallback when this mount is full. Default false. |
username |
Source username for this mount. Defaults to source. Needs password. |
password |
Source password for this mount, replacing source_password. |
hidden |
Leave the mount off the status page (/), the status JSON, /api/v1/stations and /statistics. Default false. Admin responses still show it. |
intro |
File in webroot sent once to each new listener before the live burst. Same codec as the mount, at most 16 MiB. Needs webroot. |
record |
Record every source on this mount to recordings_dir. Default false. |
hls |
Offer this mount over HLS, overriding the server-wide hls. |
SHOUTcast v1 and Ultravox sources log in with the mount's password only.
Fallbacks#
| Setting | Default | Notes |
|---|---|---|
fallbacks |
{} |
Map of mount to fallback mount. File only. |
fallback_override |
true |
Move listeners back to the original mount when its source returns. |
webroot |
unset | Directory for fallback and intro files. Must exist. |
fallback_file_bitrate |
128 |
Bitrate in kbps used to pace fallback files. |
fallbacks:
/live: /backup
/backup: /offline.mp3
fallback_override: true
webroot: /var/lib/lurcast
When /live ends, its listeners move to /backup. If /backup has no source, they move to webroot/offline.mp3, which repeats. When the /live source returns, fallback_override moves its listeners back. An admin can change a fallback at runtime with /admin/fallbacks?mount=/live&fallback=/backup.
Relays#
Pull relays reconnect on their own. Each entry under relays (file only):
| Relay setting | Default | Notes |
|---|---|---|
url |
required | Upstream http or https URL. |
mount |
required | Local mount. Must be unique across relays. |
username, password |
unset | Upstream credentials. Set both or neither. |
retry_delay |
5 |
Seconds between reconnect attempts. |
on_demand |
false |
Connect upstream only while someone listens. |
relays:
- url: https://upstream.example/live.ogg
mount: /relay.ogg
username: relay
password: change-me-upstream
retry_delay: 5
on_demand: true
A relay keeps its upstream's icy-metaint unless the mount sets metadata_interval.
Master server#
To mirror every mount from another Icecast-compatible server, up to max_sources:
| Setting | Default | Notes |
|---|---|---|
master_url |
unset | The master server's URL. |
master_username |
relay |
Login on the master. |
master_password |
unset | Required with master_url. |
master_update_interval |
120 |
Seconds between mount list checks. |
relays_on_demand |
false |
Pull master mounts only while someone listens. |
relay_username |
relay |
Login this server offers to downstream relays. |
relay_password |
hackme |
Password this server offers to downstream relays. Must not be empty. |
External authentication#
| Setting | Default | Notes |
|---|---|---|
auth_url |
unset | URL that receives authentication callbacks. |
auth_header |
icecast-auth-user |
Response header that must be 1 to allow a request. File only. |
auth_timeout |
5 |
Seconds to wait for the callback. File only. |
Lurcast posts form-encoded stream_auth, listener_add, listener_remove, mount_add and mount_remove callbacks. A request is allowed only when the response is successful and carries auth_header with the value 1.
Directory listings (YP)#
| Setting | Default | Notes |
|---|---|---|
yp_urls |
[] |
Directory endpoints. File only. |
yp_timeout |
15 |
Seconds per directory request. File only. |
yp_touch_interval |
60 |
Seconds between directory updates. File only. |
Only sources that send Ice-Public: 1 or icy-pub: 1 are listed. admin_email is required when yp_urls is set.
hostname: radio.example
public_url: https://radio.example
admin_email: admin@radio.example
yp_urls:
- https://dir.xiph.org/cgi-bin/yp-cgi
Song history#
| Setting | Default | Notes |
|---|---|---|
song_history_size |
10 |
Songs kept per mount for /played, the status page and the dashboard. File only. |
Operations#
These are explained in Operations.
| Setting | Default | Notes |
|---|---|---|
access_log |
none | File for the access log, or - for standard output. |
trusted_proxies |
[] |
Reverse proxies (addresses or CIDR ranges) whose X-Forwarded-For gives the listener's address. File only. |
recordings_dir |
none | Directory for recordings. Needed for record and for recording from the dashboard. |
record_split_minutes |
0 |
Start a new recording file after this many minutes (MP3 and AAC). 0 keeps one file per connection. File only. |
hls |
false |
Offer MP3 and AAC mounts over HLS at /<mount>.m3u8. |
hls_segment_seconds |
6 |
Target length of each HLS segment, 1 to 30. File only. |
hls_window |
6 |
Segments in the HLS playlist, 3 to 30. File only. |
webhooks |
[] |
List of url, optional secret and optional events. File only. |
webhook_timeout |
5 |
Seconds to wait for a webhook receiver. File only. |
data_dir |
none | Where to keep the ban list and listener history across restarts. The Docker image sets /var/lib/lurcast. Needs a restart to change. |
Hosting edition#
The core accepts a hosting: section and ignores it. The Hosting edition reads it; see Install the Hosting edition.