Command line interface

Command line interface
Prev	Chapter 7. Reference	Next

Getting help

administrator has extensive built-in help. To access the top level help use administrator help.

administrator help         
  
  administrator [<global-parameter>=<value>,...]
      <command> <target> [<parameter>=<value>,...]
      Command line syntax
  
  administrator {[hostname=<host>] adminport=<port>
      | servicename=<name>} help
      List of available targets on a node.
  
  administrator {[hostname=<host>] adminport=<port>
      | servicename=<name>} help <target>
      Help for a specific target on a node.
  
  administrator help node
      Help for the node target.
  
  administrator help services
      Help for the services target.
  
  administrator help snapshot
      Help for the snapshot target.
  
  administrator help globals
      Help for global parameters

These different help options can be seen from the usage message:

List of all available targets on a node. A running node, adminport and hostname, or servicename, is required to access this help. See Example 7.1, “Target list help”.
Help for a specific target on a node. A running node, adminport and hostname, or servicename, is required to access this help. See Example 7.2, “Specific target help”.
Node target help. No running node is required to access this help. See Example 7.3, “Node target help”.
Services target help. No running node is required to access this help. See Example 7.4, “Services target help”.
Snapshot target help. No running node is required to access this help. See Example 7.5, “Snapshot target help”.
Global parameter help. No running node is required to access this help. See Example 7.6, “Global parameters help”.

Example 7.1. Target list help

administrator adminport=21447 help
  ldap
  jvm
  endpoint
  space
  distribution
  globaltransaction
  configuration
  session
  partition
  service
  security
  cluster
  cache
  node
  snapshot
  statistics

Example 7.2. Specific target help

administrator adminport=21447 help jvm
  display jvm
    [ name=<string value, default = ""> ]
        The JVM name.

    Display the state of a JVM.

  stop jvm
    name=<string value>
        The JVM name.

    Stop a JVM.

  start jvm
    name=<string value>
        The JVM name.

    Start a JVM.

  remove jvm
    name=<string value>
        The JVM name.

    Remove a JVM from the node.

Description:

    Manage JVMs on a node.

Example 7.3. Node target help

administrator help node
  display node

  getadminport node
        [ installpath=<value> ]
        [ nodename=<value> ]

    install node
      [ adminhost=<value> ]
      [ adminport=<value> ]
      [ application=<value> ]
      [ buildtype=<value> ]
      [ configpath=<value> ]
      [ deploydirectories=<value> ]
      [ description=<value> ]
      [ discoveryenabled=<true|false> ]
      [ discoveryport=<value> ]
      [ installpath=<value> ]
      [ javabinarypath=<value> ]
      [ javaenvironment=<value> ]
      [ javahome=<value> ]
      [ javalibrarypath=<value> ]
      [ memoryallocators=<value> ]
      [ memorysize=<value> ]
      [ memorytype=<value> ]
      [ nodename=<value> ]
      [ trustedhosts=<value> ]
      [ usehostaliases=<value> ]

   ...

Example 7.4. Services target help

administrator help services
  display services
    [ servicetype=<value> ]
    [ servicename=<value> ]
    [ timeout=<seconds> ]
    [ detailed=<boolean> ]
    [ properties=<property list> ]

  ...

Example 7.5. Snapshot target help

administrator help snapshot
  create snapshot
      [ description=<value> ]
      [ destination=<value> ]
      [ includeclasspaths=<false|true> ]
      [ installpath=<value> ]

      Create a snapshot archive.

  ...

Example 7.6. Global parameters help

administrator help globals
  adminport:      Administration port (no default).
  delimiter:      Enable delimited tabular output using parameter value
                  as delimiter.  Default is formatted text output.
  discoveryport   Port to use for service discovery.
                  Defaults to 54321.
  discoveryhost   The hostname to use to select which network
                  interface gets used for sending the discovery
                  request. The default uses the system's host name.
  domaingroup:    Target all nodes in domain group (no default).
  domainname:     Target all nodes in domain (no default).
  domainnode:     Target specific node (no default).
  hostname:       Host name (default localhost).
  password:       User password (no default).
  servicename:    Service name (no default).
  username:       User name (default login name).

Accessing a node

Accessing a node to perform an administrative action requires:

Valid credentials, i.e. a user name and password
Network addressing information

Credentials and network address information are specified using global parameters. See the section called “Global parameters” for details.

If a username is specified but a password is not, then administrator prompts for a password. If username is not specified, the user name in the shell environment in which administrator is executed is used as the user name. See Chapter 5, Security to learn how to configure access control.

Node address information is required for most commands (those that apply to a node). You can specify an explicit hostname and port number, or alternatively you can use a service name to access a node. See the section called “Service discovery” for details on using a service name.

Administration actions can also be addressed to multiple nodes simultaneously. This is supported by targeting an action at a domain manager node and specifying that the command should be targeted at all nodes in the domain, a subset of the nodes, or a specific node.

Service discovery

You do not need to supply a specific host name or port to address a node; you can use the node's published service name. If you need to find the nodes running on the network, you can perform discovery manually using the display services action.

Here is example output from the display services action:

administrator display services
Service Name = B
Service Type = node
Network Address = Kapoho.local:2002

Service Name = A
Service Type = node
Network Address = Kapoho.local:2001

Service Name = C
Service Type = node
Network Address = Kapoho.local:2003

Service Name = domainmanager
Service Type = node
Network Address = Kapoho.local:2000

This output indicates that administration actions could be targeted at a node named A using a service name of A instead of using a host name of Kapoho.local and a port number of 2001.

Domain manager

Administrative actions can be sent to a domain manager node for distribution to managed application nodes by specifying the host name and port number, or the service name, of the domain manager node. Global variables are used to indicate the final target of the administration command. See the section called “Global parameters” for details on the syntax. The final target if an action can be:

A single managed application node.
Multiple managed application nodes in the same domain group.
All application nodes being managed in the domain.


	Domain manager nodes also support administrative actions similar to application nodes to allow them to be managed using the same targets and commands as application nodes.

The following example sends a display cluster action to all nodes in the domain by specifying the domain name and the network address of the domain manager node. The annotated output shows that the output comes from each node in the domain. There are three nodes in the domain - A, B, and C.

administrator servicename=domainmanager domainname="Development" display cluster type=local
Node Name = C // Output from node C
Node Name = C
Distribution State = Running
Quorum State = Active
Quorum Description = All nodes up and running.
Number of Active Nodes = 2
Number of Discovered Nodes = 2
Number of Undiscovered Nodes = 0
Number of Connections to Remote Nodes = 9
Number of Type Mismatches = 0
Location Code = 67
Calculated CRC of System Types = 3695020283

Node Name = B // Output from node B
Node Name = B
Distribution State = Running
Quorum State = Active
Quorum Description = All nodes up and running.
Number of Active Nodes = 2
Number of Discovered Nodes = 2
Number of Undiscovered Nodes = 0
Number of Connections to Remote Nodes = 9
Number of Type Mismatches = 0
Location Code = 66
Calculated CRC of System Types = 3695020283

Node Name = A // Output from node C
Node Name = A
Distribution State = Running
Quorum State = Active
Quorum Description = All nodes up and running.
Number of Active Nodes = 2
Number of Discovered Nodes = 2
Number of Undiscovered Nodes = 0
Number of Connections to Remote Nodes = 8
Number of Type Mismatches = 0
Location Code = 65
Calculated CRC of System Types = 3695020283

Global parameters

Table 7.2, “Global parameters” summarizes the supported global parameters.

Table 7.2. Global parameters

Name	Example	Description
`adminport`	`adminport=2001`	Administration port on target node. Required if `servicename` not specified. No default.
`delimiter`	`delimiter=\|`	Format output as a table with the first row containing column names, and all other rows containing the columnar data. The delimiter character is used to separate all columns in all rows. Default is to output formatted plain text.
`discoveryport`	`discoveryport=54321`	Port to use for service discovery. Default value is 54321.
`discoveryhost`	`discoverhost=myhost`	The hostname to use to select which network interface gets used for sending the discovery request. The default value is the local machine's host name.
`domaingroup`	`domaingroup=EastCoast`	Target action at all application nodes in the specified domain group managed by a domain manager. Only valid if network address specifies a domain manager node. No default value.
`domainname`	`domainname=Development`	Target action at all application nodes in the specified domain managed by a domain manager Only valid if network address specifies a domain manager node. No default value.
`domainnode`	`domainnode=A`	Target action at a specific application node managed by a domain manager. Only valid if network address specifies a domain manager node. No default value.
`hostname`	`hostname=venus`	Host name where target node is running. This can be a simple name, a fully qualified name, or an IP address. Default value is `localhost`.
`password`	`password=guest`	User password to access target node. It is strongly recommended that passwords never be specified on the command line. See the section called “Accessing a node” for details on specifying a password. No default.
`servicename`	`servicename=A`	The service name of the target node. See the section called “Service discovery” for details on using service discovery. If `servicename` is specified, `hostname` and `adminport` are not required. No default.
`username`	`username=guest`	User name to access target node. Default value is login name of user executing `administrator`.

Supported targets

administrator supports both built-in targets and application specific targets. Application targets may be added during development of an application. See the TIBCO BusinessEvents® Extreme Java Developer's Guide for details. Application specific targets are not discussed further here.

The supported built-in targets are show in Table 7.3, “Built-in administration targets”.

Table 7.3. Built-in administration targets

Target	Description
`cache`	Named cache management
`cluster`	Cluster management.
`configuration`	Configuration management
`distribution`	Manage distribution services.
`domain`	Manage administration domain. Only available in a domain manager node.
`endpoint`	Manage channel endpoint (Java channels only)
`jvm`	Java virtual machine management.
`ldap`	Control external LDAP authentication sources.
`manager`	Display status of TIBCO BusinessEvents® Extreme Administrator server. Only available in domain manager node.
`node`	Node management.
`partition`	Partition management.
`security`	Security management.
`service`	Manage channel services (Java channels only)
`services`	Discover nodes using service discovery.
`session`	Manage channel sessions (Java channels only)
`snapshot`	Create a diagnostic snapshot of a node.
`statistics`	Capture and display runtime statistics.

Details on each of these targets can be found in the following sections. These sections provide a brief description of the supported commands and targets, along with any parameters. Examples are provided to help clarify a command's usage.


	Global parameters are not shown in the examples unless they are required to clarify command usage.

Channels

Channels are managed using the endpoint, service, and session targets.


	These targets can only be used to manage custom Java channels.

endpoint target

Manage channel endpoints.

clearstatistics command

Clear endpoint statistics.

clearstatistics endpoint
clearstatistics endpoint name=myEndpoint

Table 7.4. clearstatistics command parameters

Name	Description	Required
`name`	Optional endpoint name. If omitted, statistics are cleared for all endpoints.	No. No default.

disabletrace command

Disable tracing for an endpoint. The valid trace options are:

endpoint - trace endpoint level messages.
pdu - trace protocol data units.
session - trace session level messages.

A value of all can be used to indicate all trace options.

disabletrace endpoint name=myEndpoint
disabletrace endpoint name=myEndpoint options="session,pdu"

Table 7.5. disabletrace command parameters

Name	Description	Required
`name`	Endpoint name.	Yes.
`options`	Optional tracing options. A comma separated list of trace options to disable. Valid values are `endpoint`, `session`, `pdu`, or `all`. Specified values will be subtracted from current trace values.	No. Default value is `all`.

display command

Display endpoint information.

The name, state, servicename, and group parameters are used to filter the displayed endpoints. Only one of these parameters can be specified. If none of these parameters are specified, all endpoints are displayed.

display endpoint
display endpoint name=myEndpoint
display endpoint state=Started
display endpoint group=myGroup
display endpoint servicename=myService

Table 7.6. display command parameters

Name	Description	Required
`name`	Optional endpoint name. Only display endpoint with this name.	No. No default value.
`state`	Optional endpoint state. Valid values are `Stopped` or `Started`. Only display endpoints with specified state.	No. No default value.
`servicename`	Optional service name. Only display endpoints owned by this service.	No. No default value.
`group`	Optional group name. Only display endpoints owned by this group.	No. No default value.

enabletrace command

Enable tracing for an endpoint. The valid trace options are:

endpoint - trace endpoint level messages.
pdu - trace protocol data units.
session - trace session level messages.

A value of all can be used to indicate all trace options.

enabletrace endpoint name=myEndpoint
enabletrace endpoint name=myEndpoint options="session,pdu"

Table 7.7. enabletrace command parameters

Name	Description	Required
`name`	Endpoint name.	Yes.
`options`	Optional tracing options. A comma separated list of trace options to enable. Valid values are `endpoint`, `session`, `pdu`, or `all`. Specified values will be added to current trace values.	No. Default value is `all`.
`count`	Optional number of message to trace. Tracing is disabled after count messages. Use a value of zero to enable tracing until it is explicitly disabled using the `disabletrace` command.	No. Default value is `0`.

lock command

Lock an endpoint.

lock endpoint name=myEndpoint

Table 7.8. lock command parameters

Name	Description	Required
`name`	Endpoint name.	Yes.

start command

Start an endpoint.

start endpoint name=myEndpoint

Table 7.9. start command parameters

Name	Description	Required
`name`	Endpoint name.	Yes.

startall command

Start all endpoints.

The group parameter can be used to only start endpoints in a specific group, otherwise all endpoints are started.

startall endpoint
startall endpoint group=myGroup

Table 7.10. startall command parameters

Name	Description	Required
`group`	Optional group name. Only start endpoints in this group.	No. No default.

stop command

Stop an endpoint.

stop endpoint name=myEndpoint

Table 7.11. stop command parameters

Name	Description	Required
`name`	Endpoint name.	Yes.

stopall command

Stop all endpoints.

The group parameter can be used to only stop endpoints in a specific group, otherwise all endpoints are stopped.

stopall endpoint
stopall endpoint group=myGroup

Table 7.12. stopall command parameters

Name	Description	Required
`group`	Optional group name. Only stop endpoints in this group.	No. No default.

unlock command

Unlock an endpoint.

unlock endpoint name=myEndpoint

Table 7.13. unlock command parameters

Name	Description	Required
`name`	Endpoint name.	Yes.

service target

Manage channel services.

display command

Display service information.

The name, state, and group parameters are used to filter the displayed services. Only one of these parameters can be specified. If none of these parameters are specified, all services are displayed.

display service
display service name=myService
display service state=Started
display service group=myGroup

Table 7.14. display command parameters

Name	Description	Required
`name`	Optional service name. Only display service with this name.	No. No default value.
`state`	Optional service state. Valid values are `Stopped` or `Started`. Only display services with specified state.	No. No default value.
`group`	Optional group name. Only display services owned by this group.	No. No default value.

start command

Start a service.

start service name=myService

Table 7.15. start command parameters

Name	Description	Required
`name`	Service name.	Yes.

startall command

Start all services.

The group parameter can be used to only start services in a specific group, otherwise all services are started.

startall service
startall service group=myGroup

Table 7.16. startall command parameters

Name	Description	Required
`group`	Optional group name. Only start services in this group.	No. No default.

stop command

Stop a service.

stop service name=myService

Table 7.17. stop command parameters

Name	Description	Required
`name`	Service name.	Yes.

stopall command

Stop all services.

The group parameter can be used to only stop services in a specific group, otherwise all services are stopped.

stopall service
stopall service group=myGroup

Table 7.18. stopall command parameters

Name	Description	Required
`group`	Optional group name. Only stop services in this group.	No. No default.

session target

Manage channel sessions.

clearstatistics command

Clear session statistics.

clearstatistics session
clearstatistics session name=mySession

Table 7.19. clearstatistics command parameters

Name	Description	Required
`name`	Optional session name. If omitted, statistics are cleared for all session.	No. No default.

display command

Display session information.

The name, endpointname, and servicename parameters are used to filter the displayed sessions. Only one of these parameters can be specified. If none of these parameters are specified, all sessions are displayed.

display session
display session name=mySession
display session endpointname=myEndpoint
display session servicename=myService

Table 7.20. display command parameters

Name	Description	Required
`name`	Optional session name. Only display session with this name.	No. No default value.
`endpointname`	Optional endpoint name. Only display sessions owned by this endpoint.	No. No default value.
`servicename`	Optional service name. Only display sessions owned by this service.	No. No default value.

start command

Start a session.

start session name=mySession

Table 7.21. start command parameters

Name	Description	Required
`name`	Session name.	Yes.

stop command

Stop a session.

stop session name=mySession

Table 7.22. stop command parameters

Name	Description	Required
`name`	Session name.	Yes.

Diagnostics

Diagnostic information is captured by the snapshot target. The snapshot target creates an archive containing log files and other information required to help troubleshoot problems. A snapshot archive can be captured for an active or a failed node.

Snapshots are taken against active nodes using the adminport and hostname or servicename global parameters.

Snapshots are taken against failed nodes using the installpath parameter.

snapshot target

Create and manage snapshot archive files.

create command

Create a snapshot archive. The created archive is named <node name>.<timestamp>.zip.

create snapshot
create snapshot description="issue 4567"
create snapshot destination=/tmp
create snapshot includeclasspaths=true
create snapshot installpath=/opt/tibco/nodes/A

Table 7.23. create command parameters

Name	Description	Required
`description`	Optional description to include in archive. If specified a file named `description.txt` is included in the snapshot archive with the specified description.	No. No default value.
`destination`	Optional destination directory for archive.	No. Default directory is `<node directory>``/../snapshots/``<node name>`.
`includeclasspaths`	Optional boolean value on whether or not to include the contents of a node's classpath directories.	No. Default value is `false`.
`installpath`	Optional node installation path. This parameter can be used to specify the node directory to create a snapshot archive if the node is not operational.	Yes, if node not operational, otherwise optional. No default value.

Domain Manager

Domain management is accomplished using the domain and manager targets. These targets are only supported on Domain Manager nodes.

domain target

Manage an administrative domain.

addgroup command

Add a group to the administrative domain.

addgroup domain groupname=myGroup
addgroup domain groupname=myGroup properties="prop1=a,prop2=b"

Table 7.24. addgroup command parameters

Name	Description	Required
`groupname`	Group name.	Yes.
`properties`	Comma separated list of `<name>``=``<value>` service property pairs. If a node has these properties published in their ndoe service record, they will be automatically added to the group.	No. No default.

addgroupnode command

Add a managed node to a group. The node must already be managed by the domain and the group must be defined.

addgroupnode domain groupname=myGroup name=myNode

Table 7.25. addgroupnode command parameters

Name	Description	Required
`groupname`	Group name.	Yes.
`name`	Node name.	Yes.

addnode command

Add a new node to the administrative domain. The node must be started.

addnode domain name=myNodeServiceName
addnode domain name=myNodeServiceName timeout=10

Table 7.26. addnode command parameters

Name	Description	Required
`name`	Service name of node to add.	Yes.
`timeout`	Optional service lookup timeout in seconds. If the lookup of the node service is not completed in this time, the command fails.	No. Default value is 5.

display command

Display domain information. The supported display types are summarized in Table 7.27, “Display types”.

Table 7.27. Display types

Type	Description	Name Filter	Detailed Output
`application`	Deployed applications.	Application name.	Supported.
`domain`	Managed domain information.	Not used.	Unsupported.
`group`	Domain group information.	Group name.	Supported.
`node`	Managed node information.	Node name.	Unsupported.
`service`	Nodes visible to service discovery on the network that are not managed by the domain.	Node service name.	Supported.
`session`	User sessions with managed nodes.	User name.	Unsupported.

display domain
display domain type=application name=myApplication
display domain type=service detailed=true

Table 7.28. display command parameters

Name	Description	Required
`name`	Name filter. Name filtering is only supported on a subset of the display types. See Table 7.27, “Display types” for details.	No. No default value.
`type`	Display type indicator. Valid values are `application`, `domain`, `group`, `node`, `service`, or `session`.	No. Default value is `domain`.
`detailed`	Control detailed display output. Detailed output is only supported on a subset of the display types. See Table 7.27, “Display types” for details.	No. Default value is `false`.

endsession command

Terminate all user sessions with application nodes. If a user has no sessions with application nodes, this command quietly does nothing.

endsession domain
endsession domain username=aUser

Table 7.29. endsession command parameters

Name	Description	Required
`username`	Terminate sessions for this user.	No. Default value is login name of user executing administrative action.

removegroup command

Remove a group from the administration domain. Any nodes contained in this group are still managed by the domain.

removegroup domain groupname=myGroup

Table 7.30. removegroup command parameters

Name	Description	Required
`groupname`	Group name.	Yes.

removegroupnode command

Remove a managed node from a group. The node is still managed by the domain.

removegroupnode domain groupname=myGroup name=myNode

Table 7.31. removegroupnode command parameters

Name	Description	Required
`groupname`	Group name.	Yes.
`name`	Node name.	Yes.

removenode command

Remove a node from management by this domain.

removenode domain name=myNodeServiceName

Table 7.32. removenode command parameters

Name	Description	Required
`name`	Service name of node to add.	Yes.

manager target

Display information on the TIBCO BusinessEvents® Extreme Administrator server.

display command

Display the status of the TIBCO BusinessEvents® Extreme Administrator server.

display manager

High Availability and Distribution

High availability and distribution management is accomplished using the cluster, distribution, and partition targets.

cluster target

Manage the high-availability cluster

discover command

Verify connectivity to remote nodes.

This command ensures that the local node has network connectivity to all of the nodes in the nodes parameter. Success is reported if connectivity exists, otherwise a failure is returned.

discover cluster nodes="A,B"

Table 7.33. discover command parameters

Name	Description	Required
`nodes`	Comma separated list of nodes.	Yes.

display command

Display cluster information.

The type controls the information displayed. Valid values are:

classmismatches - Display class mismatch information between the local and discovered remote nodes.
configuration - Display local node configuration information.
local - Display local node status information.
remote - Display information about discovered remote nodes.

display cluster
display cluster type=configuration
display cluster type=local
display cluster type=remote
display cluster type=classmismatches

Table 7.34. display command parameters

Name	Description	Required
`type`	Optional information type to display. Valid values are one of `classmismatches`, `configuration`, `local`, or `remote`.	No. Default value is `remote`.

join command

Join the cluster.

Object migration is performed and active nodes are updated based on the partition definitions on the local node. This command blocks until all required object migration is complete. This is true for both synchronous and asynchronous partition definitions. A periodic percent complete message is returned while the join is executing. When this command returns any object migrations required to join the cluster have completed.

The type parameter controls the type of join that is performed. The valid join types are:

normal - Join following a normal node restart with no partitioned objects in shared memory.
purge - Join used to clear partitioned objects in shared memory. All partitioned objects on the local node are removed from shared memory before any object migrations occur.
merge - Join used to recover from a multiple master scenario. Partitioned objects on the local node are merged with objects from the current active nodes specified using the restorefromnode parameter. See the section called “define command” for details.

This command will fail if connectivity cannot be established to all required nodes.


	Concurrent execution of this command will fail.

join cluster
join cluster type=normal
join cluster type=purge
join cluster type=merge

Table 7.35. join command parameters

Name	Description	Required
`type`	Optional join type. Valid values are `normal` `purge`, or `merge`.	No. Default value is `normal`.

leave command

Leave the cluster.

The local node is removed from all partition definitions. If the local node was the active node, the next node in the node list is made the active node. If there are no replica nodes defined for partitions with the local node as the active node, the type parameter must be set to force to leave the cluster since these partitions will be abandoned.

This command will fail if connectivity cannot be established to all required nodes.


	Concurrent execution of this command will fail.

leave cluster
leave cluster type=normal
leave cluster type=force

Table 7.36. leave command parameters

Name	Description	Required
`type`	Optional leave type. Valid values are `normal` and `force`. A value of `force` allows the local node to leave a cluster even if a partition will be abandoned.	No. Default value is `normal`.

distribution target

Manage distribution services.

removenode command

Remove a discovered node.

removenode distribution remotenode=A

Table 7.37. removenode command parameters

Name	Description	Required
`remotenode`	Remote node name.	Yes.

globaltransaction target

Manage global transactions for a node.

abort command

Abort a local transaction initiated by a global transaction. The abort command cannot be run on the node initiating the global transaction. It can only be run on remote nodes involved in the global transaction.

abort globaltransaction tranId="serializable:98752449084876475:221:33:360614189986813"

Table 7.38. abort command parameters

Name	Description	Required
`tranId`	Global transaction identifier.	Yes.

commit command

Commit a local transaction initiated by a global transaction. The commit command cannot be run on the node initiating the global transaction. It can only be run on remote nodes involved in the global transaction.

commit globaltransaction tranId="serializable:98752449084876475:221:33:360614189986813"

Table 7.39. commit command parameters

Name	Description	Required
`tranId`	Global transaction identifier.	Yes.

display command

Display global transactions running on this node.

display globaltransaction
display globaltransaction verbose=true

Table 7.40. display command parameters

Name	Description	Required
`verbose`	Include additional global transaction details. The `verbose` option only displays additional details if debug tracing is enabled for distribution.	No. Default value if `false`.

partition target

Manage partitions.

define command

Define, or redefine, a partition definition.

Partitions should be defined on all nodes that need to be aware of the partition. This includes the active node, any replica nodes, and nodes that are using sparse partitions.

A join cluster command (the section called “join command”) or enable partition command (the section called “enable command”) must be executed after defining a partition to update the cluster with the new partition definitions.


	Concurrent execution of this command will fail.

define partition name=MyPartition activenode=A
define partition name=MyPartition activenode=A replicas="B,C"
define partition name=MyPartition activenode=A replicas="B,C" replicatypes="synchronous,asynchronous"
define partition name=MyPartition activenode=A replicas="B,C" replicaudit=discardreplica
define partition name=MyPartition activenode=A forcereplication=true
define partition name=MyPartition activenode=A objectspertransaction=10000
define partition name=MyPartition activenode=A numberofthreads=10
define partition name=MyPartition activenode=A restorefromnode=B
define partition name=MyPartition activenode=A broadcastupdates=false
define partition name=MyPartition activenode=A remoteenableaction=leavedisabled

//
//  Defines MyPartition on node D which is not the active or replica 
//  node for the partition, i.e. a sparse partition.
//
servicename=D define partition name=MyPartition activenode=A replicas="B,C"
servicename=D define partition name=MyPartition activenode=A replicas="B,C" sparseaudit=ignorenodelist

Table 7.41. define command parameters

Name	Description	Required
`name`	Partition name.	Yes.
`activenode`	Active node.	Yes.
`replicas`	Comma-separated list of replica nodes.	No. No default.
`replicatypes`	Comma-separated list of replica types. Valid values are `synchronous` or `asynchronous`. If specified, the number of entries in the `replicatypes` list must be the same as the number of entries in the `replicas` parameter.	No. Default value is `synchronous`.
`broadcastupdates`	Control broadcasting of partition updates to all nodes in the cluster when the partition is enabled. This option is used to support multiple-master testing. It should not be set to `true` in production deployments.	No. Default value is `true`.
`forcereplication`	Boolean controlling whether or not to force the copy of partitioned objects to all replica nodes when the partition's objects are migrated during a join cluster or a partition failover.	No. Default value is `false`.
`objectspertransaction`	The number of objects locked per transaction when the partition's objects are migrated during a join cluster or a partition failover. A value of 0 means that all objects are migrated in a single transaction.	No. Default value is 1000.
`numberofthreads`	The number of threads used when performing a partition migration during a join cluster or a partition failover. If the number of partition instances is less than the `objectspertransaction` property value, only one thread will be used. If the value of the `objectspertransaction` property is zero, the `numberofthreads` property is ignored, and all work is done in a single transaction.	No. Default value is 1.
`remoteenableaction`	Control whether this partition can be made active by an enable partition command on a remote node. Valid values are `enablepartition` and `leavedisabled`. Setting this property to `enablepartition` will allow this partition to be enabled by remote enable partitition commands. Setting this property to `leavedisabled` will prevent this partition from being enabled by remote enable partition commands.	No. Default value is `enablepartition`.
`replicaaudit`	An enumeration of the possible audits done when enabling a partition with replica nodes. Valid values are `ignorereplica,discardreplica`, or `waitactive`. `ignorereplica` ignores any non-active replica nodes when a partition is enabled. `discardreplica` removes any non-active replica nodes from the node list when a partition is enabled. `waitactive` waits for any non-active replica nodes when a partition is enabled. This parameter is quietly ignored if set for a partition without replica nodes.	No. Default value is `waitactive`.
`restorefromnode`	Define the node that the partition should be restored from when recovering from a multi-master scenario. The actual restore occurs when the join cluster type=merge command executes.	No. No default value. A cluster wide broadcast is used to determine the active node if not specified.
`sparseaudit`	An enumeration of the possible audits done when enabling a sparse partition. Valid values are `verifynodelist` and `ignorenodelist`. `verifynodelist` will audit that the active and replica nodes defined for the sparse partition match the active node's definition when the partition is enabled. `ignorenodelist` does not perform this audit. This property is quietly ignored if set for a non-sparse partition.	No. Default value is `verifynodelist`.

disable command

Disable a partition.

The partition is disabled on the local node. If the local node was the active node, the next node in the node list is made the active node. If there are no replica nodes defined for the partition with the local node as the active node, the type parameter must be set to force to disable the partition since the partition will be abandoned.

This command will fail if connectivity cannot be established to all required nodes.


	Concurrent execution of this command will fail.

disable partition name=MyPartition
disable partition name=MyPartition type=normal
disable partition name=MyPartition type=force

Table 7.42. disable command parameters

Name	Description	Required
`name`	Partition name.	Yes.
`type`	Optional disable type. Valid values are `normal` and `force`. A value of `force` will disable the partition even if the partition will be abandoned.	No. Default value is `normal`.

display command

Display partition information.

display partition
display partition name=MyPartition

Table 7.43. display command parameters

Name	Description	Required
`name`	Optional partition name. If not specified, all partitions are displayed.	No. No default value.

enable command

Enable a partition.

Object migration is performed and the active node is updated based on the partition definition on the local node. This command blocks until the enable is complete.

The type parameter controls the type of enable that is performed. The valid enable types are:

normal - Enable following a normal node restart with no partitioned objects in shared memory.
purge - Enable used to clear partitioned objects in the partition being enabled. All partitioned objects on the local node in the partition being enabled are removed from shared memory before any object migrations occur.
merge - Enable used to recover from a multiple master scenario. Partitioned objects on the local node in the partition being enabled are merged with objects from the current active node specified using the restorefromnode parameter. See the section called “define command” for details.

This command will fail if connectivity cannot be established to all required nodes.


	Concurrent execution of this command will fail.

enable partition name=MyPartition
enable partition name=MyPartition type=normal
enable partition name=MyPartition type=purge
enable partition name=MyPartition type=merge

Table 7.44. enable command parameters

Name	Description	Required
`name`	Partition name.	Yes.
`type`	Optional join type. Valid values are `normal` `purge`, or `merge`.	No. Default value is `normal`.

migrate command

Migrate a partition.

This command can only be executed on the current active node for a partition and the partition state must be active.

When the migration completes, the partition definition has been updated with the values specified in the activenode, replicas, and replicatypes parameters. Any of these values may be different than the original partition definition. Each object in the partition is migrated as needed to the active and replica nodes as specified by the activenode and replicas parameters.

This command blocks until partition migration has completed.


	Concurrent execution of this command will fail.

migrate partition name=MyPartition activenode=B
migrate partition name=MyPartition activenode=B replicas="A,C"
migrate partition name=MyPartition replicas="A,C" replicatypes="asynchronous,asynchronous"
migrate partition name=MyPartition activenode=B replicas="A,C" forcereplication=true
migrate partition name=MyPartition activenode=B replicas="A,C" objectspertransaction=100
migrate partition name=MyPartition activenode=B replicas="A,C" numberofthreads=5
migrate partition name=MyPartition activenode=B replicas="A,C" replicaaudit=discardreplica
migrate partition name=MyPartition activenode=B replicas="A,C" sparseaudit=ignorenodelist

Table 7.45. migrate command parameters

Name	Description	Required
`name`	Partition name.	Yes.
`activenode`	Active node for the partition.	No. Default value is the local node.
`replicas`	Comma-separated list of replica nodes.	No. No default.
`replicatypes`	Comma-separated list of replica types. Valid values are `synchronous` or `asynchronous`. If specified, the number of entries in the `replicatypes` list must be the same as the number of entries in the `replicas` parameter.	No. Default value is `synchronous`.
`forcereplication`	Boolean controlling whether or not to force the copy of the partition's objects to all existing replica nodes during the partition migration. Note that this value applies only to this partition migration. It does not override the `forcereplication` value set when defining the partition.	No. Default value is `false`.
`objectspertransaction`	The number of objects locked per transaction during the partition migration. A value of 0 means that all objects are migrated in a single transaction. Note that this value applies only to this partition migration. It does not override the `objectspertransaction` value set when defining the partition.	No. Default value is 1000.
`numberofthreads`	The number of threads to use when performing partition migration. If the number of partition instances is less than the `objectspertransaction` property value, only one thread will be used. If the value of the `objectspertransaction` property is zero, the `numberofthreads` property is ignored, and all work is done in a single transaction. Note that this value applies only to this partition migration. It does not override the `numberofthreads` value set when defining the partition.	No. Default value is 1.
`replicaaudit`	An enumeration of the possible audits done when enabling a partition with replica nodes. Valid values are `ignorereplica,discardreplica`, or `waitactive`. `ignorereplica` ignores any non-active replica nodes when a partition is enabled. `discardreplica` removes any non-active replica nodes from the node list when a partition is enabled. `waitactive` waits for any non-active replica nodes when a partition is enabled. This parameter is quietly ignored if set for a partition without replica nodes.	No. Default value is `waitactive`.
`sparseaudit`	An enumeration of the possible audits done when enabling a sparse partition. Valid values are `verifynodelist` and `ignorenodelist`. `verifynodelist` will audit that the active and replica nodes defined for the sparse partition match the active node's definition when the partition is enabled. `ignorenodelist` does not perform this audit. This property is quietly ignored if set for a non-sparse partition.	No. Default value is `verifynodelist`.

update command

Update partition mappings.

This command updates the partition mapping of all instances in the partitions specified in the names parameter. The actual updates that occur is dependent on the installed partition mappers.

This command blocks until the update is complete.


	Concurrent execution of this command will fail.

update partition names="MyPartition,MyOtherPartition
update partition names="MyPartition,MyOtherPartition" objectspertransaction=10000
update partition names="MyPartition,MyOtherPartition" numberofthreads=25

Table 7.46. update command parameters

Name	Description	Required
`names`	Comma separated list of partitions to update.	Yes.
`objectspertransaction`	The number of objects locked per transaction during the partition update. A value of 0 means that all objects are updated in a single transaction. Note that this value applies only to this partition update. It does not override the `objectspertransaction` value set when defining the partition.	No. Default value is 1000.
`numberofthreads`	The number of threads to use when performing the partition update. If the number of partition instances is less than the `objectspertransaction` property value, only one thread will be used. If the value of the `objectspertransaction` property is zero, the `numberofthreads` property is ignored, and all work is done in a single transaction. Note that this value applies only to this partition update. It does not override the `numberofthreads` value set when defining the partition.	No. Default value is 1.

Java Virtual Machines

Java virtual machine management within a node is accomplished using the jvm target.

jvm target

Manage the life-cycle of Java Virtual Machines.

display command

Display the status of deployed JVMs. If name parameter not specified information is displayed for all deployed JVMs.

display jvm
display jvm name=myJvmName

Table 7.47. display command parameters

Name	Description	Required
`name`	JVM name.	No. No default value.

remove command

Remove a stopped JVM.

remove jvm name=myJvmName

Table 7.48. remove command parameters

Name	Description	Required
`name`	JVM name.	Yes.

start command

Start a deployed JVM

start jvm name=myJvmName

Table 7.49. start command parameters

Name	Description	Required
name	JVM name.	Yes.

stop command

Stop a running JVM.

stop jvm name=myJvmName

Table 7.50. stop command parameters

Name	Description	Required
`name`	JVM name.	Yes.

Named Caches

Named cache management is accomplished using the cache target.

cache target

Manage named caches.

add command

Add a new type to an existing named cache.

add cache name=MyCache type=managed.Type

Table 7.51. add command parameters

Name	Description	Required
`name`	Cache name.	Yes.
`type`	Fully scoped type name.	Yes.

create command

Create a named cache. Cache names are unique on a node. If the cache being created already exists, this command quietly does nothing. Newly created caches have an unlimited cache size.

create cache name=MyCache

Table 7.52. create command parameters

Name	Description	Required
`name`	Cache name.	Yes.

display command

Display information about named caches on a node. If name is not specified, information about all caches is displayed.

display cache
display cache name=MyCache

Table 7.53. display command parameters

Name	Description	Required
`name`	Cache name.	No. No default value.

remove command

Remove a named cache. All objects in the cache are restored to their default caching behavior.

remove cache name=MyCache

Table 7.54. remove command parameters

Name	Description	Required
`name`	Cache name.	Yes.

set command

Set or change cache size. When changing a cache size, any required object flushing will occur asynchronously.

Cache sizes can be set as a percentage of total shared memory in the node, or as an absolute size. When setting size using an absolute size these suffixes are supported:

None - size in bytes.
K - size in kilobytes.
M - size in megabytes.
G - size in gigabytes.

Percentage values are specified using a % suffix.

set cache name=MyCache size=0%    // Disables caching
set cache name=MyCache size=100%  // Unlimited cache size
set cache name=MyCache size=50%   // Size cache to 50% of node shared memory
set cache name=MyCache size=0     // Disables caching
set cache name=MyCache size=25000 // Set cache size to 25000 bytes
set cache name=MyCache size=25K   // Set cache size to 25 kilobytes
set cache name=MyCache size=2M    // Set cache size to 2 megabytes
set cache name=MyCache size=1G    // Set cache size to 1 gigabyte

Table 7.55. set command parameters

Name	Description	Required
`name`	Cache name.	Yes.
`size`	Cache size - percentage of shared memory or an absolute value.	Yes.

Nodes

Configuration management for a node is accomplished using the configuration target. Node management is accomplished using the node target. Nodes can be discovered using service discovery using the services target.

configuration target

Manage configuration.

activate command

Activate configuration.

If there is already an active configuration with the same type and name, it is deactivated as part of activating the current configuration.

activate configuration type=MyConfigurationType name=myConfiguration version="1.0"

Table 7.56. activate command parameters

Name	Description	Required
`type`	Configuration type.	Yes.
`name`	Configuration name.	Yes.
`version`	Configuration version.	Yes.

clearhistory command

Clear configuration state change history.

Configuration change history that meets the specified filter criteria defined using the parameters to this command is cleared. The filter parameters have this precedence - type, name, version, date. To specify a lower precedent filter value, all higher precedent values must be specified. For example, if name is specified, type also must be.

The date parameter is used to remove configuration history older than the specified date.

clearhistory configuration
clearhistory configuration type=MyConfigurationType
clearhistory configuration type=MyConfigurationType name=myConfiguration
clearhistory configuration type=MyConfigurationType name=myConfiguration version="1.0"
clearhistory configuration type=MyConfigurationType name=myConfiguration version="1.0" date="2005-07-31-23:59:59"

Table 7.57. clearhistory command parameters

Name	Description	Required
`type`	Configuration type.	No. No default value.
`name`	Configuration name.	No. No default value.
`version`	Configuration version.	No. No default value.
date	Older than date. Format is `%Y``-``%m``-``%d``-``%H``:``%M``:``%S` where month (%m) is specified as a number (1-12), hour (%H) is between 0 and 23 inclusive, and a dash separates the date and time. For example, `2005-07-31-23:59:59`. Time value must be specified in the local timezone of the node.	No. No default value.

deactivate command

Deactivate configuration.

This command will leave the node with no active configuration. It is generally recommended to use the activate command to atomically deactivate and activate new configuration.

deactivate configuration type=MyConfigurationType name=myConfiguration version="1.0"

Table 7.58. deactivate command parameters

Name	Description	Required
`type`	Configuration type.	Yes.
`name`	Configuration name.	Yes.
`version`	Configuration version.	Yes.

display command

Display configuration.

The type, name, and version parameters are used as filters to control which configuration is displayed. The parameters have this precedence - type, name, version. To specify a lower precedent parameter, all higher precedent parameters must be specified. For example, if name is specified, type also must be.

display configuration
display configuration type=MyConfigurationType
display configuration type=MyConfigurationType name=myConfiguration
display configuration type=MyConfigurationType name=myConfiguration version="1.0"
display configuration history=true

Table 7.59. display command parameters

Name	Description	Required
`type`	Configuration type.	No. No default value.
`name`	Configuration name.	No. No default value.
`version`	Configuration version.	No. No default value.
history	Boolean to control display of configuration state change history. A value of `true` will display the history.	No. Default value is `false`.

export command

Export configuration data.

The exported configuration is in format that can be reloaded after making any required changes.

export configuration type=MyConfigurationType name=myConfiguration version="1.0"

Table 7.60. export command parameters

Name	Description	Required
`type`	Configuration type.	Yes.
`name`	Configuration name.	Yes.
`version`	Configuration version.	Yes.

load command

Load configuration data.

The configuration file has been loaded into shared memory after this command completes - but it is not active. It needs to be activated using the activate command to take affect.

load configuration source=myConfiguration.kcs
load configuration source=myConfiguration.kcs forcelocal=true
load configuration source=myConfiguration.kcs ignorethrottle=true

Table 7.61. load command parameters

Name	Description	Required
`source`	Configuration file.	Yes.
`forcelocal`	If `true`, this parameter loads the configuration file from the node's file system, rather than loading the configuration file from `administrator` client using the network connection to the node. If `true`, any path information in the `source` parameter must be valid for the node.	No. Default is `false`.
`ignorethrottle`	By default configuration files cannot be loaded if a node's shared memory utilization exceeds the configured throttle threshold (See Table 3.4, “Memory throttling configuration”). Setting this parameter to `true` will load the configuration file even if shared memory utilization exceeds the configured throttle value. Set this value to `true` with caution since it can cause memory exhaustion on a running system.	No. Default is `false`.

loadactivate command

Load and activate configuration data.

The configuration files have been loaded into shared memory and activated after this command completes.

loadactivate configuration sourcelist="myConfiguration.kcs:myOtherConfiguration.kcs"
loadactivate configuration sourcelist=myConfiguration.kcs forcelocal=true
loadactivate configuration sourcelist=myConfiguration.kcs ignorethrottle=true

Table 7.62. load command parameters

Name	Description	Required
`sourcelist`	A colon separated list of configuration files.	Yes.
`forcelocal`	If `true`, this parameter loads the configuration file from the node's file system, rather than loading the configuration file from `administrator` client using the network connection to the node. If `true`, any path information in the `source` parameter must be valid for the node.	No. Default is `false`.
`ignorethrottle`	By default configuration files cannot be loaded if a node's shared memory utilization exceeds the configured throttle threshold (See Table 3.4, “Memory throttling configuration”). Setting this parameter to `true` will load the configuration file even if shared memory utilization exceeds the configured throttle value. Set this value to `true` with caution since it can cause memory exhaustion on a running system.	No. Default is `false`.

remove command

Remove configuration data from shared memory.

The configuration being removed cannot be active. Configuration that is removed from shared memory must be reloaded using either the load or loadactivate commands.

remove configuration type=MyConfigurationType name=myConfiguration version="1.0"

Table 7.63. remove command parameters

Name	Description	Required
`type`	Configuration type.	Yes.
`name`	Configuration name.	Yes.
`version`	Configuration version.	Yes.

node target

Manage node life-cycle.

display command

Display node information.

display node

getadminport command

Get the administrative port for a node.

The only valid global parameter for this command is hostname. The hostname global parameter can be used to execute this command on a remote machine. SSH access is required to the machine specified in the hostname parameter. See the section called “Secure Shell (SSH)” for details.

getadminport node
getadminport node installpath=/opt/tibco/RUN/A
hostname=acme.com getadminport node installpath=/opt/tibco/RUN/A

Table 7.64. getadminport command parameters

Name	Description	Required
`installpath`	Installation path.	No. Default is `<current working directory>``/``<local host name>`

install command

Install a node.

The only valid global parameter for this command is hostname. The hostname global parameter can be used to execute this command on a remote machine. SSH access is required to the machine specified in the hostname parameter. See the section called “Secure Shell (SSH)” for details.

The javahome parameter can be used to configure the JRE or JDK used by the node. Usually, this parameter is not required since you will typically want the node to use the JRE shipped with the product.

The javalibrarypath, javabinarypath, and javaenvironment parameters can be used to update the node's environment, as required, for the JRE/JDK configured with the javahome parameter. The default values for these parameters are set for the JRE shipped with the product. If your JRE/JDK is a different version of that JRE then the default values for these options are likely correct for your JRE.

install node
install node application=kabira/kdm
install node adminport=1234 nodename="MyNode"
install node buildtype=DEVELOPMENT memorytype=sysvshm memorysize=2048 memoryallocators=4
install node description="my application node"
install node installpath=/opt/tibco/A configpath=/opt/tibco/configuration deploydirectories=/opt/tibco/deploy
install node javahome=$JAVA_HOME 
install node trustedhosts="host1,host2,host3" usehostaliases=false
hostname=acme.com install node installpath=/opt/tibco/RUN/A nodename=A

Table 7.65. install command parameters

Name	Description	Required
`adminhost`	Set the host address used to receive administrative commands.	No. Default is all network interfaces.
`adminport`	Set the port used to receive administrative commands. Note that the `adminport` parameter follows `install node`, and is not the `adminport` global parameter. Use of the `adminport` global parameter is illegal for the `install` command, since the node is not running when the command is executed.	No. Default is a random port.
`application`	Type of node to install. Supported node types are application or a domain manager. To install an application node, this parameter should be omitted. To install a domain manager node this parameter should have a value of `kabira/kdm`.	No. Default is an application node.
`buildtype`	Build type of node to be installed. Valid values are `DEVELOPMENT` and `PRODUCTION`.	No . Default is `PRODUCTION`.
`configpath`	Directory in which to install configuration files. May be absolute or relative to the current directory.	No. Default is `<installpath>``/../configuration/``<nodename>`
`deploydirectories`	One or more directories where application JAR files can be installed. The directory names can be absolute or relative, and are separated with a `:`. All non-absolute paths are relative to the node `installpath` directory. If the directories do not exist, they are created during node installation. If a directory cannot be created, a warning message is generated, but node installation continues. Removing a node has no impact on the `deploydirectories` directories and their contents. All of the JAR files contained in these directories are automatically added to the class path for all JVMs started in the node. The directories are added in the order they are specified in the `deploydirectories` parameter. All file names within each directory are added using an ASCII sort order on the file names.	No. Default is `<installpath>``/../deploy`.
`description`	A description string for the node, which will be part of the node service record for the node.	No. Default is an empty string.
`discoveryenabled`	A boolean property to enable or disable the discovery service.	No. Default is `true`.
`discoveryport`	Discovery port number.	No. Default value is 54321.
`installpath`	Directory in which to install the node. May be absolute or relative to the current directory. The directory cannot exist.	No. Default is `<current working directory>``/``<node name>`
`javabinarypath`	A list of JRE/JDK directories to add to the node's binary search path. Relative paths are relative to the directory specified in the `javahome` parameter. Use the `:` character to separate directories in the list. If this parameter is specified then the `javahome` parameter must also be specified.	No. Default is built-in value.
`javaenvironment`	A comma-separated list of name/value pairs specifying the environment variables to add to the node's environment for the JRE/JDK specified by the `javahome` parameter.	No. Default is an empty list.
`javahome`	Location of the JRE or JDK to be used by the node.	No. Default is built-in value.
`javalibrarypath`	A list of JRE/JDK directories to add to the node's library search path. Relative paths are relative to the directory specified in the `javahome` parameter. Use the `:` character to separate directories in the list. If this parameter is specified then the `javahome` parameter must also be specified.	No. Default is built-in value.
`memoryallocators`	Number of concurrent shared memory allocators.	No. Default value is based on number of cores in the machine.
`memorysize`	Size of shared memory in megabytes.	No. Default value is 512.
`memorytype`	Type of memory to use for system shared memory. The value `file` indicates a memory mapped file. The value `sysvshm` is System V Shared memory.	No. Default value is `file`.
`nodename`	Node name.	No. Default value is local host name.
`trustedhosts`	Specifies trusted hosts for node. The value to this parameter is a comma-separated list of host names`.`	No. Default value is empty list.
`usehostaliases`	Boolean value that specifies whether the node should look for host aliases (in `/etc/hosts` and directory services) when defining trusted hosts.	No. Default value is `true`.

remove command

Remove a stopped node.

When a node is removed, the node coordinator is stopped if it is still running, and the node directory is deleted. If the node configuration directory was located outside the node directory, it is left intact.

Use the hostname and adminport or servicename global parameters to identify the node to be removed.

If the remove command fails because it cannot connect to the node, then use the installpath parameter to identify the node directory. To remove a failed node on a remote machine use the hostname global parameter. SSH access is required to the machine specified in the hostname parameter. See the section called “Secure Shell (SSH)” for details.

remove node
remove node installpath=/opt/tibco/RUN/A
hostname=acme.com remove node installpath=/opt/tibco/RUN/A

Table 7.66. remove command parameters

Name	Description	Required
`installpath`	Installation path.	No. No default value.

restore command

Restore a node that was previously upgraded using the upgrade command.

The JAR files being restored must be copied into one of the deployment directories for the node before executing the restore command.

The restore command performs the following steps if the node is running:

Leave the cluster. All partitions with this node as the active node will migrate to a replica.
Stop the node.
Update the deployment directories for the node if deploydirectories is set on the command line.
Remove all managed objects for classes being restored.
Restart the node.
Add this node as a replica to all partitions that were active on this node and join the cluster.

The restore command performs the following steps if the node is not running:

Update the deployment directories for the node if deploydirectories is set on the command line.
Remove all managed objects for classes being restored.
Start the node.

Upon successful completion a restore report is generated containing information on what was restored.

restore node restorefile=version2.txt
restore node restorefile=version2.txt execute=true
restore node restorefile=version2.txt execute=true deploydirectories=/opt/tibco/deployV2

Table 7.67. restore command parameters

Name	Description	Required
`restorefile`	File containing the list of classes to restore. This is the `upgradefile` that was passed to the upgrade command. All non-absolute paths are relative to the node `installpath` directory.	Yes.
`allownonpartitioned`	A boolean value indicating whether a restore should be allowed if there are instances of non-partitioned objects in shared memory. Setting this value to `true` allows restores to continue, but all non-partitioned objects are deleted as part of the restore process.	No. Default value is `false`.
`execute`	A boolean value indicating whether the command should be executed. A value of `false` only generates the restore report. A value of `true` generates the report and also executes the command.	No. Default value is `false`.
`deploydirectories`	Updated deployment directories for the node. See Table 7.65, “install command parameters” for more details on this parameter.	No. Default is value set when node was installed.

start command

Start a node or restart the node coordinator.

The start command can be used to start a node, or restart the node coordinator after a terminate command. The installpath parameter controls whether the start command is being used to start the node, or to restart the node coordinator.

start node
start node maxretries=50
start node installpath=/opt/tibco/A

Table 7.68. start command parameters

Name	Description	Required
`installpath`	Node installation directory. May be absolute or relative to the current directory. This parameter must be specified to restart the node coordinator.	No. Default is `<current working directory>``/``<node name>.`
`maxretries`	Amount of time in seconds to wait for node to start.	No. Default value is 300 seconds.

stop command

Stop a running node.

When a node is stopped, the node coordinator is left running, and will not be stopped unless the node is removed. Executing the start command will restart all application processes.

stop node

terminate command

Terminate the node coordinator.

The start command can be used to restart the node coordinator.

terminate node

upgrade command

Upgrade a node.

This command upgrades the classes specified in the upgradefile parameter. This command must be used to upgrade nodes in a cluster. It can be run against a newly installed node, or a running node.

The new JAR files for the upgrade must be copied into a deployment directory for the node before performing the upgrade command.

The upgrade command performs the following steps if the node is running:

Validate that all classes being upgraded have a partition mapper installed, unless the allownonpartitioned parameter is set to true.
Leave the cluster. All partitions with this node as the active node will migrate to a replica.
Stop the node.
Update the deployment directories for the node if deploydirectories is set on the command line.
Remove all managed objects for classes being upgraded.
Restart the node.
Add this node as a replica to all partitions that were active on this node and join the cluster.

The upgrade command performs the following steps if the node is not running:

Update the deployment directories for the node if deploydirectories is set on the command line.
Remove all managed objects for classes being restored.
Start the node.

Upon successful completion an upgrade report is generated containing information on what was upgrade.

upgrade node upgradefile=version2.txt
upgrade node upgradefile=version2.txt execute=true
upgrade node upgradefile=version2.txt execute=true deploydirectories=/opt/tibco/deployV2
upgrade node upgradefile=version2.txt jvmnames=myApplication allownonpartitioned=true

Table 7.69. upgrade command parameters

Name	Description	Required
`upgradefile`	File containing the list of classes to upgrade. This file is generated by the upgrade tool. All non-absolute paths are relative to the node `installpath` directory.	Yes.
`allownonpartitioned`	A boolean value indicating whether an upgrade should be allowed if there are instances of non-partitioned objects in shared memory. Setting this value to `true` allows upgrades to continue, but all non-partitioned objects are deleted as part of the upgrade process.	No. Default value is `false`.
`execute`	A boolean value indicating whether the command should be executed. A value of `false` only generates the upgrade report. A value of `true` generates the report and also executes the command.	No. Default value is `false`.
`deploydirectories`	Updated deployment directories for the node. See Table 7.65, “install command parameters” for more details on this parameter.	No. Default is value set when node was installed.
`jvmnames`	A comma-separated list of JVM names to be used when searching for JVM specific deploy directories, when updating into a freshly installed node.	No. Default value is an empty list.

services target

Use service discovery to discover nodes on the local network.

display command

Display services.

display services timeout=30
display services timeout=30 servicename=A
display services timeout=30 detailed=true
display services timeout=30 properties="property2=value1,property2=value2"

Table 7.70. display command parameters

Name	Description	Required
`servicetype`	Service type to discover.	No. Default is show all service types.
`servicename`	Service name to discover.	No. Default is show all discovered services.
`timeout`	Number of seconds to wait for results.	No. Default is two seconds.
`detailed`	Boolean value controlling detailed output.	No. Default is `false`.
`properties`	Comma separated list of `<name>``=``<value>` pairs used to filter returned services.	No. Default value is an empty list.

Security

Control of external LDAP servers used for authorization is accomplished using the ldap target. User management is done using the security target.

ldap target

Manage LDAP authentication servers.

disable command

Disable an LDAP server.

disable ldap server=myLdapServer

Table 7.71. disable command parameters

Name	Description	Required
`server`	Configured LDAP server name.	Yes.

display command

Display the status of LDAP servers.

The server and source parameters are used to filter the output. If neither is specified, all configured LDAP servers will be displayed. If server is specified, only that server will be displayed. If source is specified, all LDAP servers configured for that authentication source will be displayed.

display ldap
display ldap server=myLdapServer
display ldap source=myLdapAuthenticationSource

Table 7.72. display command parameters

Name	Description	Required
`server`	Configured LDAP server name.	No. No default value.
`source`	Configured authentication source.	No. No default value.

enable command

Enable an LDAP server.

enable ldap server=myLdapServer

Table 7.73. enable command parameters

Name	Description	Required
`server`	Configured LDAP server name.	Yes.

security target

Manage node security.

add command

Add a user.

The user being added cannot already exist on this node.

The administrator executing this command will be prompted for the new user's password, unless the deferredpassword parameter is set to true.

add security username=auser roles=switchmonitor
add security username=auser roles=switchmonitor passwordexpirationdays=10 trustedhostuser=true allowemptypassword=false
add security username=auser roles=switchmonitor passwordrequired=true deferredpassword=true

Table 7.74. add command parameters

Name	Description	Required
`username`	User name.	Yes.
`roles`	Comma separated list of roles.	Yes.
`passwordexpirationdays`	Password expiration time, in days. A value of 0 means that the password does not expire.	No. Default value is 0.
`trustedhostuser`	Boolean indicating whether the user may only be authenticated when connecting from a trusted host.	No. Default value is `false`.
`allowemptypassword`	Boolean indicating whether to allow an empty password for this user.	No. Default value is `true`.
`passwordrequired`	Boolean indicating whether a password is always required. If `true`, the user must always present a password during authentication, and cannot use the trusted host facility.	No. Default value is `false`.
`deferredpassword`	If `true`, password definition is deferred until the initial authentication event.	No. Default value is `false`.

audit command

Audit security policy configuration for administration targets.

If the name parameter is not specified, auditing is performed on all installed administration targets.

audit security
audit security name=configuration

Table 7.75. audit command parameters

Name	Description	Required
`name`	Target name.	No. No default value.

display command

Display security information.

Table 7.76. Display types

Type	Description	Name	Detailed
`accesscontrol`	Access control rules.	Fully scoped type name.	Yes.
`audit`	Audit rules.	Not used.	No.
`authenticationsources`	Authentication sources.	Authentication source name.	No.
`hosts`	Trusted hosts.	Host name.	No.
`principals`	Defined principals.	Principal name.	Yes.

display security type=accesscontrol
display security type=audit
display security type=authenticationsources name=Local
display security type=hosts 
display security type=principals detailed=true

Table 7.77. display command parameters

Name	Description	Required
`type`	Type of information to display. See Table 7.27, “Display types” for supported values.	Yes.
`name`	Filter output. See Table 7.27, “Display types” for details on name filtering.	No. No default value.
`detailed`	Display detailed output. See Table 7.27, “Display types” for details on which display types support detailed output. It is not an error to specify a value of `true` for types that do not support detailed output.	No. Default value is `false`.

export command

Export user configuration.

The exported configuration can be saved as a file and reloaded as configuration data to restore all user definitions for a node.

The users parameter can be used to restrict the export to a subset of the users defined on the node.

export security name=myUsers version="1.0"
export security name=myUsers version="1.0" users="auser,anotheruser"

Table 7.78. export command parameters

Name	Description	Required
`name`	Configuration name.	Yes.
`version`	Configuration version.	Yes.
`users`	Comma separated list of users to include in the configuration.	No. No default value.

remove command

Remove a user.

remove security username=auser

Table 7.79. remove command parameters

Name	Description	Required
`username`	User name.	Yes.

reset command

Reset a user's password.

The administrator executing this command will be prompted for the new password, unless the deferredpassword parameter is set to true.

reset security username=auser
reset security username=auser deferredpassword=true

Table 7.80. reset command parameters

Name	Description	Required
`username`	User name.	Yes.
`deferredpassword`	If `true`, password definition is deferred until the initial authentication event.	No. Default value is `false`.

update command

Update a user's security parameters.

The parameter values specified in this command update the current values for the user.


	This command cannot be used to change a user's password. Use the `reset` command to change a user's password.

update security username=auser roles="switchmonitor,switchadmin"
update security username=auser roles=switchmonitor passwordexpirationdays=20 trustedhostuser=false allowemptypassword=true
update security username=auser roles=switchmonitor passwordrequired=false

Table 7.81. update command parameters

Name	Description	Required
`username`	User name.	Yes.
`roles`	Comma separated list of roles.	Yes.
`passwordexpirationdays`	Password expiration time, in days. A value of 0 means that the password does not expire.	No. Default value is 0.
`trustedhostuser`	Boolean indicating whether the user may only be authenticated when connecting from a trusted host.	No. Default value is `false`.
`allowemptypassword`	Boolean indicating whether to allow an empty password for this user.	No. Default value is `true`.
`passwordrequired`	Boolean indicating whether a password is always required. If `true`, the user must always present a password during authentication, and cannot use the trusted host facility.	No. Default value is `false`.

Statistics

Access and control of runtime statistics collection is done using the statistics target.

Details on the statistics data gathered, and their meaning, can be found in the TIBCO BusinessEvents® Extreme Performance Tuning Guide.

statistics target

Access and control runtime statistics collection.

Supported statistics are defined in Table 7.82, “Supported statistics”. This columns in the table have these meanings:

Statistic - Statistic name
Description - Brief description.
Enable / Disable - Yes indicates that the statistic must be explicitly enabled to start collection and disabled to stop collection.
Clear - Yes indicates that the statistic value can be cleared.
Detailed - Yes indicates that detailed output is available for the statistic.
Filter - Indicates whether filtering is support for the statistic. For statistics that support filtering, the valid filter values are java or none. A value of java indicates that statistics are only reported for Java managed objects. A value of none reports statistics for all managed objects.

Table 7.82. Supported statistics

Statistic	Description	Enable / Disable	Clear	Detailed	Filter
`activetransactions`	Active Transactions	No	No	No	No
`allocationsummary`	Allocator Allocation Summary	No	No	No	No
`allocatorbuckets`	Allocator Buckets	No	No	Yes	No
`allocatorsummary`	Allocator Summary	No	No	No	No
`blockedtransactions`	Blocked Transactions	No	No	No	No
`businessstatemachine`	Business State Machine	No	Yes	No	No
`cpu`	CPU Utilization	Yes	No	No	No
`deadlock`	Deadlock	No	Yes	Yes	No
`disk`	Disk	Yes	No	No	No
`distributionchannel`	Distribution Network	Yes	Yes	Yes	No
`distributionnode`	Distribution	No	Yes	No	No
`engine`	Node Processes	No	No	No	No
`eventbus`	Shared Memory IPC	No	Yes	Yes	No
`eventlog`	Shared Memory IPC Detailed	Yes	Yes	No	No
`files`	Files	No	No	No	No
`hash`	Shared Memory Hashing	No	No	Yes	No
`host`	Kernel Information	No	No	No	No
`javacache`	JNI Cache	No	Yes	No	No
`javatransaction`	Transaction	Yes	Yes	Yes	No
`jni`	Runtime JNI Calls	Yes	Yes	No	No
`ktsevents`	Operator Events	No	Yes	No	No
`localmutex`	Local Mutex	Yes	Yes	Yes	No
`memoryusage`	Memory Usage	No	No	No	No
`mutex`	Shared Memory Mutex	Yes	Yes	Yes	No
`namedcache`	Named Caches	No	Yes	No	No
`native`	Native Runtime Calls	No	Yes	No	No
`navigation`	Query	No	Yes	No	`java` or `none`. Default is `java`.
`network`	Network	Yes	No	No	No
`object`	Objects	No	Yes	No	`java` or `none`. Default is `java`.
`partition`	Partition	No	Yes	No	No
`sar`	System Activity Reporter	Yes	No	No	No
`systeminfo`	System Information	No	No	No	No
`threads`	System Threads	No	No	No	No
`timer`	Timers	No	No	No	No
`transaction`	Transaction Locking	Yes	Yes	Yes	`java` or `none`. Default is `java`.
`transactioncontention`	Transaction Contention	Yes	Yes	No	`java` or `none`. Default is `java`.
`transactionpromotion`	Transaction Promotion	Yes	Yes	No	`java` or `none`. Default is `java`.
`vmstat`	Virtual Memory	Yes	No	No	No

clear command

Clear current statistic values. Clearing a statistic that does not support clear has no effect. See Table 7.82, “Supported statistics” for a list of statistics that support clearing.

clear statistics statistics="transaction,mutex"

Table 7.83. clear command parameters

Name	Description	Required
`statistics`	Comma separated list of statistics. See Table 7.82, “Supported statistics” for a complete list of valid statistics.	Yes.

disable command

Disable collection of statistics. Disabling a statistic that does not support disable has no effect. See Table 7.82, “Supported statistics” for a list of statistics that support disable.

disable statistics statistics="transaction,mutex"

Table 7.84. disable command parameters

Name	Description	Required
`statistics`	Comma separated list of statistics. See Table 7.82, “Supported statistics” for a complete list of valid statistics.	Yes.

display command

Display statistic values.

Displaying a statistic that has no data available will generate empty output.

display statistics statistics="transaction,mutex"
display statistics statistics="transaction,mutex" detailed=true
display statistics statistics="object,transaction" filter=none
display statistics statistics="transaction,mutex" label="Transaction & Mutex Report"

Table 7.85. display command parameters

Name	Description	Required
`statistics`	Comma separated list of statistics. See Table 7.82, “Supported statistics” for a complete list of valid statistics.	Yes.
`detailed`	Boolean indicating whether detailed values should be displayed. See Table 7.82, “Supported statistics” for statistics that support detailed output.	No. Default value is `false`.
`filter`	Filter statistics output. See Table 7.82, “Supported statistics” for statistics that support filtering and valid filter values. Only a single filter value may be specified for a list of statistics.	No. Default value is statistics specific.
`label`	A value to add to the header in non-delimited output.	No. No default.

enable command

Enable collection of statistics. Enabling a statistic that does not support enable has no effect. See Table 7.82, “Supported statistics” for a list of statistics that support enabling.

enable statistics statistics="transaction,mutex"

Table 7.86. enable command parameters

Name	Description	Required
`statistics`	Comma separated list of statistics. See Table 7.82, “Supported statistics” for a complete list of valid statistics.	Yes.

snapshot command

Display a timed snapshot of statistic values.

Internally the snapshot command performs these steps in order - warm up sleep, disable, clear, enable, time sleep, disable, display. The warm up sleep duration is controlled by the warmupseconds parameter. The time sleep duration is controlled by the time parameter.

snapshot statistics statistics="transaction,mutex" seconds=10
snapshot statistics statistics="transaction,mutex" seconds=10 warmupseconds=10 detailed=true
snapshot statistics statistics="object,transaction" seconds=10 filter=none
snapshot statistics statistics="transaction,mutex" seconds=10 warmupseconds=10 serialize=true

Table 7.87. snapshot command parameters

Name	Description	Required
`statistics`	Comma separated list of statistics. See Table 7.82, “Supported statistics” for a complete list of valid statistics.	Yes.
`seconds`	The number of seconds to collect data.	Yes.
`warmupseconds`	The number of seconds to wait before starting the snapshot collection cycle.	No . Default value is 0.
`detailed`	Value passed to the `display` command in the snapshot collection cycle.	No. No default value.
`filter`	Value passed to the `display` command in the snapshot collection cycle.	No. No default value.
`serialize`	Serialize collection of statistics if `true`. A separate collection cycle is executed for each statistic being collected, starting with the `warm up sleep`.	No. Default value is `false`.

status command

Display current collection status of statistics that can be enabled and disabled.

status statistics

supported command

Display supported statistics.

supported statistics

Prev	Up	Next
Required network ports	Home	Configuration file syntax