Icecast Server/Custom HTTP Headers

From XiphWiki
Jump to navigation Jump to search

Custom HTTP Headers


Icecast allows to set custom HTTP headers. This is done via a <http-headers /> section. Each such section contains zero or more <header /> tags. Such sections are permitted within the following tags:

  • <icecast /> (global headers)
  • <listen-socket />
  • <mount />
  • <role />
  • <acl /> (Experimental! Do not use!)


Each <header /> may have the following XML properties:

Property Required Type Default Description
type no enum static The type of the header. static, or cors.
name Yes token none The name of the header to add. Note that this field is case insensitive. The case of the sent header my be different from what is configured here.
value depends on type depends on type none The value of the header to add. the meaning depends on it's type.
status no HTTP status code any Limit this header to the responses that return the given status code.


There are different types of headers. The type generally controls how the header is generated.

Type static

This is used to generate a static header. The value is sent as-is to the client.

Type cors

The CORS type is used to generate a CORS (cross-origin resource sharing) header. The name is the name of the header. If a value is given, that value overrides the auto generated value (if any).

Header Value required Type Default Description
Access-Control-Allow-Origin no origin The request origin on success, null otherwise Sets the allowed origin. Should be null, or * for manual configuration or left unset.
Access-Control-Allow-Credentials Yes¹ boolean none¹ Whether or not clients are allowed to send credentials to the mount point.
Access-Control-Expose-Headers no token list content-range, icy-br, icy-description, icy-genre, icy-name, icy-pub, icy-url¹ List of extra headers a client may have access to.
Access-Control-Max-Age no time interval 300 (5 minutes) Time in seconds on how long CORS related information may be cached.
Access-Control-Allow-Methods no list of HTTP methods Same as Allow list on success, none otherwise The list of allowed HTTP methods. If no value is given this equals to all allowed methods for the given mount point.
Access-Control-Allow-Headers no token list range, if-range¹ The extra headers a client my send during actual requests.

¹ The default is subject to updates in order to represent the current state of development.