Server Parameters

Edit online

About the Server Parameters

When you start Universal Messaging, the server uses a number of parameters in its initial startup sequence. These parameters are in the form of -D options specified in the Server_Common.conf configuration file. This file is located in the <InstallDir>/UniversalMessaging/server/<InstanceName>/bin directory of your installation, where <InstanceName> is the name of the Universal Messaging realm.

The -D options are specified in the configuration file in the following format: 

wrapper.java.additional.<n>=-D<parameter>=<value>

where <parameter> is the name of the parameter whose value you wish to set, <value> is the value that you want to assign to the parameter, and <n> is any positive integer. If you have several -D options in the file, ensure that <n> values are unique. If you supply several -D options with the same <n> value, only the last of the specified options with this value of <n> will be effective and the earlier ones with this value of <n> will be ignored.

Example: 

wrapper.java.additional.25=-DMaxFileSize=4000000000
wrapper.java.additional.26=-DLOGLEVEL=3

The Universal Messaging client API also supports several parameters that can be specified in the command line of any Universal Messaging client application.

Description of the Server Parameters

This section describes the parameters that are used when the server starts, what they are used for, and what their typical values are.

Note:

In some cases, the initial values described here can be changed dynamically, i.e. while the server is running, by using realm configuration properties. For example, the initial value set by the server startup parameter LogFileDepth can be superseded for a running server by the realm configuration property RolledLogFileDepth.

See the section Realm Configuration in the Administration Guide for further information.

Name Required Default Description
ADAPTER N Specifies an interface to use, for example nsp://0.0.0.0:9000/
ADAPTER_x N Specifies an interface to use, for example nsp://0.0.0.0:9000/ where x = 0 -> 9
AuthenticationTimeLogThreshold N 1000 Enables the server to report warning messages if a connection takes more than a specified time in miliseconds to authenticate. Usually, the property should have a value of between 1000 and 30000, but you can adjust it according to the requirements of your system.

For more information about using the property, see Server Behavior when Authenticating Connections.
CACHE_SIZE N 10 000

Specifies how many events to cache in memory for a store with multi-file disk storage (where the "events per spindle" storage property is set above 0), thereby avoiding I/O operations on disk.

You might want to increase or decrease this value depending on your publish and consume rates, available heap size and individual event size.

CAKEYSTORE N Shorthand for javax.net.ssl.trustStore
CAKEYSTOREPASSWD N Shorthand for javax.net.ssl.trustStorePassword
CHANNELUMASK N Specifies the default channel protection mask
CKEYSTORE N Shorthand for javax.net.ssl.keyStore
CKEYSTOREPASSWD N Shorthand for javax.net.ssl.keyStorePassword
com.softwareag.um.authentication.maxHeaderCount N 0 Limits the number of headers that the Universal Messaging client and the Universal Messaging server exchange during protocol negotiation. Do not change the value of the parameter because the supported Universal Messaging client and server versions do not require exchanging headers.
DATADIR Y The path that Universal Messaging uses to store its internal status and configuration information about the realm. See the section below for related information.
DISK_USAGE_SCAN_ENABLE N (no default)
Note: This parameter is deprecated in Universal Messaging version 10.7 and will be removed in a subsequent release.

The parameter determines whether to check at regular intervals if there is sufficient free disk space for the Universal Messaging server to continue normal processing. This parameter can be set to true or false, or can be left undefined. If it is set to true or false, it overrides the setting of the realm configuration property DiskScanEnable.

If DISK_USAGE_SCAN_ENABLE is set to true, the percentage of available free space must be greater than the value given by the realm configuration parameter DiskUsageFreeThreshold in order for processing to continue normally. If the amount of free disk space drops below this percentage value, the server logs an error message. The server will initiate a clean shutdown with an appropriate error message if the disk space available is less than 500 MB.

If DISK_USAGE_SCAN_ENABLE is set to false, no check of available free space is done; in this case, if the server runs out of disk space, an unorderly shutdown may result.

If DISK_USAGE_SCAN_ENABLE is not set, i.e. is set to neither true nor false, the regular checks for free disk space can still be carried out if the realm configuration parameter DiskScanEnable is set to true.

See the description of realm configuration properties in the section Realm Configuration in the Administration Guide.

HTTPHeaderSize N 8192 Specifies the initial size of the HTTP header.
HTTPMaxHeaderSize N 2 * HTTPHeaderSize Specifies the maximum size of the HTTP header.
javax.net.debug N Useful to debug SSL issues.
javax.net.ssl.keyStore N Used to set the default KeyStore the server will use. If not supplied the client MUST set one when configuring an SSL interface
javax.net.ssl.keyStorePassword N Used to set the default password for the keystore. If not supplied the client must set one when configuring an SSL interface
javax.net.ssl.trustStore N Used to set the default trust store the server will use. If not supplied the client MUST set one when configuring an SSL interface
javax.net.ssl.trustStorePassword N Used to set the default Truststore password the server will use. If not supplied the client MUST set one when configuring an SSL interface

LOG_FRAMEWORK

N Specifies a third-party logging framework to use. Can be set to LOGBACK or LOG4J2. The default is fLogger.

The Log4J2 logging framework is supported only in a Docker environment.
LogFileDepth N The number of log files to keep on disk when using log rolling. The oldest log files will be deleted when new log files are created.
LOGLEVEL N

5

Specifies the current log level to use
LOGFILE N System.out Specifies a log file to write the log entries to
LOGSIZE N 100000 The maximum size (in bytes) of the log file before the log file is rolled
-XX:MaxDirectMemorySize Y 1G Sets a limit on the amount of memory that the JVM can reserve for all direct byte buffers. Direct memory allows more efficient I/O operations by avoiding unnecessary data copying between the Java heap and native heap.

