epadmin-node

epadmin node target — Manages the life cycle of nodes.

SYNOPSIS

epadmin [globalparameters] command node [commandparameters]

DESCRIPTION

Use the node target to manage the life cycle of nodes, from the foundational install and start commands to stop and remove. You can also retrieve information about running nodes, and can upgrade the application version running in a node. See Nodes in the Architecture Guide to understand the state machine for StreamBase Runtime nodes.

All epadmin node commands require you to identify the node and/or cluster you want to address, except when installing the node. You can provide this identity with global parameters in the following ways:

  • ‑‑servicename  Specify ‑‑servicename=nodename.clustername to identify a node, or ‑‑servicename=clustername to apply the command to all nodes in that cluster. You can shorten this parameter down to ‑‑servicen=.

  • ‑‑adminport on localhost  To address a node on the same machine, determine the node's administration port, and use ‑‑adminport=nnnnn. This can be shortened to ‑‑ad=nnnnn or even ‑‑a=nnnnn.

  • ‑‑adminport with --hostname  If the node of interest is on a remote machine, use the --hostname parameter with --adminport to identify the remote host. For the --hostname parameter to work, add a TrustedHosts configuration file to the src/main/configurations folder of the node's Studio project and restart the node (or for an already running node, upload and activate the new configuration). This configuration file must include addresses for the remote hosts you expect to connect from. See Trusted Hosts for a detailed look at the Trusted Hosts feature and a sample configuration file. See Default Security Configuration to understand how a TrustedHosts configuration works with the security system's defaults.

  • ‑‑hostname with ‑‑installpath  Certain node commands use an SSH connection to a remote host. The epadmin install node command uses SSH because the node does not yet exist. For certain other commands, If the node is on a remote host, and you have a record of the node directory's location, you can specify both the --hostname global parameter with the --installpath command parameter. This can work for quiesced or even for crashed nodes, and does not require Trusted Hosts configuration. For example: 

    epadmin install node
epadmin --hostname=sbsvr.acme.com start node --installpath=/path/to/node/dir/on/server
epadmin --hostname=sbsvr.acme.com remove node --installpath=/path/to/node/dir/on/server
epadmin --hostname=sbsvr.acme.com getadminport node --installpath=/path/to/node/dir/on/server

The node target has eight commands:

The designation [sn|ad] in syntax examples is a reminder that this command requires either the global parameter ‑‑servicename or the ‑‑adminport and ‑‑hostname combination to identify the node or cluster of interest.

epadmin display node

Retrieves and displays information lines about running nodes. display node has no command parameters. 

epadmin [sn|ad] display node
epadmin --servicename=M.sbuser display node    // the single node, M.sbuser
epadmin --adminport=29863 display node         // the same node by admin port
epadmin --servicename=sbuser display node      // all nodes in the sbuser cluster

Example output: 

[M.sbuser] Node Name = M.sbuser
[M.sbuser] Node Description = No description
[M.sbuser] Node State = Started
[M.sbuser] Host Name = devmachine.local
[M.sbuser] Administration Port = 29863
[M.sbuser] Discovery Service Implementation = UDP
[M.sbuser] Discovery Service Port = 54321
[M.sbuser] Discovery Service State = Running
[M.sbuser] Node Directory = /Users/sbuser/Documents/ws/Studio_1060E/.nodes/M.sbuser
[M.sbuser] Deployment Directories = /Users/sbuser/Documents/ws/Studio_1060E/.nodes/M.sbuser/deploy
[M.sbuser] Install Time = 2020-04-09 12:53:22 -0400 UTC
[M.sbuser] Last Start Time = 2020-04-09 12:53:29 -0400 UTC
[M.sbuser] Build Type = PRODUCTION
[M.sbuser] Product Version = TIBCO StreamBase Runtime 10.6.0-SNAPSHOT (build 2004061330)
[M.sbuser] Product Installation Directory = /Users/sbuser/Applications/TIBCO Streaming 10.6.0
[M.sbuser] Sensitive Configuration Data Encryption = Disabled
[M.sbuser] Secure Communication Profile Name = None

epadmin help display node

Retrieves and displays node information only if the node is active in availability zone. 

display node [--availabilityzone=<String>] 
 
 
      Display node information. 
 
 
      [--availabilityzone=<String>] Display node information only if the node 
          is in this availability zone. Default: none

Example output: 

epadmin --servicename=M.sbuser display node --availabilityzone=myzone 
          // information of all nodes in the myzone availability zone

epadmin getadminport node

Retrieves the administrative port for a node for use with the --adminport global parameter in subsequent epadmin commands.

Use this getadminport command if you know a node's nodename.clustername and the node is running locally. With the same information, you can also use the display command like the following: 

epadmin [sn|ad] display node | grep Administration
epadmin [sn|ad] display node | findstr Administration

If you have a record of the node directory's location, you can retrieve the administrative port number using the --installpath command parameter. This can work for quiesced or even for crashed nodes. If the node is on a remote host, also use the --hostname global parameter.

hostname is the only valid global parameter for this command. When using the --hostname parameter to connect to a remote machine, this command requires an SSH connection and does not require Trusted Hosts configuration. Some remote machines have SSH configured to accept password authentication; if your remote machine is not so configured, then you must have SSH public and private keys established on both local and remote machines. This is further described in Secure Shell on the epadmin reference page. 

epadmin [sn|ad] getadminport node
epadmin --servicename=M.sbuser getadminport node   // admin port for the named node
epadmin --servicename=sbuser getadminport node     // admin ports for all nodes in cluster
epadmin getadminport node --installpath=/opt/tibco/Nodedirs/M       // On localhost, Mac
epadmin getadminport node --installpath=C:\Users\sbuser\Nodedirs\M  // On localhost, Windows
epadmin --hostname=srv.acme.com getadminport node --installpath=/opt/tibco/Nodedirs/M
    // On remote host, with SSH keys configured locally and remotely
Command Parameter Description Required
installpath On localhost, the absolute path (or path relative to the current directory), of the node directory for the node of interest.

When used with --hostname to connect to a remote server, the absolute path to the node directory on the remote server.

No. The default is ./local-hostname

epadmin install node

Installs a node and optionally deploys a StreamBase application on that node.

The only valid global parameters for this command are hostname and username. Use the hostname global parameter to run this command on a remote machine, which requires SSH access as described in Secure Shell on the epadmin reference page. Use the username global parameter to specify a non-default user name for the node administration user.

Use the javahome command parameter to configure the JRE or JDK to be used by the node. If the javahome parameter is not specified, it defaults to JAVA_HOME set in the environment. Use the javalibrarypath, javabinarypath, and javaenvironment command parameters to update the node's environment, as required, for the JRE or JDK configured with the javahome parameter.

Any install node parameters, such as adminhost, that are also present in the node deployment configuration file override the values in the node deployment configuration. 

epadmin install node --nodename=A.X
epadmin install node --application=myapplication.zip --substitutions="foo=bar,pi=3.14159" \
        --nodedeploy=mynodeploy.conf --nodename=A.X
epadmin install node --application=myapplication.zip --nodedeploy=mydeploy.conf \
        --substitutionfile=mysubstitutions.prop
epadmin install node --adminport=1234 --nodename="MyNode"
epadmin install node --discoveryhosts="host1:host2" --discoveryport=9737
epadmin install node --buildtype=DEVELOPMENT --memorytype=sysvshm --memorysize=2048 \
        --memoryallocators=4
epadmin install node --nodedirectory=/opt/tibco/Nodedirs/A \
        --deploydirectories=/opt/tibco/deploy
epadmin install node --javahome=$JAVA_HOME --javabinarypath=/opt/jre/bin 
        --javalibrarypath=/opt/jre/lib --javaenvironment="foo=bar,pi=3.14159"
epadmin --hostname=acme.com install node --nodedirectory=/opt/tibco/Nodedirs/A --nodename=A \
        --producthome=/opt/tibco/str/11.1
epadmin install node --nodename=A.X --keystore=secret.ks --keystorepassword=supersecret

Here are the example contents of a substitution file. 

#
#  Substitution properties for myConfiguration.conf
#
foo=bar
pi=3.14159

install Command Parameters

Command Parameter Description Required
adminhost Sets the host address for the network interface on the local or remote host that is to receive administrative commands for the running node. The host can be specified as a simple host name, a fully qualified DNS name, or an IP address. No. The default is all network interfaces on localhost.
adminport Sets the port used to receive administrative commands.

Note

This adminport command parameter follows install node, and is not the adminport global parameter. The adminport global parameter is illegal for the install command, because the node is not running when the command is executed.

No. The default is a random port.
application Specifies the full or relative path to a StreamBase application archive to install on the node. Relative paths are relative to the current directory. The parameter does not recognize environment variable expansion or the tilde (~) shortcut. If you do not designate an application to load at install node time, the node installs without an application. Not required but used in most cases. The default is to install a node without an application.
buildtype Build type of node to be installed. Valid values are DEVELOPMENT and PRODUCTION. No. The default is PRODUCTION.
deploydirectories Specifies the full or relative paths to one or more directories where you can place application JAR files or resources for reference by the node being installed. The directory names can be absolute or relative, and are separated with a colon (:), except for Windows which uses a semi-colon (;). All non-absolute paths are relative to the node nodedirectory directory. The directories must exist. All of the JAR files contained in these directories are automatically added to the class path for all engines 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. The default is nodedir/deploy. These JARs and resources in the default location are removed when the node is removed.
discoveryhosts A comma-separated list of host names to specify which network interfaces the node uses to send discovery requests. The host names can be specified as a simple host name, a fully qualified DNS name, or an IP address. No. Default value is the interface associated with the system's host name.
discoveryport Discovery port number. No. The default value is 54321.
javabinarypath A list of JRE or 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 colon (:) character to separate directories in the list, except for Windows which uses a semi-colon (;). If this parameter is specified, then the javahome parameter must also be specified. This parameter is not allowed if the application parameter is specified. No. The default is the 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 or JDK specified by the javahome parameter. This parameter is not allowed if the application parameter is specified. No. The default is an empty list.
javahome Location of the JRE or JDK to be used by the node. This parameter is not allowed if the application parameter is specified. No. The default is the value of the JAVA_HOME environment variable or a built-in platform default.
javalibrarypath A list of JRE or 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 colon (:) character to separate directories in the list, except for Windows which uses a semi-colon (;). If this parameter is specified then the javahome parameter must also be specified. This parameter is not allowed if the application parameter is specified. No. The default is built-in value.
keystore Path to the keystore file containing the master secret the node is to use when decrypting data. The keystore file must have been generated by the epadmin create secret command, as described in Encrypting Sensitive Configuration Data. No. No default value.
keystorepassword The password for the keystore file. Required if keystore parameter specified. If not specified, a password prompt is displayed.
memoryallocators Number of concurrent shared memory allocators. No. The default value is based on number of cores in the machine.
memorysize Size of shared memory in megabytes. No. The 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. The default value is file.
nodedeploy Optional node deploy configuration file. This parameter can only be specified if the application parameter is specified. No. Default values are built-in.
nodedirectory The parent directory for the node's installation directory. The full path to the node's installation directory is nodedirectory/nodename. No. The default value is the current working directory.
nodename Node name. A fully-qualified service name that uniquely identifies the node. No. The default value is hostname.cluster
producthome Location of the product installation on the host specified by the global hostname parameter. No. Default value is based on the location of the epadmin executable on the local host.
substitutions Comma-separated list of name=value pairs used to replace substitution variables in application definition and node deploy configuration files. A value specified in this substitutions parameter takes precedence over a value specified in substitutionfile if they both specify a value for the same name.

Note

If the substitution variable value contains commas, then the value portion must be enclosed in double quotes.

No. No default value.
substitutionfile A file containing new-line terminated name=value pairs used to replace substitution variables in application definition and node deploy configuration files. Blank lines, and lines beginning with a #, are ignored. A value specified in substitutions takes precedence over a value specified in substitutionfile if they both specify a value for the same name. No. No default value.

epadmin kill node

Kills a running node, which places it in the Killed state. Nodes are killed asynchronously. The kill command may return before the node has been killed.

When a node is killed, it must be reinstalled after removing the node directory with epadmin remove node. The primary use of the kill command is in development and testing; do not use this command on a production cluster. This command has no command parameters. 

epadmin [sn|ad] kill node

epadmin remove node

Removes a stopped node or killed node. A node must be stopped before it can be removed, unless the installpath parameter is specified. If installpath is specified, and a node is running, any running fragment engines are killed.

When a node is removed, the node coordinator is stopped if it is still running, and the node directory is deleted.

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, installpath parameter, and the producthome parameter to specify the location of the product installation on the remote machine. SSH access is required to the machine specified in the hostname parameter as described in Secure Shell. 

epadmin [sn|ad] remove node
epadmin [sn|ad] remove node --installpath=/opt/tibco/RUN/A
epadmin --hostname=svr.acme.com remove node --installpath=/opt/tibco/RUN/A 
   --producthome=/opt/tibco/str/11.1
Command Parameter Description Required
installpath Installation path. No. No default value.
producthome Location of the product installation on the host specified by the global hostname parameter. This parameter can only be specified when the installpath parameter is also specified. No. Default value is based on the location of the epadmin executable on the local host.

epadmin start node

Starts a node or restart the node coordinator.

Use the start command 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. If the installpath parameter is specified, the node coordinator is restarted; if not specified, the node is started. It is an error to specify the installpath parameter if the node coordinator is already running. Executing start node on a node that is already started succeeds without performing any action.

The start command can restart a node coordinator on remote nodes using the hostname parameter. The producthome parameter can be used to specify the location of the product installation on the remote node. 

epadmin [sn|ad] start node
epadmin [sn|ad] start node --autostart=false
epadmin [sn|ad] start node --maxretries=50
epadmin [sn|ad] start node --installpath=/opt/tibco/A
  // restarts the node coordinator on remote host named remotehost
epadmin --hostname=remotehost start node --installpath=/opt/tibco/A 
  --producthome=/opt/tibco/str/11.1
Command Parameter Description Required
autostart A boolean value controlling whether any engines are auto-started when the node is started. A value of true automatically starts any engines. A value of false leaves the engines stopped. No. Default value is true.
enginepoolsize Cached engine pool size. 0 disables the engine cache. This parameter is only valid for non-application nodes. No. The default is 0.
installpath Node installation directory. May be absolute or relative to the current directory. This parameter must be specified to restart the node coordinator if it was previously stopped using the terminate command. No. The default is currentdir/nodename.
maxretries Amount of time in seconds to wait for the node to start. No. The default value is 300 seconds.
producthome Location of the product installation on the host specified by the hostname parameter. This parameter can only be specified when the installpath parameter is also specified. No. Default value is based on the location of the epadmin executable on the local host.

epadmin stop node

Stops 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 can restart all application processes. This command has no command parameters. 

epadmin [sn|ad] stop node

epadmin terminate node

Terminates the node coordinator.

You can use the start command to restart the node coordinator. This command has no command parameters. 

epadmin [sn|ad] terminate node

SEE ALSO

epadmin(1), epadmin-globals(1), Help System for epadmin