Previous Next JavaScript must be enabled to correctly display this content

## ping

    java -Xmx64m -Xms64m \
    -jar KVHOME/lib/kvstore.jar ping [-verbose] [-json] [-shard <shardId>]
    -host <hostname> -port <port> or
    -helper-hosts  <host:port>[,host:port]*>
    -username <user>
    -security <security-file-path>

Attempts to contact a store to get status of running services. This utility provides both a concise summary of the health of a store, as well as detailed information about the topology of the store. It can signal a red/yellow/green status, to let you know whether the store is in full health, whether the store has experienced some failures but is operational, or whether the store has critical problems. `ping` uses the nodes specified by the `-helper-hosts` or `-host/-port` arguments to locate topology metadata describing the store. Using that topology, `ping` contacts all the RNs, SNs, Arbiters, and Admin services associated with a store. You can also indicate a specific shard to return its status information.

Specify the `-helper-hosts` flag as an alternative to the existing `-host` and `-port` flags. If multiple helper hosts are in use, this utility has multiple nodes it can use to make an initial point of contact with the store, and will have a greater chance of success if some nodes of the store are unavailable.

Specify `–shard <shardId>` to return a subset of information.

### Ping Command Line Parameters

The `ping` utility's command line parameters are:

- `-host` identifies the name of a specific host in the store. Use this option to check whether the SNA on that particular host can be contacted.

  If this parameter is specified, then `-port` must also be specified. Further, if the `-host` and `-port` parameters are specified, then the `-helper-hosts` must not be specified.

- `-port` identifies the listening port for a specific host in the store. Use this parameter only if you are also using the `-host` parameter.

- `-helper-hosts` identifies a comma-separated list of one or more host:port pairs in the store. Use this parameter to check the health of the entire store.

  Using the `–helper-hosts` parameter precludes specifying the `-host` and `-port` flags.

  If multiple helper hosts are provided, this utility has multiple nodes it can use to make an initial point of contact with the store, and thus a greater chance of success if some nodes of the store are unavailable. For example:

      -helper-hosts hst1:5000,hst2:5100, hst3:5100

- `-username` is the name of the user that you want to ping the store as. This parameter is required if your store is configured to require authentication. This user should have at least `SYSVIEW` access to the store. The built-in `dbadmin` role is sufficient.

- `-security` is the client security configuration file. This parameter is required if your store is configured to require authentication. For information on the parameters contained in this file, see Configuring SSL in the Java Direct Driver Developer's Guide. For example:

      oracle.kv.auth.username=clientUID1
      oracle.kv.auth.pwdfile.file=/home/nosql/login.pwd
      oracle.kv.transport=ssl
      oracle.kv.ssl.trustStore=/home/nosql/client.trust

  If you are using Kerberos, then this file would look something like this:

      oracle.kv.auth.kerberos.keytab = kerberos/mykeytab
      oracle.kv.auth.username = krbuser@EXAMPLE.COM
      oracle.kv.auth.external.mechanism=kerberos
      oracle.kv.auth.kerberos.services=
      node01:oraclenosql/node01.example.com@EXAMPLE.COM
      oracle.kv.auth.kerberos.mutualAuth=false

- `-verbose` is optional. It causes the `ping` utility to provide additional information about the utility's current actions.

- `-json` causes the `ping` utility to write its output in JSON format.

