Installing Liberator

This page tells you how to deploy Liberator 8 using the Caplin Deployment Framework.

For instructions on upgrading an existing deployment of Liberator, see Upgrading Liberator.

Contents:

Requirements
Deploying Liberator
Additional steps for production and test deployments
Starting and stopping Liberator

Requirements

Liberator 8 has the following requirements:

Operating system	Red Hat Enterprise Linux 9 (x86_64, aarch64) [recommended] Red Hat Enterprise Linux 8 (x86_64) Red Hat Enterprise Linux 7 (x86_64)^*
Java	OpenJDK 17, OpenJDK 21

Operating system

Red Hat Enterprise Linux 9 (x86_64, aarch64) [recommended]
Red Hat Enterprise Linux 8 (x86_64)
Red Hat Enterprise Linux 7 (x86_64)^*

Java

OpenJDK 17, OpenJDK 21

^* Red Hat Extended Life Cycle Support subscription required from 30th June 2024

Liberator is written in C, and Java is required only for Java authentication modules (for example, the Caplin Permissioning Service) and legacy JMX monitoring (for example, the Caplin Management Console). If you don’t use either of these modules, then you don’t need Java to run Liberator.

For suggested server hardware specifications, see Caplin Platform System Requirements.

Deploying Liberator

Follow the steps below to deploy Liberator to a Caplin Deployment Framework:

If you have not done so already, prepare a Deployment Framework to host the components in your deployment. See Installing the Deployment Framework.
Run the dfw stop command to stop all components in the deployment:
```
$ ./dfw stop
```

Copy your licence file for Liberator (license_rttpd.conf) to the Deployment Framework’s global_config/licenses directory.

If you don’t have a licence file for Liberator, the Deployment Framework will copy an evaluation licence to the global_config/licenses directory on deployment of Liberator. Evaluation licenses permit only 30 minutes of continuous uptime and do not include options for the TokenAuth feature blade, Java auth modules (required by the Caplin Permissioning Service), and the Snapshot web module (required to export blotters as CSV or XLSX).

If you are using KeyMaster in this deployment, copy the public key you generated for KeyMaster (keymaster_public.der) to the Deployment Framework’s global_config/ssl directory on Liberator’s host. See Installing KeyMaster.

The Deployment Framework includes an example public key for KeyMaster, global_config/ssl/keymaster_public.der. Do not use this example key in production.
Copy the Liberator deployment kit (archive ending in .tar.gz or .zip) to the Deployment Framework’s kits directory.

Run the dfw deploy command to deploy Liberator:

$ ./dfw deploy

  Deploying Liberator kit Liberator-7.1.31-142175-37823e35-x86_64-pc-linux-EL6-gnu.tar.gz
   Kit will be saved in kits/archive.
   Kit successfully unpacked.
   Not copying license from Liberator kit. Ensure the current license is the same version as the kit
   just deployed.

   Liberator kit has deployed a new blade: BlotterExport
   Liberator kit has deployed a new blade: DemoDataSourceLatency
   Liberator kit has deployed a new blade: DirectConnection
   Liberator kit has deployed a new blade: DirectSSLConnection
   Liberator kit has deployed a new blade: HTTP
   Liberator kit has deployed a new blade: HTTPS
   Liberator kit has deployed a new blade: JavaOpenPermissioning
   Liberator kit has deployed a new blade: LiberatorDemoDataSource
   Liberator kit has deployed a new blade: LiberatorDemoDataSourceDiscovery
   Liberator kit has deployed a new blade: LiberatorDiscovery
   Liberator kit has deployed a new blade: LiberatorJMX
   Liberator kit has deployed a new blade: LiberatorSockmon
   Liberator kit has deployed a new blade: LiberatorWebsite
   Liberator kit has deployed a new blade: MinimalLiberatorWebsite
   Liberator kit has deployed a new blade: OpenPermissioning
   Liberator kit has deployed a new blade: ServerIdentification
   Liberator kit has deployed a new blade: TokenPermissioning

   Activating a minimal set of blades to allow Liberator to be started.

   Activating DirectConnection
   Activating HTTP
   Activating LiberatorWebsite
   Activating OpenPermissioning
   Activating ServerIdentification

   Blades ok

   The configuration has been updated. The new configuration will not be active
   until the Framework is restarted.


   1 kit(s) deployed

   Blades ok

