SOClass Configuration and Start Procedure

Activation/Deactivation of the SSL Bit-encrypting

A Brief Note about SSL

The Secure Sockets Layer (SSL) is a commonly-used protocol for managing the security of web browsing, e-mail, Internet faxing, instant messaging and other data transfers on the Internet. SSL has evolved to Transport Layer Security (TLS). SSL uses a program layer located between the Hypertext Transfer Protocol (HTTP) and Transport Control Protocol (TCP) layers, used in Internet. This protocol secures the transfer of private information, such as credit card numbers or passwords.

Configuring the SSL Bit-encrypting

The directory SOCLASS_HOME/server/etc/security contains 3 files and a directory with four files, related to SSL bit-encrypting:

• access.properties
  
• password.properties
  
• server.randseed
  
• keystore
  
  • jmxssl.keystore
    
  • jmxsslca.keystore
    
  • ssl.keystore
    
  • sslca.keystore
    

Both access.properties and password.properties files are related to the SOClass JMX Server users. The first file sets the access rights of the users and the second contains the passwords for them - encrypted. The server.randseed file represents a pre-generated random seed.

The jmxssl.keystore represents the private key of SOClass JMX Server and the jmxsslca.keystore represents the list of trusted certificate authorities for it. Respectively the ssl.keystore and sslca.keystore represent the private key and the list of trusted certificate authorities for the SOClass Server.

The configuration of the SSL behaviour is set in the properties file: SOCLASS_HOME/server/etc/config/serverssl.properties.

Turn on/off the SSL bit-encrypting:

Set the value (yes/no) of the ssl.mode property:

ssl.mode=yes (activates the SSL bit-encrypting)

or

ssl.mode=no (deactivates the SSL bit-encrypting)

Activate/deactivate the predefined random encryption key:

The SOClass system either uses a predefined encryption key, stored in a file on the server, or generates a random encryption key each time the SOClass server is restarted. Although the second option slightly slows down the start of the server, it is the more secured solution.

The choice of using or not a predefined encryption key is defined by the property ssl.random.

Set the value (Yes/No) of the ssl.random property:

ssl.random=yes (use the file set in server.randseed)

or 

ssl.random=no (bypass the file set in server.randseed)

When the property is set to “yes”, the system uses the predefined encryption key from the file indicated by the ssl.randomfile property.

ssl.randomFile=${so.home}/etc/security/server.randseed

The SOCLASS_HOME/server/etc/security/keystore directory contains the ssl.keystore file with the private keys used by SSL. These keys are in conjunction with the public key stored in the so.keystore file generated by the system during the installation of the certificate (see next section). The other file in that directory – sslca.keystore contains the list of trusted Certificate Authorities.

Detailed information about Properties Files can be found in an annex to the Developer’s Guide documentation.

Connection to the Relational Database System

The interfacing between a SOClass application and its related database is implemented through the JDBC drivers.

The JDBC technology is an API that allows access to virtually any tabular data source from the Java programming language. It provides cross-DBMS connectivity to a wide range of SQL databases, and with the JDBC API, it also provides access to other tabular data sources, such as spreadsheets or flat files.

The JDBC API allows developers to take advantage of the Java platform's "Write Once, Run Anywhere” capabilities for industrial strength, cross-platform applications that require access to enterprise data. With a JDBC technology-enabled driver, a developer can easily connect all corporate data even in a heterogeneous environment.

Annex to the Installation Guide illustrates the configuration procedures of the JDBC drivers for Oracle database management systems and the steps that have to be followed to complete these drivers configuration prior to the first start of the SOClass engine.

It is highly recommended to use the Oracle JDBC drivers provided with the Oracle Database that is going to be used for the respective Java version.

Starting the SOClass Server

Once the module’s jar files are deployed into the application server directory, the server is ready to install the module. The server will detect the new jars and integrate them into the system. At this stage stop the server after the installation of the module and restart it. Apart from creating the shortcuts in the desktop library and the binder, it will also be ready for use, waiting for clients to connect.

The file used to launch the application server is located into the application server directory: SOCLASS_HOME/server/bin

Executing in a console the following command will start the server:

Several modes of operation are available for the SOClass server starting process. Here is a list of the available options to use as a parameter when running the server from a shell.

Under Linux

Under MS Windows

First Server Start: Activation Key Request

Server activation is the licensing control procedure for the legal usage of the SOClass system. If the SOClass Server is newly installed on the computer, then it requires an activation key, based on hardware configuration.

The steps to obtain a SOClass activation key are the following:

1. Launch the server as described in the previous section.
2. The system will ask for several identification parameters such as:

• First and last name;
  
• Name of the organization unit;
  
• Name of the organization;
  
• Location including city, state, two letters country code, mail address, phone number, fax number and email address.
  

3. Confirm the accuracy of the information entered to complete registration. This will generate a message file in the SOCLASS_HOME/server/etc/activation directory.
4. Send the message file to the SOClass software provider. As a reply you will receive a file called “actk” that has to be copied into the SOCLASS_HOME/server/etc/activation directory.

