Icecast Server/Custom HTTP Headers: Difference between revisions

From XiphWiki
Jump to navigation Jump to search
(Initial stub)
 
(Feature: Documented headers)
 
Line 6: Line 6:
</div>
</div>


Icecast allows to set custom HTTP headers. This is done via a <code><<nowiki />http-headers /></code> section.
== Overview ==
Icecast allows to set custom HTTP headers. This is done via a <code><<nowiki />http-headers /></code> section. Each such section contains zero or more <code><<nowiki />header /></code> tags. Such sections are permitted within the following tags:
* <code><<nowiki />icecast /></code> (global headers)
* <code><<nowiki />listen-socket /></code>
* <code><<nowiki />mount /></code>
* <code><<nowiki />role /></code>
* <code><<nowiki />acl /></code> (Experimental! Do not use!)
 
== Properties ==
Each <code><<nowiki />header /></code> may have the following XML properties:
{| class="wikitable"
! Property !! Required !! Type !! Default !! Description
|-
| <code>type</code> || no || enum || <code>static</code> || The type of the header. <code>static</code>, or <code>cors</code>.
|-
| <code>name</code> || 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.
|-
| <code>value</code> || depends on <code>type</code> || depends on <code>type</code> || ''none'' || The value of the header to add. the meaning depends on it's <code>type</code>.
|-
| <code>status</code> || no || HTTP status code || ''any'' || Limit this header to the responses that return the given status code.
|}
 
== Types ==
There are different types of headers. The type generally controls how the header is generated.
 
=== Type <code>static</code> ===
This is used to generate a static header. The <code>value</code> is sent as-is to the client.
 
=== Type <code>cors</code> ===
The CORS type is used to generate a CORS (cross-origin resource sharing) header. The <code>name</code> is the name of the header. If a <code>value</code> is given, that value overrides the auto generated value (if any).
 
{| class="wikitable"
! Header !! Value required !! Type !! Default !! Description
|-
|| <code>Access-Control-Allow-Origin</code> || no || origin || The request origin on success, <code>null</code> otherwise || Sets the allowed origin. Should be <code>null</code>, or <code>*</code> for manual configuration or left unset.
|-
|| <code>Access-Control-Allow-Credentials</code> || Yes¹ || boolean || ''none''¹ || Whether or not clients are allowed to send credentials to the mount point.
|-
|| <code>Access-Control-Expose-Headers</code> || no || token list || <code>content-range, icy-br, icy-description, icy-genre, icy-name, icy-pub, icy-url</code>¹ || List of extra headers a client may have access to.
|-
|| <code>Access-Control-Max-Age</code> || no || time interval || <code>300</code> (5 minutes) || Time in seconds on how long CORS related information may be cached.
|-
|| <code>Access-Control-Allow-Methods</code> || no || list of HTTP methods || Same as <code>Allow</code> list on success, none otherwise || The list of allowed HTTP methods. If no <code>value</code> is given this equals to all allowed methods for the given mount point.
|-
|| <code>Access-Control-Allow-Headers</code> || no || token list || <code>range, if-range</code>¹ ||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.

Latest revision as of 08:15, 11 March 2023

Custom HTTP Headers

Icecast 2.5.x page

This page discusses the topic in context of Icecast 2.5.x. The situation for 2.4.x might be different.

Overview

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!)

Properties

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.

Types

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.

Retrieved from "https://wiki.xiph.org/index.php?title=Icecast_Server/Custom_HTTP_Headers&oldid=16799"