Creating a Domain

This chapter describes the requirements for creating a domain, how to create a domain using a tool provided by JEUS (jeusadmin), and the directory structure of a domain.

1. Creating a Domain

A domain directory is created when a domain is created. Scripts and basic configuration files that start and stop servers in the domain are created in this directory. The parent directory for each domain is DOMAIN_HOME and its path is as follows:

JEUS_HOME/domains/<domain_name>

When a domain is created, it only contains MASTER. Managed serves can be added using jeusadmin. After an MS is added and started, it receives the domain information from MASTER. In other words, MASTER creates the domain directory when the domain is created, and managed servers create the domain directory through MASTER when they start.

A domain can be created using Ant task or jeusadmin. The following are the requirements.

  • Network configuration

    JEUS requires an IP address and port number because it shares domain server status using multicast. If servers exist outside of the local network and are not able to share information via multicast, TCP is used instead. This is called virtual multicasting in JEUS, and it can be configured when a domain is created.

    Since server information is shared using the default listener IP address and port number on the server, all servers in the domain that exist outside of the local network must specify a listener IP address and port number. They must also set the option to disable multicasting.

  • Default MASTER configuration

    Each domain must contain a MASTER. A default configuration is used and can be further configured by the user. Dynamic configuration items can be changed at any time, but static items must be configured when the domain is created. Examples of static configuration items include the default listener IP address, port number, and JVM configuration.

1.1. Creating a Default Domain

This section describes how to create the default domain. When the default domain is created, Virtual Multicast is disabled.

The following are the command attributes for Ant task and jeusadmin.

Attribute Default Value

MASTER name

adminServer

Listen IP address

0.0.0.0 / 0:0:0:0:0:0:0:0

Listen port number

9736

user name

administrator

Multicast IP address

230.30.1.1 / FF01:0:0:0:0:0:0:1

Multicast port number

3030

  • Creating a domain with Ant

    The default configuration values when using Ant are defined in JEUS_HOME/setup/domain-config-template.properties. The following is an example of configuring the attributes. The default value is used if an attribute is not configured.

    JEUS_HOME/setup$ ant create-domain -Ddomain=jeus_domain
-Dservername=adminServer
-Djeus.address=0.0.0.0
-Djeus.port=9736
-Dtransport.address=230.30.1.1
-Dtransport.port=3030

  • Creating a domain with jeusadmin

    The default configuration values when using jeusadmin are defined in JEUS_HOME/setup/domain-config-template.properties. If jeus.password is set in domain-config-template.properties, use the configured value. Otherwise, enter the password as in the following example.

    offline>create-domain -domain jeus_domain -mastername adminServer -taddress 230.30.1.1 -tport 3030
Enter the password for [administrator]: **********
Confirm the password: **********
Do you want to encrypt the password? (y/n): y
================================================================================
The domain [jeus_domain] was created successfully.
+-------------------------------+----------------------------------------------+
|         Property              |                        Value                 |
+-------------------------------+----------------------------------------------+
| Domain name                   | jeus_domain                                  |
| Master Name                   | adminServer                                  |
| Master Base Listen Port       | 9736                                         |
| Master Base Listen Address    | 0.0.0.0                                      |
| HTTP Port                     | 8088                                         |
| User Name                     | administrator                                |
| Node Name                     | node1                                        |
| Password                      | {base}amV1cw==                               |
| JVM Option                    | -Xmx256m -XX:MaxMetaspaceSize=128m           |
| Production Mode               | true                                         |
| Transport Type                | HYBRID                                       |
+-------------------------------+----------------------------------------------+
===============================================================================

1.2. Creating a Domain that Uses Virtual Multicast

This section describes how to check if the environment supports the IP Multicast functionality, and how to create a domain that uses the virtual multicasting when the environment does not support the IP multitasking or the domain goes beyond the subnet range.

To check if the environment supports IP multitasking, execute the two mcastSender and mcastReceiver test scripts. The two scripts are in JEUS_HOME/bin. Execute each one on a different machine as in the following.

JEUS_HOME/bin$ mcastReceiver -addr 224.0.0.1 -port 3030
Socket == 0.0.0.0/0.0.0.0 : 3030, bound to /fe80:0:0:0:2a37:37ff:fe1e:fc4%5
Socket == 0.0.0.0/0.0.0.0 : 3030, bound to /192.168.0.26
Socket == 0.0.0.0/0.0.0.0 : 3030, bound to /fe80:0:0:0:3e07:54ff:fe6f:95e%4
Socket == 0.0.0.0/0.0.0.0 : 3030, bound to /61.77.153.207
Socket == 0.0.0.0/0.0.0.0 : 3030, bound to /fe80:0:0:0:0:0:0:1%1
Socket == 0.0.0.0/0.0.0.0 : 3030, bound to /0:0:0:0:0:0:0:1
Socket == 0.0.0.0/0.0.0.0 : 3030, bound to /127.0.0.1
JEUS_HOME/bin$ mcastSender -addr 224.0.0.1 -port 3030
1 == 0.0.0.0/0.0.0.0 : 3030, bound to /fe80:0:0:0:2a37:37ff:fe1e:fc4%5
2 == 0.0.0.0/0.0.0.0 : 3030, bound to /192.168.0.26
3 == 0.0.0.0/0.0.0.0 : 3030, bound to /fe80:0:0:0:3e07:54ff:fe6f:95e%4
4 == 0.0.0.0/0.0.0.0 : 3030, bound to /61.77.153.207
5 == 0.0.0.0/0.0.0.0 : 3030, bound to /fe80:0:0:0:0:0:0:1%1
6 == 0.0.0.0/0.0.0.0 : 3030, bound to /0:0:0:0:0:0:0:1
7 == 0.0.0.0/0.0.0.0 : 3030, bound to /127.0.0.1

This test attempts to send and receive IP multicast packets through all network interfaces. The addresses at the top are for all network interfaces.

At the prompt that appears on the Sender side, enter a message that is sent to the Receiver. If the Receiver cannot receive the message, it means that IP multicasting is not working properly. In such a case, set the following virtual multicast configuration. The following is the execution of a test message for the mcastSender example above.

> test
>
test [sender = 192.168.0.26 : 5555], [bind_addr=/127.0.0.1]
test [sender = 192.168.0.26 : 5555], [bind_addr=/61.77.153.207]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:3e07:54ff:fe6f:95e%4]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:3e07:54ff:fe6f:95e%4]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:2a37:37ff:fe1e:fc4%5]
test [sender = 192.168.0.26 : 5555], [bind_addr=/61.77.153.207]
test [sender = 192.168.0.26 : 5555], [bind_addr=/192.168.0.26]
test [sender = 192.168.0.26 : 5555], [bind_addr=/192.168.0.26]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:3e07:54ff:fe6f:95e%4]
test [sender = 192.168.0.26 : 5555], [bind_addr=/61.77.153.207]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:2a37:37ff:fe1e:fc4%5]
test [sender = 192.168.0.26 : 5555], [bind_addr=/61.77.153.207]
test [sender = 192.168.0.26 : 5555], [bind_addr=/61.77.153.207]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:2a37:37ff:fe1e:fc4%5]
test [sender = 192.168.0.26 : 5555], [bind_addr=/61.77.153.207]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:3e07:54ff:fe6f:95e%4]
test [sender = 192.168.0.26 : 5555], [bind_addr=/192.168.0.26]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:3e07:54ff:fe6f:95e%4]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:3e07:54ff:fe6f:95e%4]
test [sender = 192.168.0.26 : 5555], [bind_addr=/192.168.0.26]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:3e07:54ff:fe6f:95e%4]
test [sender = 192.168.0.26 : 5555], [bind_addr=/192.168.0.26]
test [sender = 192.168.0.26 : 5555], [bind_addr=/61.77.153.207]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:2a37:37ff:fe1e:fc4%5]
test [sender = 192.168.0.26 : 5555], [bind_addr=/192.168.0.26]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:2a37:37ff:fe1e:fc4%5]
test [sender = 192.168.0.26 : 5555], [bind_addr=/192.168.0.26]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:2a37:37ff:fe1e:fc4%5]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:2a37:37ff:fe1e:fc4%5]

Since the same message is sent/received through all network interfaces of the machine, duplicate messages can be transmitted. To quit the test, enter 'quit' or 'exit' at the Sender’s prompt. At the Receiver’s end, press <Ctrl> + C to quit.

To see help, enter '-help' as a parameter or do not include a parameter.

The following describes how to configure a virtual multicast domain. The default attribute values are the same as those in Creating a Default Domain. The virtual multicast has two types: MESH and Tree.

  • Creating a domain with Ant (MESH type)

    JEUS_HOME/setup$ ant create-domain
                    -Ddomain=jeus_domain
                    -Djeus.address=192.168.34.1
                    -Dtransport.type=MESH

  • Creating a domain with jeusadmin (MESH type)

    offline>create-domain -domain jeus_domain -baseaddress 192.168.34.1 -ttype MESH