- `-shard <shardId>` is optional and returns a subset of status information about the specific shard ID you supply. .

  For example:

      bash-4.1$ java -jar $KVHOME/lib/kvstore.jar ping -host mynode.mycompany.com
      -port 5000 -shard rg2 Pinging components of store mystore based upon topology
      sequence #2376    shard rg2
      500 partitions and 3 storage nodes
      Time: 2024-04-05 06:57:10 UTC   Version: 24.1.11
      Shard Status: healthy
      Admin Status: healthy
      Zone [name=myshardzone id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
      RN Status: online:3 offline:0 maxDelayMillis:0 maxCatchupTimeSecs:0
      Storage Node [sn10] on nodeA:5000    Zone: [name=myshardzone id=zn1
      type=PRIMARY allowArbiters=false masterAffinity=false]
      Status: RUNNING   Ver: 24.1.11 2024-04-05 09:33:45 UTC
      Build id: a72484b8b33c Edition: Enterprise
               Rep Node [rg2-rn1]      Status: RUNNING,MASTER sequenceNumber:71,166
      haPort:5010 available storage size:12 GB
      Storage Node [sn11] on nodeB:5000    Zone: [name=myshardzone id=zn1
      type=PRIMARY allowArbiters=false masterAffinity=false]
      Status: RUNNING   Ver: 24.1.11 2024-04-05 09:33:45 UTC
      Build id: a72484b8b33c Edition: Enterprise
               Rep Node [rg2-rn2]      Status: RUNNING,REPLICA sequenceNumber:71,166
      haPort:5011 available storage size:14 GB delayMillis:0 catchupTimeSecs:0
      Storage Node [sn12] on nodeC:5000    Zone: [name=myshardzone id=zn1
      type=PRIMARY allowArbiters=false masterAffinity=false]
      Status: RUNNING   Ver: 24.1.11 2024-04-05 09:33:45 UTC
      Build id: a72484b8b33c Edition: Enterprise
               Rep Node [rg2-rn3]      Status: RUNNING,REPLICA sequenceNumber:71,166
      haPort:5012 available storage size:24 GB delayMillis:0 catchupTimeSecs:0

### Ping Exit Codes

The following exit codes can be returned by this utility. Exit codes can be returned both as a process exit code, and as part of the JSON output.

Name | Code | Description
--- | --- | ---
EXIT_OK | 0 | All services in the store could be located and are in a known, good state (for example, RUNNING).
EXIT_OPERATIONAL | 1 | One or more services in the store could not be reached, or are in an unknown or not usable state. In this case the store should support all data operations across all shards, as well as all administrative operations, but may be in a state of degraded performance. Some action should be taken to find and fix the problem before part of the store becomes unavailable.
EXIT_NO_ADMIN_QUORUM | 2 | The Admin Service replication group does not have quorum or is not available at all, and it is not possible to execute administrative operations which modify store configuration. The store supports all normal data operations despite the loss of admin quorum, but this state requires immediate attention to restore full store capabilities.
EXIT_NO_SHARD_QUORUM | 3 | One or more of the shards does not have quorum and either cannot accept write requests, or is completely unavailable. This state requires immediate attention to restore store capabilities. The exit code takes precedence over `EXIT_NO_ADMIN_QUORUM`, so if this exit code is used, it is possible that the administrative capabilities are also reduced or unavailable.
EXIT_USAGE | 100 | Illegal ping command usage.
EXIT_TOPOLOGY_FAILURE | 101 | `ping` was unable to find a topology in order to operate. This could be a store problem, a network problem, or it could be a usage problem with the parameters passed to ping. For example, the specified `-host`/`-port` pair are not part of the store, or none of the hosts specified on `-helper-hosts` can be contacted.
EXIT_UNEXPECTED | 102 | The utility has experienced an unexpected error.
EXIT_STATUS_UNKNOWN | 103 | The store is operational but some Replication Nodes are in unknown state.

Note:

Exit codes 1 through 3 may indicate a network connectivity issue that should be checked first before concluding that any services have a problem.

### Ping Report Text Output

By default, the `ping` utility reports store health in human readable format. For example:

Note:

Extra line breaks have been added so that the command output fits in the available space.

    $ java -Xmx64m -Xms64m -jar <KVHOME>/lib/kvstore.jar ping -host nodeA -port 1310
    Pinging components of store mystore based upon topology sequence #108
    100 partitions and 3 storage nodes
    Time: 2024-04-05 10:37:43 UTC Version: 24.1.11
    Shard Status: healthy:1 writable-degraded:0 read-only:0 offline:0 total:1
    Admin Status: healthy
    Zone [name=MyDC id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
    RN Status: online:3 read-only:0 offline:0 maxDelayMillis:0 maxCatchupTimeSecs:0
    Storage Node [sn1] on nodeA:13100
    Zone: [name=MyDC id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
    Status: RUNNING Ver: 24.1.11 2024-04-05 05:02:01 UTC
    Build id: 0ce629097e92 Edition: Enterprise isMasterBalanced:true
            Admin [admin1]         Status: RUNNING,MASTER
            Rep Node [rg1-rn1]     Status: RUNNING,MASTER
            sequenceNumber:227 haPort:13117 available storage size:16 GB storage type:HD
    Storage Node [sn2] on nodeB:13200
        Zone: [name=MyDC id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
        Status: RUNNING Ver: 24.1.11 2024-04-05 05:02:01 UTC
        Build id: 0ce629097e92
            Admin [admin2]         Status: RUNNING,REPLICA
            Rep Node [rg1-rn2]     Status: RUNNING,REPLICA
                sequenceNumber:227 haPort:13217 available storage size:14 GB storage type:HD delayMillis:0
                catchupTimeSecs:0
    Storage Node [sn3] on nodeC:13300
        Zone: [name=MyDC id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
        Status: RUNNING Ver: 24.1.11 2024-04-05 05:02:01 UTC
        Build id: 0ce629097e92
            Admin [admin3]         Status: RUNNING,REPLICA
            Rep Node [rg1-rn3]     Status: RUNNING,REPLICA
                sequenceNumber:227 haPort:13317 available storage size:24 GB storage type:HD delayMillis:0
                catchupTimeSecs:0

### Ping Report JSON Output

When the `-json` command line parameter is specified, this utility provides its report in JSON formatting.

Note:

Extra line breaks have been introduced to allow this output to fit in the available space.

    bash-3.2$ java -Xmx64m -Xms64m \
    -jar dist/lib/kvstore.jar ping -host node01 \
    -port 5000 -json
    {
      "operation" : "ping",
      "returnCode" : 5000,
      "description" : "No errors found",
      "returnValue" : {
        "topology" : {
          "storeName" : "orcl",
          "sequenceNumber" : 9,
          "numPartitions" : 0,
          "numStorageNodes" : 2,
          "time" : 1539857069504,
          "version" : "24.1.11"
        },
        "adminStatus" : "healthy",
        "shardStatus" : {
          "healthy" : 1,
          "writable-degraded" : 1,
          "read-only" : 0,
          "offline" : 0,
          "total" : 2
        },
        "zoneStatus" : [ {
          "resourceId" : "zn1",
          "name" : "Atlanta",
          "type" : "PRIMARY",
          "allowArbiters" : false,
          "masterAffinity" : false,
          "rnSummaryStatus" : {
            "online" : 2,
            "offline" : 0,
            "read-only" : 0,
            "hasReplicas" : false
          }
        }, {
          "resourceId" : "zn2",
          "name" : "Boston",
          "type" : "SECONDARY",
          "allowArbiters" : false,
          "masterAffinity" : false,
          "rnSummaryStatus" : {
            "online" : 1,
            "offline" : 0,
            "read-only" : 0,
            "hasReplicas" : true,
            "maxDelayMillis" : 0,
            "maxCatchupTimeSecs" : 0
          }
        } ],
        "snStatus" : [ {
          "resourceId" : "sn1",
          "hostname" : "node01",
          "registryPort" : 5000,
          "zone" : {
            "resourceId" : "zn1",
            "name" : "Atlanta",
            "type" : "PRIMARY",
            "allowArbiters" : false,
            "masterAffinity" : false
          },
          "serviceStatus" : "RUNNING",
          "version" : "24.1.11 2024-04-05 09:33:45 UTC  Build id: a72484b8b33c Edition: Enterprise",
          "adminStatus" : {
            "resourceId" : "admin1",
            "status" : "RUNNING",
            "state" : "MASTER",
            "authoritativeMaster" : true
          },
          "rnStatus" : [ {
            "resourceId" : "rg1-rn1",
            "status" : "RUNNING",
            "requestsEnabled" : "ALL",
            "state" : "MASTER",
            "authoritativeMaster" : true,
            "sequenceNumber" : 23,
            "haPort" : 5002,
            "availableStorageSize" : "3 GB"
          }, {
            "resourceId" : "rg2-rn1",
            "status" : "RUNNING",
            "requestsEnabled" : "ALL",
            "state" : "MASTER",
            "authoritativeMaster" : true,
            "sequenceNumber" : 23,
            "haPort" : 5003,
            "availableStorageSize" : "3 GB"
          } ],
          "anStatus" : [ ]
        }, {
          "resourceId" : "sn2",
          "hostname" : "node02",
          "registryPort" : 6000,
          "zone" : {
            "resourceId" : "zn2",
            "name" : "Boston",
            "type" : "SECONDARY",
            "allowArbiters" : false,
            "masterAffinity" : false
          },
          "serviceStatus" : "RUNNING",
          "version" : "24.1.11 2024-04-05 09:33:45 UTC  Build id: a72484b8b33c Edition: Enterprise",
          "adminStatus" : {
            "resourceId" : "admin2",
            "status" : "RUNNING",
            "state" : "REPLICA"
          },
          "rnStatus" : [ {
            "resourceId" : "rg1-rn2",
            "status" : "RUNNING",
            "requestsEnabled" : "ALL",
            "state" : "REPLICA",
            "sequenceNumber" : 23,
            "haPort" : 6003,
            "availableStorageSize" : "3 GB",
            "networkRestoreUnderway" : false,
            "delayMillis" : 0,
            "catchupTimeSecs" : 0,
            "catchupRateMillisPerMinute" : 0
          } ],
          "anStatus" : [ ]
        } ],
        "exitCode" : 0
      }
    }