Universal Messaging Instance Manager
During the installation of Universal Messaging, you have the option of creating a default instance (called umserver by default) for all the components installed. If you need to create additional instances, this can be done using the ninstancemanager command line tool, which can be found under <InstallDir>/UniversalMessaging/tools/InstanceManager/.
Components
The ninstancemanager tool can create instances of the following component types:
realm server (RS)
Enterprise Manager (EM)
template applications (TA)
In order to create an instance of a component, this needs to have been installed first.
Usage Message
Executing the ninstancemanager tool without any arguments provides a usage message as follows:
<Action> can be either
create,
delete,
query,
deleteAll (followed directly by a component), or
configure.
<InstanceName> can be any instance name.
<Component> is the component the action applies on, namely
RS (for Realm Server),
EM (for Enterprise Manager),
TA (for Template Applications) or
ALL (for everything installed).
<Host> is the hostname or IP that the template applications and Enterprise Manager will point to, and the adapter the realm will bind to.
You can use the hostname instead of the IP when you wish to provide an environment that is not specific to the underlying IP address of the server. This will allow the UM server to be accessed only by its hostname, so if the IP address changes, the server will still be accessible.
<Port> is the TCP port that the template applications and Enterprise Manager will point to, and the adapter the realm will bind to.
<DataDirectory> is the realm server working directory. This parameter is optional, and the default value is
<InstallDir>/UniversalMessaging/server/<InstanceName>.
Example 1: To create a new instance called umserver2 and listening to all IPs on port 9001, you would run:
ninstancemanager create umserver2 all 0.0.0.0 9001
Example 2: To create a new EM instance called umserver2 and pointing to a realm on 192.168.1.100 port 9001 you would run:
ninstancemanager create umserver2 all 192.168.1.100 9001
Example 3: To delete all instances called umserver2 you would run:
ninstancemanager delete umserver2 all
Example 4: To delete an EM instance called umserver2 you would run:
ninstancemanager delete umserver2 em
Example 5: To query installed instances you would run:
ninstancemanager query
Example 6: To delete all realm server instances you would run:
ninstancemanager deleteAll rs
Querying Installed Instances
Running the ninstancemanager tool with the query action displays a list of currently installed instances. For example:
ninstancemanager query
will display an output similar to the following in a default installation (taking release 9.8.0 as an example):
Universal Messaging installation query
--------------------------------------
Realm Server Installed Version:
e2ei/11/NUM_9.8.0.0.13321/UniversalMessaging/NUMRealmServer
Instances: umserver
Enterprise Manager Installed Version:
e2ei/11/NUM_9.8.0.0.13321/UniversalMessaging/NUMEnterpriseManager
Instances: umserver
Template Applications Installed Version:
e2ei/11/NUM_9.8.0.0.13321/UniversalMessaging/NUMTemplateApplications
Instances: umserver
Creating Instances
Running the ninstancemanager tool with the create action allows you to create instances of all the installed components or a subset. In order to create an instance, you need to run the ninstancemanager as follows:
Where:
<InstanceName> is a logical name for the instance which needs to be unique for each installation.
<Component> is the component you wish to create an instance of. The possible values are
ALL (for all components installed),
RS (for a realm server instance),
TA (for template applications instance) or
EM (for Enterprise Manager instance).
Note that after you create a server instance you cannot change the server instance name or the realm name. When creating the server instance, the server instance name is set to the realm name by default.
Example: If we wanted to create an instance of all components installed called testinstance, bound to all IPs of the machine and listening on port 9002 you would enter:
ninstancemanager create testinstance all 0.0.0.0 9002
Output:
Created RS instance testinstance
Created TA instance testinstance
Created EM instance testinstance
You can then verify the instance's presence by issuing a query action:
ninstancemanager query
Output:
Universal Messaging installation query
--------------------------------------
Realm Server Installed Version:
e2ei/11/NUM_9.8.0.0.13321/UniversalMessaging/NUMRealmServer
Instances: testinstance , umserver
Enterprise Manager Installed Version:
e2ei/11/NUM_9.8.0.0.13321/UniversalMessaging/NUMEnterpriseManager
Instances: testinstance , umserver
Template Applications Installed Version:
e2ei/11/NUM_9.8.0.0.13321/UniversalMessaging/NUMTemplateApplications
Instances: testinstance , umserver
Deleting Instances
The ninstancemanager tool can be used to delete any instances created, including the default instance created using the installer. The components specified allow you to remove an instance for one component while keeping it for the others.
In order to delete an instance, you need to run the ninstancemanager as follows:
ninstancemanager delete <InstanceName> <Component>
Where:
<InstanceName> is a logical name for the instance which needs to be unique for each installation.
<Component> is the component you wish to create an instance of. The possible values are
ALL (for all components installed),
RS (for a realm server instance),
TA (for template applications instance) or
EM (for Enterprise Manager instance).
Example: If we wanted to delete a previously created instance of all components called testinstance, you would enter:
ninstancemanager delete testinstance all
Output:
RS instance testinstance has been deleted
TA instance testinstance has been deleted
EM instance testinstance has been deleted
You can then verify the instance's presence by issuing a query action:
ninstancemanager query
Output:
Universal Messaging installation query
--------------------------------------
Realm Server Installed Version:
e2ei/11/NUM_9.8.0.0.13321/UniversalMessaging/NUMRealmServer
Instances: umserver
Enterprise Manager Installed Version:
e2ei/11/NUM_9.8.0.0.13321/UniversalMessaging/NUMEnterpriseManager
Instances: umserver
Template Applications Installed Version:
e2ei/11/NUM_9.8.0.0.13321/UniversalMessaging/NUMTemplateApplications
Instances: umserver
Deleting All Instances of a Component
You can delete all instances of a component (RS, EM, TA or ALL) by using the deleteAll action and passing the component:
Example: If we wanted to delete all previously created instances of the component type TA (for template applications), you would enter:
ninstancemanager deleteAll ta
Output:
TA instance umserver has been deleted
You can then verify that the instance(s) have been deleted by issuing a query action:
ninstancemanager query
Output:
Universal Messaging installation query
--------------------------------------
Realm Server Installed Version:
e2ei/11/NUM_9.8.0.0.13321/UniversalMessaging/NUMRealmServer
Instances: umserver
Enterprise Manager Installed Version:
e2ei/11/NUM_9.8.0.0.13321/UniversalMessaging/NUMEnterpriseManager
Instances: umserver
Template Applications Installed Version:
e2ei/11/NUM_9.8.0.0.13321/UniversalMessaging/NUMTemplateApplications
Instances:
Configuring an existing Server Instance
The ninstancemanager command line tool can be used to configure existing server instances.
It provides two ways to import a configuration for an instance:
Import a configuration from a predefined profile. These predefined profiles are shipped with the installation. The configure command allows you to view the available predefined profiles.
Import a custom configuration XML file that you have previously exported. This option can be used to apply a specific configuration, unique for a separate customer use case.
Note:
In both cases, before the import is performed, a backup of the existing configuration will be made. Backups will be created under
<InstallDir>/
UniversalMessaging/server/
<InstanceName>/data/configBackup, where
<InstanceName> is the name of your server instance.
The server instance needs to be stopped when importing a configuration, otherwise an error message will be printed and the configuration will not be imported.
Displaying the command's help text
You can use the following command to display the command usage help text:
ninstancemanager configure
Listing available predefined profiles
To list information about currently available profiles, use the following command:
ninstancemanager configure --listProfiles
The command lists information about the available predefined profiles. A short description about each of the profiles will be also printed.
Currently two predefined profiles are available: wM (for webMethods) and TC (for Terracotta). Each profile contains a set of Universal Messaging server configuration values that fits best to the profile's use case.
Profile name | Description |
wM | webMethods suite use cases (large messages, transactions, persistence) |
TC | Standalone use cases (small messages, non-transactional data) |
Importing a predefined profile
You can import a predefined configuration profile. Use the --listProfiles command as shown above to list the available predefined profiles.
The command to import a predefined profile is as follows:
ninstancemanager configure umserver --importProfile=<ProfileName>
--dataDir=<InstallDir>/UniversalMessaging/server/<InstanceName>
Here, <ProfileName> is the name of the profile you wish to import.
The parameter <InstanceName> is the name of the server instance.
The parameter --dataDir is optional. If you do not supply this parameter, the default base data folder is assumed, which is <InstallDir>/UniversalMessaging/server/umserver.
Importing a custom configuration file
You can import a custom configuration file using a command of the following form (note the use of the parameter --import rather than --importProfile):
ninstancemanager configure umserver --import=<customConfigFile>
--dataDir=<InstallDir>/UniversalMessaging/server/<InstanceName>
For example:
ninstancemanager configure umserver --import=c:\myConfig\myCustomConfig.xml
--dataDir=<InstallDir>/UniversalMessaging/server/umserver
Exporting configuration to a file
You can export the current configuration into an external file, using a command of the form:
For example:
ninstancemanager configure umserver --export=c:\myBackup\myBackup.xml
The command will export the current configuration in a file, which afterwards can be imported with the --import command.
Note:
The export command can be run even if the server instance is running.
Naming rules for realm server instances
When you are creating a new realm server instance, some rules relating to the instance name apply.
A realm server instance name can be the same as the name of an Enterprise Manager instance or a Template Applications instance. Apart from this, the following restrictions apply:
Realm server instance names used throughout your Universal Messaging infrastructure must be unique.
Realm server instance names must not be the same as the name of any host, cluster, or any other non-realm component in your Universal Messaging infrastructure.
Instance names can contain only lower case Latin letters (a-z), digits (0-9), an underscore, and a non-leading ASCII hyphen (minus) character.
The length of instance names with a shortcut path string must be fewer than 258 characters.
The length of instance names with an instance path string must be fewer than 258 characters.
The reason for the naming restrictions is that Universal Messaging uses the name of the realm server instance internally as a unique identifier.