Enter the password for [administrator]: **********
Confirm the password: **********
Do you want to encrypt the password? (y/n): y
================================================================================
The domain [jeus_domain] was created successfully.
+-------------------------------+----------------------------------------------+
|         Property              |                        Value                 |
+-------------------------------+----------------------------------------------+
| Domain name                   | jeus_domain                                  |
| Master Name                   | adminServer                                  |
| Master Base Listen Port       | 9736                                         |
| Master Base Listen Address    | 192.168.34.1                                 |
| HTTP Port                     | 8088                                         |
| User Name                     | administrator                                |
| Node Name                     | node1                                        |
| Password                      | {base}amV1cw==                               |
| JVM Option                    | -Xmx256m -XX:MaxMetaspaceSize=128m           |
| Production Mode               | true                                         |
| Transport Type                | MESH                                         |
+-------------------------------+----------------------------------------------+
================================================================================

  • Creating a domain with jeusadmin (TREE type)

    offline>create-domain -domain jeus_domain -baseaddress 192.168.34.1 -ttype TREE -taddress 192.168.34.1 -tport 9736
Enter the password for [administrator]: **********
Confirm the password: **********
Do you want to encrypt the password? (y/n): y
================================================================================
The domain [jeus_domain] was created successfully.
+-------------------------------+----------------------------------------------+
|         Property              |                        Value                 |
+-------------------------------+----------------------------------------------+
| Domain name                   | jeus_domain                                  |
| Master Name                   | adminServer                                  |
| Master Base Listen Port       | 9736                                         |
| Master Base Listen Address    | 192.168.34.1                                 |
| HTTP Port                     | 8088                                         |
| User Name                     | administrator                                |
| Node Name                     | node1                                        |
| Password                      | {base}amV1cw==                               |
| JVM Option                    | -Xmx256m -XX:MaxMetaspaceSize=128m           |
| Production Mode               | true                                         |
| Transport Type                | TREE                                         |
| Transport address             | 192.168.34.1                                 |
| Transport port                | 9736                                         |
+-------------------------------+----------------------------------------------+
================================================================================

2. Configuring a Domain

This section describes how to change the composition of a domain by adding servers and clusters to the domain created in Creating a Domain.

The MASTER must be started to add servers and clusters which changes the configuration. Refer to Changing Domain Settings for detailed information about changing the configuration.

DOMAIN_HOME/bin$ startMasterServer -u jeus -p jeus

2.1. Using the Console Tool

The following are the steps for adding a server and a cluster.

  1. Add Managed Servers (MS)

  2. Add a cluster

Add Managed Servers (MS)

Managed Server configuration cannot be changed dynamically.

Similar to the default configuration of MASTER, when the domain described in Creating a Domain is created, default configuration set when adding an MS is not applied dynamically. Choose a unique IP address and port number that do not conflict with other servers, and configure the JVM options. If a domain does not exist on the local network, specify an IP address to use instead of the default value of 0:0:0:0. Since server names in a domain must be unique, verify that there are no conflicts. Since the servers in the example are in the same cluster, settings that exist at the cluster level do not need to be configured separately for each server.

The following are the steps for adding an MS by using jeusadmin.

Add an MS, server1, using the add-server command. Add server2 in the same way. For detailed instructions about using the add-server command, refer to add-server in JEUS Reference Guide.

[MASTER]domain1.adminServer>add-server server1 -node node1 -addr 192.168.34.1 -port 9836
Successfully performed the ADD operation for server (server1).
 NOTICE : base-addr [192.168.34.1] base-port [9836] http-port [8088]
Check the results using "list-servers or add-server"
Add Clusters

When adding a cluster, load balancing, failover, and the servers in the cluster must all be configured. Refer to Configuring a Cluster for detailed information about configuring a cluster.

The following are the steps for adding a cluster.

  1. Add a cluster 'cluster1' that consists of server1 and server2 using the add-cluster command. Refer to add-cluster for detailed instructions about using the add-cluster command.

    [MASTER]domain1.adminServer> add-cluster cluster1 -servers server1,server2
