Configure how Liberator handles direct client connections

Here’s how to configure direct connections between clients and Liberator, including secure connections via SSL.

Liberator can accept direct persistent RTTP connections from StreamLink clients via TCP/IP, rather than via HTTP or HTTPS. The client connects to Liberator via a TCP/IP socket, and the Liberator streams data directly to the client across this connection. Direct connections can also use the Secure Sockets Layer (SSL) to provide greater security.

The instructions below on setting up secure (SSL) direct conections apply to Liberator 6.2 release and later, deployed using the Caplin Platform Deployment Framework release 6.2 and later.
Some of the instructions on this page require you to use the dfw command of the Deployment Framework. Before entering any dfw command as ./dfw <command-name>, make sure your current (working) directory is set to the Deployment Framework’s topmost directory. For a list of dfw commands, click here.

Configuring Liberator’s direct port and interface

When you install Liberator to run under the Caplin Platform Deployment Framework, it’s automatically configured to use direct connections through a built-in Config blade called DirectConnection. The Liberator listens for direct connections on all available interfaces, on port 14001.

This type of connection isn’t secure. In a production installation, clients shouldn’t be allowed to connect to Liberator through such connections, for security reasons. Use secure direct (SSL) connections instead - see Enabling secure direct connections (SSL) below.

If you want to change the Liberator’s direct connection interface and/or port, set the following configuration items.

  • To change the Liberator’s direct port, add the macro definition LIBERATOR${THIS_LEG}_DIRECTPORT to the Deployment Framework file <Framework-root>/global_config/environment.conf

    Insert the definition at the end of the section headed "Add updated configuration after this point"

    For example:

    #
# Add updated configuration after this point
#
...
#
# Set Liberator's Direct port
#
define LIBERATOR${THIS_LEG}_DIRECTPORT 14051
    Don’t change the value of the configuration item direct-port directly. Always define the HTTP port using the macro LIBERATOR${THIS_LEG}_DIRECTPORT

  • If you want to restrict Liberator to listening for direct connection requests on specific network interfaces, add the macro definition LIBERATOR${THIS_LEG}_DIRECTINTERFACE to the Deployment Framework file <Framework-root>/global_config/environment.conf

    Insert the definition at the end of the section headed "Add updated configuration after this point"

    For example:

    #
# Add updated configuration after this point
#
...
#
# Restrict Liberator's direct interface to specific network interfaces
#
define LIBERATOR${THIS_LEG}_DIRECTINTERFACE aaa.aaa.aaa.aaa bbb.bbb.bbb.bbb
    Don’t change the value of the configuration item direct-interface directly. Always define the HTTP interface using the macro LIBERATOR${THIS_LEG}_DIRECTINTERFACE

Enabling secure direct connections (SSL)

In the Caplin Deployment Framework release 6.2 and later, Liberator’s supplied with a built-in Config blade called DirectSSLConnection that implements secure direct connections using the OpenSSL implementation of SSL (see Built-in blades). To enable secure direct connections, just activate this blade. To ensure maximum security, you should also disable non-secure direct connections by deactivating the built-in DirectConnection blade:

./dfw deactivate DirectConnection
./dfw activate DirectSSLConnection

Enabling the DirectConnection blade makes the Deployment Framework use the blade configuration file <Framework-root>/kits/DirectSSLConnection/Liberator/etc/rttpd.conf. This file contains configuration items that

You can change the default settings of these configuration items as required - see the following sections.

Configuring the direct SSL port and interface

When you activate Liberator’s DirectSSLConnection Config blade, Liberator by default listens for direct connections on all available interfaces, on port 14002. If you want to change the Liberator’s direct SSL connection interface and/or port, set the following configuration items.

  • To change the Liberator’s Direct SSL port, add the macro definition LIBERATOR${THIS_LEG}_DIRECTSSLPORT to the Deployment Framework file <Framework-root>/global_config/environment.conf

    Insert the definition at the end of the section headed "Add updated configuration after this point"

For example:

