2.2. Configuring the xGT Server

Most configuration parameters have reasonable defaults that work in many cases, and installations generally won’t need to change them. The main exceptions to this guidance is the security information:

  1. The defined security labels and “group-label” connections may need to be updated to reflect a site’s specific user base and user-authentication system. Details of this set up are in the Configuring Groups and Labels section.

  2. The AWS credential information has no reasonable defaults for securely accessing data in S3 buckets.

  3. To run with SSL encryption between the Python client and the xGT server the configuration parameters for system.hostname, system.ssl_root_dir, and system.usessl must be provided.

Configuring the xGT server is done using key-value pairs. The pairs can be given either in configuration files written in JSON format or as command line arguments when launching xgtd, the xGT server process.

There are two standard locations for the configuration file: /home/xgtd/.xgtd.conf and /etc/xgtd.conf. When launched, the xgtd application will first look for a configuration file at /home/xgtd/.xgtd.conf. If the file doesn’t exist, xgtd will look at /etc/xgtd.conf. Only one of these configuration files will be read, and no message is given if neither of these files are found.

The xgtd application will next process configuration files given as program arguments. An arbitrary configuration file can be used by passing the following program argument to xgtd: -c /path/to/xgtd.conf.

Users may split configuration information into multiple files and repeat the -c argument. Users may also give a config file on the command line when a config file exists in one of the standard locations. A config file in the standard location is processed first, and then files given on the command line are processed in the order they are given (left to right). This results in later configuration for the same key overriding earlier configuration for that key.

xGT also supports providing a single key-value configuration item in the form of a program argument: -Dkey=value or -Dkey:value. These -D options can appear multiple times and repeated keys are set to the latest appearance in the command line (left to right). Users can mix -c and -D options. They are collectively processed in a left to right manner.

The following keys for configuring xGT are supported. The Boot Only column indicates if the configuration variable can only be set at system startup. Changes to the value of a boot only variable after system startup will be ignored.

Key

Type

Default

Boot Only

Description

audit.config_file

string

Y

Provides the log4cxx configuration file name.

license.core_count

int

Number of physical cores on the system

Y

Controls how many cores to checkout from the license manager.

license.feature

string

Standard xgtd license feature

Y

Controls the feature to checkout in a license.

license.server

string

Port 6200 of localhost

Y

Controls the server network path xgtd will look for when checking out a license. The format is port@hostname. Multiple paths may be given, but should be seperated by a colon (:).

logging.filepath

string

/tmp/

Y

Provides the directory path where the log file will be written. If the filepath is “stdout” or “stderr”, then the log stream is written to standard out or standard error.

logging.fileprefix

string

xGT

Y

Provides the prefix of the log file name.

logging.level.<component>

string

warning

Sets the level of detail to place into a log stream for the given logging component. The components are described in Logging Components. The levels are: “debug”, “info”, “warning”, “fatal”.

metrics.cache

bool

true

Controls whether the metrics cache is running and generating statistical information about each frame. These statistics are used for query order optimization.

security.adminlabel

string

xgtadmin

Y

Value for the administrator label.

security.grouplabelfile

string

Y

The location of the group label file listing the mappings from groups to security labels to be loaded at boot time.

security.labelfile

string

Y

The location of the label file listing the security labels to be loaded at boot time.

security.session_refresh_window

int

-1

The time in seconds for how often to refresh the life extent of a session. A value of -1 indicates an unlimited time meaning a refresh will always be done.

security.session_ttl

int

-1

The time-to-live for the server. The maximum amount of time in seconds that a session will stay alive. A value of -1 indicates no limit.

system.hostname

string

localhost

Y

Controls the hostname (or IP address) the server will listen on for client connections. An IP address or “localhost” are allowed.

system.io_directory

string

Server’s current working directory

Y

All input/output (ingest/egest) must be done in this filesystem location or below (sandbox directory).

system.io_follow_symbolic_links

bool

false

Y

Controls whether or not to follow symbolic links in the underlying filesystem.

system.io_threads

int

16

Controls the number of I/O threads xGT uses per file. The number will never exceed the system cores count including hyperthreads.

system.locale

string

C

Y

Locale for comparing strings. Details provided in Configuring the locale.

system.max_memory

int

Available system RAM

Y

Controls the maximum amount of memory (in GiB) that xGT will use. The value given is capped at the available system RAM.

system.port

int

4367

Y

Controls the port the server will listen on for client connections. Valid values are [0, 65535].

system.ssl_root_dir

string

Home directory of the user running xgtd

Y

The path to the root directory that holds the server’s SSL certificates and private keys.

system.usessl

bool

false

Y

Controls whether to turn on SSL authentication between the client and server.

system.worker_threads

int

Number of cores including hyperthreads on the system

Y

Controls the number of worker threads xGT uses. The number will never exceed the system cores count including hyperthreads.

The log filename is created using both logging.filepath and logging.fileprefix. Assuming a fileprefix of “prefix” and a filepath of “/path/to”, the log file will be created with a name: /path/to/prefix.XYZ, where XYZ is chosen by the logger and usually involves a date and timestamp.

