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:

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

Additional requirements for Caplin Support

The following additional requirements increase the speed at which Caplin Support can diagnose issues in production and test environments:

  • System clock: UTC

  • Core dumps: set to unlimited size for all user accounts that run Caplin components

  • Java garbage collection logging: enabled for all active JVMs on the Caplin Platform

  • Red Hat packages: gdb (the GNU Debugger)

For instructions on setting up the additional requirements, see Getting information about a failed Platform component: Prerequisites.

Deploying Liberator

Follow the steps below in the Deployment Framework for the host:

  1. Ensure Liberator’s requirements are met. See Requirements above.

  2. Stop all running Caplin Platform components:

    $ ./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.9-313149-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: CfgPermissioning
      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: LiberatorJMX
      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
      Liberator kit has deployed a new blade: XMLPermissioning
    
      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.1-313146
    
      Core components                          Version
      ---------------------------------------------------------------------
      Liberator                                7.1.9-313149
    
      Deployed blades                          Version            State
      ---------------------------------------------------------------------
      BlotterExport                            7.1.9-313149       Inactive
      CfgPermissioning                         7.1.9-313149       Inactive
      DemoDataSourceLatency                    7.1.9-313149       Inactive
      DirectConnection                         7.1.9-313149       Active
      DirectSSLConnection                      7.1.9-313149       Inactive
      HTTP                                     7.1.9-313149       Active
      HTTPS                                    7.1.9-313149       Inactive
      JavaOpenPermissioning                    7.1.9-313149       Inactive
      LiberatorDemoDataSource                  7.1.9-313149       Inactive
      LiberatorJMX                             7.1.9-313149       Inactive
      LiberatorWebsite                         7.1.9-313149       Active
      MinimalLiberatorWebsite                  7.1.9-313149       Inactive
      OpenPermissioning                        7.1.9-313149       Active
      ServerIdentification                     7.1.9-313149       Active
      TokenPermissioning                       7.1.9-313149       Inactive
      XMLPermissioning                         7.1.9-313149       Inactive
  8. Run the dfw hosts command to specify on which hosts the Deployment Framework command dfw start will start Liberator:

    Example: dfw start starts Liberator if hostname matches 'liberator1.example.com' or 'liberator2.example.com'
    $ ./dfw hosts Liberator liberator1.example.com liberator2.example.com
    Example: dfw start starts Liberator on any host (use this for a local development environment only)
    $ ./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

    2. In the /etc/security/limits.conf file, set the core file size limit for the user account that runs Liberator to unlimited. 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
  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. (Recommended) Set the HTTPS port for Liberator to 443. The default port, 18081, may be blocked by some customer firewalls.

      To allow Liberator to bind a service to a privileged port number (1 - 1023), either start Liberator as root (see runtime-user) or use the setcap command to increase the capabilities of the rttpd binary:

      $ sudo setcap 'cap_net_bind_service=+ep' <path_to_rttpd>
    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:

      jvm-options -Xloggc:var/gc.log
      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: