Installing Liberator

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

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

Support for Liberator 6.2 ended 17 January 2019. For Liberator 6.2 installation instructions, see Installing Liberator 6.2).

Requirements

Liberator 7 has the following requirements:

  • Operating System:

    • Red Hat Enterprise Linux 8, 7*, or 6

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

    • Microsoft Windows 10 (not supported in production)

    • Apple macOS 10.12.6 Sierra (not supported in production)

  • Java runtime environment (JRE). Required for Java authentication modules and JMX monitoring. See Installing Java.

    Liberator version Supported JREs

    7.1.15+

    Oracle Java 8 (<= 8u202), Red Hat OpenJDK 8, Red Hat OpenJDK 11

    7.0.0–7.1.14

    Oracle Java 8 (<= 8u202)

  • Caplin Deployment Framework 7 (see Installing the Deployment Framework)

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

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.

  2. Run the dfw stop command to stop all components in the deployment:

    $ ./dfw stop
  3. 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).
  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.

    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 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
    
  7. 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
  8. 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
  9. 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 on the Red Hat website.

    3. 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.
  2. Deactivate unsecure feature blades:

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

  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.

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

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

  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:

    $ 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:

    $ ./dfw activate BlotterExport
  9. 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.

  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.

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

  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, Logging in DataSource applications, and DataSource logging configuration.

Starting and stopping Liberator

Follow the steps below to confirm Liberator has installed correctly:

  1. Run the dfw start command to start Liberator:

    $ ./dfw start Liberator
  2. 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
       -------------------------------------------------------------
  3. Run the dfw stop command to stop Liberator:

    $ ./dfw stop Liberator

See also: