1. Using the Docker Image

This command is a common way of running the Rocketgraph xGT Docker container:

$ docker run --name xgt --detach --publish 4367:4367 \
      --volume=$PWD/conf:/conf \
      --volume=$PWD/data:/data \
      --volume=$PWD/xgtlog:/log \
      rocketgraph/xgt

The command starts xGT listening on the host port 4367, the default port used by xGT. It maps a configuration directory to allow configuration of xGT’s behavior. It maps a data directory to allow file I/O operations to go through the server file system. It maps a log directory to access the log and audit files written by the server. Each of these options will be discussed in more detail below.

Python scripts using the xGT client can now connect to the server. This script prints the configuration of the server:

import xgt
server = xgt.Connection()
config = server.get_config()
print("\n".join([f"{k} = {v}" for k,v in sorted(config.items())]))

The running Docker container can be terminated using this command:

$ docker stop xgt

1.1. Mapping the Config Directory

Rocketgraph’s xGT server supports quite a few configuration options. The configuration files are in the /conf directory in the container. The easiest way to change the configuration is to map the container’s configuration directory to the host. The --volume=/host/directory:/conf parameter maps the given host directory to the config directory in the container. Starting the Docker image while mapping the volume will create the config directory along with the files in it on the host if the directory doesn’t already exist. Run this command to initially populate the config directory with the default configuration files.

$ docker run --name xgt --detach --publish 4367:4367 \
      --volume $PWD/conf:/conf \
      rocketgraph/xgt

The $PWD/conf directory should now contain default versions of the configuration files.

Name

Description

audit.xml

Configuration file to setup auditing for the xGT server.

grouplabel.csv

Access control configuration file to setup the mappings from groups to labels.

label.csv

Access control configuration file that lists the available labels.

licenses/

Directory where the license for the xGT server is stored.

xgtd.conf

The main configuration file for the xGT server.

You can now update any of these configuration files to suit your local requirements. Updates to the configuration files will not take effect until xGT is restarted. To restart the container, issue the command:

$ docker restart xgt

1.2. Mapping the Data Directory

xGT supports file I/O via the server’s file system, and it is much faster than I/O through the client. To use server I/O, a data directory must be mapped from the host file system to the xGT container’s data directory: /data. The --volume /host/directory:/data parameter maps the given host directory to the data directory in the container.

$ docker run --name xgt --detach --publish 4367:4367 \
      --volume $PWD/data:/data \
      rocketgraph/xgt

This command will use the $PWD/data directory on the host file system as the location from which to ingest data directly into the server and the location where the server will save data to files.

To see an example of the server saving some data into a file (on the host file system), run this python script:

import xgt
server = xgt.Connection(auth = xgt.BasicAuth('admin'))
server.run_job("MATCH (j:xgt__Running_Jobs) RETURN j INTO jobs_history")
jobs_history = server.get_frame('jobs_history')
jobs_history.save('xgtd://jobs_history.csv', headers=True)

This program should result in the xGT server saving some data into $PWD/data/jobs_history.csv.

1.3. Mapping the Log and Audit Directory

xGT writes logging information to a log file and audit information to an audit file. An easy way to see these files is to map xGT’s log directory (/log) to the host. The --volume=/host/directory:/log parameter maps the given host directory to the log directory in the container.

$ docker run --name xgt --detach --publish 4367:4367 \
      --volume=$PWD/xgtlog:/log \
      rocketgraph/xgt

This command maps the container’s log directory to the $PWD/xgtlog directory on the host. The default log file is xgtd.log, and the default audit file is audit.log.

1.4. Adding Your License

It is possible to manage a licensed deployment on-premises that uses the Rocketgraph xGT Docker image instead of installing from an RPM.

The Mapping the Config Directory section describes how to run a Docker container with custom configuration settings. One of those settings can be the license file itself.

The first step is to go through the process of obtaining a license file as described in License Management System. There are two exceptions to the procedure described for obtaining a license file:

  1. The location of the license file is the host file system location described in section Mapping the Config Directory.

  2. There is no need to install the application from an RPM; the application is run as a Docker container.

After initially setting up a host file system with a $PWD/conf directory, copy the obtained file license to the $PWD/conf/licenses/xgtd.lic location and relaunch the Docker container.

1.5. Configuring Logging and Auditing

After mapping the config directory as described in Mapping the Config Directory, the logging and auditing features of xGT can be modified from the defaults. Configuring logging involves modifying the xgtd.conf file. Configuring auditing is done by modifying the audit.xml file.

See Logging and Auditing for details.

1.6. Enabling Access Control

Mapping the config directory as described in Mapping the Config Directory allows enabling access control. This involves setting up the available access labels in the label.csv file and setting group label mappings in the grouplabel.csv file.

See Access Control for a discussion of how access control works in xGT and Configuring Groups and Labels for more details on configuring access control.

1.7. Using SSL between Client and Server

A secure channel using SSL certificates can be enabled for communication between the client and server. Turning it on requires having mapped the config directory as described in Mapping the Config Directory.

The host needs a directory containing the directory structure, certs, and private key described in Using an SSL Secure Channel. This directory should be the subdirectory ssl/ inside the host’s mapped config directory, which for the example above would be $PWD/conf/ssl.

Setting this variable in the xgtd.conf file turns on SSL.

"system.usessl" : true,

Mutual TLS can also be enabled for a more secure connection requiring the client to authenticate its identity with certificates. To enable mTLS, add this variable to the xgtd.conf file:

"system.usemtls" : true

A script using the client would then need to pass extra parameters when creating a connection.

See Using an SSL Secure Channel for more details.

1.8. Enterprise Authentication using LDAP

Rocketgraph’s xGT Docker image can be configured to use an LDAP directory server running on a customer’s network. The host system running Docker must be configured appropriately to be an LDAP client. A common configuration is to use the FreeIPA framework for both servers and clients: https://www.freeipa.org.

If the host system has been configured as a FreeIPA client, then a simple approach to enable xGT inside a Docker image to use the FreeIPA LDAP server for authentication is the following:

When running the xGT image mount the following volumes (only the pam and sss volumes are required for LDAP, conf and xgtlog are convenient):

$ docker run --name xgt --detach --publish 4367:4367 \
      --volume=$PWD/conf:/conf \
      --volume=$PWD/data:/data \
      --volume=$PWD/xgtlog:/log \
      --volume=$PWD/pam:/etc/pam.d \
      --volume=/var/lib/sss:/var/lib/sss \
      rocketgraph/xgt

In the mounted pam directory modify the xgtd file to:

#
# /etc/pam.d/xgtd - specify the PAM behavior for xgtd
#

auth       required     pam_sss.so
account    required     pam_sss.so
session    required     pam_sss.so

The xGT Docker image must be restarted after making these changes.

Mounting the /var/lib/sss volume on the same location inside the Docker image enables xGT to use the pam_sss module to connect to the sssd daemon running on the host without requiring extra services running inside the Docker image.

For more details on LDAP authentication, IPA and SSSD see LDAP User Password Authentication.