For more information about configuring direct memory, see Configuring the JVM Heap Size and Direct Memory.
MaxFileSize N 1000000000 (1GB)

Specifies the maximum size (in bytes) of a channel/queue file on disk, before automatic maintenance (auto-maintenance) is performed to re-order the file to remove purged events. The default is 1GB, although auto-maintenance is usually performed well before this limit is reached.

MaxMemory N

Uses the -Xms (minimum heap size) value

Specifies a target value for the maximum memory usage. As this value is approached, the realm server will attempt to free caches in order to release memory.

MaxMemSize N

Specifies the default value of the "MaintenanceMemoryThreshold" realm configuration option.

See the section Realm Configuration in the Administration Guide for related details.

mode N If set to IPAQ forces a small memory mode for the server
Nirvana.auth.exempt N   Specifies the path to a text file that contains a list of users exempt from authentication. For more information about defining exempt users and configuring the property, see Configuring Authentication and Client Negotiation.
REALM Y Specifies the name of the realm server. When creating a server instance, the server instance name is set to the realm name by default. After you create a server instance you cannot change the instance name or the realm name.

For more information about creating instances, see Universal Messaging Instance Manager in the Installation Guide.

SECURITYFILE N

Specifies the super users for a realm server in a security file in the format user@host, one user per line. The default security file is secfile.conf in the bin directory of the server. Note that this is a bootstrap method on start-up of a realm. If you started the realm before specifying a SECURITYFILE, you must remove the realms.nst and realms.nst _old files from the RealmSpecific directory, and then restart the realm with the -DSECURITYFILE property set in the Server_Common.conf file to add the super user entries in the file to the realm ACL.

In addition, you can use the SECURITYFILE property in recovery scenarios after you accidentally removed realm ACLs and as a result cannot connect to the server due to insufficient permissions. For more information about using the property to recover ACL permissions, see Recovering Accidentally Removed ACL Permissions.
SSLProtocols N TLSv1,TLSv1.1,TLSv1.2, TLSv1.3 Specifies one or more (comma-separated) SSL protocols that the realm server is allowed to use. If an attempt is made to use any other protocol on the server, an error will be raised.

Notes on DATADIR

The server parameter DATADIR defines a location where Universal Messaging stores its internal status and configuration information for the realm. This location is set automatically when you create a realm. Normally you do not need to change this location.

DATADIR points to the location server/<realmname>/data. This location contains various files and sub-directories. If you define any plugins, Universal Messaging stores the related internal configuration information in the parallel location server/<realmname>/plugins.

Note: The data and plugins locations contain various files and sub-directories that are essential for the smooth running of the product, and any attempt by the customer to modify these files directly may make the system unusable.

The value of the DATADIR parameter is set in the following files that are located in the realm-specific location server/<realmname>/bin:

  • env.bat on Windows, or env.sh on UNIX-based systems
  • nstopserver.bat on Windows, or nstopserver on UNIX-based systems
  • Server_Common.conf
Note: On UNIX-based systems, the environment variable in the nstopserver file is named data instead of DATADIR.

There are some rare cases when you might want to change the value of DATADIR to point to a new location. Such cases are:

  • You want to point DATADIR to a new location but you want the realm server to continue using all of its existing status and configuration data.
  • You want to point DATADIR to a new location but you do not want the realm server to use any existing status or configuration data.

The steps required to implement these cases are described in the following sections.

Case 1: Define a new DATADIR, retaining the existing realm status and configuration data

  1. If the realm server is running, stop the realm server.
  2. In a temporary location, make a copy of the contents of the server/<realmname>/data. Also copy server/<realmname>/plugins if you have defined any plugins.

  3. Change the value of DATADIR in the files listed above. Ensure there are no trailing spaces in the new value. In the nstopserver file on UNIX-based systems, change the value of the variable data instead of DATADIR.

    If you specify a value for DATADIR that does not end with "/data", the realm server will assume a value for DATADIR as if you had appended "/data" to the value.

    For example, if you define DATADIR to be "/folder1/folder2/data", then the realm server uses exactly this value as the new DATADIR. If however you define DATADIR to be "/dir1/dir2", then the realm server will behave as if you had specified "/dir1/dir2/data".

  4. The following steps 5-7 describe how to create the structure for the new data directory and copy in the required files from the old data directory. Note that there is an alternative method, described at the end of this procedure.
  5. Start the realm server. This automatically creates the structure for the data directory at the location defined by the new DATADIR.
  6. Stop the realm server.
  7. Overwrite the contents of the new data directory and all sub-directories with the temporary copy of the data directory and all sub-directories you stored earlier.
  8. If you had defined plugins, copy in the plugins directory and contents from your temporary copy.
  9. Start the realm server.

As an alternative to steps 5-7 above, you can create the new data directory manually using standard operating system commands while the realm server is stopped, and copy in the contents of the old data directory and all sub-directories.

Case 2: Define a new DATADIR, without using any existing realm status or configuration data

If you want to define a new value for DATADIR but you do not want to copy in the existing status and configuration data from the old DATADIR location, follow the instructions in Case 1 above but omit any steps that involve manually copying data to the new DATADIR location. This means that when the realm server starts for the first time after DATADIR has been changed, the realm server has no knowledge of any previously stored data.

Template files

Note that there are also template files in the location server/templates. These template files are used to automatically create the above mentioned realm-specific files when you create a realm. If you want to create new realms and ensure that they also use the new value of DATADIR, you need to change the contents of these template files before you create the new realms.