Universal Messaging 10.3 | Concepts | Deployment | Server | Server Parameters
 
Server Parameters
Introduction
When a Universal Messaging Realm Server is started, there are a number of parameters used 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, what they are used for and their typical values.
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
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
DATADIR
Y
The path that Universal Messaging uses to store its internal status and configuration information about the realm. See the section Notes on DATADIR below for related information.
DISK_USAGE_SCAN_INTERVAL
N
5000 (5 seconds)
Specifies the time between scans for free disk space (activated by DISK_USAGE_SCAN_ENABLE) in milliseconds. This allows the client to specify how regularly this check is performed.
DISK_USAGE_FREE_THRESHOLD
N
5
Specifies a minimum threshold for the percentage amount of free disk space required by the Universal Messaging server for processing to continue normally. This threshold is only in effect if DISK_USAGE_SCAN_ENABLE is set to true.
DISK_USAGE_SCAN_ENABLE
N
true
Specifies whether to check 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.
If the parameter is set to true, the percentage of available free space must be greater than the value given by the server parameter DISK_USAGE_FREE_THRESHOLD 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 the parameter 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.
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 part logging framework to use. Can be set to "LOGBACK" or "LOG4J2". The default is "fLogger".
LOGLEVEL
N
5
Specifies the current log level to use
LOGFILE
N
System.err
Used to specify a log file to write the log entries to
LOGSIZE
N
100000
Specified in bytes before the log file is rolled
MaxFileSize
N
1000000000 (1GB)
Specifies the maximum size (in bytes) of a channel/queue file on disk, before automatic maintenance is performed to re-order the file to remove purged events. The default is 1GB, although 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
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
Used to specify the Super Users for this realm. Format is user@host (one per line). Note that this is only a bootstrap method on startup of a realm. If you had previously started the realm before specifying a SECURITYFILE, you will need to remove the files realms.nst and realms.nst _old from the RealmSpecific directory, then restart the realm with the -DSECURITYFILE setting in the Server_Common.conf file for the super user entries in the file to be added to the realm ACL.
SSLProtocols
N
TLSv1,TLSv1.1,TLSv1.2
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 subdirectories. 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 subdirectories 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:
*CertificateGenerator.conf
*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 subdirectories with the temporary copy of the data directory and all subdirectories 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 subdirectories.
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.