System Administration FAQs

General

How do I apply or update my license key?

If you have a version 1.0 string-type license key, then during initial platform installation, you can either specify your license key as an argument, for example:

./install.sh -l <your_license_key>

Or you may input it when prompted.

To apply a new license key string, use the following command:

gadmin license set <license_key>
or
gadmin license set @textfile

Example:

$ gadmin license set
<key>
[   Info] Configuration has been changed. Please use 'gadmin config apply' to persist the changes.
$ gadmin config apply
[Warning] No difference from staging config, config apply is skipped.
[   Info] Successfully applied configuration change. Please restart services to make it effective immediately.
$ gadmin restart all
[   Note] Restart the service(s)? (y/N)y
[   Info] Stopping ZK ETCD DICT KAFKA ADMIN GSE NGINX GPE RESTPP KAFKASTRM-LL KAFKACONN GSQL IFM GUI
[   Info] Stopping CTRL
[   Info] Stopping EXE
[   Info] Starting EXE
[   Info] Starting CTRL
[   Info] Starting ZK ETCD DICT KAFKA ADMIN GSE NGINX GPE RESTPP KAFKASTRM-LL KAFKACONN CTRL GSQL IFM GUI

If you have a version 2.0 file-type license key which is linked to a specific machine or cluster:

  • If this is the initial installation or you are updating a previous key file, then please see the document Advanced License Issues

  • If you are updating from a version 1.0 key string to a version 2.0 key file, please open a support ticket for the correct procedure.

When does my license key expire?

If you have a version 1.0 string-type license key, the following command will tell you your key’s expiration date:

gadmin status license

If you have a version 2.0 file-type license key which is linked to a specific machine or cluster, then run the following command:

curl -X GET "localhost:14240/restpp/showlicenseinfo"

If you are running TigerGraph v3.0+, run the following command:

gadmin license status

Example:

[Warning] License will expire in 0 days

What are the components of the TigerGraph platform?

Command Line Usage Name : Official Name

"GPE" : GPE,
"GSE" : GSE,
"RESTPP" : RESTPP,
"GSQL" : GSQL,
"EXE" : EXECUTOR,
"IFM" : INFORMANT,
"GUI" : GUI,
"CTRL" : CONTROLLER,
"KAFKA" : KAFKA,
"ETCD" : ETCD,
"ZK" : ZK,
"NGINX" : NGINX,
"DICT" : DICT,
"ADMIN" : ADMIN,
"KAFKACONN" : KAFKACONN,
"KAFKASTRM-LL" : KAFKASTRMLL,

A description of each component is given in the Glossary section of the Internal Architecture document.

How can I find out current status of the system?

The following command tells you the basic summary of each component:

gadmin status

Example:

$ gadmin status
+--------------------+-------------------------+-------------------------+
|    Service Name    |     Service Status      |      Process State      |
+--------------------+-------------------------+-------------------------+
|       ADMIN        |         Online          |         Running         |
|        CTRL        |         Online          |         Running         |
|        DICT        |         Online          |         Running         |
|        ETCD        |         Online          |         Running         |
|        EXE         |         Online          |         Running         |
|        GPE         |         Online          |         Running         |
|        GSE         |         Online          |         Running         |
|        GSQL        |         Online          |         Running         |
|        GUI         |         Online          |         Running         |
|        IFM         |         Online          |         Running         |
|       KAFKA        |         Online          |         Running         |
|     KAFKACONN      |         Online          |         Running         |
|    KAFKASTRM-LL    |         Online          |         Running         |
|       NGINX        |         Online          |         Running         |
|       RESTPP       |         Online          |         Running         |
|         ZK         |         Online          |         Running         |
+--------------------+-------------------------+-------------------------+

If you want to know more, including process information, memory/cpu usage information of each component, use the -v option for verbose output.

gadmin status -v

Example:

$ gadmin status -v
+--------------------+-------------------------+-------------------------+-------------------------+-------------------------+
|    Service Name    |     Service Status      |      Process State      |       Process ID        |          Role           |
+--------------------+-------------------------+-------------------------+-------------------------+-------------------------+
|      ADMIN#1       |         Online          |         Running         |          99872          |           NA            |
|       CTRL#1       |         Online          |         Running         |          11323          |           NA            |
|       DICT#1       |         Online          |         Running         |          98901          |           NA            |
|       ETCD#1       |         Online          |         Running         |          33061          |           NA            |
|       EXE_1        |         Online          |         Running         |          11299          |           NA            |
|      GPE_1#1       |         Online          |         Running         |          99944          |         Leader          |
|      GSE_1#1       |         Online          |         Running         |          99897          |         Leader          |
|       GSQL#1       |         Online          |         Running         |         100711          |         Leader          |
|       GUI#1        |         Online          |         Running         |         100895          |           NA            |
|       IFM#1        |         Online          |         Running         |          34908          |           NA            |
|      KAFKA#1       |         Online          |         Running         |          76909          |           NA            |
|    KAFKACONN#1     |         Online          |         Running         |         100192          |           NA            |
|   KAFKASTRM-LL_1   |         Online          |         Running         |         100035          |           NA            |
|      NGINX#1       |         Online          |         Running         |          99929          |           NA            |
|      RESTPP#1      |         Online          |         Running         |          99973          |           NA            |
|        ZK#1        |         Online          |         Running         |          11365          |           NA            |
+--------------------+-------------------------+-------------------------+-------------------------+-------------------------+

How can I find out the port of a service?

To find out the port of a service, use the gadmin config get <port_name> command:

$ gadmin config get RESTPP.NginxPort

Example:

9000

To list and edit all ports, use the following command:

gadmin config group port

Example:

$ gadmin config group port

Security.LDAP.Port [ 389 ]: Configure LDAP server port: default 389
New: 389
[   Info] no changes for Security.LDAP.Port

System.SSH.Port [ 22 ]: SSH port
New: 22
[   Info] no changes for System.SSH.Port

System.CrossRegionReplication.PrimaryKafkaPort [ 30002 ]: Kafka mirrormaker primary cluster's KafkaPort
New: 30002
[   Info] no changes for System.CrossRegionReplication.PrimaryKafkaPort

Executor.Port [ 9177 ]: The serving port for Executor
New: 9177
[   Info] no changes for Executor.Port

Executor.FileTransferPort [ 9178 ]: The port for Executor to do file transfer
New: 9178
[   Info] no changes for Executor.FileTransferPort
Actual values may vary depending on cluster configuration.

To change the port number of one service, use the following command:

gadmin config set <port_name> <port_number>

Example:

gadmin config set RESTPP.NginxPort 9001
[   Info] Configuration has been changed. Please use 'gadmin config apply' to persist the changes.
$ gadmin config apply
[   Note] Changes:
RESTPP.NginxPort: 9000 -> 9001
Proceed to apply? (y/N)y
[   Info] Successfully applied configuration change. Please restart services to make it effective immediately.
$ gadmin restart all
[   Note] Restart the service(s)? (y/N)y
[   Info] Stopping ZK ETCD DICT KAFKA ADMIN GSE NGINX GPE RESTPP KAFKASTRM-LL KAFKACONN GSQL IFM GUI
[   Info] Stopping CTRL
[   Info] Stopping EXE
[   Info] Starting EXE
[   Info] Starting CTRL
[   Info] Starting ZK ETCD DICT KAFKA ADMIN GSE NGINX GPE RESTPP KAFKASTRM-LL KAFKACONN CTRL GSQL IFM GUI
$ gadmin config get RESTPP.NginxPort
9001

How do I back up my data?

gadmin backup is the utility to do backup and restore of TigerGraph system. Before a backup, the backup operations need to be configured. Please see Backup and Restore for details.

To back up the current system:

gadmin backup create <tag_of_the_backup>

Example:

[   Info] [Mon Jan 26 08:17:41 UTC 2026] Tag is qa_test_backup_01-2026-01-26T081741.607
[   Info] [Mon Jan 26 08:17:41 UTC 2026] Backup timeout is 18000 seconds
[   Info] [Mon Jan 26 08:17:41 UTC 2026] Backup path: /home/tigergraph/backup/qa_test_backup_01-2026-01-26T081741.607
[   Info] [Mon Jan 26 08:17:41 UTC 2026] Created backup directories
[   Info] [Mon Jan 26 08:17:42 UTC 2026] Exporting GSQL data... (async)
[   Info] [Mon Jan 26 08:17:42 UTC 2026] Exporting GSE data... (async)
[   Info] [Mon Jan 26 08:17:42 UTC 2026] Exporting GPE data... (async)
...

[   Info] [Mon Jan 26 08:18:25 UTC 2026] Backup completes, backup files are under the path:
       /home/tigergraph/backup/qa_test_backup_01-2026-01-26T081741.607

Please be advised that backup only backs up data and configuration. No logs or binaries will be backed up.

How do I restore a backup?

To restore an existing backup:

gadmin backup restore <tag of the backup>

Example:

$ gadmin backup restore --help
Restore a cluster from backup

Usage:
  gadmin backup restore <tag/time point> [flags]

Description:

  Restores a backup of cluster data.

  Example:
  gadmin backup restore my-backup-2021-11-04T120000

Flags:
      --dr                     Enable cross-region replication (CRR) and set the cluster as a disaster recovery (DR) cluster after restore.
                               Note: all CRR-related configs must be populated before running the restore.
                               This flag can be used in the following ways:
                               1. 'gadmin backup restore <tag> --dr'
                                Restore from a backup and initialize the cluster as a DR cluster.
                               2. 'gadmin backup restore --dr --dr-checkpoint <crr_checkpoint_json>'
                                Switch an existing cluster directly into the DR role which was previously in Primary role.
                                To ensure data consistency, the <crr_checkpoint_json> file must be provided for data validation.
                                This file can be generated when promoting the old DR cluster to Primary by running 'gadmin crr stop --promote'.
                               3. 'gadmin backup restore --dr'
                                Set up both a Primary cluster and a DR cluster on freshly installed clusters.
      --dr-checkpoint string   The path of the JSON CRR checkpoint file dumped by 'gadmin crr stop --promote'. This file is used to ensure data consistency when switching the old Primary cluster to the DR role without performing a full backup and restore.
  -h, --help                   help for restore
      --ignore-space-check     Ignore the space check during the backup/restore.
      --keep-users             The keep-users flag can be used to retain the current cluster GSQL users instead of being overwritten by the backup ones.
      --staging-path string    The path used to store the graph data during backup/restore. Defaults to dataroot.
      --time-point             this flag indicates whether to restore to a specific point in time, rather than from a certain backup.
  -y, --y                      yes to all questions

Global Flags:
      --debug   enable debug log output to stdout

Please be advised that running restore will STOP the service and ERASE existing data.

How can I find out statistics of my graph data?

You can get statistics of Graph data on TigerGraph database instance using gstatusgraph utility:

Syntax:

gstatusgraph [-s <node_name>]

using -s to do statistics for one node

Example:

$ gstatusgraph -s m1
=== graph ===
[GRAPH  ] Graph was loaded (/home/tigergraph/tigergraph/data/gstore):
[m1     ] Partition size: 0B, IDS size: 0B, Vertex count: 18897065, Edge count: 215246699, NumOfDeletedVertices: 2, NumOfSkippedVertices: 0, Vector size: 0B, Graph size: 0B
[WARN   ] Above vertex and edge counts are for internal use which show approximate topology size of the local graph partition. Use DML to get the correct graph topology information
$ gstatusgraph
=== graph ===
[GRAPH  ] Graph was loaded (/data/tigergraph/tigergraph3/data/gstore/0/part/):
[m1     ] Partition size: 43GiB, IDS size: 16GiB, Vertex count: 262053633, Edge count: 1115267545, NumOfDeletedVertices: 130988916 NumOfSkippedVertices: 0
[m2     ] Partition size: 40GiB, IDS size: 16GiB, Vertex count: 261996922, Edge count: 971304656, NumOfDeletedVertices: 130998461 NumOfSkippedVertices: 0
[m3     ] Partition size: 44GiB, IDS size: 16GiB, Vertex count: 271436710, Edge count: 1115214212, NumOfDeletedVertices: 121605839 NumOfSkippedVertices: 0
[m4     ] Partition size: 44GiB, IDS size: 16GiB, Vertex count: 262030593, Edge count: 1191498785, NumOfDeletedVertices: 130964790 NumOfSkippedVertices: 0
[WARN   ] Above vertex and edge counts are for internal use which show approximate topology size of the local graph partition. Use DML to get the correct graph topology information

Example:

$ gstatusgraph
=== graph ===
[GRAPH  ] Graph was loaded (/home/tigergraph/tigergraph/data/gstore):
[m1     ] Partition size: 2.8GiB, IDS size: 157MiB, Vertex count: 18897065, Edge count: 215246699, NumOfDeletedVertices: 2, NumOfSkippedVertices: 0, Vector size: 0B, Graph size: 2.8GiB
[WARN   ] Above vertex and edge counts are for internal use which show approximate topology size of the local graph partition. Use DML to get the correct graph topology information

Due to a known bug, gstatusgraph command will count each undirected edge as two edges. To get an accurate number of undirected edges, user should use the built-in queries instead. The message below is sent as a warning to users when gstatusgraph is used.

"[WARN ] Above vertex and edge counts are for internal use which show approximate topology size of the local graph partition. Use DML to get the correct graph topology information"

How can I find out statistics of requests?

TigerGraph provides a RESTful API to tell request statistics. Assuming REST port is 9000, use command below:

curl -l http://localhost:14240/restpp/statistics

Example:

$ curl http://localhost:14240/restpp/statistics?seconds=60
{"POST /restppkafkaloader/{graph_name}":{"CompletedRequests":1,"QPS":0.01666666666666667,"TimeoutRequests":0,"AverageLatency":1,"MaxLatency":1,"MinLatency":1,"LatencyPercentile":[2,2,2,2,2,2,2,2,2,2]},"GET /statistics/{graph_name}":{"CompletedRequests":1,"QPS":0.01666666666666667,"TimeoutRequests":0,"AverageLatency":0,"MaxLatency":0,"MinLatency":0,"LatencyPercentile":[1,1,1,1,1,1,1,1,1,1]}}

How do I restart a service?

If you need to restart everything, use the following:

gadmin restart

Example:

$ gadmin restart
[   Note] Restart the service(s)? (y/N)y
[   Info] Stopping DICT ADMIN GSE NGINX GPE RESTPP KAFKASTRM-LL KAFKACONN GSQL GUI
[   Info] Starting ZK ETCD DICT KAFKA ADMIN GSE NGINX GPE RESTPP KAFKASTRM-LL KAFKACONN CTRL GSQL GUI

If you know which component(s) you want to restart,you can list them:

gadmin restart <component_name(s)>

Example:

$ gadmin restart
[   Note] Restart the service(s)? (y/N)y
[   Info] Stopping DICT ADMIN GSE NGINX GPE RESTPP KAFKASTRM-LL KAFKACONN GSQL GUI
[   Info] Starting ZK ETCD DICT KAFKA ADMIN GSE NGINX GPE RESTPP KAFKASTRM-LL KAFKACONN CTRL GSQL GUI

$ gadmin restart gse
[   Note] Restart the service(s)? (y/N)y
[   Info] Stopping GSE
[   Info] Starting ZK ETCD DICT KAFKA ADMIN GSE


gadmin restart all
[   Note] Restart the service(s)? (y/N)y
[   Info] Stopping ZK ETCD DICT KAFKA ADMIN GSE NGINX GPE RESTPP KAFKASTRM-LL KAFKACONN GSQL IFM GUI
[   Info] Stopping CTRL
[   Info] Stopping EXE
[   Info] Starting EXE
[   Info] Starting CTRL
[   Info] Starting ZK ETCD DICT KAFKA ADMIN GSE NGINX GPE RESTPP KAFKASTRM-LL KAFKACONN CTRL GSQL IFM GUI



$ gadmin stop
[   Info] If no serviceID is specified, it only stops services excluding the infrastructure. Use 'gadmin stop all' to stop all services.
[   Note] Stop the service(s)? (y/N)y
[   Info] Stopping DICT ADMIN GSE NGINX GPE RESTPP KAFKASTRM-LL KAFKACONN GSQL GUI


$  gadmin stop gpe
[   Note] Stop the service(s)? (y/N)y
[   Info] Stopping GPE

Multiple component names are separated by spaces.

How to I stop some or all services?

Normally it is not necessary to manually turn off any services. However if you wish to, use the stop command.

# stop (nearly) all services
# will stop services except for infrastructure services
gadmin stop

# stop selected services
gadmin stop <component_name(s)>

Why the service is down?

There are a few typical causes for a service being down:

  1. Expired license key. Double-check your license key expiration date, and please open a support ticket if it is expired. After applying a new license key, your service will come back online. Usually, TigerGraph will reach out before your license key expires. Please act accordingly when that happens.

  2. Not enough memory. TigerGraph is a memory intensive system. When there is not much free memory, Linux may kill a process based on memory usage. Please check your memory usage after TigerGraph starts. We suggest at least 30% free memory after TigerGraph starts up. To confirm if one of TigerGraph’s processes is a victim, use dmesgto check.

  3. Not enough free disk space. TigerGraph writes data, logs, as well as some temporary files onto disk(s). It requires enough free space to function properly. If TigerGraph service or one of its components is down, please check whether there is enough free space on the disk using df.

Where are the logs?

Use following command to figure out where are log files for each component:

gadmin log

Example:

$ gadmin log
ADMIN  : /home/tigergraph/tigergraph/log/admin/ADMIN#1.out
ADMIN  : /home/tigergraph/tigergraph/log/admin/ADMIN.INFO
CTRL   : /home/tigergraph/tigergraph/log/controller/CTRL#1.log
CTRL   : /home/tigergraph/tigergraph/log/controller/CTRL#1.out
DICT   : /home/tigergraph/tigergraph/log/dict/DICT#1.out
DICT   : /home/tigergraph/tigergraph/log/dict/DICT.INFO
ETCD   : /home/tigergraph/tigergraph/log/etcd/ETCD#1.out
EXE    : /home/tigergraph/tigergraph/log/executor/EXE_1.log
EXE    : /home/tigergraph/tigergraph/log/executor/EXE_1.out
GPE    : /home/tigergraph/tigergraph/log/gpe/GPE_1#1.out
GPE    : /home/tigergraph/tigergraph/log/gpe/log.INFO
GSE    : /home/tigergraph/tigergraph/log/gse/GSE_1#1.out
GSE    : /home/tigergraph/tigergraph/log/gse/log.INFO
GSQL   : /home/tigergraph/tigergraph/log/auditlog/log.AUDIT-GSQL
GSQL   : /home/tigergraph/tigergraph/log/gsql/GSQL#1.out
GSQL   : /home/tigergraph/tigergraph/log/gsql/log.INFO
GUI    : /home/tigergraph/tigergraph/log/gui/GUI#1.out
IFM    : /home/tigergraph/tigergraph/log/informant/IFM#1.log
IFM    : /home/tigergraph/tigergraph/log/informant/IFM#1.out
KAFKA  : /home/tigergraph/tigergraph/log/kafka/KAFKA#1.out
KAFKA  : /home/tigergraph/tigergraph/log/kafka/controller.log
KAFKA  : /home/tigergraph/tigergraph/log/kafka/kafka-request.log
KAFKA  : /home/tigergraph/tigergraph/log/kafka/kafka.log
KAFKA  : /home/tigergraph/tigergraph/log/kafka/server.log
KAFKA  : /home/tigergraph/tigergraph/log/kafka/state-change.log
KAFKA-LOADER: /home/tigergraph/tigergraph/log/kafkaLoader
KAFKACONN: /home/tigergraph/tigergraph/log/kafkaconn/KAFKACONN#1.out
KAFKACONN: /home/tigergraph/tigergraph/log/kafkaconn/kafkaconn.log
KAFKASTRM-LL: /home/tigergraph/tigergraph/log/kafkastrm-ll/KAFKASTRM-LL_1.out
KAFKASTRM-LL: /home/tigergraph/tigergraph/log/kafkastrm-ll/kafkastrm-ll.log
NGINX  : /home/tigergraph/tigergraph/log/nginx/logs/NGINX#1.out
NGINX  : /home/tigergraph/tigergraph/log/nginx/logs/error.log
RESTPP : /home/tigergraph/tigergraph/log/auditlog/log.AUDIT-RESTPP
RESTPP : /home/tigergraph/tigergraph/log/restpp/RESTPP#1.INFO
RESTPP : /home/tigergraph/tigergraph/log/restpp/RESTPP#1.out
RESTPP-LOADER: /home/tigergraph/tigergraph/log/fileLoader
ZK     : /home/tigergraph/tigergraph/log/zk/ZK#1.out
ZK     : /home/tigergraph/tigergraph/log/zk/zookeeper.log
gadmin : /home/tigergraph/tigergraph/log/auditlog/log.AUDIT-GADMIN

To log at the log file for a particular component:

gadmin log <component>

Example:

$ gadmin log gpe
GPE    : /home/tigergraph/tigergraph/log/gpe/GPE_1#1.out
GPE    : /home/tigergraph/tigergraph/log/gpe/log.INFO

Why has my request timed out?

Timeout is applied to any request coming into TigerGraph system. If a request runs longer than the Timeout value, it will be killed. The default timeout value is 16 second.

If you knows that your query will run longer than the value, configure all related timeouts to a bigger value. To do this:

gadmin config entry RESTPP.Factory.DefaultQueryTimeoutSec

Example:

$ gadmin config entry RESTPP.Factory.DefaultQueryTimeoutSec

RESTPP.Factory.DefaultQueryTimeoutSec [ 16 ]: The default query timeout (s) for RESTPP
New: 16
[   Info] no changes for RESTPP.Factory.DefaultQueryTimeoutSec
$ gadmin config apply
[Warning] No difference from staging config, config apply is skipped.
[   Info] Successfully applied configuration change. Please restart services to make it effective immediately.
$ gadmin restart all
[   Note] Restart the service(s)? (y/N)y
[   Info] Stopping ZK ETCD DICT KAFKA ADMIN GSE NGINX GPE RESTPP KAFKASTRM-LL KAFKACONN GSQL IFM GUI
[   Info] Stopping CTRL
[   Info] Stopping EXE
[   Info] Starting EXE
[   Info] Starting CTRL
[   Info] Starting ZK ETCD DICT KAFKA ADMIN GSE NGINX GPE RESTPP KAFKASTRM-LL KAFKACONN CTRL GSQL IFM GUI

Input a value you expected, the unit is in second. Then apply the config to the system and restart the service.

gadmin config apply
gadmin restart

The timeout can also be changed for each query, but only when calling the REST endpoint. You would need to use a timeout value each time you run a query, otherwise the default timeout value will be assumed.

curl -X <GET/POST> -H "GSQL-TIMEOUT: <timeout value in milliseconds>" '<request_URL>'

Where are the core dump files located?

A core dump file is produced by the OS when a certain signal causes a process to terminate. The core dump is a disk file containing an image of the process’s memory at the time of termination. This image can be used in a debugger (e.g., gdb) to inspect the state of the program at the time that it terminated.

The TigerGraph installation process configures the operating system to place core dump files in the TigerGraph root directory, with the name core-%e-%s-%p.%t, where

  • %e: executable filename (without path prefix)

  • %s: signal number which caused the dump

  • %p: PID of dumped process

  • %t: time of dump, expressed as seconds since the epoch

The coredump configuration was set by the following command:

echo "$coreLocation/core-%e-%s-%p.%t" > /proc/sys/kernel/core_pattern

If you want to alter the location or file name template, you can edit the contents of /proc/sys/kernel/core_pattern