Installation Procedure
Chapter 2. Installing GT.M

Create a backup copy of any existing version of GT.M before running the installation procedure. The installation procedure overwrites any existing version of GT.M in the installation target directory.

Important

Never install a GT.M release into an existing directory overwriting another release that might be needed for research or recovery and never on the one currently in use. FIS recommends installing each version of GT.M in a separate directory using the naming convention /usr/lib/fis-gtm/version_platform , where version is the GT.M version being installed and platform is the hardware architecture. For example, /usr/lib/fis-gtm/V6.1-000_x86_64.

Run the installation procedure as root for everything to install correctly.

Find or create a temporary directory to hold your GT.M distribution files and change to that directory.

Example:

$ cd /tmp

or

$ cd /usr/tmp

	Note
	When choosing a temporary directory, keep in mind the following points: Whether it is safe to use a directory (like /tmp) subject to concurrent use by the operating system, applications, and so on. Whether you can protect any sensitive information in temporary files with appropriate access permissions.

Unpack the distribution to the current directory with a command such as the following (your UNIX version may require you to first use gzip to decompress the archive and then tar to unpack it; the tar options may also vary):

$ tar zxvf /Distrib/GT.M/gtm_V55000_linux_x8664_pro.tar.gz

	Note
	The name of the device and the tar options may vary from system to system.

The GT.M distribution contains various GT.M system administration scripts. These include:

configure      to install GT.M
gtm            sets a default user environment and starts GT.M.     
gtmbase        An example to set up a default user environment.

Note that gtmbase is simply an example of the type of script you can develop. Do not use it as is.

For more information on using gtmbase and other scripts, refer to Chapter 3: “Basic Operations”.

To start the GT.M installation procedure, execute the following script:

#./configure

The configure script displays a message like the following:

           GT.M Configuration Script
GT.M Configuration Script Copyright 2009, 2012 Fidelity Information Services, Inc. Use of this
software is restricted by the provisions of your license agreement.

What user account should own the files? (bin) 

Enter the name of the user who should own GT.M distribution files. The default is bin. If there is no user with the name bin, the configure script asks for an alternate user who should own GT.M distribution files.

What group should own the files? (bin) 

Enter the name of the group who should own GT.M distribution files. The default is bin. If there is no group with the name bin, the configure script asks for an alternate group who should own GT.M distribution files.

Should execution of GT.M be restricted to this group? (y or n)

Choose y to restrict the ownership of your GT.M distribution to the specified group. This is a security-related option. By default, GT.M does not restrict the ownership to a group.

In what directory should GT.M be installed?

Enter a directory name, such as /usr/lib/fis-gtm/V6.1-000_x86_64. If the directory does not exist, the configure script displays a message like the following:

Directory /usr/lib/fis-gtm/V6.1-000_x86_64 does not exist. 
Do you wish to create it as part of this installation? (y or n)

Choose y to create the directory or n to cancel the installation.

Installing GT.M...

This is followed by a confirmation message for installing UTF-8 support.

Should UTF-8 support be installed? (y or n)

Choose y to confirm. If you choose n, Unicode functionality is not installed.

	Note
	GT.M requires at least ICU Version 3.6 to install the functionality related to Unicode.

If you choose y, the configure script displays a message like the following:

Should an ICU version other than the default be used?

If you choose n, the configure script looks for the symbolic link of libicuuc.so to determine the default ICU version.

If you choose y, the configure script displays a message like the following:

Enter ICU version (at least ICU version 3.6 is required. 
Enter as <major-ver>.<minor-ver>):

Enter the ICU version number in the major-ver.minor-ver format. The configure script displays the following message:

All of the GT.M MUMPS routines are distributed with uppercase 
names. You can create lowercase copies of these routines 
if you wish, but to avoid problems with compatibility in 
the future, consider keeping only the uppercase versions 
of the files.

Do you want uppercase and lowercase versions of the MUMPS routines? (y or n).

Choose y to confirm. The configure script then displays the list of MUMPS routines while creating their lowercase versions. Then the script compiles those MUMPS routines. On platforms where GT.M supports placing object code in shared library, it creates a library libgtmutil.so with the object files of the utility programs and GDE distributed with GT.M. On these platforms, it asks the question:

Object files of M routines placed in shared library /usr/lib/fis-gtm/V6.1-000_x86_64/libgtmutil.so. 
Keep original .o object files (y or n)? 

Unless your scripts require separate object files for these routines, you can safely delete the .o object files, and place $gtm_dist/libgtmutil.so as the last element of gtmroutines in lieu of $gtm_dist.

The configure script then asks you:

Installation completed. Would you like all the temporary files removed from this directory? (y or n)

Choose y to confirm. FIS recommends deleting all temporary files.

Congratulations! GT.M is now installed on the system. Proceed to “Reference Implementation Plugin - Shared Library Dependencies” section to identify and resolve shared library dependencies on your system and then Chapter 3: “Basic Operations” to set up a default user environment.

Reference Implementation Plugin - Shared Library Dependencies

