Server Parameters
Introduction
When a Universal Messaging Realm Server is started, there are a number of parameters used in its initial startup sequence.
If you start the realm server manually, e.g. from a shortcut or from the command line, these parameters are in the form of -D options specified in the nserver.conf configuration file. This file is located in the server/<realm>/bin directory of your installation, where <realm> is the name of the Universal Messaging realm. If you start the realm server as a Windows service or as a UNIX daemon, the parameters are taken from nserverdaemon.conf instead.
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. |
javax.net.ssl.debug | N | | Useful to debug SSL issues, see www.javasoft.com for more information |
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.out | Used to specify a log file to write the log entries to |
LOGSIZE | N | 100000 | Specified in bytes before the log file is rolled |
MaintenanceFileSizeThreshold | | | Specifies the upper size limit of the file (for the store's associated store on disk) at which the store will perform maintenance operations (compaction on disk) to attempt to free up disk space. |
MaintenanceMemorythreshold | | | Specifies the memory limit for a store, after which the store will attempt to free memory by clearing caches and performing any other maintenance operations. |
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. |
mode | N | | If set to IPAQ forces a small memory mode for the server |
REALM | Y | | Specifies the name of the Realm Server |
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 nserver.conf or nserverdaemon.conf file for the super user entries in the file to be added to the realm ACL. |
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.confenv.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.