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 streaming traffic (see StreamLink connection types) 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.

More HTTP-related configuration items can be found in HTTP configuration (part 2).

http-access-control-header

http-access-control-header sets a list of URLs that the Liberator recognises as valid 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.

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 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 <IP address> because origin <Origin URL> doesn't match any configured

If you see the above message in Liberator’s event log, and <Origin URL> is a valid CORS origin URL for your application, then add <Origin URL> 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.
`%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 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 and RTTP 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 when set to TRUE, causes Liberator to send a cookie to each client that connects over HTTP.

Also see http-connection-cookie-expires.

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

Type: boolean

Default value: FALSE

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

Also see 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.
`%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 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 configuration item.

Supported flags
Flag	Description
`force-type5-chunked`	This flag forces Liberator to use HTTP chunked transfer encoding for type 5 (hidden IFRAME) StreamLink connections. (This connection type is typically used for Microsoft Internet Explorer). Using chunked transfer encoding for hidden IFRAME connections helps RTTP 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

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, 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, 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.

In the Caplin Platform Deployment Framework, you use a configuration macro LIBERATOR${THIS_LEG}_HTTPPORT to specify Liberator’s http-port. See Configuration macros and items and How can I … Configure how Liberator handles HTTP connections.

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

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

%%< http.username >%%

The authenticated HTTP username

%%< http.password >%%

The authenticated HTTP password

%%< http.request >%%

The raw HTTP resource request

%%< http.filtered_request >%%

The resource request filtered to prevent cross-site scripting attacks (XSS attacks)

%%< version >%%

The Liberator version

Syntax: http-process-extension <filetype> …

Parameter Description

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

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-rest-path

http-rest-path specifies a URI prefix that identifies URLs to be handled by Liberator’s HTTP and HTTPS interfaces' REST handler. By default, http-rest-path is unset, and no URLs are handled by the REST handler.

The REST handler strips the specified prefix from the URI and treats the remainder of the URI as a subject, which it serves according to the Liberator’s configured data service routing. Both subjects routed to DataSources and subjects routed to onward REST endpoints via Liberator’s REST Adapter are supported.

Because the prefix is stripped from the URI, specify the prefix without a trailing slash. For example: /REST not /REST/.

Syntax: http-rest-path <uri_prefix>

Type: string

Default value: none

Example:

http-rest-path /REST

With the configuration above, an authenticated HTTP GET request for /REST/SYSTEM/INFO returns a JSON representation of Liberator’s built-in subject /SYSTEM/INFO:

$ curl -u admin:admin http://localhost:18080/REST/SYSTEM/INFO
{"subject":"/SYSTEM/INFO","type":"map","status":"UNKNOWN","data":{"GlobalMaxSessionsType8":"1","GlobalMaxSessionsType2":"1","NodeID":"0","GlobalMaxSessionsType1":"0","GlobalSessionsType9":"0","GlobalSessionsType3":"0","GlobalSessionsType8":"1","GlobalSessionsType2":"1","GlobalSessionsType1":"0","GlobalSessions":"2","GlobalMaxSessionsType5":"0","GlobalMaxSessions":"2","GlobalSessionsType5":"0","GlobalMaxSessionsType4":"0","Version":"0.0.0","GlobalMaxSessionsType9":"0","GlobalSessionsType4":"0","GlobalMaxSessionsType3":"0"}}

http-rttp-content-type

http-rttp-content-type specifies the default content type for RTTP 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.

In the Caplin Platform Deployment Framework, a configuration macro LIBERATOR${THIS_LEG}_HTTP_SERVERNAME is used to specify Liberator’s http-server-name. See Configuration macros and items.

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) under which the Liberator runs.

This item is overidden for specific virtual host connections by the wwwroot option of the 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
Reference: HTTP configuration (part 2)
Reference: HTTPS configuration
Reference: RTTP configuration