epadmin-configuration

epadmin configuration target — Manages configuration of a running node.

SYNOPSIS

epadmin [globalparameters] command configuration [commandparameters]

DESCRIPTION

StreamBase Runtime nodes have a certain set of authored configuration settings, backed by a number of default configurations, that are all loaded and activated at node install time. Use the epadmin configuration target to dynamically manage configuration settings for a running node with the load, activate, deactivate, and remove commands. The clearhistory, display, export, generate, and list commands support the primary objective of dynamic configuration management.

The load, activate, deactivate, and remove commands are restricted to working on nodes that are both installed and started. An error message results if you attempt these commands on a node in the stopped state, or installed without being started.

There are three command parameters required by most configuration target commands: type, name, and version. These refer to the Required Header Lines for every HOCON configuration file, which together identify a configuration and establish its uniqueness. For example, a configuration with the same name and type but different version, if loaded and activated on a running node, is expected to replace the same-named configuration already there. Configuration files of the same type but different names can also be treated as versions of each other. All three properties are string values, and as HOCON properties in a configuration file, must be surrounded with quotes. However, the same terms as command parameters do not require quotes.

These basic three configuration identifiers have the following meanings:

Property/Parameter Description
type type is a fully qualified class name for a class that implements a configuration object. The type, when required as a command parameter, must be fully expanded and spelled as shown in the Configuration Guide for each HOCON variety. Examples are: 
type = com.tibco.ep.dtm.configuration.node
type = com.tibco.ep.streambase.configuration.sbengine
type = com.tibco.ep.ldm.configuration.ldmclientapilistener

The name and version command parameters usually require the type parameter to be specified as well.

name name is an arbitrary string you choose to represent the contents of the configuration file. One possible standard is to always use the same name value as the basename of the file, but this is not required.
version version is an arbitrary string you choose to represent versions of a configuration with the same type and name. Versions are traditionally shown as numbers, such as 1.0.0, but these are still string values.

The configuration target has nine 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 activate configuration

Activates a configuration, which must be already loaded into the node's shared memory. If there is an active configuration with the same type and name, it is deactivated as part of activating the current configuration. This command is restricted to working on nodes that are both installed and started. An error message results if you attempt this command on a node in the stopped state, or installed without being started. 

epadmin [sn|ad] activate configuration \
  --type=com.tibco.ep.streambase.configuration.sbclientapilistener \
  --name=sbportnumber --version="1.1"
Command Parameter Description Required
type Configuration type. Yes.
name Configuration name. Yes.
version Configuration version. Yes.

epadmin clearhistory configuration

Clears configuration state change history that meets the specified filter criteria defined using the command parameters. The filter parameters have the following precedence: type, name, version, date. To specify a lower precedence filter value, all higher precedence values must be specified. For example, if name is specified, type must also be.

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

epadmin [sn|ad] clearhistory configuration
epadmin [sn|ad] clearhistory configuration \
  --type=com.tibco.ep.streambase.configuration.sbclientapilistener
epadmin [sn|ad] clearhistory configuration \
  --type=com.tibco.ep.streambase.configuration.sbclientapilistener \
  --name=sbportnumber
epadmin [sn|ad] clearhistory configuration \
  --type=com.tibco.ep.streambase.configuration.sbclientapilistener \
  --name=sbportnumber --version="1.1"
epadmin [sn|ad] clearhistory configuration \
  --type=com.tibco.ep.streambase.configuration.sbclientapilistener \
  --name=sbportnumber --version="1.1" --date="2020-07-31-23:59:59"
Command Parameter 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 the specified 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 hyphen separates the date and time. For example: 2020-07-31-23:59:59. The time value must be specified in the local timezone of the node. No. No default value.

epadmin deactivate configuration

Deactivates a configuration. This command leaves the node with no active configuration of the specified type. It is generally recommended to use the activate command to atomically deactivate and activate new configuration. This command is restricted to working on nodes that are both installed and started. An error message results if you attempt this command on a node in the stopped state, or installed without being started. 

epadmin [sn|ad] deactivate configuration \
  --type=com.tibco.ep.streambase.configuration.sbclientapilistener \
  --name=sbportnumber --version=1.0
Command Parameter Description Required
type Configuration type. Yes.
name Configuration name. Yes.
version Configuration version. Yes.

epadmin display configuration

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 precedence parameter, all higher precedence parameters must be specified. For example, if name is specified, type also must be. 

epadmin [sn|ad] display configuration
epadmin [sn|ad] display configuration \
  --type=com.tibco.ep.streambase.configuration.sbclientapilistener
epadmin [sn|ad] display configuration \
  --type=com.tibco.ep.streambase.configuration.sbclientapilistener \
  --name=sbportnumber
epadmin [sn|ad] display configuration \
  --type=com.tibco.ep.streambase.configuration.sbclientapilistener \
  --name=sbportnumber version=1.0
epadmin [sn|ad] display configuration --history
Command Parameter 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 the display of configuration state change history. No. Default value is false.

epadmin export configuration

Exports configuration data to a file. The exported configuration is in a format that can be reloaded after making any required changes. 

epadmin [sn|ad] export configuration \
  --type=com.tibco.ep.streambase.configuration.sbclientapilistener \
  --name=sbportnumber --version=1.0 --file=./sbportnum-1-0-0.conf
Command Parameter Description Required
type Configuration type. Yes.
name Configuration name. Yes.
version Configuration version. Yes.
file Client-side output file. Yes.

Tip

If you just want to look at the current configuration settings, you do not need to save it to a file. Instead, on macOS or Linux, run the tty command to obtain the terminal name for your current Terminal session. Then set, for example, --file=/dev/ttys001  There is no equivalent for Windows.

epadmin generate configuration

Generates a sample configuration. 

epadmin [sn|ad] generate configuration --rootobject=OIDCAuthenticationRealm --file=example.conf
epadmin [sn|ad] generate configuration --rootobject=OIDCAuthenticationRealm --file=example.conf 
  --requiredonly
epadmin [sn|ad] generate configuration --type=com.tibco.ep.dtm.configuration.security 
  --rootobject=OIDCAuthenticationRealm --file=example.conf
Command Parameter Description Required
file Client-side output file. Yes.
requiredonly Boolean to control which properties the generated sample contains. A value of true generates a sample with only the required properties, a value of false generates a sample with all properties. No. Default value is false.
rootobject Configuration root object name. Yes.
type Configuration type. No. No default value.

epadmin list configuration

Lists available configuration types and root objects. 

epadmin [sn|ad] list configuration
epadmin [sn|ad] list configuration --type "^com.tibco.ep.dtm.configuration.*"
epadmin [sn|ad] list configuration --rootobject "^Secure.*"
epadmin [sn|ad] list configuration --type "^com.tibco.ep.dtm.configuration.*" \
  --rootobject "^OIDC.*"
Command Parameter Description Required
rootobject Configuration root object name regular expression, using Java Pattern regular expression syntax. No. No default value.
type Configuration type regular expression, using Java Pattern regular expression syntax. No. No default value.

epadmin load configuration

Loads configuration data. When this command completes, the configuration file is loaded into shared memory, but it is not active. Use the activate configuration command to for the loaded configuration to take effect. This command is restricted to working on nodes that are both installed and started. An error message results if you attempt this command on a node in the stopped state, or installed without being started. 

epadmin [sn|ad] load configuration --source=myConfiguration.conf
epadmin [sn|ad] load configuration --source=myConfiguration.conf --ignorethrottle
epadmin [sn|ad] load configuration --source=myConfiguration.conf \
  --substitutions="foo=bar,pi=3.14159"
epadmin [sn|ad] load configuration --source=myConfiguration.conf \
  --substitutionfile=mysubstitutions.prop

Here are the example contents of a substitution file. 

#
#  Substitution properties for myConfiguration.conf
#
foo=bar
pi=3.14159
Command Parameter Description Required
source Configuration file. Yes.
substitutions Comma-separated list of name-value pairs used to replace substitution variables in the configuration file. 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.
substitutionfile Specifies a file containing new-line terminated name-value pairs used to replace substitution variables in the configuration file. Blank lines, and lines beginning with # 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.
ignorethrottle By default, configuration files cannot be loaded if a node's shared memory utilization exceeds the configured throttle threshold. Setting this parameter to true loads 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.

epadmin remove configuration

Remove a configuration object from shared memory. The configuration being removed must be already deactivated. Configuration that is removed from shared memory must be reloaded using the load command. This command is restricted to working on nodes that are both installed and started. An error message results if you attempt this command on a node in the stopped state, or installed without being started. 

epadmin [sn|ad] remove configuration \
  --type=com.tibco.ep.streambase.configuration.sbclientapilistener \
  --name=sbportnumber --version=1.0
Command Parameter Description Required
type Configuration type. Yes.
name Configuration name. Yes.
version Configuration version. Yes.

SEE ALSO

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