Run the dfw versions command to confirm deployment and review which Liberator feature blades are active:

$ ./dfw versions

   Deployment Framework                     7.1.2-31326-bbafa80

   Core components                          Version
   ---------------------------------------------------------------------
   Liberator                                7.1.31-142175-37823e35

   Deployed blades                          Version            State
   ---------------------------------------------------------------------
   BlotterExport                            7.1.31-142175-37823e35 Inactive
   DemoDataSourceLatency                    7.1.31-142175-37823e35 Inactive
   DirectConnection                         7.1.31-142175-37823e35 Active
   DirectSSLConnection                      7.1.31-142175-37823e35 Inactive
   HTTP                                     7.1.31-142175-37823e35 Active
   HTTPS                                    7.1.31-142175-37823e35 Inactive
   JavaOpenPermissioning                    7.1.31-142175-37823e35 Inactive
   LiberatorDemoDataSource                  7.1.31-142175-37823e35 Inactive
   LiberatorDemoDataSourceDiscovery         7.1.31-142175-37823e35 Inactive
   LiberatorDiscovery                       7.1.31-142175-37823e35 Inactive
   LiberatorJMX                             7.1.31-142175-37823e35 Inactive
   LiberatorSockmon                         7.1.31-142175-37823e35 Inactive
   LiberatorWebsite                         7.1.31-142175-37823e35 Active
   MinimalLiberatorWebsite                  7.1.31-142175-37823e35 Inactive
   OpenPermissioning                        7.1.31-142175-37823e35 Active
   ServerIdentification                     7.1.31-142175-37823e35 Active
   TokenPermissioning                       7.1.31-142175-37823e35 Inactive

Run the dfw hosts command to specify on which deployment hosts you want Liberator to run:
Example: Liberator runs only on deployment hosts 'liberator1.example.com' and 'liberator2.example.com'
```
$ ./dfw hosts Liberator liberator1.example.com liberator2.example.com
```
Example: Liberator runs on all deployment hosts (useful for local development deployments)
```
$ ./dfw hosts Liberator localhost localhost
```
If you intend to run Liberator under a different user account to the account you used to deploy Liberator, then grant Liberator’s user account write permission to the following directories:
- Liberator’s log directory: servers/Liberator/var
- Liberator’s working directory: servers/Liberator
- Liberator’s licence-usage database directory: servers/Liberator/users

Additional steps for production and test deployments

Follow the additional steps below for production deployments of Liberator:

To improve the speed at which Caplin Support can diagnose issues with your deployment, make the following configuration changes to the host:

Set the system clock to UTC and synchronise with a time source common to all Caplin Platform servers.
For the Linux user that runs Liberator, set the soft and hard limits for the core resource to 'unlimited'. Core dumps provide valuable information for Caplin Support in the event of component failure. For more information on setting user limits, see How to set ulimit values on the Red Hat website.

Install the Red Hat package for the GNU Debugger:

$ sudo yum install gdb

The GNU Debugger tools are required by Caplin Platform Diagnostics, Bash scripts from Caplin Support that automate the collection of diagnostic data from a running or crashed Caplin component.

Deactivate unsecure feature blades:

$ ./dfw deactivate HTTP DirectConnection LiberatorWebsite
$ ./dfw deactivate OpenPermissioning
$ ./dfw deactivate LiberatorDemoDataSource

Copy your TLS key and certificate for this Liberator to the Deployment Framework’s global_config/ssl directory. See Installing keys and certificates.
Create a Diffie-Hellman parameters file and copy it to the Deployment Framework’s global_config/ssl directory. See Generating a Diffie Hellman parameters file for DHE ciphers.
To support HTTPS clients, follow the steps below:
1. Activate the feature blades below:
  $ ./dfw activate HTTPS MinimalLiberatorWebsite
2. If this is a public-facing Liberator, configure your external firewall to forward port 443 to Liberator’s default HTTPS port, 18081.
3. Review the security of the configured TLS protocols and ciphers for HTTPS connections, and schedule regular future reviews. See Configure how Liberator handles HTTPS connections.
To support secure direct-connection clients, follow the steps below:
1. Activate the feature blade below:
  $ ./dfw activate DirectSSLConnection
2. Review the security of the configured TLS protocols and ciphers for direct SSL connections, and schedule regular future reviews. See Configure how Liberator handles direct client connections.
Deploy or activate a secure permissioning blade. For example, to deploy Caplin’s Permissioning Service, copy the service’s installation kit to the Deployment Framework’s kits directory and run the ./dfw deploy command:
```
$ cp ~/Downloads/CPB_PermissioningService-7.0.1-333-919dab0.zip kits
$ ./dfw deploy
```
To support CSV/XLSX blotter export functionality (license required), activate the feature blade below:
```
$ ./dfw activate BlotterExport
```
If you have purchased the Caplin Management Console and you wish to monitor Liberator, follow the steps below:
1. Enable Liberator’s Java Management Extensions (JMX) interface. See Activating JMX in Liberator.
2. Change the JMX credentials from their default values. See Activating JMX in Liberator.
If you have activated Liberator’s JMX interface or deployed any other blade that requires Liberator’s JVM, follow the steps below:
1. Set Liberator’s JVM heap size to 1024 megabytes, test against expected workloads, and increase the heap size if required. See Configure a DataSource application’s JVM.
  
  Liberator’s default JVM heap size (256MB) is not intended to handle production-level workloads.
2. Enable garbage collection (GC) logging for Liberator’s JVM. GC logs help Caplin Support diagnose the cause of application issues. Add the following configuration lines to the Deployment Framework file global_config/overrides/servers/Liberator/etc/java.conf:
  # Set the path and filename of the GC log. # Include the PID (%p) or date (%t) in the filename # to prevent the GC log from being overwritten # on restarting the DataSource. # # jvm-options -Xloggc:var/gc-%t.log jvm-options -Xloggc:var/gc-%p.log # GC logging options jvm-options -XX:+PrintGCDetails jvm-options -XX:+PrintGCDateStamps jvm-options -XX:+UseGCLogFileRotation jvm-options -XX:NumberOfGCLogFiles=10 jvm-options -XX:GCLogFileSize=5M jvm-options -XX:+PrintConcurrentLocks jvm-options -XX:+PrintCommandLineFlags jvm-options -XX:+HeapDumpOnOutOfMemoryError jvm-options -XX:HeapDumpPath=var
If this Liberator is licensed for an unlimited number of users, set system-max-files to the sum of concurrent_clients + 512, where concurrent_clients is this Liberator’s expected number of concurrent clients.

system-max-files is set automatically if your Liberator is licensed for a unique number of users.
If you don’t start Liberator as root (see runtime-user) and you expect more than 3583 (4096 - 512) concurrent clients for this Liberator, then edit the /etc/security/limits.conf file and raise the open file hard-limit for the Liberator user to the sum of concurrent_clients + 512.

For more information on setting user limits, see How to set ulimit values on the Red Hat website.

The default hard limit for open files for a non-root user in Red Hat Enterprise Linux is 4096.
Review the configured number of Liberator session threads (see documentation for threads-num). The default number of Liberator session threads is 1. On hosts where the contention between threads for CPU cores is low, increasing the number of Liberator’s session threads can increase the number of clients Liberator can service.
Configure Liberator’s log-cycling policy and provision disk space for log files. We recommend that you set the logging level to INFO and retain logs for 7 days. Cycle the Liberator’s packet log every 15-30 minutes, and cycle all other Liberator logs every 24 hours. For more information, see Liberator logging, Logging in DataSource applications, and DataSource logging configuration.

Starting and stopping Liberator

Follow the steps below to confirm Liberator has installed correctly:

Run the dfw start command to start Liberator:
```
$ ./dfw start Liberator
```

Run the dfw status command to check Liberator’s status is 'Running':

$ ./dfw status

   Core components                Status             Process ID
   -------------------------------------------------------------
   Liberator                      Running            22935

   Deployed Adapter blades        Status             Process ID
   -------------------------------------------------------------

Run the dfw stop command to stop Liberator:
```
$ ./dfw stop Liberator
```

See also: