HTTP configuration (part 1)

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

Tip: Liberator’s supplied with a built-in HTTP Config blade that's automatically activated when you install the Liberator (see Built-in blades). For more about how to change the configuration of this blade, see How can I...  Configure how Liberator handles HTTP connections.

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

Contents:

http-access-control-header

http-access-control-header sets the HTTP Access-Control-Origin-Header (see the Wikipedia entry at https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), which Liberator sends as an HTTP response to a client. The header permits client resources that were loaded from other webservers to access data from the Liberator server. The configuration item consists of one or more fully qualified web addresses (for example, http://www.caplin.com). These are the addresses of the resources (typically JavaScript files) that were loaded into the client and need the Liberator data.

Use this configuration item to ensure security of access to Liberator by client applications that may use the following StreamLink connection types:

  • Streaming JavaScript via IFrame (when Server-Sent Events are turned off). 
  • HTML5 Server-Sent Events
  • WebSocket

If you don’t set this configuration item, or a requesting client resource was loaded from a web address that doesn’t match an address in the list, Liberator supplies the default value *, which allows access from all domains (and is therefore not secure). The Wikipedia entry states: "The value of "*" is special in that it does not allow requests to supply credentials, meaning HTTP authentication, client-side SSL certificates, nor does it allow cookies to be sent."

Syntax: http-access-control-header <fully-qualified-web-addresses>

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: * (see description above)

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.

The log filename can contain the parameters %a and %h  At run time, %a is replaced by the Liberator's application name (see the DataSource configuration item application-name ), and %h is replaced by the host name of the machine on which the Liberator is running.

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

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.

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

The log filename can contain the parameters %a and %h  At run time, %a is replaced by the Liberator's application name (see the DataSource configuration item application-name ), and %h is replaced by the host name of the machine on which the Liberator is running.

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 browser or browsers 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 when the StreamLink connection type is “Streaming JavaScript via IFrame” and Server-Sent Events are turned off. (This connection type is typically used when the browser is Microsoft Internet Explorer).

Specify this flag to allow RTTP data to pass through proxies without being rejected.

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

When using HTML5 WebSocket-based connections, during the opening handshake, the browser may offer to compress Websocket frames exchanged with the server using the DEFLATE compression algorithm. When the allow-ws-permessage-deflate flag is set, Liberator accepts such a request, and subsequent WebSocket frames can be compressed as necessary before they’re exchanged.

At the time of writing (June 2014), the latest versions of the Chrome and Safari browsers can request per-message deflate compression. For more about the DEFLATE algorithm, see RFC 1951.

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

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

http-process-extension filetypeA 
http-process-extension filetypeB
http-process-extension filetypeC
Don’t add a ‘.’ prefix to the file types. Thus, xml and html are correct, but .xml and .html are incorrect.

Type: array of strings

Default values: The default setting is equivalent to http-process-extension xml html js 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 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: