Custom HTTP Headers

RSAS allows you to customize the HTTP headers sent in its HTTP responses. This is useful in certain situations, such as:

  • If HSTS is required on HTTPS due to your organization's security policies.
  • You are using JavaScript-based error reporting in a player and want to include some extra server information in HTTP headers, so that it can be added to error reports.
  • To annotate your stream with extra metadata for RadioBrowser.
<icecast>
    ...
    <custom-headers>
         <add-header name="Strict-Transport-Security" value="max-age=31536000; includeSubDomains" />
         <add-header name="X-CDN" value="example.com" />
         <add-header name="X-ServerID" value="server1.example.com" />
         <cors>
              <allowed-origin>www.radiomast.io</allowed-origin>
              <allowed-origin>www.radiomast.com</allowed-origin>
              <expose-headers>X-CDN, X-ServerID</expose-headers>
         </cors>
    </custom-headers>
</icecast>

A <custom-headers> section can be added inside different scopes in your config file, to apply to different HTTP responses.

Supported scopes:

Scope Supported When to use
Global
(<icecast>)		YesCustom HTTP header needed on all responses.
Listen Socket
(<listen-socket>)		YesCustom headers applied only for a particular port (eg. HSTS headers for HTTPS)
VHost
(<vhost>)		YesApplied only for a specific domain.
Mount
(<mount>)		YesApplied only for a specific mount.

Directives

<add-header name="Example" value="foo">

Adds a custom HTTP header to all responses within the current scope.

CORS Directives (<cors>)

<allowed-origin>

Sets the Access-Control-Allowed-Origin header, which instructs browsers to restrict the domains from which cross-origin (AJAX) requests can be performed from. Specify this directive multiple times to allow multiple, different origins.

<expose-headers>

Sets the Access-Control-Expose-Headers header in HTTP responses, to advise browsers which HTTP headers should be allowed to be accessed via AJAX, for cross-origin requests. Any headers specified via this directive will be appended to the standard list exposed by RSAS. (Content-Type, icy-metaint, icy-br, ice-audio-info, icy-description, icy-genre, icy-name, icy-samplerate, icy-url)

This directive is useful if you are adding custom HTTP headers, which you need to access via AJAX.