1. Installing xGT¶

Running xGT on-premises can eliminate the need to move sensitive data off-premises (e.g., into a cloud repository) and, depending on the server configuration, can speed up the ingestion of large volumes of data.

1.1. Supported Environments¶

The Trovares xGT server runs on an x86-64 platform running enterprise Linux distributions. The reference implementation is RHEL 9.3 distributed via an RPM. For information about running xGT on other Linux distributions contact gettingstarted@trovares.com.

Required RHEL 9.3 Packages¶
Package Name	Minimum Version
apr	1.6.0
apr-utils	1.6.0
bzip2-libs	1.0.6
hwloc-libs	1.11.8
krb5-libs	1.15.1
numactl	2.0.12
openssl-libs	1.0.2k
zlib	1.2.7

Note that the required packages will be installed as dependencies when installing the xGT distribution. However, for those sites without direct internet access, pre-installing these packages is required.

1.1.1. Linux Server Configuration¶

Running with the Transparent Huge Pages (THP) enabled will allow xGT to manage large data buffers much more efficiently than if THP is disabled. If possible, we recommend that THP is enabled.

To determine if THP is enabled, run the following command:

$ cat /sys/kernel/mm/transparent_hugepage/enabled

which, if enabled, produces a result such as: [always] madvise never.

If THP is currently not enabled and the administrator wishes to enable it, the following command should be run (as root):

$ echo always > /sys/kernel/mm/transparent_hugepage/enabled

1.1.2. Python Environment¶

For every platform on which the xGT client will be run, a Python environment must be set up. Trovares supports using Python 3.7+.

In addition to the OS packages (e.g., python39), several Python packages are required:

Required Python Packages¶
Pip Package Name	Minimum Version
grpcio	1.24.0
isodate	0.6.1
protobuf	3.19.0
pyarrow	8.0.0

There are also some optional packages that add more capability to using the xGT client.

Optional Python Packages¶
Pip Package Name	Minimum Version	Description
jupyter		Allows using Jupyter Notebooks as an interactive environment to drive xGT.
pandas	0.24.2	Allows importing / exporting data to / from pandas frames.
gssapi	1.6.0	Allows Kerberos connections.

If there is a requirement that Python scripts can be run on the same server that is running the Trovares xGT server, then this installation command is required assuming Python 3.9:

$ sudo dnf install python39

If installing the GSSAPI for the client, the Python package will require you have the following OS packages on RHEL: krb5-devel, gcc, and python39-devel assuming Python 3.9.

Pip by default will install the most current version. Required packages will be automatically installed along with xGT like so:

$ pip install xgt

The optional packages can be installed separately, or they can be installed along with xgt like so:

$ pip install xgt[extra]

If installing on a site without direct internet access, dependencies for the xGT Python client can be downloaded as wheel files, copied to the installation site and used when installing the Python package. It’s recommended that the machine used to download the wheel files have the same operating system, architecture, pip version and Python version to obtain compatible wheel files. To download the wheel files on a machine with internet access do:

$ pip download xgt

Copy all the .whl files to the installation site in a specific folder.

Then when installing the Python package do:

$ pip install --no-index --find-links /PATH-TO-WHEEL-DIRECTORY xgt-WHEEL-NAME.whl

The pip version may need to be updated as well and can be downloaded and installed similarly:

$ pip download pip
$ pip install PIP-WHEEL-NAME.whl

1.1.3. Assistance¶

To acquire a license for Trovares xGT or for questions about configuring Trovares xGT, contact gettingstarted@trovares.com.

1.2. Licensing¶

The server component of xGT, called the xgtd process, is distributed as an encrypted executable licensed on a specific server. The server is required to have a valid license in order to run.

Detailed information about licensing is provided in License Management System.

The following steps are required to get xGT installed on your server with a node-locked license.

Step 1: Install the license tool and get host-specific information of the intended platform. Download the RPM provided as link by Trovares (typically provided by email).

Then install it:

sudo dnf install xgt-license-tools-X.Y.Z-1.x86_64.rpm
/opt/xgtd/bin/lmxendutil -hostid

A sample output from such a run:

/opt/xgtd/bin/lmxendutil -hostid
LM-X End-user Utility v5.0
Copyright (C) 2002-2021 X-Formation. All rights reserved.

ETHERNET: ens3
HostID: 000C2BC32G83

ETHERNET: ens4
HostID: 0A42F8D4C3F0

HOSTNAME: wyvern
HostID: wyvern

USERNAME: jacob
HostID: jacob

IPADDRESS: 192.128.121.148
HostID: 192.128.121.148

IPADDRESS: 192.138.111.*
HostID: 192.138.111.*

IPADDRESS: 192.118.*.*
HostID: 192.118.*.*

It may also help to capture the following information:

$ free -h
$ lscpu

Capture the entire output and send that to gettingstarted@trovares.com.

Step 2: Install the license.

Trovares creates a license specific for the machine your xgtd server is running on. You will receive a license from us.

When you receive the license, put it in /etc/xgtd/licenses/ on the xgtd server machine. It should be named xgtd.lic.
Step 3: Download and install the electronic distribution.

Download the RPM provided as link by Trovares (typically provided by email).
```
sudo dnf install xgt-server-X.Y.Z-1.x86_64.rpm
```
Of course, the name of your distribution may be different than the one shown here.

Step 4: Run the xgtd server.

To start xgtd:

$ systemctl start xgtd

To check the status of xgtd:

$ systemctl status xgtd

Note that if the installation has been successful, you should see something like this:

$ systemctl status xgtd
● xgtd.service - xgtd
   Loaded: loaded (/etc/systemd/system/xgtd.service; disabled; vendor preset: disabled)
   Active: active (running) since Fri 2020-11-06 19:05:40 UTC; 2s ago
 Main PID: 9060 (xgtdBinary)
   CGroup: /system.slice/xgtd.service
           ├─9060 /opt/xgtd/bin/xgtd -c /etc/xgtd/xgtd.conf -p 4367
           └─9061 /opt/xgtd/bin/xgtd -c /etc/xgtd/xgtd.conf -p 4367

Nov 06 19:05:40 xgtd-server-host systemd[1]: Started xgtd.

To stop xgtd:

$ systemctl stop xgtd

Note that it may be necessary to prepend sudo to these commands in your environment.

If the systemctl start xgtd command has been performed followed by a systemctl status xgtd, and the report says that the xgtd process has failed, it may be helpful to look in /var/log/xgtd/ for logging and auditing output or use journalctl -u xgtd.

For licensing error messages check LM-X Error Messages.

1.3. Site xGT Administration¶

The setup and configuration for Trovares xGT can be done by someone with root or sudo privilege on the local server.

It is also possible to establish non-root xGT administrators by adding local Linux users to the xgtd group.

This command adds a user to the xgtd group:

$ sudo usermod -aG xgtd SomeLinuxUser

Note that this must be done after the RPM installation process is complete as described in section Installing xGT.

Any user that is in the xgtd group is able to update the xGT site configuration files. Also, such a user is able to start, stop, restart, and get status of the xgtd service:

$ sudo systemctl start xgtd
$ sudo systemctl status xgtd
$ sudo systemctl restart xgtd
$ sudo systemctl stop xgtd