Configuration reference by operational task

The tables group settings by task. They follow the configuration files, manual and source code shipped with Icecast 2.5.0. Older syntax is labelled. Check your installed version before applying a setting.

Read scope before copying a value

The outer root is <icecast>. Rows containing a slash identify nesting, not literal XML element names. Some names occur at more than one scope: a mount’s listener limit is not the instance-wide client limit, and a relay’s remote mount is not its local public path. Value types and defaults must be checked against the selected release; examples are not defaults.

Back up the working file. Change only the setting needed for the task, validate the XML and read startup/reload messages. Use the linked guides for complete context, prerequisites and behavioural checks.

Server identity

Parameter	Role and boundary
`hostname`	Host name used in generated URLs and publication, not a bind address.
`location`	Display text describing the instance; supply only intentional information.
`admin`	Technical contact string; directory publication can require a real contact.
`fileserve`	Enables serving webroot files; status-page assets can depend on it.
`server-id`	Overrides identification; usually leave the version-derived default intact.

Global limits and buffering

Parameter	Role and boundary
`limits/clients`	Concurrent clients, including listeners and other HTTP uses.
`limits/sources`	Active sources, including active relays in the documented model.
`queue-size`	Stream queue limit in bytes; can also be mount-specific.
`burst-size`	Initial bytes offered to a new listener; keep below the queue.
`header-timeout`	Seconds permitted for receiving an incoming request header.
`source-timeout`	Seconds without source data before the source is removed.
`client-timeout`	Described as unused by the supplied manual; do not tune blindly.
`burst-on-connect`	Deprecated control; use the documented burst-size setting instead.
`threadpool`	Historical 2.0.2 setting, not a current tuning recommendation.

Credentials and role configuration

Parameter	Role and boundary
`source-password`	Compatibility-style global source secret; mount policy may override it.
`relay-user / relay-password`	Credentials used for authorised relay discovery.
`admin-user / admin-password`	Separate administrator identity and secret.
`authentication/role`	2.5 role-based matching, authentication and access policy.
`role/match-method`	Filters which HTTP methods the authenticator considers.
`role/allow-method / deny-method`	Permissions are distinct from selecting a matching request.
`role/allow-web / deny-web`	Controls web-resource access for the role.
`role/allow-admin / deny-admin`	Controls administration-command access for the role.
`role/connections-per-user`	Per-user connection policy; not the old duplicate-user flag.
`role/option`	Authenticator-specific settings such as filename or client_add.

Sockets and response headers

Parameter	Role and boundary
`listen-socket/port`	Local TCP port. Check conflicts with another instance or service.
`listen-socket/bind-address`	Local interface address; omission can expose all applicable interfaces.
`listen-socket/tls`	TLS policy; the 2.5 example uses auto_no_plain for TLS access.
`listen-socket/shoutcast-mount`	Compatibility source path; reserves base port and following port.
`http-headers/header`	Custom response field with name/value; test global and mount scope.
`header/type="cors"`	2.5 example generates CORS headers through the dedicated header type.

Mount policy

Parameter	Role and boundary
`mount/type`	normal targets an explicit mount; default has distinct fallback semantics.
`mount-name`	Exact stream path; not a command that starts a source.
`username / password`	Mount-specific source identity in the compatibility form.
`max-listeners`	Concurrent listeners permitted on this mount.
`max-listener-duration`	Allowed listener duration in seconds, subject to authentication policy.
`dump-file`	Optional incoming-stream dump; plan disk capacity and file permissions.
`intro`	Webroot-relative intro media; format must match the stream.
`fallback-mount`	Destination when the stream is unavailable; not a backup encoder.
`fallback-override`	Permits the returning original source to take listeners back.
`fallback-when-full`	Routes new listeners to a fallback when the mount limit is full.
`charset`	Expected source metadata encoding for applicable legacy streams.
`public`	Directory publication override; does not enforce private listening.
`hidden`	Hides a mount from certain listings; not authentication.
`stream-name / stream-description`	Display and directory metadata overriding source-provided values.
`stream-url / genre`	Descriptive programme URL and genre, not the socket address.
`bitrate / type / subtype`	Published media descriptors; these do not transcode media.
`icy-metadata-interval`	Bytes between ICY metadata blocks for applicable new listeners.
`event-bindings`	2.5 source lifecycle events; restrict executable and URL side effects.
`on-connect / on-disconnect`	Older lifecycle form; compare current event-bindings before migration.

Relay and upstream configuration

Parameter	Role and boundary
`relay/local-mount`	Path exposed by the receiving server.
`relay/on-demand`	Pulls according to listener demand rather than continuously.
`upstream/type`	normal describes a feed; default supplies common upstream settings.
`upstream/uri`	2.5 full upstream URI as shown in the shipped example.
`upstream/server / port / mount`	Alternative separate origin coordinates; keep local-mount distinct.
`upstream/username / password`	Authentication required by the requested upstream.
`relay-shoutcast-metadata`	Requests embedded ICY metadata where the upstream supports it.
`master-server / master-server-port`	Remote server coordinates for master relay discovery.
`master-username / master-password`	Relay discovery credentials on the remote server.
`master-update-interval`	Seconds between discovery polls in the documented master model.
`relays-on-demand`	Global on-demand preference for applicable relays.

Paths, logging and security

Parameter	Role and boundary
`paths/basedir`	Base for chroot; not a universal prefix for every path.
`paths/logdir`	Writable base directory for configured logs.
`paths/webroot / adminroot`	Public files versus administration transforms; keep private data separate.
`paths/pidfile`	Instance-specific process-ID file.
`paths/mime-types`	Optional file extension/media-type mapping.
`paths/allow-ip / deny-ip`	Optional IP lists; not a replacement for a complete network policy.
`paths/alias`	Current 2.5 sample uses source and destination attributes.
`logging/accesslog / errorlog`	Request log and server decision/error log.
`logging/playlistlog`	Optional metadata history, not an audio recording.
`logging/loglevel`	Named levels in the 2.5 sample; limit debug windows.
`logging/logsize / logarchive`	Rotation size and archive retention behaviour; monitor disk use.
`security/chroot`	Changes filesystem root with platform and startup constraints.
`security/changeowner`	Changes process user/group when supported; real accounts required.
`security/tls-context`	2.5 TLS context holding certificate, key and optional TLS policy.
`tls-certificate / tls-key`	PEM certificate chain and protected private key inside the context.
`security/prng-seed`	Optional entropy-source configuration; choose according to the target OS.

Follow the behaviour, not just the parser

Use mountpoints, TLS, roles and relay configuration for concrete workflows. Keep a record of the active version and changes. A well-formed XML document can still contain the wrong scope or an obsolete option. Acceptance means the intended source, listener and failure cases behave correctly.