The database encryption and TLS reference implementation plugin requires libgcrypt11, libgpgme11, libconfig 1.4.x, and libssl1.0.0 runtime libraries. Immediately after installing GT.M, install these libraries using the package manager of your operating system. If these runtime libraries are not available, the plugin may produce errors like the following (for example on Ubuntu x86_64):

%GTM-I-TEXT, libxxxxxx.so.<ver>: cannot open shared object file: No such file or directory

..where libxxxxxx is either libgcrypt, liggpgme, libconfig, libgcrypt, or libssl and <ver> is the version number of the libxxxxxx shared library. To locate missing share library dependencies in your reference implementation plugin, execute the following command:

$ ldd $gtm_dist/plugin/libgtm* | awk '/^.usr/{libname=$0}/not found/{print libname;print}'

This command produces an output like:

/usr/lib/fis-gtm/V6.1-000_x86_64/plugin/libgtmcrypt_openssl_AES256CFB.so:
        libcrypto.so.10 => not found
/usr/lib/fis-gtm/V6.1-000_x86_64/plugin/libgtmcrypt_openssl_BLOWFISHCFB.so:
        libcrypto.so.10 => not found
/usr/lib/fis-gtm/V6.1-000_x86_64/plugin/libgtmtls.so:
        libssl.so.10 => not found 

...which means that libcrypto.so.10 and libssl.so.10 shared libraries are missing from the system and the reference implementation plugin will produce a libxxxxxx.so.<ver>: cannot open shared object file: No such file or directory error during runtime. Note down the missing shared libraries and proceed as follows for each missing library:

• If libxxxxxx.so.<ver> is already installed: Set the environment variable LD_LIBRARY_PATH to include its location.

• If libxxxxxx is not installed: Install the runtime libxxxxxx library using the package manager; check for pre-packaged distributions for your operating system and ensure that it contains the library having version specified with <ver>.

• If libxxxxxx is installed but its version number is different from what GT.M expects (<ver>): You can either symlink the unversioned libxxxxxx.so library to libxxxxxx.so.<ver> (recommended) or recompile the reference implementation plugin. The instructions are as follows:

Creating a symbolic link from the unversioned .so (libxxxxxx.so) to libxxxxx.so.<ver>

1. Install the development libraries for libgcrypt11, libgpgme11, libconfig 1.4.x, libssl1.0.0. The package name of development libraries usually have the -dev suffix and are available through the package manager. For example, on Ubuntu_x86_64 a command like the following installs the required development libraries:

   sudo apt-get install libgcrypt11-dev libgpgme11-dev libconfig-dev libssl-dev

   These packages contain the unversioned .so library (libxxxxxx.so).

2. Find the directory where the unversioned .so library is installed on your system. Note down the name of the directory.

3. Login as root and change to the $gtm_dist/plugin directory.

4. Create the symlink from libxxxxxx.so to libxxxxxx.so.<ver>. For example, if libcrypto.so.10 and libssl.so.10 shared libraries are missing, create their symbolic links in $gtm_dist/plugin from the unversioned .so library location that you noted in step 2:

   ln -s /usr/lib/x86_64-linux-gnu/libcrypto.so libcrypto.so.10
   ln -s /usr/lib/x86_64-linux-gnu/libssl.so libssl.so.10

Note

The reference implementation plugin libraries are linked using the RPATH directive $ORIGIN which means that these libraries always start looking for library dependencies from the current directory. Therefore, it is safe to create symlinks for the missing libraries in $gtm_dist/plugin directory. Do not create symlinks to shared libraries in directories managed by package managers and never symlink incompatible library versions as it may not always lead to predictable results.

Recompiling the Reference Implementation Plugin

1. Install the development libraries for libgcrypt11, libgpgme11, libconfig 1.4.x, libssl1.0.0. The package name of development libraries usually have the -dev suffix and are available through the package manager. For example, on Ubuntu_x86_64 a command like the following installs the required development libraries:

2. Login as root and set the gtm_dist environment variable to point to the location of the GT.M distribution.

3. Note down the file permissions of the *.so files in $gtm_dist/plugin directory.

4. Unpack $gtm_dist/plugin/gtmcrypt/source.tar to a temporary directory.

   mkdir /tmp/plugin-build
   cd /tmp/plugin-build
   cp $gtm_dist/plugin/gtmcrypt/source.tar .  
   tar -xvf source.tar

5. Recompile the reference implementation plugin and install it in the $gtm_dist/plugin directory.

   make uninstall
   make 
   make install 
   make clean

6. Assign permissions noted in step 3 to the newly installed .so files in $gtm_dist/plugin.

Important

If you are running the V6.1-000 reference implementation plugin (database encryption and TLS replication) on a UNIX platform other than RedHat, please follow instructions from “Creating a symbolic link from the unversioned .so (libxxxxxx.so) to libxxxxx.so.<ver>” to create symlinks for the missing libcrypto.so.10 and libssl.so.10 shared libraries. GT.M UNIX distributions are compiled and linked on a RedHat platform where libcrypto.so.10 and libssl.so.10 version libraries are available from package managers. On UNIX platforms other than RedHat, these library versions may not be available from package managers and need to be linked to their unversioned .so libraries.