# Direct connections configuration The following configuration items define how Liberator handles direct connections from StreamLink clients as opposed to StreamLink connections tunnelled over HTTP, HTTPS, and WebSocket protocols. Direct connections are supported by all StreamLink libraries except for StreamLink JS. For more information on connection types, see [StreamLink connection types](../streamlink/streamlink-connection-types.md). To enable support for direct connections over SSL, see [Configure how Liberator handles direct client connections](liberator-configure-how-liberator-handles-direct-client-connections.md). ## add-direct-virtual-host `add-direct-virtual-host`, available from Liberator 8.0.1+, defines a name-based or IP-based virtual host. Each virtual-host definition overrides some or all of the global configuration options [directssl-certificate](#directssl-certificate), [directssl-privatekey](#directssl-privatekey), [directssl-passwordfile](#directssl-passwordfile), [directssl-password](#directssl-password), and [directssl-dhparams](#directssl-dhparams) for a specific IP address or hostname. To configure Liberator to present a different TLS certificate for each of the alternative hostnames by which a Liberator server is known, define an `add-direct-virtual-host` block for each alternative hostname. **Syntax:** ``` add-direct-virtual-host xref:name[name] [string] xref:addr[addr] [string] xref:add-direct-virtual-host-certificate[certificate] [string] xref:add-direct-virtual-host-passwordfile[passwordfile] [string] xref:add-direct-virtual-host-password[password] [string] xref:add-direct-virtual-host-privatekey[privatekey] [string] xref:add-direct-virtual-host-dhparams[dhparams] [string] end-direct-virtual-host ``` **Options for add-direct-virtual-host** | Options | Type | Default | Description | | --- | --- | --- | --- | | `addr` | string | +[none]+ | The IP address or hostname of this virtual host. If the address is invalid, Liberator will fail to start. | | `certificate` | string | Value of [directssl-certificate](#directssl-certificate) | The filename and directory path of the SSL (secure sockets layer) certificate used for direct connections to this virtual host. The file must be in PEM format. The directory path is optional and can be in relative or absolute format. This option overrides for this virtual host the certificate filename and path defined in the global configuration item [directssl-certificate](#directssl-certificate). | | `passwordfile` | string | Value of [directssl-passwordfile](#directssl-passwordfile) | The filename and directory path of the file containing the passphrase for the [privatekey](#add-direct-virtual-host-privatekey). The file must be in PEM format. The directory path is optional and can be in relative or absolute format. This option overrides for this virtual host the password filename and path defined in the global configuration item [directssl-passwordfile](#directssl-passwordfile). | | `password` | string | Value of [directssl-password](#directssl-password) | The passphrase for the [privatekey](#add-direct-virtual-host-privatekey). This option overrides for this virtual host the password filename and path defined in the global configuration item [directssl-password](#directssl-password). If `password` is configured then it is used and any [`passwordfile`](#add-direct-virtual-host-passwordfile) that is configured is ignored. | | `privatekey` | string | Value of [directssl-privatekey](#directssl-privatekey) | The filename and directory path of the SSL (secure sockets layer) private key used for direct connections to this virtual host. The file must be in PEM format. The directory path is optional and can be in relative or absolute format. This option overrides for this virtual host the private key filename and path defined in the global configuration item [directssl-privatekey](#directssl-privatekey). | | `dhparams` | string | +[none]+ | The path to a Diffie-Hellman (DH) parameters file, which is required by ephemeral Diffie-Hellman ciphers (DHE). For instructions on how to generate a DH parameters file, see [Generating a Diffie-Hellman parameters file for DHE ciphers](liberator-configure-how-liberator-handles-https-connections.md#dhparam). This option overrides for this virtual host the path to the DH parameters file defined in the global configuration item [directssl-dhparams](#directssl-dhparams). | | `name` | string | Value of the [addr](#addr) option | A name for this virtual host. | **Example:** In this example, a Liberator server, `host1.example.com`, also has DNS entries for the host names `host2.example.com` and `host3.example.com` at the same IP address. The example configuration below uses `add-direct-virtual-host` blocks to define the TLS certificates to use for `host1.example.com` and `host2.example.com`. ``` # TLS certificate for host2.example.com add-direct-virtual-host addr host2.example.com certificate ${SSLCERT_PATH}/host2.example.com.cert.pem privatekey ${SSLCERT_PATH}/host2.example.com.key.pem passwordfile ${SSLCERT_PATH}/host2.example.com.key.pwd end-virtual-host # TLS certificate for host3.example.com add-direct-virtual-host addr host3.example.com certificate ${SSLCERT_PATH}/host3.example.com.cert.pem privatekey ${SSLCERT_PATH}/host3.example.com.key.pem passwordfile ${SSLCERT_PATH}/host3.example.com.key.pwd end-virtual-host ``` ## direct-interface `direct-interface` specifies the network interfaces that Liberator listens on for direct connection requests. This configuration item supports IPv6 addresses from version 7 of Liberator, and multiple address wildcards from version 7.0.2. **Wildcard support** | Configuration | Liberator 6.2 | Liberator 7.0 | | --- | --- | --- | | `direct-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. | | `direct-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. | | `direct-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. | | `direct-interface ::` | _Not supported_ | A single IPv6 server socket that listens on all IPv6 interface addresses. | | `direct-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 | | `direct-interface :: 0.0.0.0` | _Not supported_ | A single IPv6 server socket that listens on all IPv6 interface addresses, and a single IPv4 server socket that listens on all IPv4 interface addresses. Supported from Liberator 7.0.2 |
đź“Ś NOTE
In the [Caplin Platform Deployment Framework](../deployment-framework/index.md), you use a configuration variable `LIBERATOR${THIS_LEG}_DIRECTINTERFACE` to specify Liberator’s `direct-interface`. See How can I ... [Configure how Liberator handles direct client connections](liberator-configure-how-liberator-handles-direct-client-connections.md) and [Configuration macros and items](../deployment-framework/cdf-configuration-macros-and-items.md). Variables cannot be assigned multiple values. To create more than one direct interface, assign one address to the macro and assign all additional addresses to new `direct-interface` configuration items in the configuration override file `/global_config/overrides/servers/Liberator/etc/rttpd.conf`.
**Syntax:** `direct-interface ...` **Type:** array of strings **Default value:** +[all available network interfaces]+ ## direct-max-line-length `direct-max-line-length` specifies the maximum number of bytes allowed in a single line of an [RTTP](liberator-rttp.md) message sent to Liberator through a direct connection. **Syntax:** `direct-max-line-length ` **Type:** integer **Default value:** `65536` ## direct-port `direct-port` specifies the network port that Liberator listens on for direct connection requests. **📌 NOTE**\ In the [Caplin Platform Deployment Framework](../deployment-framework/index.md), you use a configuration macro `LIBERATOR${THIS_LEG}_DIRECTPORT` to specify Liberator’s `direct-port`. See How can I ... [Configure how Liberator handles direct client connections](liberator-configure-how-liberator-handles-direct-client-connections.md) and [Configuration macros and items](../deployment-framework/cdf-configuration-macros-and-items.md). **Syntax:** `direct-port ` **Type:** integer **Default value:** `15000` ## direct-refuse-time `direct-refuse-time` specifies the time in seconds for Liberator to refuse new direct connections if no sockets are available. **Syntax:** `direct-refuse-time ` **Type:** float **Default value:** `5.0` seconds ## direct-tcp-nodelay-off `direct-tcp-nodelay-off` specifies whether Liberator’s direct 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:** `direct-tcp-nodelay-off ` **Type:** boolean **Default value:** `FALSE` (TCP_NODELAY is enabled) ## directssl-certificate `directssl-certificate` specifies the filename and directory path of the SSL (secure sockets layer) certificate used for direct connections. This file must be in PEM format. The directory path is optional and can be in relative or absolute format. For more information on setting `directssl-certificate`, see [Installing keys and certificates](liberator-configure-how-liberator-handles-direct-client-connections.md#installing-keys-and-certificates). The default filename for the certificate is the same as the private key’s default filename (default for [directssl-privatekey](#directssl-privatekey)) because both the certificate and the private key can be contained in the same file. **Syntax:** `directssl-certificate ` **Type:** string **Default value:** `cert.pem` ## directssl-ciphersuites (TLS 1.3) `directssl-ciphersuites` specifies the TLS 1.3 ciphers supported by Liberator’s Direct SSL interface, formatted as an [OpenSSL cipher list](https://docs.openssl.org/1.1.1/man1/ciphers/#CIPHER-LIST-FORMAT). To set the TLS 1.0–1.2 ciphers supported by Liberator, see [directssl-cipher-list](#directssl-cipher-list). This is an advanced TLS 1.3 configuration option for specific use cases only. You do not need to set this option to enable TLS 1.3 support in Liberator. TLS 1.3 support is enabled by default from Liberator 7.1.5. When `directssl-ciphersuites` is not specified, Liberator uses OpenSSL’s default TLS 1.3 cipher list. In accordance with the TLS specification, Liberator ignores the priority order of ciphers in `directssl-ciphersuites` and favours the TLS _client’s_ cipher priority order. To reverse this default behaviour, set the `SSL_OP_CIPHER_SERVER_PREFERENCE` flag in [directssl-ssl-options](#directssl-ssl-options). To log the cipher lists of connecting clients, see [directssl-log-hello-ciphers](#directssl-log-hello-ciphers). **Since:** Liberator 7.1.25 **Syntax:** `directssl-ciphersuites <[openssl_cipher_list](https://docs.openssl.org/1.1.1/man1/ciphers/#CIPHER-LIST-FORMAT)>` **Type:** string **Default value**: _OpenSSL default_ ## directssl-cipher-list `directssl-cipher-list` specifies the TLS 1.0–1.2 ciphers supported by Liberator’s Direct SSL interface, formatted as an [OpenSSL cipher list](https://docs.openssl.org/1.1.1/man1/ciphers/#CIPHER-LIST-FORMAT). In accordance with the TLS specification, when choosing a cipher for a connection, Liberator chooses the client’s most preferred cipher from among the ciphers they have in common. To reverse this default behaviour, set the `SSL_OP_CIPHER_SERVER_PREFERENCE` flag in [directssl-ssl-options](#directssl-ssl-options). To define Liberator’s cipher preference, order ciphers in `directssl-cipher-list` in descending order of preference, most preferred cipher first. To log the cipher lists of connecting TLS clients, see [directssl-log-hello-ciphers](#directssl-log-hello-ciphers). Configure this item in conjunction with [directssl-ssl-options](#directssl-ssl-options) (SSL/TLS protocol versions) and [directssl-dhparams](#directssl-dhparams) (required for DHE ciphers). **❗ IMPORTANT**\ The default TLS configuration is not a security recommendation and is not updated regularly. Review the values for [directssl-cipher-list](#directssl-cipher-list), [directssl-ssl-options](#directssl-ssl-options), and [directssl-dhparams](#directssl-dhparams) for compliance with your security policy before deploying Liberator to production, and review regularly thereafter. For detailed information on how to set ciphers for Liberator’s direct SSL interface, see [Configuring supported TLS ciphers](liberator-configure-how-liberator-handles-direct-client-connections.md#ciphers). **Syntax:** `directssl-cipher-list <[openssl_cipher_list](https://docs.openssl.org/1.1.1/man1/ciphers/#CIPHER-LIST-FORMAT)>` **Type:** string **Default:** * **Liberator 7.1.25:** `TLSv1.2+ECDHE+AESGCM:TLSv1.2+ECDHE+AESCCM:TLSv1.2+ECDHE+CHACHA20:TLSv1.2+DHE+AESGCM:TLSv1.2+DHE+AESCCM:TLSv1.2+DHE+CHACHA20` * **Liberator 7.1.5:** `ECDHE:DHE:!SSLv3:!SSLv2:@STRENGTH` * **Liberator 7.0:** `DEFAULT:!RC4-SHA:!RC4-MD5:!DES-CBC3-SHA` * **Liberator 6.0:** `DEFAULT` **Example:** See [Configuring supported TLS ciphers](liberator-configure-how-liberator-handles-direct-client-connections.md#ciphers). ## directssl-dhparams `directssl-dhparams` specifies the path to a Diffie-Hellman parameter file, which is required by ephemeral Diffie-Hellman ciphers (DHE). Configure this item in conjunction with [directssl-ssl-options](#directssl-ssl-options) (SSL/TLS protocol versions) and [directssl-cipher-list](#directssl-cipher-list) (SSL/TLS ciphers). **❗ IMPORTANT**\ The default TLS configuration is not a security recommendation and is not updated regularly. Review the values for [directssl-cipher-list](#directssl-cipher-list), [directssl-ssl-options](#directssl-ssl-options), and [directssl-dhparams](#directssl-dhparams) for compliance with your security policy before deploying Liberator to production, and review regularly thereafter. For instructions on how to generate a Diffie-Helmman (DH) parameters file, see [Generating a Diffie-Hellman parameters file for DHE ciphers](liberator-configure-how-liberator-handles-direct-client-connections.md#dhparam). **Availability:** Liberator 6.2.14+, Liberator 7.0.1+ **Syntax:** `directssl-dhparams ` **Type:** string **Default value:** <empty string> **Example:** ``` directssl-dhparams ${SSLCERT_PATH}/rttpd-dhparam-2048.pem ``` ## directssl-disable-renegotiation `directssl-disable-renegotiation` when set to `TRUE`, prevents clients from renegotiating their direct SSL connections. This protects against Denial of Service attacks involving repeated attempts to renegotiate. **Syntax:** `directssl-disable-renegotiation ` **Type:** boolean **Default value:** `FALSE` (Liberator 6.2), `TRUE` (Liberator 7) ## directssl-enable `directssl-enable` switches on support for direct connections using SSL when set to `TRUE`. **Syntax:** `directssl-enable ` **Type:** boolean **Default value:** `FALSE` (Direct connections via SSL not supported) ## directssl-interface `directssl-interface` specifies the network interfaces to listen on for direct connections using SSL. For a Liberator deployed within a Caplin Deployment Framework, `directssl-interface` is normally set indirectly by specifying a value for the Deployment Framework configuration macro `LIBERATOR${THIS_LEG}_DIRECTSSLINTERFACE`. Only one Direct SSL interface can be specified in the variable; to add extra interfaces, append new `directssl-interface` items to the configuration override file `/global_config/overrides/servers/Liberator/etc/rttpd.conf`. This configuration item supports IPv6 addresses from version 7 of Liberator, and multiple address wildcards from version 7.0.2. **Syntax:** `directssl-interface ...` **Type:** array of strings **Default value:** +[all available network interfaces]+ ## directssl-log-hello-ciphers Enables logging of the cipher list presented by TLS clients in the TLS handshake with Liberator. From Liberator 7.1.25, client cipher lists are logged at INFO level and require the `SSL.Detail` log category to be enabled (see [`log-category-filter`](../datasource/datasource-logging-configuration.md#log-category-filter)): ``` directssl-log-hello-ciphers log-category-filter SSL.Detail ``` For Liberator 7.1.23 and 7.1.24, client cipher lists for successful connections are logged at DEBUG level. Client cipher lists for unsuccessful connections are logged at INFO level. **Since:** Liberator 7.1.23 **Syntax:** `directssl-log-hello-ciphers ` **Type:** boolean **Default value:** FALSE ## directssl-ssl-options `directssl-ssl-options` configures the SSL/TLS protocols accepted by Liberator’s direct SSL interface. Configure this item in conjunction with [directssl-cipher-list](#directssl-cipher-list) (SSL/TLS ciphers) and [directssl-dhparams](#directssl-dhparams) (required for DHE ciphers). **❗ IMPORTANT**\ The default TLS configuration is not a security recommendation and is not updated regularly. Review the values for [directssl-cipher-list](#directssl-cipher-list), [directssl-ssl-options](#directssl-ssl-options), and [directssl-dhparams](#directssl-dhparams) for compliance with your security policy before deploying Liberator to production, and review regularly thereafter. Use `directssl-ssl-options` to disable support for older versions of SSL, and to enable workarounds for known bugs in client implementations of SSL. This configuration item takes one parameter: a pipe-separated list of OpenSSL options from the table below. **Supported OpenSSL options** | Option | Description | | --- | --- | | `SSL_OP_ALL` | Enable all of OpenSSL’s workarounds for known bugs in client implementations of SSL. For the full list of workarounds enabled by this option, see [SSL_CTX_set_options](https://docs.openssl.org/1.1.1/man3/SSL_CTX_set_options/) on the OpenSSL website. | | `SSL_OP_NO_SSLv2` | Disable support for SSL 2 | | `SSL_OP_NO_SSLv3` | Disable support for SSL 3 | | `SSL_OP_NO_TLSv1` | Disable support for TLS 1 | | `SSL_OP_NO_TLSv1_1` | Disable support for TLS 1.1. Available from Liberator 7.1.3. | | `SSL_OP_NO_TLSv1_2` | Disable support for TLS 1.2. Available from Liberator 7.1.3. | | `SSL_OP_NO_TLSv1_3` | Disable support for TLS 1.3. Available from Liberator 7.1.5. | | `SSL_OP_CIPHER_SERVER_PREFERENCE` | In a TLS handshake, the TLS client presents Liberator with a list of the ciphers it supports in priority order, and Liberator chooses a cipher from the list. By default, and in accordance with the TLS specification, Liberator chooses the client’s most preferred cipher from the ciphers they have in common. When `SSL_OP_CIPHER_SERVER_PREFERENCE` is set, Liberator chooses its most preferred cipher from the ciphers they have in common. This breaks with the TLS specification. Liberator’s cipher preferences are determined by the order of ciphers in [`directssl-cipher-list`](#directssl-cipher-list). Ciphers are listed in descending order of preference, most preferred cipher first. Available from Liberator 7.1.25. | For more information on setting TLS protocol versions for Liberator’s direct SSL interface, see [Configuring supported TLS protocol versions](liberator-configure-how-liberator-handles-direct-client-connections.md#protocol-versions). **Syntax:** `directssl-ssl-options