Admin Tool

Overview

The AdminTool is a lightweight tool that provides the ability for invoking commands on a running XVM or Application. It is intended primarily for use by developers; dedicated administrative tools are recommended for production use cases. The AdminTool discovers running XVMs and connects to them over TCP via their advertised XVM acceptor.

Running The Admin Tool

The AdminTool can be found in the nvx-talon or nvx-core-all jar. And can be invoked as follows:

java -Dnv.discovery.descriptor=<xvm-discovery-descriptor> -cp "libs\*" com.neeve.tools.AdminTool

__   __      _____  _            _______ ______ ____  _____  __  __
\ \ / /     |  __ \| |        /\|__   __|  ____/ __ \|  __ \|  \/  |
 \ V /      | |__) | |       /  \  | |  | |__ | |  | | |__) | \  / |
  > <       |  ___/| |      / /\ \ | |  |  __|| |  | |  _  /| |\/| |
 / . \      | |    | |____ / ____ \| |  | |   | |__| | | \ \| |  | |
/_/ \_\     |_|    |______/_/    \_\_|  |_|    \____/|_|  \_\_|  |_|
XVM Admin Tool                             nvx-talon v3.12 (build 7)
                               Copyright(c) 2019 Neeve Research, LLC
                                                 All Rights Reserved
Type 'help' for the list of commands
admin>

... where the libs folder contains the talon jar and its dependencies. The same discovery descriptor used by the XVM must be specified when launching the tool as the AdminTool discovers running XVMs and connects to them via the acceptor that each XVM has broadcast.

Listing Running XVMs

The 'xvms' command can be used to see which XVMs have been discovered:

admin> xvms
XVM...
...cardholdermaster-1-1 [host = MY-LAPTOP, connected= false]
...cardholdermaster-2-1 [host = MY-LAPTOP, connected= false]
...cardmaster-1-1 [host = MY-LAPTOP, connected= false]
...cardmaster-2-1 [host = MY-LAPTOP, connected= false]
...fraudanalyzer-1-1 [host = MY-LAPTOP, connected= false]
...fraudanalyzer-2-1 [host = MY-LAPTOP, connected= false]
...merchantmaster-1-1 [host = MY-LAPTOP, connected= false]
...merchantmaster-2-1 [host = MY-LAPTOP, connected= false]
...perfdriver-1 [host = MY-LAPTOP, connected= false]

List Apps in an XVM

The list of apps loaded in an XVM can be determined by using the 'admin' which invokes a command on the XVM that returns the list of loaded apps.

admin> admin perfdriver-1 app_list
Invoking 'app_list' --> xvm 'perfdriver-1'...
OK[admin,perfdriver]
admin>

List App Commands

The list of apps loaded in an XVM can be determined using the listAppCommand command as follows. The following shows an example of listing the commands for the perfdriver app shown to be running in the perfdriver-1 XVM in the example above.

admin> listAppCommands -x perfdriver-1 -a perfdriver -u
Fetching commands for app='perfdriver' in xvm 'perfdriver-1'...
Found '11 commands:

...

getAuthorizationResponseCount ("Get Authorization Response Count")
  Gets the number of authorizations received
  Usage:
  getAuthorizationResponseCount
getAuthorizationRequestCount ("Get Authorization Request Count")
  Gets the number of authorizations requested
  Usage:
  getAuthorizationRequestCount
stopAuthorizationRequests ("Stop Sending")
  Halts Requests being sent to driven app
  Usage:
  stopAuthorizationRequests
sendAuthorizationRequests ("Send Authorization Requests")
  Drives Authorization Request traffic
  Usage:
  sendAuthorizationRequests [-c] [-r] [-a]
       [<-c|--count> The rate at which to send requests default='10000']
       [<-r|--rate> The rate at which to send requests default='1000']
       [<-a|--async> Whether or not to spin up a background thread to do
           the sends default='true']
seedMerchants ("Seed Merchants")
  Seeds merchants with their stores.
  Usage:
  seedMerchants [-c] [-r]
       [<-c|--count> The number of merchants to seed default='100']
       [<-r|--rate> The rate at which to send in merchants default='100']
seedCardHolders ("Seed Card Holders")
  Seeds card holders with their transaction history.
  Usage:
  seedCardHolders [-c] [-r] [-a]
       [<-c|--count> The number of card holders to seed default='100']
       [<-r|--rate> The rate at which to send in card holders
           default='100']
       [<-a|--async> Whether or not to spin up a background thread to do
           the sends default='true']

Invoking an App Command

A command on an application can be invoked using the invoke command. The following shows an example of invoking the getAuthorizationRequestCount listed in the section above.

admin> invoke perfdriver perfdriver-1 getAuthorizationRequestCount
Invoking 'getAuthorizationRequestCount' --> app='perfdriver' in xvm 'perfdriver-1'...
OK[1000]
admin>

Command Reference

Tool Properties

The following properties can be set using set <Property Name> <Property Value>:

Property Name	Default Value	Description
commandTimeout	30.0s	Sets the timeout to wait for a command response. If no unit suffix is specified the value is interpreted as SECONDS
connectHandshakeTimeout	1.5s	The connect timeout. If no unit suffix is specified the value is interpreted as SECONDS
longCommandDisplayThreshold	5.0s	Commands that take longer than the given time will result in the tool outputting their execution time. If no unit suffix is specified the value is interpreted as SECONDS
stacktraces	false	Whether or not command exception stacktraces should be dumped

Commands

listXvms | xvms

Shows available XVMs

Usage:
  listXvms [-h]

       [<-h|--help> Displays this help message (default='false')]

disconnect

Closes currently open admin connections

Usage:
  disconnect [-h] [<xvm>]

       [<-h|--help> Displays this help message (default='false')]
       [xvm: The XVM in whose connection should be closed (if omitted
           closes all connections) ]

connect

Connects to an XVM

Usage:
  connect [-h] <xvm>

       [<-h|--help> Displays this help message (default='false')]
       xvm: The XVM to connect to.

listAppCommands

List commands for an XVM or an app hosted by a XVM

Usage:
  listAppCommands [-h] -x [-a] [-u] [<filter>]

       [<-h|--help> Displays this help message (default='false')]
       <-x|--xvm> The XVM in which to list commands
       [<-a|--app> The app whose command to list. If 'admin' or omitted
           then XVM administration commands are listed. (default='admin')]
       [<-u|--usage> Flag that can be specified to additionally show usage
           for the commands. (default='false')]
       [filter: Optionally can be specified to list only commands that
           contain this filter in their name. '*' indicates that all commands
           should be displayed default='*']

invoke

Sends a command to a XVM or an app hosted by a XVM

Usage:
  invoke [-h] [<app>] <xvm> <command>

       [<-h|--help> Displays this help message (default='false')]
       [app: The app whose command to list. If 'xvm' or omitted then XVM
           commands are listed. default='admin']
       xvm: The XVM in which to list commands
       command: The name of the command to execute
       [args: The command arguments]

admin

Sends a command to a XVM or an app hosted by a XVM

Usage:
  admin [-h] <dest> <command>

       [<-h|--help> Displays this help message (default='false')]
       dest: The app and XVM against which to invoke the command specified
           as <appName>@<xvmName>.
 The appName can be omitted if the command
           is an XVM command.
       command: The name of the command to execute
       [args: The command arguments]

General Commands

get

Gets a configuration or environment property

Usage:
  get [-h] [-a] [<propName>]

       [<-h|--help> Displays this help message (default='false')]
       [<-a|--all> flag indicating that all properties should be listed
           (default='false')]
       [propName: The name of property to get, or with -a, a filter on
           properties to list]

reset

Reset a configuration or environment property to its default value

Usage:
  reset [-h] <propName>

       [<-h|--help> Displays this help message (default='false')]
       propName: The name of property to reset. '*' resets all properties
           to their default value.

set

Sets a configuration or environment property

Usage:
  set [-h] [<propName>] [<propValue>]

       [<-h|--help> Displays this help message (default='false')]
       [propName: The name of property to set, if no name is set config
           properties are listed]
       [propValue: The value of the property to set. If omitted clears the
           property]

stacktraces

Sets whether or not command exception stacktraces should be shown

Usage:
  stacktraces [-h] <enabled>

       [<-h|--help> Displays this help message (default='false')]
       enabled: <true|false|off|on> Indicates whether or not command
           exceptions should be displayed

history

Displays command history

Usage:
  history [-h] [-c] [<n>]

       [<-h|--help> Displays this help message (default='false')]
       [<-c|--clear> Clears command history]
       [n: lists only the last 'n' lines default='1000']

help

Displays help message

Usage:
  help [-h] [<command>]

       [<-h|--help> Displays this help message (default='false')]
       [command: When specifies displays help for that command only]

ansi

Enables or disables ansi output

Usage:
  ansi [-h] [<value>]

       [<-h|--help> Displays this help message (default='false')]
       [value: <off|on> Turns ansi on or off. With no argument display the
           current ansi setting]

echo

Displays a message or turns echo on or off

Usage:
  echo [-h] [<value>]

       [<-h|--help> Displays this help message (default='false')]
       [value: Displays a message or turns echo on or off. With no argument
           list the current echo setting]
       [message: A message to display default='']

script

Runs a command script

Usage:
  script [-h] [<script>]

       [<-h|--help> Displays this help message (default='false')]
       [script: The script file to execute]

bye | exit | quit

Exit the tool.

Usage:
  bye [-h]

       [<-h|--help> Displays this help message (default='false')]

Related Topics

• Implementing Command Handlers - Define custom commands for your applications

• Admin Over SMA - Remote administration via messaging

• XVM Stats and Heartbeats - Monitor XVM statistics

Next Steps

1. Configure discovery to match your XVM deployment

2. Launch Admin Tool and discover running XVMs

3. Connect to target XVM

4. List applications and their available commands

5. Invoke commands interactively or via scripts