# Installing Liberator This page tells you how to deploy Liberator 8 using the [Caplin Deployment Framework](../deployment-framework/index.md). For instructions on upgrading an existing deployment of Liberator, see [Upgrading Liberator](liberator-upgrading-liberator.md). ## 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)^{asterisk}^ | | 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](../platform-architecture/platform-hardware-and-software-requirements.md). ## Deploying Liberator Follow the steps below to deploy Liberator to a Caplin Deployment Framework: 1. If you have not done so already, prepare a Deployment Framework to host the components in your deployment. See [Installing the Deployment Framework](../deployment-framework/cdf-installing-the-deployment-framework.md). 2. Run the [`**dfw stop**`](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#stop) command to stop all components in the deployment: ```console $ ./dfw stop ``` 3. Copy your licence file for Liberator (`license_rttpd.conf`) to the Deployment Framework’s `global_config/licenses` directory. **📌 NOTE**\ 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). 4. 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](../keymaster/keymaster-installing-keymaster.md). **❗ IMPORTANT**\ The Deployment Framework includes an example public key for KeyMaster, `global_config/ssl/keymaster_public.der`. Do not use this example key in production. 5. Copy the Liberator deployment kit (archive ending in `.tar.gz` or `.zip`) to the Deployment Framework’s `kits` directory. 6. Run the [`**dfw deploy**`](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md) command to deploy Liberator: ```console $ ./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 ``` 7. Run the [`**dfw versions**`](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#versions) command to confirm deployment and review which Liberator feature blades are active: ```console $ ./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 ``` 8. Run the [`**dfw hosts**`](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#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'** ```console $ ./dfw hosts Liberator liberator1.example.com liberator2.example.com ``` **Example: Liberator runs on all deployment hosts (useful for local development deployments)** ```console $ ./dfw hosts Liberator localhost localhost ``` 9. 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: 1. To improve the speed at which Caplin Support can diagnose issues with your deployment, make the following configuration changes to the host: 1. Set the system clock to UTC and synchronise with a time source common to all Caplin Platform servers. 2. 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](https://access.redhat.com/solutions/61334) on the Red Hat website. 3. Install the Red Hat package for the GNU Debugger: ```console $ sudo yum install gdb ``` **📌 NOTE**\ The GNU Debugger tools are required by [Caplin Platform Diagnostics](https://github.com/caplin/caplin-platform-diagnostics), Bash scripts from Caplin Support that automate the collection of diagnostic data from a running or crashed Caplin component. 2. Deactivate unsecure feature blades: ```console $ ./dfw deactivate HTTP DirectConnection LiberatorWebsite $ ./dfw deactivate OpenPermissioning $ ./dfw deactivate LiberatorDemoDataSource ``` 3. Copy your TLS key and certificate for this Liberator to the Deployment Framework’s `global_config/ssl` directory. See [Installing keys and certificates](liberator-configure-how-liberator-handles-https-connections.md#installing-keys-and-certificates). 4. 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](liberator-configure-how-liberator-handles-https-connections.md#dhparam). 5. To support [HTTPS clients](liberator-configure-how-liberator-handles-https-connections.md), follow the steps below: 1. Activate the feature blades below: ```console $ ./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](liberator-configure-how-liberator-handles-https-connections.md). 6. To support secure [direct-connection clients](liberator-configure-how-liberator-handles-direct-client-connections.md), follow the steps below: 1. Activate the feature blade below: ```console $ ./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](liberator-configure-how-liberator-handles-direct-client-connections.md). 7. 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: ```console $ cp ~/Downloads/CPB_PermissioningService-7.0.1-333-919dab0.zip kits $ ./dfw deploy ``` 8. To support CSV/XLSX blotter export functionality (license required), activate the feature blade below: ```console $ ./dfw activate BlotterExport ``` 9. If you have purchased the [Caplin Management Console](../cmc/index.md) and you wish to monitor Liberator, follow the steps below: 1. Enable Liberator’s Java Management Extensions (JMX) interface. See [Activating JMX in Liberator](../cmc/activating-component-jmx-interface.md#liberator). 2. Change the JMX credentials from their default values. See [Activating JMX in Liberator](../cmc/activating-component-jmx-interface.md#liberator). 10. 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](../datasource/datasource-change-the-size-of-the-jvm-heap.md). **❗ IMPORTANT**\ 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 ``` 11. If this Liberator is licensed for an unlimited number of users, set [system-max-files](liberator-tuning-configuration.md#system-max-files) to the sum of `concurrent_clients + 512`, where `concurrent_clients` is this Liberator’s expected number of concurrent clients. **📌 NOTE**\ `system-max-files` is set automatically if your Liberator is licensed for a unique number of users. 12. If you don’t start Liberator as root (see [runtime-user](../datasource/datasource-run-time-environment-configuration.md#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](https://access.redhat.com/solutions/61334) on the Red Hat website. **📌 NOTE**\ The default hard limit for open files for a non-root user in Red Hat Enterprise Linux is 4096. 13. Review the configured number of Liberator session threads (see documentation for [`threads-num`](liberator-tuning-configuration.md#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. 14. 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](liberator-logging.md), [Logging in DataSource applications](../datasource/datasource-logging-in-datasource-applications.md), and [DataSource logging configuration](../datasource/datasource-logging-configuration.md). ## Starting and stopping Liberator Follow the steps below to confirm Liberator has installed correctly: 1. Run the [`**dfw start**`](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#start) command to start Liberator: ```console $ ./dfw start Liberator ``` 2. Run the [`**dfw status**`](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#status) command to check Liberator’s status is 'Running': ```console $ ./dfw status Core components Status Process ID ------------------------------------------------------------- Liberator Running 22935 Deployed Adapter blades Status Process ID ------------------------------------------------------------- ``` 3. Run the [`**dfw stop**`](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#stop) command to stop Liberator: ```console $ ./dfw stop Liberator ``` --- **See also:** * [Start and stop components and blades](../deployment-framework/cdf-start-and-stop-components-and-blades.md) * [Change server-specific configuration](../deployment-framework/cdf-change-server-specific-configuration.md) * [Set up server failover capability](../deployment-framework/cdf-set-up-server-failover-capability.md)