It is important to backup the SOCLASS_HOME/server/etc/activation. When reinstalling the SOClass Server on the same machine, this directory should be restored.

The following code illustrates the SOClass activation request procedure:

- Phase 1, Installing Resource Manager 
- Phase 2, Performing Micro-Benchmark 
- Phase 3, Creating Registry fail.
Enter user information:
What is your first and last name?
  [Unknown]:  John Smith        
What is the name of your organizational unit?
  [Unknown]:  Documentation Unit
What is the name of your organization?
  [Unknown]:  Example Company
What is the name of your City or Locality?
  [Unknown]:  New York
What is the name of your State or Province?
  [Unknown]:  New York
What is the two-letter country code for this unit?
  [Unknown]:  US
What is your address?
  [Unknown]:  72 Main Street
What is your phone number?
  [Unknown]:  +1-212-234-5678
What is your fax?
  [Unknown]:  +1-212-234-5679
What is your e-mail?
  [Unknown]:  company@example.com
Is <CN=John Smith, OU=Documentation Unit, O=Example Company, L=New York, ST=New York, C=US, STREET=72 Main Street, 
PHONE=+1-212-234-5678, FAX=+1-212-234-5679, MAIL=company@example.com> correct?
  [no]:  y
Please wait...

Please send /home/user/so/server/etc/activation/message to 
activation@strategyobject.com to receive the activation key. Upon receipt of your activation, copy the ACTK file in the
/home/user/so/server/etc/activation folder and restart.
Press <Enter> to exit.

Once the activation procedure is successful, the server engine is ready to be restarted and to accept client connections and requests.

Traditional Server Start

Once the activation key has been received and copied into the proper directory, the server can be restarted. When ready the server should return the message: “Server is running (press <Enter> to shut down)...”.

The following example shows the server output on its first start after the activation:

- Phase 1, Installing Resource Manager 
- Phase 2, Performing Micro-Benchmark 
- Phase 3, Creating Registry 
- Phase 4, Installing Application Server 
- Phase 5, Loading Server Properties 
- Phase 6, Creating Document Binders
- Phase 7, Installing new SOM Modules 
- Phase 8, Check GCF table structures
- Phase 9, Starting Transaction Manager 
- Phase 10, Starting GCF Recovery, 6 binders.
- Phase 11, Checking GCF integrity
- Phase 12, Creating Server 
- Phase 13, Binding Server 
- Phase 14, Starting Server  
- Phase 15, Starting JMX Service  service:jmx:rmi://localhost:2104/jndi/rmi://localhost:2006/SOClassJMXServer

Server is running (press <Enter> to shut down)...

Stopping the SOClass Server Engine

To stop the SOClass server, simply press the key <enter> while the server process window has the focus. The server checks for connected users and displays information about them. Then appears the option to set shutdown delay “Set shutdown delay time in minutes (0 is default):” Pressing the key <enter> again will bring a prompt about starting the shutdown procedure “Shutdown procedure will be started. Do you want to continue? (y/n):” When confirming it a notification appears “Shutdown procedure has been started.” When the server stops, the system displays the message “Server was shut down”.

If there are any transactions in commit or rollback stage at the moment of the server shutdown command, it will wait for them to be completed for the time set under the ShutdownServer.Timeout property in the server.properties file. The default value is 5 minutes. During this timeout, when the server waits for the transactions to be completed, it will not allow any new transactions to be started.

If the ShutdownServer.BlockUntilFinish boolean flag is set to true, this will block the server shutdown procedure until all transactions in commit or rollback stage are completed.

It is not recommended to set this flag to true, because this can make the server unstoppable.

The Steps of the Server Start Procedure

The server start procedure initializes the components of the SOClass system. They are started asynchronously (taking advantage of Java multi-threading), and last step before starting the JMX Server consists in coordinating them all.

Other Operations Performed by the Server at Startup

1. Listing every jar file from the lib folder and adding it to the LIB_PATH environment variable (classpath style). The lib folder contains the code of the SOClass application server and the shared part of the SOClass platform.

2. Listing every jar file from the folder lib/ext and adding it to the EX_PATH environment variable. The lib/ext folder contains libraries of SOClass and third part APIs and also libraries not delivered by the Java Platform.

3. Listing every jar file from the patches folder and adding it to the PATCH_PATH environment variable. The patches folder (SOCLASS_HOME/server/patches) is reserved for future use (it might contain jar files overriding existing classes). If this folder doesn’t exist, you will have to create it when you are going to use server patches.

Jar files within the modules folder (usually created by the application developer) are not added to the classpath when the script is running. The classes inside these files become accessible later on when the server is running via classloaders.

4. Using the environment variables defined at steps 1-3 to construct the classpath.

5. Starting the server in a specific mode, depending on the additional option specified.

Additional Start Options