Changing Domain Settings

This chapter provides background information on managing domain settings and explains how to change the settings.

1. Overview

The domain configuration file is in the config directory (DOMAIN_HOME/config) of each domain. The configuration file, domain.xml, contains the configuration for servers and clusters as well as resources and services in the domain. The file also contains information about the deployed applications.

Dynamically applying settings refers to making changes in real-time to a running server without restarting the server. Since changes are verified by MASTER and then distributed to the MSs, the changes that are made manually to the XML file are not applied dynamically. Only the changes made by using jeusadmin are applied dynamically.

To change a dynamic configuration item, the user must have permission for the resource name jeus.domain.<domain-name> and the DynamicConfiguration resource action. When changing security configuration, users cannot delete their own permission to edit the configuration. This is to allow the users to be able to always undo their actions.

For information about how to give a resource permission to a specific user, refer to Configuring Security System Policies.

2. Modifying the Configuration

The configuration that is required to operate a server is inside a file in the domain to which the server belongs.

The configuration file is managed by MASTER, distributed to each server, and stored in a local read-only cache for better performance. JEUS supports dynamic configuration through MASTER.

3. Applying the Modified Configuration

Once the configuration has been modified, the changes are applied to the servers. Some settings can be applied dynamically, and some settings require restarting the server.

3.1. Dynamic Settings

Settings that can be applied dynamically are applied without restarting servers.

Using the Console Tool

In jeusadmin, dynamically applied command parameters have the word [Dynamic] in their description.

Commands used for jeusadmin automatically perform Lock, Save, and Apply Changes, and the changes for items that are labeled as [Dynamic] are applied immediately.

[MASTER]domain1.adminServer>help modify-server
...
OPTIONS
[-removelogdir,--removeLogHomeDirectory]
   remove the log directory which has all the log files created by this
   server

[-node,--nodeName <node-name>]
   name of the node this server is located

<server-name>
   the name of server you want to modify configuration of

[-jvm,--jvmOptions <jvm-options>]
   jvm configurations applied to this server jvm

[-logdir,--logHomeDirectory <server-log-home-directory>]
   the log directory which has all the log files created by this server

[-a,--actionOnResourceLeak <action-on-resource-leak>]
   strategy when resource leak is detected. it must be one of
   AutoClose, NoAction, Warning

[-l,--logStdoutToRawFormat <print-stdout-to-raw-format>]
   [Dynamic] whether stdout is printed in row format or in JEUS Logger
   format.

[-m,--mejb <enable-MEJB>]
   [Dynamic] whether using MEJB or not .true, false

[-c,--classFtp <enable-class-ftp-service>]
   [Dynamic] whether using class ftp service or not .true, false

[-f,--forceLock]
    Acquires the configuration lock forcibly.

[-detail]
    show detail results

Refer to jeusadmin for more information about dynamic changes.

3.2. Static Settings

If both dynamic and static settings are changed, only the dynamic settings are applied immediately. The static changes will be applied when the server restarts. This section describes how to identify the modified settings that have not been applied.

Using the Console Tool

Run the server-info command in the console tool (jeusadmin) to show the following server list and status information. Servers with 'true' in the 'Need to Restart' option must be restarted to apply the changes.

[MASTER]domain1.adminServer>server-info

Information about Domain (domain1)
===============================================================================================
+--------+---------+-----+-------+-----+----------------+---------+-------------+-------------+
| Server |  Status | Node|  PID  | Clus|  Latest Start  | Need to | Listen Ports| Running     |
|        |         |Name |       | ter |Time / Shutdown | Restart |             | Engines     |
|        |         |     |       |     |     Time       |         |             |             |
+--------+---------+-----+-------+-----+----------------+---------+-------------+-------------+
| adminSe| RUNNING | N/A | 5360  | N/A | 2016-08-23     | false   | base-192.168| jms,        |
|rver(*) |(00:25:52|     |       |     |(Tue) PM        |         |.34.3:9736   | ejb, web    |
|        |)        |     |       |     |03:53:28 KST    |         | http-server-|             |
|        |         |     |       |     |                |         |0.0.0.0:8088 |             |
|        |         |     |       |     |                |         |jms-internal-|             |
|        |         |     |       |     |                |         |0.0.0.0:9741 |             |
+--------+---------+-----+-------+-----+----------------+---------+-------------+-------------+
| server1| RUNNING |node1| 6424  | N/A | 2016-08-23     | true    | base-192.168| jms,        |
|        |(00:16:15|     |       |     |(Tue) PM        |         |.34.1:9836   | ejb, web    |
|        |)        |     |       |     |04:03:05 KST    |         |             |             |
+--------+---------+-----+-------+-----+----------------+---------+-------------+-------------+
| server2| RUNNING |node2| 3012  | N/A | 2016-08-23     | true    | base-192.168| jms,        |
|        |(00:16:15|     |       |     |(Tue) PM        |         |.34.2:9936   | ejb, web    |
|        |)        |     |       |     |04:03:05 KST    |         |             |             |
+--------+---------+-----+-------+-----+----------------+---------+-------------+-------------+
===============================================================================================

4. Settings Rotation

When settings are changed, the original settings are backed up. This is called settings rotation.

The current settings are always in the following files.

DOMAIN_HOME/config/domain.xml
DOMAIN_HOME/config/security/SECURITY_DOMAIN_NAME/policies.xml
DOMAIN_HOME/config/security/SECURITY_DOMAIN_NAME/accounts.xml

When there are any changes in the domain.xml file, whether they are dynamic or not, the previous domain.xml file is backed up as a file named 'domain_yyyymmdd_hhmmss.xml' in the DOMAIN_HOME/config/.history directory. The number of backed up files can be specified using the jeus.server.configfile.backup.size option (default value: 50).

5. Changing Common Domain Settings

The following is an example of domain common settings.

<domain>
    ...
    <production-mode>true</production-mode>
    <id>427655071</id>
    <master-server-name>adminServer</master-server-name>
    <domain-log-home>${JEUS_HOME}/domain1/logs</domain-log-home>
    <enable-json-command>false</enable-json-command>
    <enable-to-resynchronize-applications>false</enable-to-resynchronize-applications>
    <application-repositories>
        ...
    </application-repositories>
    <system-clustering-framework>
        <transport-type>HYBRID</transport-type>
        <trsnsport-address>224.0.0.1</trsnsport-address>
        <transport-port>12488</transport-port>
        <leader-discovery-timeout>3000</leader-discovery-timeout>
        <failure-detection-timeout>3000</failure-detection-timeout>
        <max-thread-pool-size>10</max-thread-pool-size>
        <min-thread-pool-size>0</min-thread-pool-size>
    </system-clustering-framework>
    <domain-backup>
        <backup-on-boot>false</backup-on-boot>
    </domain-backup>
    ...
</domain>

The following describes each item.

Item Description

Jeus Master Server Name

MASTER ID. This cannot be changed after the domain is created.

Id

Domain ID. This cannot be changed after the domain is created.

Domain Log Home

Directory name to be shared by servers within a domain. It cannot be changed after a domain is configured

Production Mode

Actual production mode. Auto-reload or hot-swap function is not available.

Enable Json Command

Option to use Json Command. This is off by default. This can be selectively enabled/disabled.

Enable To Resynchronize Applications

Option for MS to synchronize applications with MASTER when MS is changed from the INDEPENDENT mode to the DEPENDENT mode. (Default: false, do not synchronize)

Application Repositories

Location of the Applications. This can be changed dynamically. Refer to Adding, Deleting, and Searching Application Repositories for detailed information.

System Clustering Framework

Network configuration used to check internal communication and status of servers. This is applied to the entire domain. If this item is updated, the entire domain must be restarted.

By default, JEUS uses multicast to allow servers to share their status. For more information, refer to Creating a Domain.

  • transport: Specifies a communication method (DUMMY, HYBRID, MESH, and TREE) for communicating with other servers.

    • DUMMY: Does not involve any communication with other servers.

    • HYBRID: Uses IP multicast.

    • MESH, TREE: Operates similarly to multicast by using TCP/IP in an environment where the domain configuration extends beyond the sebnet or IP multicast is not supported. MESH connects all servers in a full-mesh topology, while TREE designates the Master Server as the root and Managed Server as leaf nodes like a tree structure.

  • transport-address, transport-port: Configures the required address or port for the selected transport type.

The following items are not required but they must be properly adjusted according to the domain size.

  • 'failure-detection-timeout': Time required to detect a server failure. Too low of a timeout setting may result in an incorrect detection. In HYBRID mode, it may take longer for a failure to be detected since IP multicast is used.

  • 'leader-discovery-timeout': Time required for a starting server to find a group of servers that have been running.

  • 'max-thread-pool-size': Maximum size of the thread pool used by SCF.

  • 'min-thread-pool-size': Minimum size of the thread pool used by SCF.

Domain Backup

Option to create backup files when starting the JEUS Master Server.

Backup files and directories can be created. By default, a domain backup is not created. For more information, refer to Failover through Domain Backup.

All settings except for 'Enable Json Command', 'Enable To Resynchronize Application', 'Application Repositories', and 'Domain Backup' require the restart of the entire domain to apply the settings. Unlike individual server settings, since domain settings affect the domain configuration, 'Jeus Master Server Name', 'Id', 'Domain Log Home', 'Production Mode', and 'System Clustering Framework' should be configured with care when a domain is created.

6. Example: Changing Settings

This section describes how to change the system thread pool count and JVM settings of the server by using the jeusadmin console tool.

6.1. Changing the System Thread Pool Count

This section describes how to change the system thread pool count by using the console tool jeusadmin.

Using the Console Tool

You can change the number of system thread pools by executing the modify-system-thread-pool command of the console tool (jeusadmin). For more information about the modify-system-thread-pool command, refer to modify-system-thread-pool in JEUS Reference Guide.

[MASTER]domain1.adminServer>modify-system-thread-pool server1 -max 120
Successfully performed the MODIFY operation for the system thread pool of the server (server1), but all changes were non-dynamic. They will be applied after restarting.
Check the results using "modify-system-thread-pool server1 or show-system-thread-pool server1".

6.2. Changing a Server’s JVM Settings

This section describes how to change a server’s JVM settings using the console tool jeusadmin.

Using the Console Tool

To add the server’s JVM settings using jeusadmin, run the add-jvm-option command as in the following example. The add-jvm-option command compares the user-entered settings to those in the jvm-option list and add the settings that are not in the list already.

[MASTER]domain1.adminServer>add-jvm-option -server server1 -opt "-Xmx256m -XX:MaxPermSize=128m"
Successfully performed the ADD operation for JVM configuration for the server(server1)..
Check the results using "list-jvm-options or add-jvm-option".

To change the server’s JVM settings using jeusadmin, run the modify-jvm-option command as in the following example. The modify-jvm-option command compares user-entered options with the jvm-option list and modifies the corresponding items.

[MASTER]domain1.adminServer>modify-jvm-option -server server1 -old "-Xmx256m -XX:MaxPermSize=128m" -new "-Xmx512m -XX:MaxPermSize=128m"
Successfully performed the MODIFY operation for JVM configuration for the server(server1)..
Check the results using "list-jvm-options or modify-jvm-option".

To delete the server’s JVM settings using jeusadmin, run the remove-jvm-option command as in the following example. The remove-jvm-option command compares user-entered options with the jvm-option list and deletes the corresponding items.

[MASTER]domain1.adminServer>remove-jvm-option -server server1 -opt "-Xmx256m -XX:MaxPermSize=128m"
Successfully performed the REMOVE operation for JVM configuration for the server(server1)..
Check the results using "list-jvm-options or remove-jvm-option".

It is recommended to add one option item at a time to the jvm-option list, and to modify or delete an option by using the list-jvm-option command.