Consider this example configuration file located at /path/to/xgtd.conf:

{
  "system": {
    "worker_threads": 16,
    "io_threads": 10,
    "port": 4369
  },

  "system.locale": "en_US.UTF-8"
}

To launch xgtd using this configuration file and supplementing with a definition for system.host:

$ xgtd -c /path/to/xgtd.conf -Dsystem.host=127.0.0.1

To launch xgtd using this configuration file but overriding the worker_threads configuration value:

$ xgtd -c /path/to/xgtd.conf -Dsystem.worker_threads=8

To launch xgtd using multiple configuration files:

$ xgtd -c /path/to/xgtd_conf1.conf -Dsystem.port=4369 -c /path/to/xgtd_conf2.conf

2.2.1. Configuring Groups and Labels

The collection of groups and labels is used extensively by the Access Control system. Users are not configured in xGT, relying instead on some external authentication system such as LDAP to manage the users. This external authentication system is queried for a list of groups of which an authenticated user is a member. The xGT application maintains recognized groups, security labels (one may imagine these to be names of roles), and which groups possess which labels.

These labels and group-to-label relationships are held in CSV files that are read into xGT when it launches. The configuration variables security.labelfile and security.grouplabelfile indicate where xGT should find these CSV files. To establish appropriate security configuration, the content of the two CSV files should be updated. It is recommended that these CSV files contain the “master” copy of the groups and labels information. It is possible to alter the online data frames holding this information (with the appropriate administrator privilege), but the only way this information is remembered across application restarts is if the information is stored into the CSV files.

An authenticated user may belong to several groups, each of which is associated with many security labels. The union of the labels that are reachable through the groups that the user belongs to is called the user’s label set.

An example group and label setup is shown below. The groups listed are those that exist in an external authentication system such as LDAP. In this example, a user that belongs to groups group1 and group3 has a label set consisting of labels labelA, labelB, and labelD. A user that belongs to group adminGroup has the label xgtadmin in their label set.

Example contents of security.labelfile:

xgtadmin
labelA
labelB
labelC
labelD

Example contents of security.grouplabelfile:

adminGroup, xgtadmin
group1, labelA
group1, labelB
group2, labelC
group2, labelD
group3, labelD

2.2.2. Configuring Administrator Privileges

Within the xGT application, there is a special security label that gives administrator privilege. This security label can be set by the security.adminlabel configuration variable, and its default is “xgtadmin”. Any user that has the configured security.adminlabel in their label set has administrator privileges.

By default, xGT is configured to authenticate users using their local UNIX credentials. Section User Authentication and Access Control explains in more detail how authentication operates for the xGT server. To configure an xGT site administrator, the group xgtgroup can be created locally on the Linux system running xGT and added to any existing UNIX user on that system. xgtgroup is the default name of the group that maps to the administrator label xgtadmin. A Linux user belonging to that group can now log in to xGT using their regular Linux credentials and will have system administrator privileges inside the xGT server.

The default contents of the security.labelfile provided with the xGT installation are as follows:

xgtadmin

The default contents of the security.grouplabelfile provided with the xGT installation are as follows:

xgtgroup,xgtadmin

Any user that has the security.adminlabel in their label set has unrestricted visibility and access to any data in the server. Any access control check with a user that holds the security.adminlabel behaves as though the user holds all possible labels.

2.2.3. Configuring the locale

The system.locale (locale) is used by xGT to impact how to compare two different strings according to the lexicographic comparison rules defined by the locale. The default value for locale is “C”, which essentially means using the standard C library for string comparisons.

The xGT configuration mechanism will check every configured value for semantic correctness. This means that before a configured value is accepted as valid, xGT will try to configure the underlying C++ and xGT runtime systems passing in the configured value. If no exception is thrown, the string is accepted as a valid locale value.

2.2.4. Using an SSL Secure Channel

By default xGT uses an insecure channel, but an admin or user can enable a secure channel using SSL certificates. To run a secure server, pass the flags -s (or --ssl) and -d (or --ssl_root_dir) when starting the xgtd executable. The ssl_root_dir argument should be the path to the root directory that holds the server’s SSL certificates and private keys. A user can also turn on the secure server by setting the configuration variable system.usessl to True. Setting the configuration variable system.ssl_root_dir is an alternative way to specify the root directory that holds the server’s SSL certificates and private keys. xGT expects the following directory structure:

.
├── certs
│   ├── ca-chain.cert.pem
│   └── server.cert.pem
└── private
    └── server.key.pem

To connect to an xGT server using SSL, the client needs to pass the following flags to the xgt.Connection method: ssl, ssl_root_dir, and ssl_server_cn. The ssl flag needs to be set to true. The ssl_root_dir flag should be set to the root directory containing the SSL certificates and private keys. The ssl_server_cn flag should be set to the common name for the server listed on the server side SSL certificate. The xGT client expects the following directory structure for SSL certificates and private keys:

.
├── certs
│   ├── ca-chain.cert.pem
│   └── client.cert.pem
└── private
    └── client.key.pem