Icecast KH configuration reference

The tables group KH settings by where they are used. They follow the supplied documentation and the pinned source code. A slash shows the path to a setting; @ marks an attribute. Do not include these characters in XML element names.

Apply a setting in the right place

Keep one outer <icecast> root. An instance-wide limit, mount override and relay origin are separate contexts even when names resemble one another. The supplied full configuration is an example, not a set of universal defaults. Replace credentials and paths before use.

Check XML syntax, then verify parser acceptance and the resulting request behaviour on the exact binary. A well-formed document can still contain a misspelled option. In particular, documentation and implementation disagree about a few names, which are marked below.

Instance and network

Parameter	Role and boundary
`hostname`	Public name for generated stream URLs; not a bind address.
`location / admin`	Intentionally public descriptive/contact strings.
`listen-socket/port / bind-address`	Local port and interface; verify external reachability separately.
`listen-socket/ssl`	Enable socket TLS when compiled with support.
`listen-socket/shoutcast-mount`	Compatibility source mount with related source-port handling.
`http-headers/header`	Name/value response fields; review CORS and information exposure.

Limits and queues

Parameter	Role and boundary
`limits/clients / sources`	Instance-wide concurrent client and source limits.
`limits/queue-size`	Maximum media queue; KH supports documented sizing forms.
`limits/burst-size / min-queue-size`	Initial burst and retained minimum; compare the maximum.
`limits/header-timeout / source-timeout`	Timeouts in seconds for headers and missing source data.
`limits/client-timeout`	Legacy configuration knob; do not infer a modern idle policy.
`limits/workers`	KH worker count; measure before changing it.

Exact and patterned mounts

Parameter	Role and boundary
`mount/mount-name`	Exact path or supported wildcard pattern.
`mount/priority`	Lower numeric value wins among applicable patterns; exact match first.
`username / password`	Mount-specific source credentials.
`max-listeners`	Concurrent listener limit for the chosen mount.
`max-listener-duration`	Listener session duration in seconds.
`queue-size / burst-size / min-queue-size`	Mount buffering overrides; byte and time forms need rate context.
`source-timeout`	Mount-specific seconds without source data.
`fallback-mount`	Backup destination; optional rate attribute for supported file fallback.
`fallback-override / fallback-when-full`	Return-to-source policy and full-mount routing.
`hijack`	Explicit source takeover permission; protect source credentials.
`linger-for`	Seconds to retain source state after disconnect in supported flow.
`intro / dump-file`	Intro media and optional incoming recording; plan format and disk access.
`public / hidden`	Directory/list visibility controls, not listener authentication.
`stream-name / stream-description / stream-url / genre`	Published descriptors; these do not change media encoding.
`metadata-interval / mp3-metadata-interval`	KH names for ICY metadata interval in bytes.
`allow-url-ogg-metadata`	Hyphenated parser name; do not copy the manual underscore typo.
`skip-accesslog`	Suppress this mount in the access log; reduces diagnostic evidence.

Authentication

Parameter	Role and boundary
`authentication/source-password`	Global source secret; mount rules may override it.
`authentication/admin-user / admin-password`	Separate management credentials.
`authentication/relay-user / relay-password`	Credentials for permitted relay discovery.
`mount/authentication/@type`	Classic htpasswd or URL backend; not 2.5 role XML.
`option filename / allow_duplicate_users`	Private htpasswd file and duplicate-account concurrency switch.
`option listener_add / listener_remove`	KH admission and departure callback URLs.
`option stream_auth / mount_add / mount_remove`	Source authorization and mount lifecycle callbacks.
`option auth_header / timelimit_header`	Response header contracts, not arbitrary successful status codes.
`option headers / header_prefix`	Forward selected request fields; singular header_prefix is implemented.

Relay origins and discovery

Parameter	Role and boundary
`relay/local-mount`	Stable local public mount independent of origin path.
`relay/host/server / port / mount`	Origin coordinates inside each host candidate.
`relay/host/priority`	Order candidates; lower configured values have higher priority.
`relay/username / password`	Upstream credentials where required.
`relay/on-demand`	Fetch according to demand; test first-listener latency.
`relay/retry-delay`	Seconds between relay retry attempts.
`relay/relay-shoutcast-metadata`	Request ICY metadata from a compatible origin.
`master-server / master-server-port / master-password`	Global master discovery coordinates and credential.
`master-update-interval / relays-on-demand`	Discovery interval in seconds and global demand policy.
`master-redirect / max-redirect-slaves`	Optional redirect policy; redirects are not moving an existing TCP stream.

Files, TLS, directories and logs

Parameter	Role and boundary
`paths/basedir / webroot / adminroot / logdir`	Separate base, public files, admin stylesheets and logs.
`paths/pidfile / mime-types`	Process-ID file and media-type mappings.
`paths/alias @source / @dest`	KH alias attributes; 2.5 destination is a different contract.
`paths/ssl-certificate / ssl-private-key`	Certificate chain and private key in the classic KH layout.
`logging/accesslog / errorlog / playlistlog`	Request, diagnostic and metadata logs.
`logging/loglevel`	Classic numeric level; 3 informational, 4 debug.
`logging/logsize / logarchive`	Classic rotation size in kilobytes and archiving behaviour.
`directory/yp-url / yp-url-timeout`	Directory endpoint and timeout in seconds.
`security/chroot / changeowner`	Filesystem isolation and supported user/group change.

Follow the relevant operating procedure

Use the guides for mount priority, multiple origins, URL admission and TLS. They explain prerequisites, fragments and failure cases. Configuration review does not replace a source/listener test or a rollback exercise.