Successfully performed the ADD operation for cluster (cluster1).
Check the results using "list-clusters or add-cluster"

  2. After adding all items up to the cluster, use the serverinfo command to verify the result.

    [MASTER]domain1.adminServer>serverinfo
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:01:11|     |       |     |(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  | clus| 2016-08-23     | false   | base-192.168| jms,        |
 |        |(00:00:03|     |       |ter1 |(Tue) PM        |         |.34.1:9836   | ejb, web    |
 |        |)        |     |       |     |03:54:37 KST    |         |             |             |
 +--------+---------+-----+-------+-----+----------------+---------+-------------+-------------+
 | server2| RUNNING |node2| 3012  | clus| 2016-08-23     | false   | base-192.168| jms,        |
 |        |(00:00:03|     |       |ter1 |(Tue) PM        |         |.34.2:9936   | ejb, web    |
 |        |)        |     |       |     |03:54:36 KST    |         |             |             |
 +--------+---------+-----+-------+-----+----------------+---------+-------------+-------------+
 ===============================================================================================

3. Directory Structure

When JEUS is installed, JEUS_HOME directory and jeus_domain, which is the sub directory of JEUS_HOME, are created.

This section describes the directory structure with the assumption that the path of the user home is '/home/user1' and the domain is called 'domain1'.

3.1. JEUS_HOME Directory

The JEUS directory structure is as follows. JEUS_HOME is the top-level directory of JEUS. The actual directory name and location can be configured during the installation.

/home/jeus/JEUS_HOME

The following is the directory structure of JEUS_HOME.

{JEUS_HOME}
   |--bin
   |    |--[01]startMasterServer
   |    |--[01]startManagedServer
   |    |--[01]stopserver
   |    |--[01]jeusadmin
   |--derby
   |--docs
   |--domains
   |    |--domain1
   |--lib
   |--license
   |--setup
   |--templates

* Legend
- [01]: binary or executable file
- [X] : XML document
- [J] : JAR file
- [T] : Text file
- [C] : Class file
- [V] : java source file
- [DD] : deployment descriptor
bin

Contains executable files, including startMasterServer, startManagedServer, and stopServer, which are scripts that start and stop servers. It also contains jeusadmin, JEUS console tool.

derby

Contains Apache Derby so that sample applications and tests can be easily used.

docs

Contains Javadoc documents for the API provided by JEUS.

domains

Contains a DOMAIN_HOME subdirectory for each domain.

lib

Contains the libraries that are needed to run JEUS. A users does not need to access other directories except the shared directory.

Subdirectory Description

shared

Contains libraries that are used by applications.

To use the libraries, add the information about the libraries to libraries.xml. Also, the reference information of the libraries must be configured in the JEUS Deployment Descriptor (DD) of the application that will reference them.

Refer to Shared Libraries for detailed information about shared libraries.
license

Contains JEUS license files that are required to run JEUS.

setup

Contains the files that are required for implementing JEUS environment.

templates

Contains template files for various configurations and environments.

3.2. Domain Directory

JEUS_HOME/domains/domain1 is the DOMAIN_HOME directory for domain1.

The following is the directory structure of domain1.

domain1
   |--.applications
   |--.deploymentplans
   |--.libraries
   |--bin
   |--config
   |--lib
   |   |--application
   |--servers
.applications

Contains application files managed by the domain. This directory has restricted access. Files can only be added or deleted using the install-application or uninstall-application commands. For details about each command, refer to install-application, uninstall-application.

.deploymentplans

Contains deployment plans managed by the domain. This directory has restricted access. Files can only be added or deleted using the install-deployment-plan and uninstall-deployment-plan commands. For details about each command, refer to install-deployment-plan and uninstall-application.

.libraries

Contains the library files installed in the domain. User access is limited to the directory that JEUS uses. The install-library and uninstall-library can be used to add and delete libraries. For details about each command, refer to install-library and uninstall-library.

bin

Contains the MASTER and MS start and stop scripts.

These have the same function as the startMasterServer, startManagedServer, and stopServer scripts in 'JEUS_HOME/bin' except that they do not need to specify the name of the domain.

config

Contains the backup copies of the domain.xml file. Refer to Changing Domain Settings for detailed information about configuring the domain.

  • security

    Subdirectory Description

    SYSTEM_DOMAIN

    Directory that contains the accounts.xml and policies.xml domain security files. These files contain settings that can be changed dynamically using jeusadmin.

    Refer to Configuring the Security System Domain in JEUS Security Guide for a detailed description of domain security settings.

    security.key

    File that contains the encryption keys that is created when JEUS_HOME/bin/encryption is created. Refer to Configuring Password Security in JEUS Security Guide for a detailed description of the security.key file.

    policy

    Java permissions configuration file. This is unrelated to the JEUS security system; it is used by the Java SE Security Manager.

  • servlet

    Subdirectory Description

    webcommon.xml

    The common configuration file which applies to all web modules on the web engine of a server in the domain.

    For details about this configuration, refer to Directory Structure in JEUS Web Engine Guide.
lib/application

Contains application libraries that are applied to the entire domain.

If there is a duplicate copy of the library in the SERVER_HOME directory, the copy in the SERVER_HOME/lib/application directory has priority, and a warning message is also displayed. For a detailed description of the lib/application directory, refer to lib/application Directory in JEUS Applications & Deployment Guide.

servers

The SERVER_HOME directory is a subdirectory that uses the server name. For a detailed description of the lib/application directory, refer to Server Directory Structure in JEUS Server Guide.