Install and Configure Terracotta server array 4.1 Tutorial

Objective: After reading this tutorial you should be able to configure, and start the terracota server array version 4.1 on windows, or Unix, or Linux.

The tutorial might be interesting for Administrators, developers, or architects who are: in-charge of preparing the environments, want to have a basic idea on how to design clustered Integration server solution.

Note: The configuration of Terracotta server array is not valid for versions earlier than 4.1.

Here are the points which will be discussed in this tutorial:
1. When and why to use cluster?
2. Architecture Diagram.
3. Terracotta server array as windows service Vs command-line.
4. Configure windows service config file ‘wrapper-tsa.conf’.
5. Configure Terracotta server array config file ‘tc-config.xml’
6. Start Terracotta as windows service.
7. Start Terracotta using the command line.

1. When and why to use cluster?

We use cluster to eliminate the single points of failure, maintain high availability, and failover. So if one application server failed (integration server), the other servers in the cluster will continue the processing, the clustered integration servers are working as one integration server which means they are using the same database, and they must be identical. The integration server in the cluster is working in the mode active-active NOT active-passive (meaning that both server are processing requests).

Cluster is a good idea to achieve the failover in these cases:

  1. Schedulers.
  2. Processing of business processes.
  3. Services invoked by triggers.

Cluster is not recommended in Integration server hosting web service only as Cluster adds overhead on the performance which will affect the response time of the web service.

Keep in mind that:

1. The processing power will reduced when an Integration server in the cluster is down.

ex. if you have 2 Integration server in the cluster, when one of them is down this means that you are working with 1/2 of your processing power.

2. The cluster is not a replacement for the load balancer in case of the web service calls.

3. The load is not divided equally over the integration servers in the cluster.

2. Architecture Diagram

In this section we will discuss 2 architecture options to install Terracotta servers.

Option 1: Install the cluster with single Terracotta

IS cluster with 1 terracotta

In this option the Integration server is connected to only one terracotta server. We don’t recommend this option as this server became a single point of failure.

Option 2: Install the cluster with more than Terracotta server

IS cluster with 2 terracotta

In the option we have 2 terracotta servers to avoid having it as a single point of failure. You can configure more than 2 terracotta servers if needed. We recommend this option as it is more reliable than the first option. And make sure to install the terracotta servers in two different physical machines to avoid the single point of failure due to the unavailability of the physical machine.

3. Terracotta server array as windows service Vs command-line

If you are using windows you can run Terracotta server as windows service or using the command-line. To manage the terracotta easily it is strongly recommended to use windows service.

If you are using Linux or Unix you can start the terracotta server array from the command-line and send it in background otherwise it will be turned-off when closing the session.

Here are the steps to configure and start Terracotta 4.1 as Windows Service:

  1. Install Terracotta server array 4.1 using SoftwareAG Installer and your empower account or installation image.
  2. Copy the license file to the Terracotta installation directory (by default it should be copied to the folder ‘softwareAG_Dir\Terracotta\’ the file name is ‘Terracotta-license.key’)
  3. Configure the windows service configuration file ‘wrapper-tsa.conf’.
  4. Configure the terracotta server array configuration file ‘tc-config.xml’.
  5. Create the windows service using the command line.
  6. Start the terracotta server array using the windows service.

Here are the steps to configure and start Terracotta 4.1 from command-line:

  1. Install Terracotta server array 4.1 using SoftwareAG Installer and your empower account or installation image.
  2. Copy the license file to the Terracotta installation directory (by default it should be copied to the folder ‘softwareAG_Dir\Terracotta\’ the file name is ‘Terracotta-license.key’)
  3. Configure the terracotta server array configuration file ‘tc-config.xml’.
  4. Start the terracotta server array using the command-line.

4. Configure windows service config file ‘wrapper-tsa.conf’

Please click on the link below to see a sample file for the windows service configuration file ‘wrapper-tsa.conf’.

wrapper-tsa

Please make sure to change or verify the following parameters in the file:

  • the working directory which contains data of terracotta server
    wrapper.working.dir=c:\SoftwareAg\Terracotta\server\wrapper\work
  • java home directory: it is strongly recommended to use the jvm which comes with the teracotta installation
    set.JAVA_HOME=c:\ SoftwareAg\jvm\jvm

* The license key file location
wrapper.java.additional.2=-Dcom.tc.productkey.path=c:\SoftwareAg\Terracotta\Terracotta-license.key

* Initial Java Heap Size (in MB)
wrapper.java.initmemory=1024

* Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=1024

* set the name of the TC server you want to start, found in conf/tc-config.xml
set.SERVER_NAME=TcServer1

* the location of the tc-conf.xml file
wrapper.app.parameter.4=c:\SoftwareAg\Terracotta\server\wrapper\conf\tc-config.xml
wrapper.app.parameter.11=c:\SoftwareAg\Terracotta\server\wrapper\conf\tc-config.xml

* Display name of the windows service
wrapper.ntservice.displayname=Terracotta 4.1 Server1

# Description of the windows service
wrapper.ntservice.description=Terracotta 4.1 Server1

Note: you can take a copy from the sample config file, modify it with your values of your environment, and make sure that the name of the file wrapper-tsa.conf.

5. Configure Terracotta server array config file ‘tc-config.xml’

Here is a sample xml you can copy it, modify it, and save the file name as tc-config.xml to use it as your config file:

<?xml version=”1.0″ encoding=”UTF-8″ ?>

    <tc:tc-config xmlns:tc=”http://www.terracotta.org/config

          xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance

          xsi:schemaLocation=”http://www.terracotta.org/schema/terracotta-9.xsd“>
      <servers>
<!– host: the host name, name: must be the same as the SERVER_NAME in conf\wrapper-tsa.conf –>
         <server host=”server1″ name=”TcServer1″>
<!– Specify the path where the server should store its data. –>
  <data>c:\SoftwareAg\Terracotta\server\wrapper\work\terracotta\data</data>
<!– Specify the port where the server should listen for client            traffic. –>
           <tsa-port>9510</tsa-port>
<jmx-port>9520</jmx-port>
            <tsa-group-port>9530</tsa-group-port>
            <!– Enable BigMemory on the server. –>
            <offheap>
              <enabled>true</enabled>
              <maxDataSize>2g</maxDataSize>
            </offheap>
         </server>
<server host=”server2″ name=”TcServer2″>
          <!– Specify the path where the server should store its data. –>    <data>c:\SoftwareAg\Terracotta\server\wrapper\work\terracotta\data</data>
<!– Specify the port where the server should listen for client            traffic. –>
            <tsa-port>9510</tsa-port>
            <jmx-port>9520</jmx-port>
            <tsa-group-port>9530</tsa-group-port>
            <!– Enable BigMemory on the server. –>
            <offheap>
              <enabled>true</enabled>
              <maxDataSize>2g</maxDataSize>
            </offheap>
         </server>
<!– Add the restartable element for Fast Restartability (optional). –>
<update-check>
<enabled>false</enabled>
</update-check>
<restartable enabled=”true”/>
<client-reconnect-window>120</client-reconnect-window>
      </servers>
<clients>
<logs>logs-%i</logs>
</clients>
</tc:tc-config>

6. Start Terracotta as windows service

After configuring the ‘wrapper-tsa.conf’, and ‘tc-config’ we will create the windows service by running the following command in the command-line:

c:\Terracotta_install_dir\Terracotta\server\wrapper\bin\wrapper-windows-x86-64 <command> <wrapper-tsa.conf file>

<command>:

-i  : install windows service

-r : remove windows service

Example :

To install the windows service:

wrapper-windows-x86-64 -i c:\SoftwareAg\Terracotta\server\wrapper\conf\wrapper-tsa.conf

To remove the windows service:

wrapper-windows-x86-64 -r c:\SoftwareAg\Terracotta\server\wrapper\conf\wrapper-tsa.conf

Note: If you made any changes in the wrapper-tsa.conf you will have to remove the windows service and recreate it so the changes will take effect. And choose the right script for your server, in this example we used the script for 64bit processor.

7. Start Terracotta using the command line

After configuring the tc-config.xml, you can use the following command to start the terracotta server array:

SoftwareAg\Terracotta\server\bin\start-tc-server -f <tc-config.xml configuration file> -n <terracotta server name>

<terracotta server name>: is the name of the teracotta server which we are going to start using the command-line, it must be one of the servers defined in the config file ‘tc-config.xml’

Example:

start-tc-server -f c:\SoftwareAg\Terracotta\conf\tc-config.xml -n TcServer1

In Unix/Linux run the command in background as follows:

nohup start-tc-server -f c:\SoftwareAg\Terracotta\conf\tc-config.xml -n TcServer1 &

At the end I would like to thank my friend Bassem Elsodany for helping me on this tutorial.

Thank you for visiting our website. We are looking forward reading your comments and questions.

Follow us:

on twitter: @WM_Expert

Group on LinkedIn: webmethodsExpert.com

(C) 2015 Hossam Elsharkawy. All rights reserved.

Create/Manage KeyStore and TrustStore

This tutorial will discuss how create and manage the keystore and truststore. We will be using openSSL (open source tool), and the java keytool (existing with any jvm installation).

If you are not familiar with the security certificates and how it works,It is strongly recommended to review our last articles ‘creating security certificate tutorial’, here is the link:

https://webmethodsexpert.com/2014/11/24/creating-security-certificate-tutorial/

We will discuss the following points :

  1. What is key store and trust store?
  2. Why using the key store and trust store?
  3. Create the keystore.
  4. Manage the store with the java keytool.

 

1. What is key store and trust store?

It is a password protected file which is used to store security certificates, private keys, and root security certificates. The most common types are JKS (Java ket store), and PKCS12. The key store and trust store have the same format and capabilities, the difference is in how you use them in your application.

Key store is used when your server is offering a secured connection (ex. https) to clients or servers, and it stores pair of private key, and security certificate.

Trust store is used when you receive secured calls (ex. https), it stores the following:

  1. Root security certificate (Certification authority certificate) : which is used to trust all the certificate issued by specific entity. Ex. Verisign certificate.
  2. The partner’s self-signed certificate : add the security certificate of the server calling you if you in the development or test servers and you use self-signed certificate, or if you have a partner who you trust and who uses self-signed certificate.

2. Why using keystore and truststore?

‘Security in depth’ is a concept which promotes the idea of creating layers of security, and more layers = more security. So by protecting your private key, and the certificate you trust in case of the trust store by putting them in a password protected file will add a layer of security.

To make it easier imagine the following situations :

  • Your private key file is stored in a location in your application/server (in some cases without encryption), so anyone can access your server can take a copy from it and use it to decrypt your messages, or pretend that the message is coming from you.
  • You use a specific folder to store the root security certificates, or partner security certificates you trust. So if someone copied a fake certificate in this folder your server will accept requests from untrusted server.

The two above situations can be avoided by using the keystore and truststore.

3. Create the keystore

For the keyStore you need to store your private key file, and your server certificate. You have two ways to do it:

  1. Use the openSSL to generate the keystore with the private key and the certificate in the PKCS12 fromat (and you can convert it to JKS format with the java keytool).
  2. Use the KeyTool to create the the JKS keystore, this option is not valid if you already have the certificate and private key. The only way to do it is by creating the private key, and generate the CSR (certificate signing request). This is not always practical specially in the case of the self-signed certificate. (we will not cover this way in the tutorial).

So follow these steps to create your keystore:

1. Create the key store in the PKCS12 format. by executing this command in the openSSL:

openssl pkcs12 -export -name myAlias -in myServer.crt -inkey myServer.key -out myKeyStore.p12

myServer.key : is the server’s private key
myServer.crt : is the server’s security certificate
myAlias : is the alias you will be using in your code to access the private key. The alias must be unique in each keystore, the alias is unique in this case as we are creating a new store.
myKeyStore.p12:  is the name of the new keystore generated from the command.

Note : the new keystore ‘myKeyStore.p12’ will be in the bin directory of the openSSL.

2. Converting the keystore from the PKCS12 to JKS

We will use the java keytool which is a part from the installation of the JVM, you should find it in the following bin folder :’\jvm\jvm\bin’

keytool -importkeystore -srckeystore myKeyStore.p12 -srcstoretype pkcs12 -destkeystore myKeyStore.jks -deststoretype jks

4. Manage the store with the java keytool.

Creating the truststore

The following command can be used to import the root certificate of the self-signed certificate.

keytool -import -file server.crt -alias myCertAlias -keystore myTrustStore.jks

server.crt: The security certificate you want to import to the truststore.

myCertAlias: The unique alias you will be using to access the certificate from the store

myTrustStore.jks: The name of the truststore file. If the file doesn’t exist the keytool will create a new file, and if it was existing the certificate will be added to it.

Delete certificate from the truststore

To delete a certificate from an existing truststore.

keytool -delete -alias myCertAlias -keystore myTrustStore.jks

myCertAlias: the alias of the certificate to be deleted.

myTrustStore.jks: the name of the keystore which contain the certificate ti be deleted.

List the certificates in the Store

List the items in the store, usually we use it to see what is in the truststore as it might contains more than a certificate, however you can use it to see the contents of keystore.

Keytool -list -keystore mytruststore.jks

mytruststore.jks: is the name of the store file (keystore or truststore)

Change Alias in Trust Store or key store

To change the alias of an existing entry in the store use the following command:

keytool -changealias -alias oldAlias -destalias newAlias -keystore myStore.jks

oldAlias: is the old alias name to be changed.

newAlias: is the new alias name.

myStore.jks: the JKS file name which contain the alias to be changed.

 

Thank you for visiting our website. We are looking forward reading your comments and questions.

Follow us:

on twitter: @WM_Expert

Group on LinkedIn: webmethodsExpert.com

(C) 2014 Hossam Elsharkawy. All rights reserved.