# HTTP configuration (part 1)

These Liberator configuration items define how Liberator handles HTTP connections with clients.

Liberator’s HTTP interface is used to serve [RTTP](liberator-rttp.md) streaming traffic (see [StreamLink connection types](../streamlink/streamlink-connection-types.md)) and web pages from Liberator’s `htdocs` directory.

For production servers, you should disable Liberator’s HTTP interface and enable Liberator’s HTTPS interface. See [Enabling HTTPS](liberator-configure-how-liberator-handles-https-connections.md#enabling-https).

More HTTP-related configuration items can be found in [HTTP configuration (part 2)](liberator-http-configuration-part-2.md).

## http-access-control-header

`http-access-control-header` sets a list of URLs that the Liberator recognises as valid [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) origin URLs.

If Liberator is on a different host to a web app’s application server, the web app includes an `Origin` HTTP header, set to the URL of the application server, in all requests to Liberator.

When Liberator receives an `Origin` HTTP request header, Liberator’s behaviour is as follows:

* If `http-access-control-header` is not set (the default), Liberator allows the request and appends a `Access-Control-Allow-Origin: *` header to its response. For more information, see [Access-Control-Allow-Origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Origin).
* If `http-access-control-header` is set:
  * If the `Origin` request header value matches a CORS origin URL defined by `http-access-control-header`, then Liberator allows the request and sets the [Access-Control-Allow-Origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Origin) HTTP response header to the value of the `Origin` HTTP request header.
  * If the `Origin` request header value does not match any CORS origin URL defined by `http-access-control-header`, then the Liberator refuses the request with HTTP status `304` (forbidden) and writes the following message to the event log (`event-rttpd.log`):

    ```
    NOTIFY: Rejecting WebSocket connection attempt from <[underline]##IP address##> because origin <[underline]##Origin URL##> doesn't match any configured
    ```

    **💡 TIP**\
    If you see the above message in Liberator’s event log, and &lt;#Origin URL<mark>> is a valid CORS origin URL for your application, then add &lt;[underline]</mark><mark>Origin URL</mark>#> to a `http-access-control-header` configuration item.

The comparison between the URL in the `Origin` request header and the URLs set by `http-access-control-header` is a strict, case-sensitive string match. No DNS lookup is performed.

**Syntax:** `http-access-control-header <protocol>://<hostname|ip>[:port] ...`

You can also specify multiple instances of `http-access-control-header` like this:

```
http-access-control-header web-address-A
http-access-control-header web-address-B
http-access-control-header web-address-C
```

**Type:** array of strings

**Default value:** _none_

**Example:**

```
http-access-control-header  https://application.mydomain.com
http-access-control-header  https://application2.anotherdomain.com
```

## http-access-log

`http-access-log` specifies the name of the HTTP access log file.

**Supported substitution tokens**

| Token | Description |
| --- | --- |
| %a | The DataSource [application-name](../datasource/datasource-run-time-environment-configuration.md#application-name). |
| %h | The host name of the machine on which this DataSource application is running. |

Log files are written to the location specified by the [log-dir](../datasource/datasource-logging-configuration.md#log-dir) configuration item.

**Syntax:** `http-access-log <log-file-name>`

**Type:** string

**Default value:** `http-access-%a.log` , which, by default, translates to `http-access-rttpd.log`

## http-add-custom-header

Adds a custom HTTP header field to all Liberator HTTP and HTTPS response headers, including responses by Liberator [web modules](liberator-web-modules.md) and [RTTP](liberator-rttp.md) served over HTTP/HTTPS.

**Since**: Liberator 7.0.4

**Syntax**: `http-add-custom-header <header-name> <header-value>`

**Type:** String array

**Default value**: _none_

**Example**: `http-add-custom-header X-Environment "Testing Leg 1"`

## http-connection-cookie-enable

`http-connection-cookie-enable` when set to TRUE, causes Liberator to send a cookie to each client that connects over HTTP.

Also see [http-connection-cookie-expires](#http-connection-cookie-expires).

**Syntax:** `http-connection-cookie-enable <boolean>`

**Type:** boolean

**Default value:** `FALSE`

## http-connection-cookie-expires

`http-connection-cookie-expires` specifies the number of days before a cookie sent to a client expires.

Also see [http-connection-cookie-enable](#http-connection-cookie-enable).

**Syntax:** `http-connection-cookie-expires <number-of-days>`

**Type:** integer

**Default value:** `1` day

## http-def-content-type

`http-def-content-type` specifies the default HTTP content-type (MIME type).

**Syntax:** `http-def-content-type <content-type>`

**Type:** string

**Default value:** `text/plain`

## http-err-content-type

`http-err-content-type` specifies the content-type (MIME type) of error messages sent to clients.

**Syntax:** `http-err-content-type <content-type>`

**Type:** string

**Default value:** `text/html`

## http-error-file-400

`http-error-file-400` specifies the filename of a custom page that’s returned to the client in response to an HTTP 400 error ("Bad Request").

**Syntax:** `http-error-file-400 <filename>`

**Type:** string

**Default value:** The standard Error 400 page is returned to the client.

## http-error-file-401

`http-error-file-401` specifies the filename of a custom page that’s returned to the client in response to an HTTP 401 error ("Unauthorized").

**Syntax:** `http-error-file-401 <filename>`

**Type:** string

**Default value:** The standard Error 401 page is returned to the client.

## http-error-file-403

`http-error-file-403` specifies the filename of a custom page that’s returned to the client in response to an HTTP 403 error ("Forbidden").

**Syntax:** `http-error-file-403 <filename>`

**Type:** string

**Default value:** The standard Error 403 page is returned to the client.

## http-error-file-404

`http-error-file-404` specifies the filename of a custom page that’s returned to the client in response to an HTTP 404 error ("Not Found").

**Syntax:** `http-error-file-404 <filename>`

**Type:** string

**Default value:** The standard Error 404 page is returned to the client.

## http-error-file-503

`http-error-file-503` specifies the filename of a custom page that’s returned to the client in response to an HTTP 503 error ("Service unavailable").

**Syntax:** `http-error-file-503 <filename>`

**Since:** Liberator 7.1.19

**Type:** string

**Default value:** The standard Error 503 page is returned to the client.

## http-error-log

`http-error-log` specifies the name of the HTTP error log file. This file contains information about all the HTTP requests that result in an "Object not found" error.

**Supported substitution tokens**

| Token | Description |
| --- | --- |
| %a | The DataSource [application-name](../datasource/datasource-run-time-environment-configuration.md#application-name). |
| %h | The host name of the machine on which this DataSource application is running. |

Log files are written to the location specified by the [log-dir](../datasource/datasource-logging-configuration.md#log-dir) configuration item.

**Syntax:** `http-error-log <log-file-name>`

**Type:** string

**Default value:** `http-error-%a.log` which, by default, translates to `http-error-rttpd.log`

## http-extensions

`http-extensions` specifies flags that enable various HTTP protocol extensions. These flags allow you to turn on HTTP features that can utilise the client-Liberator connection more efficiently. You can override and /or add to the settings of this item for a particular HTTP client or clients by using the extensions option of an [add-useragent](liberator-http-configuration-part-2.md#add-useragent) configuration item.

**Supported flags**

| Flag | Description |
| --- | --- |
| `force-type5-chunked` | This flag forces Liberator to use HTTP [chunked transfer encoding](https://en.wikipedia.org/wiki/Chunked_transfer_encoding) for type 5 (hidden IFRAME) [StreamLink](../streamlink/index.md) connections. (This connection type is typically used for Microsoft Internet Explorer). Using chunked transfer encoding for hidden IFRAME connections helps [RTTP](liberator-rttp.md) data to pass through proxies. |
| `allow-sse-deflate` | This flag allows Liberator to negotiate compression for the HTML5 Server-Sent Events connection type. Compression typically reduces the amount of traffic being sent by 50-60%, but it does have an adverse impact on both Liberator performance and latency. |
| `allow-ws-permessage-deflate` | By default, Liberator does not compress WebSocket data. Since Liberator version 7.1.14, when the `allow-ws-permessage-deflate` flag is set, Liberator serves WebSockets with `permessage-deflate` compression for HTTP clients that request it during the WebSocket handshake. WebSocket compression is supported by the following StreamLink distributions: * StreamLink JS (all versions) * StreamLink TS (all versions) * StreamLink .NET (version 7.1.7+) |

**Syntax:** `http-extensions flag|flag|flag|...`

You can also specify multiple instances of `http-extensions` like this:

```
http-extensions flag1
http-extensions flag2
http-extensions flag3
```

**Type:** string

**Default value:** +[no flags set]+

## http-idx-content-type

`http-idx-content-type` specifies the content-type (MIME type) of index pages sent to clients.

**Syntax:** `http-idx-content-type <content-type>`

**Type:** string

**Default value:** `text/html`

## http-indexfile

`http-indexfile` specifies a comma-separated list of files to attempt to use when a directory is requested.

**Syntax:** `http-indexfile <list-of-files>`

**Type:** string

**Default value:** `index.html,index.js`

## http-interface

`http-interface` specifies the network interfaces that Liberator listens on for HTTP connection requests.

For a Liberator deployed within a Caplin Deployment Framework, `http-interface` is normally set indirectly by specifying a value for the Deployment Framework configuration macro `LIBERATOR${THIS_LEG}_HTTPINTERFACE`. Only one HTTP interface can be specified in the macro; to add extra interfaces, append new `http-interface` items to the configuration override file `<Framework-root>/global_config/overrides/servers/Liberator/etc/rttpd.conf`.

This configuration item supports IPv6 addresses from Liberator 7 and multiple address wildcards from Liberator 7.0.2.

**Supported IP-address wildcard configurations**

| Configuration | Liberator 6.2 | Liberator 7.0 |
| --- | --- | --- |
| `http-interface` | **Default**. A single IPv4 server socket that listens on all IPv4 interface addresses. | **Default**. A single IPv6 server socket that accepts IPv4-mapped addresses and that listens on all IPv6 and IPv4 interface addresses. See **Tip** below. |
| `http-interface *` | A single IPv4 server socket that listens on all IPv4 interface addresses. | A single IPv6 server socket that accepts IPv4-mapped addresses and that listens on all IPv6 and IPv4 interface addresses. |
| `http-interface 0.0.0.0` | A single IPv4 server socket that listens on all IPv4 interface addresses. | A single IPv4 server socket that listens on all IPv4 interface addresses. |
| `http-interface ::` | _Not supported_ | A single IPv6 server socket that listens on all IPv6 interface addresses. |
| `http-interface 0.0.0.0 ::` | _Not supported_ | A single IPv4 server socket that listens on all IPv4 interface addresses, and a single IPv6 server socket that listens on all IPv6 interface addresses. Supported from Liberator 7.0.2 |

**💡 TIP**\
To configure Liberator’s HTTP server to listen on all its host’s IPv4 and IPv6 addresses, use `http-interface 0.0.0.0 ::` in preference to relying on the default setting. The default setting is less resilient than specifying separate IPv4 and IPv6 wildcards because IPv4-to-IPv6 address mapping can be disabled by a system administrator at the operating system level.

**Syntax:** `http-interface <space-separated-list-of-interface-ip-addresses>`

**Type:** array of strings

**Default value:** +[all available network interfaces]+

## http-keepalive-max

`http-keepalive-max` specifies the maximum number of requests the Liberator will allow per persistent HTTP connection. (Together with [http-keepalive-timeout](#http-keepalive-timeout), this configures the HTTP Keep Alive feature.)

**Syntax:** `http-keepalive-max <max-requests>`

**Type:** integer

**Default value:** `10000 requests`

## http-keepalive-timeout

`http-keepalive-timeout` specifies the maximum time in seconds for which the Liberator will keep a persistent HTTP connection open. (Together with [http-keepalive-max](#http-keepalive-max), this configures the HTTP Keep Alive feature.)

**Syntax:** `http-keepalive-timeout <timeout-in-seconds>`

**Type:** integer

**Default value:** `120 seconds` (2 minutes)

## http-max-body-length

`http-max-body-length` specifies the maximum number of bytes allowed in the body of an HTTP message.

If the maximum number of bytes is exceeded then the user’s connection will be closed and the following error will be written to the event log: "Received WebSocket frame with length _bytes_ - closing connection to rogue client."

**Syntax:** `http-max-body-length <length-in-bytes>`

**Type:** integer

**Default value:** `65536`

## http-max-header-line-length

`http-max-header-line-length` specifies the maximum number of bytes allowed in a single HTTP header line.

**Syntax:** `http-max-header-line-length <length-in-bytes>`

**Type:** integer

**Default value:** `65536`

## http-max-header-lines

`http-max-header-lines` specifies the maximum number of header lines allowed in an HTTP message.

**Syntax:** `http-max-header-lines <length-in-lines>`

**Type:** integer

**Default value:** `30`

## http-max-request-length

`http-max-request-length` specifies the maximum number of bytes allowed in a single HTTP request line (the line that contains a GET or a POST).

**Syntax:** `http-max-request-length <length-in-bytes>`

**Type:** integer

**Default value:** `1024`

## http-port

`http-port` specifies the network port that Liberator listens on for HTTP connection requests.

**📌 NOTE**\
In the [Caplin Platform Deployment Framework](../deployment-framework/index.md), you use a configuration macro `LIBERATOR${THIS_LEG}_HTTPPORT` to specify Liberator’s `http-port`. See [Configuration macros and items](../deployment-framework/cdf-configuration-macros-and-items.md) and How can I ... [Configure how Liberator handles HTTP connections](liberator-configure-how-liberator-handles-http-connections.md).

**Syntax:** `http-port <network-port>`

**Type:** integer

**Default value:** `8080`

## http-process-extension

`http-process-extension` specifies the types of file on which the Liberator performs server-side processing. When such a file is to be served to a client, Liberator first searches it for processing directives and replaces the directives with their run-time equivalents. The processing directives supported are:

| Processing directive | Is replaced by |
| --- | --- |
| %%&lt; http.username >%% | The authenticated HTTP username |
| %%&lt; http.password >%% | The authenticated HTTP password |
| %%&lt; http.request >%% | The raw HTTP resource request |
| %%&lt; http.filtered_request >%% | The resource request filtered to prevent cross-site scripting attacks (XSS attacks) |
| %%&lt; version >%% | The Liberator version |

**Syntax:** `http-process-extension <filetype> ...`

| Parameter | Description |
| --- | --- |
| filetype | File extension, without the preceeding period ( `.` ). Example: `xml` |

**Type:** array of strings

**Default values:** `xml html js txt`

**Example**:

```
http-process-extension xml html js txt
```

You can also specify multiple instances of `http-process-extension` like this:

```
http-process-extension xml
http-process-extension html
http-process-extension js
http-process-extension txt
```

## http-refuse-time

`http-refuse-time` specifies the time in seconds after which Liberator refuses new HTTP connections when no more sockets are available.

**Syntax:** `http-refuse-time <time-in-seconds>`

**Type:** float

**Default value:** `5.0` second

## http-rttp-content-type

`http-rttp-content-type` specifies the default content type for [RTTP](liberator-rttp.md) streams over HTTP.

**Syntax:** `http-rttp-content-type <RTTP-stream-content-type>`

**Type:** string

**Default value:** `application/octet-stream`

## http-server-name

`http-server-name` specifies the name of the Liberator server to be returned in the HTTP response headers. This item allows you change the name returned to something other than the default, which is sometimes advised for security reasons so that the type of server isn’t advertised to clients.

**📌 NOTE**\
In the [Caplin Platform Deployment Framework](../deployment-framework/index.md), a configuration macro `LIBERATOR${THIS_LEG}_HTTP_SERVERNAME` is used to specify Liberator’s `http-server-name`. See [Configuration macros and items](../deployment-framework/cdf-configuration-macros-and-items.md).

**Syntax:** `http-server-name <alternative-name-for-Liberator-server>`

**Type:** string

**Default value:** string

## http-tcp-nodelay-off

`http-tcp-nodelay-off` specifies whether Liberator’s HTTP client connection sockets should have the TCP_NODELAY feature turned off. The default is `FALSE`, which means TCP_NODELAY is enabled. Setting this configuration item to `TRUE` _disables_ TCP_NODELAY.

**Syntax:** `http-tcp-nodelay-off <boolean>`

**Type:** boolean

**Default value:** `FALSE` (TCP_NODELAY is disabled)

## http-wwwroot

`http-wwwroot` specifies the root directory of the Liberator’s HTML files.

The directory path can contain the parameter `%r`, which is replaced at run time by the root directory ([application-root](../datasource/datasource-run-time-environment-configuration.md#application-root)) under which the Liberator runs.

This item is overidden for specific virtual host connections by the [wwwroot](liberator-https-configuration.md#wwwroot) option of the [add-virtual-host](liberator-https-configuration.md#add-virtual-host) that defines the virtual host.

**Syntax:** `http-wwwroot <HTML-root-directory>`

**Type:** string

**Default value:** `%r/htdocs`

---

**See also:**

* How can I ... [Configure how Liberator handles HTTP connections](liberator-configure-how-liberator-handles-http-connections.md)
* Reference: [HTTP configuration (part 2)](liberator-http-configuration-part-2.md)
* Reference: [HTTPS configuration](liberator-https-configuration.md)
* Reference: [RTTP configuration](liberator-rttp-configuration.md)