HOCON File Generation with epadmin

The epadmin command supports the generation of HOCON configuration files, as explained on this page. This feature is an alternative to creating a configuration file in StreamBase Studio's HOCON File Editor.

Once generated with epadmin, use the HOCON File Editor to validate your file as you customize it for your deployment scenario. The Editor validates StreamBase's extension of standard HOCON, which itself is an extension of standard JSON.

Generate Command

Command syntax:

epadmin global-param generate configuration [--type=string] --rootobject=String 
    [--requiredonly=Boolean] --file=filename

The components of this command are:

  • The rootobject parameter is required, and specifies the HOCON configuration root object desired.

  • If the root object is unique across all configuration types, the --type parameter is not required. Use --type to distinguish root objects with the same name in different types, such as ClientAPIListener.

  • The required-only parameter is optional. If set to true, only the required properties are placed in the generated configuration file. The default of false generates a complete file with all supported properties. All generated properties are commented with their descriptions, with a header at the top noting that the file will not validate until comments are removed from required properties.

  • The file parameter is required. Use it to specify the generated HOCON configuration file name, and optionally, a file path for the configuration file.

A servicename, adminport, or hostname global parameter is required with this command.

Generate Command Examples

Example command syntax:

epadmin --servicename A.X generate configuration  --rootobject=object --file=myfile.conf

Example 1 generates a HOCON file named oidc.conf in the current directory for the OIDCAuthenticationRealm root object, which is a security type.

epadmin --servicename=A.sbuser generate configuration --rootobject=OIDCAuthenticationRealm 
    --file=oidc.conf

Example 2 also generates a configuration file for the OIDCAuthenticationRealm root object, but with only the required properties:

epadmin --servicename=A.sbuser generate configuration --rootobject=OIDCAuthenticationRealm 
    --file=oidc.conf --requiredonly

Example 3 generates a ClientAPIListener configuration file, but also specifies the sbclientapilistener type because there are two ClientAPIListener root objects:

epadmin --servicename=A.sbuser generate configuration 
    --type=com.tibco.ep.streambase.configuration.sbclientapilistener
    --rootobject=ClientAPIListener --file=portnum.conf

List Command

The epadmin list command identifies available HOCON configuration types and root objects, using the following syntax:

epadmin global-param list configuration [--rootobject "regex"] [--type "regex"] 
  • The rootobject parameter is optional, and specifies the HOCON configuration root object desired.

  • The type parameter is optional, and specifies the HOCON configuration type desired.

Use only one of each parameter, or both, or none. For both parameters, use a quoted regular expression string using Java Pattern syntax that specifies a type or root object name or a portion thereof.

A servicename, adminport, or hostname global parameter is required with this command. For example:

epadmin --adminport 52664 list configuration  --rootobject "^Secure.*"

or

epadmin --servicename A.sbuser list configuration  --rootobject "^Secure.*"

List Command Examples

In the following list command examples, we use an abbreviation of the --adminport parameter with the example port number 52664. Determine the correct administration port for your running node in StreamBase Studio's Clusters View, or with a command like the following:

epadmin display services | grep -B 2 dtm-adm (macOS, Linux)
epadmin display services | find "dtm-adm"    (Windows)

Use the --adminport global parameter instead of --servicename to avoid the bracketed node and cluster name prefixed to every line of output (or use --serviceprefix false to suppress the prefix).

1. Use the list command without parameters to display every available HOCON configuration object. For example:

epadmin --adm=52664 list configuration

This returns:

type = com.tibco.ep.dtm.configuration.application
rootobject = ApplicationDefinition
description = Application Definition

type = com.tibco.ep.dtm.configuration.application
rootobject = FragmentDefinition
description = Fragment Definition

type = com.tibco.ep.dtm.configuration.javaengine
rootobject = JavaEngine
description = Java Engine

...

2. Specify a particular root object if you know its name. The regular expression string is not case sensitive:

epadmin --adm=52664 list configuration --root "nodedeploy"

This returns:

type = com.tibco.ep.dtm.configuration.node
rootobject = NodeDeploy
description = Node Deploy Configuration

3. Specify a regular expression for a portion of a root object's name:

epadmin --adm=52664 list configuration --root "clientapi.*"

This returns:

type = com.tibco.ep.ldm.configuration.ldmclientapilistener
rootobject = ClientAPIListener
description = LiveView Client API Listener

type = com.tibco.ep.streambase.configuration.sbclientapilistener
rootobject = ClientAPIListener
description = EventFlow Client API Listener

4. Get a list of all root objects specific to EventFlow modules:

epadmin --adm=52664 list configuration --type ".*ep.streambase.*"

or

epadmin --servicename A.sbuser list configuration --type ".*ep.streambase.*"

5. Get a list of all security-related root objects:

epadmin --adm=52664 list configuration --type ".*dtm.*security.*"

or

epadmin --servicename A.sbuser list configuration --type ".*dtm.*security.*"