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) accept 1, true, yes, 0, false or no.
  • LURCAST_ALLOWED_ORIGINS takes a comma-separated list.
  • LURCAST_BUFFER_SIZE is accepted as an alias for LURCAST_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.