#
# Add updated configuration after this point
#
...
#
# Set Liberator's Direct SSL port
#
define LIBERATOR${THIS_LEG}_DIRECTSSLPORT 14052
Don’t change the value of the configuration item directssl-port directly. Always define the HTTP port using the macro LIBERATOR${THIS_LEG}_DIRECTSSLPORT

  • If you want to restrict Liberator to listening for direct SSL connection requests on specific network interfaces, add the macro definition LIBERATOR${THIS_LEG}_DIRECTSSLINTERFACE to the Deployment Framework file <Framework-root>/global_config/environment.conf

    Insert the definition at the end of the section headed "Add updated configuration after this point"

For example:

#
# Add updated configuration after this point
#
...
#
# Restrict Liberator's Direct SSL interface to specific network interfaces
#
define LIBERATOR${THIS_LEG}_DIRECTSSLINTERFACE aaa.aaa.aaa.aaa bbb.bbb.bbb.bbb
Don’t change the value of the configuration item directssl-interface directly. Always define the HTTP interface using the macro LIBERATOR${THIS_LEG}_DIRECTSSLINTERFACE

Applying the security policy

The Liberator install kit comes with a set of SSL files containing a certificate, private key and certificate passphrase that are suitable for development and testing purposes. The files were created using the OpenSSL toolkit and consist of:

  • An SSL certificate file in PEM format: rttpd_https.pem

  • An SSL private key file in PEM format rttpd_https.key

  • A file containing the SSL certificate passphrase: rttpd_https.pwd

When you deploy Liberator, these files are copied to the Deployment Framework directory <Framework-root>/global_config/ssl/, provided that there are no files already in this directory. (You may have production versions of the SSL files in the directory - see Setting certificates for production use. In that case, when you deploy a new version of Liberator, the production files aren’t replaced by the development versions.) When you enable Liberator’s built-in DirectSSLConnection Config blade, it uses the SSL files that it finds in <Framework-root>/global_config/ssl/

For more about the OpenSSL toolkit, see www.openssl.org

Setting certificates for production use

You must obtain your own certificate, private key and passphrase for production use. When you’ve done this:

  • Put the production files in <Framework-root>/global_config/ssl/

  • Configure the DirectSSLConnection blade to point at the new files.

    To do this, add the following entries to <Framework-root>/global_config/overrides/servers/Liberator/etc/rttpd.conf

directssl-certificate   ${SSLCERT_PATH}/.pem
directssl-privatekey    ${SSLCERT_PATH}/.key
directssl-passwordfile  ${SSLCERT_PATH}/.pwd

Where, of course, <my-production-certificate-file> and so on, are really the actual names of the files.

You can see from this example that in the Deployment Framework, a configuration macro SSLCERT_PATH is used to specify the directory path to the relevant files. See the Framework Configuration macros and items page.

When you set up secure direct connections to Liberator, you’ll probably want to set up HTTPS connections at the same time (see How can I…​ Configure how Liberator handles HTTPS connections). In development and test environments, it’s convenient to share the same certificate, private key file and certificate pass phrase file between these two types of connection. But for added security in production environments, you can configure a different set of these files for each connection type.

Seeding the OpenSSL random number generator

See How can I…​ Seed the OpenSSL random number generator.

Configuring OpenSSL

Liberator uses the OpenSSL software to implement the security policies for secure direct connections with clients. You can configure OpenSSL using the following DataSource configuration items, which are defined on the page DataSource Secure Sockets Layer (SSL) configuration:

When you change the configuration of OpenSSL, the new settings apply to all of Liberator’s secure (SSL) connections: Direct secure connections to clients, HTTPS connections and secure connections between Liberator and other DataSource applications.

Improving the security of direct connections

To resist attacks on your system, Liberator includes a configuration option called direct-max-line-length that limits the length of an RTTP message sent across a direct connection. If Liberator receives a message longer than that configured, it’ll reject it rather than reading it continuously until memory runs out.

The default setting for this item should be sufficient, but if you experience security problems, set it to a lower value. Add the new setting to the Deployment Framework file <Framework-root>/global_config/overrides/servers/Liberator/etc/rttpd.conf

See also: