8.18. The tapi Command

Version Support: 7.0.0

The tapi command was added in version 7.0.0

The tapi command is designed to act as an interface to the Tungsten REST APIv2.

The original goal of this script was to provide a way to test and exercise the API which then grew to include additional functionality and convenience options.

Usage for tapi:

shell> tapi [options] [API_call_path]

See the tables below for a list of valid arguments:

Table 8.21. tapi Generic Options

OptionDescription
--debug, -d
--help, -h
--quiet, -q
--service, -sSpecify a service name. Used with --run, --getpolicy, --setpolicy and the --policy NRPE plugin
--verbose, -v

Table 8.22. tapi CURL-related Options

OptionDescription
--curlSpecify where to find curl executable (default: curl)
--getSet the curl request to GET
--hostSpecify the host name to connect to (default: 127.0.0.1)
--nossl, --httpSpecify NON-SSL/http-only connection (default: https, SSL enabled)
--portSpecify the port number to connect to (default: 8090)
--postSet the curl request to POST
--putSet the curl request to PUT
-p, --passwordSpecify auth password (default: not defined)
--request {GET|POST|PUT}Specify the curl request method (default: none)
--user, -uSpecify auth user (default: not defined)

Table 8.23. tapi Nagios/NRPE/Zabbix-related Options

OptionDescription
--allperf, --per-replica-perfdataWhen --allperf is specified with --perf, each service is listed separately; used with --latency
-c, --criticalSpecify the critical threshold value in seconds; used with --latency
--latencyCheck the replicator for latency as an NRPE plugin
--onlineCheck the manager to see if the datasource is online as an NRPE plugin
--perf, --perfdataDisplay additional performance data; used with --latency
--policyCheck the manager to see if the cluster is in automatic policy mode as an NRPE plugin
--progressCheck the replicator to see that it is making progress over time as an NRPE plugin
--servicesCheck the host for running services (Manager, Connector and Replicator) as an NRPE plugin
--wait, -WSpecify the time to wait in seconds during the --progress test (default: 1 second)
--warn, -wSpecify the warning threshold value in seconds; used with --latency
--zabbix, -zUse Zabbix-style exit messages which are the same as the exit code, unlike NRPE which outputs a string starting with OK, WARNING or CRITICAL

Table 8.24. tapi Admin-related Options

OptionDescription
--createConnect to the specified host and port, then call the createAdminUser path with a special body to instantiate the user. Must supply --create-user and --create-password.
--create-passSets password for the APIv2 admin user created using the --create flag. --create and --create-user must also be supplied.
--create-userSets the user name for the APIv2 admin user created using the --create flag. --create and --create-pass must also be supplied.
--getdsDisplay the main Manager dataservice name
--getmainDisplay the main Replicator service name
--getpolicyGet the current local policy. If --service {svcname} is specified, then the policy will be displayed for that service.
--getportsDisplay the API default port for each component
--getsubsDisplay the Replicator sub-service(s)
--includeServiceNameOutput service names.
--no-connectorsAppend '?no-connectors=1' to all API calls to disable the Manager internal status calls to the Connectors
--setautoSet the current policy to AUTOMATIC
--setmaintSet the current policy to MAINTENANCE
--setpolicy {auto|maint}Set the current local policy. If --service {svcname} is specified, then the policy will be set for that service. One-letter abbreviations are allowed for the policy mode names.
--topologyDisplay the main Manager topology

Table 8.25. tapi Filter-related Options

OptionDescription
--connector, -CSpecify the connector path
--filter, -FSpecify {string} to Limit the call path (typically used with --listapi)
--manager, -MSpecify the manager path
--replicator, -RSpecify the replicator path

Table 8.26. tapi API-related Options

OptionDescription
--allservicesOperate on all available services. Used with --run
--follow, --descend, -fIf the resulting payload type is URIsPayload then call every key in the payload as a sub-item of the original path
--listapi, -LList all available REST API calls by unique key
--run, --alias, -rSpecify an API call name by unique key. Use --listapi to see all keys/aliases

Table 8.27. tapi Status-related Options

OptionDescription
--affinityDisplay only the affinity-specific values from the '/connector/configuration/module/connector' path
--allstatsDisplay all statistics cluster-wide using the Manager API
--connectorstatusUse the '/connector/configuration/module/connector' path
--cs, --clusterstatusUse the 'manager/cluster/status' path
--mgrstats, --managerstatsDisplay Manager statistics cluster-wide using the Manager API
--routersDisplay Connector statistics cluster-wide using the Manager API
--statusUse the 'manager/status' path
--trstatsDisplay Replicator statistics cluster-wide using the Manager API

Table 8.28. tapi Backup and Restore-related Options

OptionDescription
--backuptimeoutSpecify the backup timeout in seconds
--mysqldumpUse the mysqldump backup agent
--restoretimeoutSpecify the restore timeout in seconds
--restoreuriSpecify the restore URI
--storageagentSpecify the storage agent
--xtrabackupUse the xtrabackup backup agent
--xtrabackupFullUse the xtrabackupFull backup agent
--xtrabackupIncrementalUse the xtrabackupIncremental backup agent

There are many cli options which invoke the various functions of the tapi script.

With no options specified, the tapi script will construct a curl command to query the Tungsten Manager API (default https://127.0.0.1:8090) using the {API_call_path} provided on the command line.

Basic Example

Running tapi -M status would result in something like the following:

shell> tapi manager/status
Executing: curl -s --user tungsten:secret --insecure --request GET 'https://127.0.0.1:8090/api/v2/manager/status'
{"payloadType":"StatusPayload","payloadVersion":"1","payload":{"dataServiceName":"east","dataSourceName":"db1-demo.continuent.com",
"startTime":"2021-03-25T16:47:50.523 UTC","uptimeSeconds":1909,"state":"ONLINE","isCoordinator":true,"isWitness":false,
"managerPID":4052,"parentPID":4031,"policyMode":"MAINTENANCE","coordinator":"db1-demo.continuent.com"}}

If both --user and --password are defined, curl will use them in the call.

If either or both --user and --password are missing, tapi will attempt to derive the values using the tpm command.

Simple Admin Command Examples

tapi --getds
tapi --topology
tapi --setmaint
tapi --setauto

tapi --setpolicy maintenance
tapi --setpolicy m
tapi --setpolicy automatic
tapi --setpolicy a

Simple Replicator Command Examples

tapi --getmain
tapi --getsubs

Running API Command Examples

Show all available API calls in four columns: component, unique key, request type, request path:

tapi -R --listapi

Show all available API calls filtered by Manager (-M), Replicator (-R) or Connector (-c):

tapi --listapi -M
tapi --listapi -R
tapi --listapi -C

Execute an API call by unique key per component:

tapi -R --listapi
tapi -R --run ping
tapi -R -v --run offline (like `trepctl offline`)
tapi -R -v --run online (like `trepctl online`)

Backup and Restore Examples

tapi -v -R --run backup --mysqldump
tapi -v -R --run backup --xtrabackupFull
tapi -v -R -j --run restore
tapi -v -R -j --run task d28465a2-6023-47c4-9a4c-20f93514db75