epadmin-node
epadmin node target — Manages the life cycle of nodes.
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=
to identify a node, ornodename.clustername
‑‑servicename=
to apply the command to all nodes in that cluster. You can shorten this parameter down toclustername
‑‑servicen=
. -
‑‑adminport on localhost
To address a node on the same machine, determine the node's administration port, and use‑‑adminport=
. This can be shortened tonnnnn
‑‑ad=
or evennnnnn
‑‑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 thesrc/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 [
in syntax examples is a reminder that this command requires either the global parameter sn
|ad
]‑‑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[
display node | grep Administration epadminsn
|ad
][
display node | findstr Administrationsn
|ad
]
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 |
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.
NoteThis |
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 . 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 .
|
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
|
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.
NoteIf 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[
remove node epadminsn
|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.1sn
|ad
]
Command Parameter | Description | Required |
---|---|---|
|
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[
start node epadminsn
|ad
][
start node --autostart=false epadminsn
|ad
][
start node --maxretries=50 epadminsn
|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.1sn
|ad
]
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 .
|
|
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.
|