Eclipse GlassFish High Availability Administration Guide, Release 7

A common load balancing configuration for Eclipse GlassFish 7 is to use the Apache HTTP Server as the web server front-end, and the Apache mod_jk or mod_proxy_ajp module as the connector between the web server and Eclipse GlassFish. See Configuring Eclipse GlassFish with Apache HTTP Server and mod_jk and Configuring Eclipse GlassFish with Apache HTTP Server and mod_proxy_ajp for more information.

Eclipse GlassFish provides high availability of HTTP requests and session data (both HTTP session data and stateful session bean data).

Jakarta EE applications typically have significant amounts of session state data. A web shopping cart is the classic example of a session state. Also, an application can cache frequently-needed data in the session object. In fact, almost all applications with significant user interactions need to maintain session state. Both HTTP sessions and stateful session beans (SFSBs) have session state data.

Preserving session state across server failures can be important to end users. If the Eclipse GlassFish instance hosting the user session experiences a failure, the session state can be recovered, and the session can continue without loss of information. High availability is implemented in Eclipse GlassFish by means of in-memory session replication on Eclipse GlassFish instances running in a cluster.

For more information about in-memory session replication in Eclipse GlassFish, see How Eclipse GlassFish Provides High Availability. For detailed instructions on configuring high availability session persistence, see Configuring High Availability Session Persistence and Failover.

Eclipse GlassFish supports the Java Message Service (JMS) API and JMS messaging through its built-in jmsra resource adapter communicating with Open Message Queue as the JMS provider. This combination is often called the JMS Service.

The JMS service makes JMS messaging highly available as follows:

With RMI-IIOP load balancing, IIOP client requests are distributed to different server instances or name servers, which spreads the load evenly across the cluster, providing scalability. IIOP load balancing combined with EJB clustering and availability also provides EJB failover.

When a client performs a JNDI lookup for an object, the Naming Service essentially binds the request to a particular server instance. From then on, all lookup requests made from that client are sent to the same server instance, and thus all EJBHome objects will be hosted on the same target server. Any bean references obtained henceforth are also created on the same target host. This effectively provides load balancing, since all clients randomize the list of target servers when performing JNDI lookups. If the target server instance goes down, the lookup or EJB method invocation will failover to another server instance.

IIOP Load balancing and failover happens transparently. No special steps are needed during application deployment. If the Eclipse GlassFish instance on which the application client is deployed participates in a cluster, the Eclipse GlassFish finds all currently active IIOP endpoints in the cluster automatically. However, a client should have at least two endpoints specified for bootstrapping purposes, in case one of the endpoints has failed.

For more information on RMI-IIOP load balancing and failover, see RMI-IIOP Load Balancing and Failover.

Storing session state data enables the session state to be recovered after the failover of a server instance in a cluster. Recovering the session state enables the session to continue without loss of information. Eclipse GlassFish supports in-memory session replication on other servers in the cluster for maintaining HTTP session and stateful session bean data.

In-memory session replication is implemented in Eclipse GlassFish 7 as an OSGi module. Internally, the replication module uses a consistent hash algorithm to pick a replica server instance within a cluster of instances. This allows the replication module to easily locate the replica or replicated data when a container needs to retrieve the data.

The use of in-memory replication requires the Group Management Service (GMS) to be enabled. For more information about GMS, see Group Management Service.

If server instances in a cluster are located on different hosts, ensure that the following prerequisites are met:

A highly available cluster integrates a state replication service with clusters and load balancer.

Loss of the Domain Administration Server (DAS) affects only administration. Eclipse GlassFish clusters and standalone instances, and the applications deployed to them, continue to run as before, even if the DAS is not reachable

Use any of the following methods to recover the DAS:

Eclipse GlassFish provide tools for backing up and restoring Eclipse GlassFish instances. For more information, see To Resynchronize an Instance and the DAS Offline.

There are no explicit commands to back up only a web server configuration. Simply zip the web server installation directory. After failure, unzip the saved backup on a new host with the same network identity. If the new host has a different IP address, update the DNS server or the routers.

The Load Balancer Plug-In (plugins directory) and configurations are in the web server installation directory, typically /opt/SUNWwbsvr. The web-install/web-instance/config directory contains the loadbalancer.xml file.

When a Message Queue broker becomes unavailable, the method you use to restore the broker to operation depends on the nature of the failure that caused the broker to become unavailable:

Additionally, the urgency of restoring an unavailable broker to operation depends on the type of the broker:

Before setting up a Eclipse GlassFish cluster, use the following considerations to determine whether to enable centralized administration of remote instances:

How you administer instances and the nodes on which they resides varies depending on whether and how centralized administration is enabled. The following table provides cross-references to instructions for administering nodes and instances depending on the protocol that is used for enabling centralized administration, if any.

DCOM enables communications between Windows hosts. In a typical Eclipse GlassFish deployment, the DAS acts as a DCOM client, and hosts where instances reside act as DCOM servers. To create or start an instance on a remote host, the DAS instructs the DCOM server on the host to start the asadmin utility of Eclipse GlassFish. The asadmin utility then performs the required operation on the host to create or start the instance.

The DCOM service must be running on hosts where instances reside, but is not required to be running on the DAS host. The DAS uses its own DCOM client for communicating with hosts where instances reside. On Windows hosts, the DCOM server is typically running by default as a Windows Service.

DCOM is available only with the Windows operating system. Because DCOM is typically installed and preconfigured, minimal additional setup is required to use DCOM with Eclipse GlassFish.

Before setting up DCOM, decide which Windows user Eclipse GlassFish will use when connecting to remote hosts. For the following reasons, administration is simplest if the Windows user is the user that starts the DAS:

In a typical Eclipse GlassFish deployment, the DAS acts as the SSH client, and hosts where instances reside act as SSH servers. The SSH Server Daemon sshd must be running on hosts where instances reside, but is not required to be running on the DAS host. The DAS uses its own SSH client for communicating with hosts where instances reside. However, to generate keys and test SSH setup, a native SSH client must be installed on the DAS host.

The requirements for SSH configuration and user management are different for each operating system on which Eclipse GlassFish is supported. Therefore, the use of SSH for centralized administration involves using SSH tools to configure SSH on the operating system that you are using.

On UNIX and Linux systems, SSH is typically installed and preconfigured, and requires minimal additional setup. On Windows systems, additional setup is required to install and configure an SSH provider.

To enable access to a host over DCOM, ensure that the following items in the Windows operating system are set as follows on the host:

To run scripts on a remote host, full control over the following Windows registry keys must be allowed for the Windows user or the group that contains the Windows user:

In some versions of Windows, only the user NT SERVICE\TrustedInstaller has full control over these Windows registry keys. If your version of Windows is configured in this way, you must modify these keys to allow full control over them for the Windows user or the group that contains the Windows user.

Perform this procedure for each Windows registry key that you are modifying on each host where instances in your cluster will reside.

Next Steps

Set up password authentication for the Windows user as explained in To Set Up Password Authentication for the Windows User.

When a Eclipse GlassFish subcommand uses DCOM to log in to a remote host, Eclipse GlassFish requires the Windows user’s password to authenticate the Windows user. To provide this password securely to Eclipse GlassFish, create a Eclipse GlassFish password alias to represent the password and store this alias in a password file that is passed to the asadmin utility.

Before You Begin

Ensure that the following prerequisites are met:

Example 2-1 Creating an Alias for the Windows User’s Password

This example creates an alias that is named winuser-password for the Windows user’s password.

The entry in the password file for the winuser-password alias is as follows:

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-password-alias at the command line.

Next Steps

Test the DCOM setup as explained in To Test the Connection Over DCOM to a Remote Host.

Testing the connection over DCOM to a remote host verifies that the required Windows services are running, the required ports are open, and the Windows user has a valid user account on the host.

Before attempting to perform any task that the requires the DAS contact the DCOM server on a remote host, test the connection over DCOM to the host. If this test fails, any attempt to perform a task that the requires the DAS contact the DCOM server on the host will also fail. Examples of such tasks are creating a DCOM node to represent the host or creating an instance that resides on the host. For more information, see To Create a DCOM Node and To Create an Instance Centrally.

If you cannot connect to the host over DCOM, troubleshoot the DCOM setup before proceeding.

Before You Begin

Ensure that the following prerequisites are met:

Example 2-2 Testing the Connection Over DCOM to a Remote Host

This example tests the connection over DCOM to the host wpmdl2.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help validate-dcom at the command line.

For centralized Eclipse GlassFish administration, a basic Cygwin installation that includes the SSH client and the SSH server daemon sshd is sufficient. The default installation options are sufficient to create such a basic installation.

See Also

For detailed information about installing Cygwin, see "Internet Setup" in Cygwin User’s Guide (http://cygwin.com/cygwin-ug-net/setup-net.html#internet-setup).

To enable Eclipse GlassFish tools to find commands for SSH, each user’s path for Windows and for the Cygwin shell must contain the following directories:

The SSH Server Daemon sshd locates a user’s home directory from the configuration in the user database, not from environment variables such as HOME. To ensure that all Eclipse GlassFish commands can run without errors, each SSH user must be configured to have a home directory.

Each user on a Windows host where SSH is set up potentially has two home directories:

If these home directories are different, Eclipse GlassFish and SSH each locate a user’s .ssh directory in different directories. To simplify the set up of SSH, configure each user’s home directory for SSH and Windows to be the same directory. A disadvantage of this approach is that the SSH home directory has spaces in its path name. Spaces in path names are cumbersome in the UNIX environment.

Before You Begin

Ensure that the following prerequisites are met:

The SSH server daemon sshd disallows authentication of any user for whose account a password is not set.

Next Steps

After you have completed the setup of SSH on a host, test the setup on the host as explained in Testing the SSH Setup on a Host.

For centralized Eclipse GlassFish administration, the default installation of the MKS Toolkit is sufficient.

Follow the instructions in the MKS Toolkit product documentation to install OpenSSH from the MKS Toolkit with default installation options.

See Also

For detailed information about installing MKS Toolkit, see "Installing MKS Toolkit" in MKS Toolkit v9.4 Release Notes (http://www.mkssoftware.com/docs/rn/relnotes_tk94.asp#install).

To enable Eclipse GlassFish tools to find commands for SSH, each user’s path for Windows and for the MKS Toolkit shell must contain the following directories:

The MKS Toolkit installer automatically adds the MKS Toolkit bin directory to the path. However, you must add the bin directory of the JDK software to the path yourself.

The SSH Server Daemon sshd locates a user’s home directory from the configuration in the user database, not from environment variables such as HOME. To ensure that all Eclipse GlassFish commands can run without errors, each SSH user must be configured to have a home directory.

Each user on a Windows host where SSH is set up potentially has two home directories:

If these home directories are different, Eclipse GlassFish and SSH each locate a user’s .ssh directory in different directories. To simplify the set up of SSH, configure each user’s home directory for SSH and Windows to be the same directory. A disadvantage of this approach is that the SSH home directory has spaces in its path name. Spaces in path names are cumbersome in the UNIX environment.

Example 2-3 Setting the Home Directory for the MKS Toolkit User

This example sets the home directory for the MKS Toolkit user Administrator to C:\Documents and Settings\Administrator.

Next Steps

After you have completed the setup of SSH on a host, test the setup on the host as explained in Testing the SSH Setup on a Host.

Example 2-4 Determining if the sshd Daemon Is Running on an Oracle Solaris System

This example confirms that the SSH server daemon sshd is running on an Oracle Solaris system.

See Also

svcs(1)

Next Steps

After you have completed the setup of SSH on a host, test the setup on the host as explained in Testing the SSH Setup on a Host.

Next Steps

After you have completed the setup of SSH on a host, test the setup on the host as explained in Testing the SSH Setup on a Host.

Example 2-5 Determining if the sshd Daemon Is Running on a Linux System

This example confirms that the SSH server daemon sshd is running on a Linux system.

Next Steps

After you have completed the setup of SSH on a host, test the setup on the host as explained in Testing the SSH Setup on a Host.

Troubleshooting

To obtain diagnostic information, use the -v option of the command-line SSH client and the -d option of the SSH server daemon sshd. How to start the SSH server daemon sshd manually depends on the operating system and SSH provider that you are using.

If the SSH server daemon sshd is set up on a host that has a firewall, ensure that a rule is defined to allow inbound traffic on the SSH port. The default SSH port is port 22.

If your connection is refused, the SSH server daemon sshd is not running and you must start the daemon. For instructions, see the following sections:

If your connection is accepted, but you cannot log in, ensure that the SSH user has a valid user account on the host.

Next Steps

After testing the SSH setup, set up SSH user authentication to enable SSH to authenticate users without prompting for a password. For more information, see Setting Up SSH User Authentication.

Use the setup-ssh subcommand in local mode to set up public key authentication without encryption. This subcommand enables you to set up public key authentication on multiple hosts in a single operation.

The setup-ssh subcommand generates a key pair and distributes the public key file to specified hosts. The private key file and the public key file are protected only by the file system’s file access permissions. If you require additional security, set up public key authentication with passphrase-protected encryption as explained in To Set Up Encrypted Public Key Authentication.

Before You Begin

Ensure that the following prerequisites are met:

Example 2-6 Setting Up Public Key Authentication Without Encryption

This example generates and sets up an SSH key for the user gfuser on the hosts sua01 and sua02. The command is run by the user gfuser.

Next Steps

After setting up public key authentication, test the setup by using ssh to log in as the SSH user to each host where the public key was distributed. For each host, log in first with the unqualified host name and then with the fully qualified name. If SSH does not prompt for password, public key authentication is set up correctly on the host.

If you are prompted for a password, verify that the public key file was copied correctly to the SSH user’s authorized_keys file.

Troubleshooting

Setup might fail because file access permissions in the SSH user’s home directory are too permissive. In this situation, ensure that the file access permissions in the SSH user’s home directory meet the requirements for performing this procedure.

If you have set the file access permissions in the SSH user’s home directory correctly, setup might still fail if you are using the MKS Toolkit. In this situation, correct the problem in one of the following ways:

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help setup-ssh at the command line.

Encrypted key file authentication uses an encrypted private key file that is protected with a passphrase. This passphrase must be provided to use the private key to unlock the public key. If you require encrypted public key authentication, you must use the SSH utility ssh-keygen to generate an SSH key pair with an encrypted private key. You can then use the setup-ssh subcommand to distribute the public key file to specified hosts.

To use the encrypted key file, Eclipse GlassFish requires the passphrase with which the key file was encrypted. To provide this passphrase securely to Eclipse GlassFish, create a Eclipse GlassFish password alias to represent the passphrase and store this alias in a password file that is passed to the asadmin utility.

Before You Begin

Ensure that the following prerequisites are met:

Example 2-7 Setting Up Encrypted Public Key Authentication

This example generates an SSH key pair with an encrypted private key for the user gfadmin and distributes the public key to the hosts sj01 and ja02. The example also creates an alias that is named ssh-key-passphrase for the private key’s passphrase.

The entry in the password file for the ssh-key-passphrase alias is as follows:

Troubleshooting

Setup might fail because file access permissions in the SSH user’s home directory are too permissive. In this situation, ensure that the file access permissions in the SSH user’s home directory meet the requirements for performing this procedure.

If you have set the file access permissions in the SSH user’s home directory correctly, setup might still fail if you are using the MKS Toolkit. In this situation, correct the problem in one of the following ways:

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line:

To use SSH to log in to a remote host, Eclipse GlassFish requires the SSH user’s password. To provide this password securely to Eclipse GlassFish, create a Eclipse GlassFish password alias to represent the password and store this alias in a password file that is passed to the asadmin utility.

Before You Begin

Ensure that SSH is set up on each host where you are setting up password authentication. For more information, see the following sections:

Example 2-8 Creating an Alias for the SSH User’s Password

This example creates an alias that is named ssh-password for the SSH user’s password.

The entry in the password file for the ssh-password alias is as follows:

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-password-alias at the command line.

Use the install-node-dcom subcommand or the install-node-ssh subcommand in local mode to copy an installation of Eclipse GlassFish software to multiple hosts.

Before You Begin

Ensure that DCOM or SSH is set up on the host where you are running the subcommand and on each host where you are copying the Eclipse GlassFish software.

Run the appropriate subcommand for the protocol that is set up for communication between the hosts.

Example 2-9 Copying a Eclipse GlassFish Installation to Multiple DCOM-Enabled Hosts

This example copies the Eclipse GlassFish software on the host where the subcommand is run to the default location on the DCOM-enabled hosts wpmdl1.example.com and wpmdl2.example.com.

Some lines of output are omitted from this example for readability.

Example 2-10 Copying a Eclipse GlassFish Installation to Multiple SSH-Enabled Hosts

This example copies the Eclipse GlassFish software on the host where the subcommand is run to the default location on the SSH-enabled hosts sj03.example.com and sj04.example.com.

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line:

Use the uninstall-node-dcom subcommand or the uninstall-node-ssh subcommand in local mode to remove Eclipse GlassFish software from multiple hosts.

Before You Begin

Ensure that the following prerequisites are met:

Run the appropriate subcommand for the protocol that is set up for communication between the hosts.

Example 2-11 Removing Eclipse GlassFish Software From Multiple DCO\M-Enabled Hosts

This example removes Eclipse GlassFish software on the DCOM-enabled hosts wpmdl1.example.com and wpmdl2.example.com from the default location.

Example 2-12 Removing Eclipse GlassFish Software From Multiple SSH-Enabled Hosts

This example removes Eclipse GlassFish software on the SSH-enabled hosts sj03.example.com and sj04.example.com from the default location.

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line:

Use the create-node-dcom subcommand in remote mode to create a DCOM node.

Before You Begin

Ensure that the Windows user can use DCOM to connect to the host that the node will represent. By default, the create-node-dcom subcommand validates the node’s parameters and the DCOM connection to the host. If the Windows user cannot use DCOM to connect to the host, the validation fails.

Example 3-1 Creating a DCOM Node

This example creates the DCOM node wpmdl1 to represent the host wpmdl1.example.com. The Eclipse GlassFish software is installed in the same directory on the DAS host and on the host wpmdl1.example.com.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-node-dcom at the command line.

Next Steps

After creating a node, you can create instances on the node as explained in the following sections:

Use the list-nodes-dcom subcommand in remote mode to obtain information about existing DCOM nodes in a domain.

Example 3-2 Listing Basic Information About All DCOM Nodes in a Domain

This example lists the name, type, and host of all DCOM nodes in the current domain.

Example 3-3 Listing Detailed Information About All DCOM Nodes in a Domain

This example lists detailed information about all DCOM nodes in the current domain.

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line:

Use the ping-node-dcom subcommand in remote mode to test if a DCOM node is reachable.

Before You Begin

Ensure that DCOM is configured on the host where the DAS is running and on the host that the node represents.

Example 3-4 Testing if a DCOM Node Is Reachable

This example tests if the DCOM node wpmdl2 is reachable.

See Also

ping-node-dcom(1)

You can also view the full syntax and options of the subcommand by typing asadmin help ping-node-dcom at the command line.

Use the delete-node-dcom subcommand in remote mode to delete a DCOM node.

Deleting a node removes the node from the configuration of the DAS. The node’s directories and files are deleted when the last Eclipse GlassFish instance that resides on the node is deleted.

Before You Begin

Ensure that no Eclipse GlassFish instances reside on the node that you are deleting. For information about how to delete an instance, see the following sections.

Example 3-5 Deleting a DCOM Node

This example confirms that no instances reside on the DCOM node xkyd and deletes the node xkyd.

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line:

Use the create-node-ssh subcommand in remote mode to create an SSH node.

Before You Begin

Ensure that the SSH user can use SSH to log in to the host that the node will represent. By default, the create-node-ssh subcommand validates the node’s parameters and the SSH connection to the host. If the SSH user cannot use SSH to log in to the host, the validation fails.

Example 3-6 Creating an SSH Node

This example creates the SSH node sj01 to represent the host sj01.example.com. The Eclipse GlassFish software is installed in the same directory on the DAS host and on the host sj01.example.com.

Troubleshooting

The create-node-ssh subcommand might fail to create the node and report the error Illegal sftp packet len. If this error occurs, ensure that no the startup file on the remote host displays text for noninteractive shells. Examples of startup files are .bashrc, .cshrc, .login, and .profile.

The SSH session interprets any text message that is displayed during login as a file-transfer protocol packet. Therefore, any statement in a startup file that displays text messages corrupts the SSH session, causing this error.

See Also

create-node-ssh(1)

You can also view the full syntax and options of the subcommand by typing asadmin help create-node-ssh at the command line.

Next Steps

After creating a node, you can create instances on the node as explained in the following sections:

Use the list-nodes-ssh subcommand in remote mode to obtain information about existing SSH nodes in a domain.

Example 3-7 Listing Basic Information About All SSH Nodes in a Domain

This example lists the name, type, and host of all SSH nodes in the current domain.

Example 3-8 Listing Detailed Information About All SSH Nodes in a Domain

This example lists detailed information about all SSH nodes in the current domain.

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line:

Use the ping-node-ssh subcommand in remote mode to test if an SSH node is reachable.

Before You Begin

Ensure that SSH is configured on the host where the DAS is running and on the host that the node represents.

Example 3-9 Testing if an SSH Node Is Reachable

This example tests if the SSH node sj01 is reachable.

See Also

ping-node-ssh(1)

You can also view the full syntax and options of the subcommand by typing asadmin help ping-node-ssh at the command line.

Use the delete-node-ssh subcommand in remote mode to delete an SSH node.

Deleting a node removes the node from the configuration of the DAS. The node’s directories and files are deleted when the last Eclipse GlassFish instance that resides on the node is deleted.

Before You Begin

Ensure that no Eclipse GlassFish instances reside on the node that you are deleting. For information about how to delete an instance, see the following sections.

Example 3-10 Deleting an SSH Node

This example confirms that no instances reside on the SSH node sj01 and deletes the node sj01.

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line:

Use the create-node-config command in remote mode to create a CONFIG node.

Example 3-11 Creating a CONFIG Node

This example creates the CONFIG node cfg01. The host that the node represents and the installation directory of the Eclipse GlassFish software on the host are to be determined when instances are added to the node.

See Also

create-node-config(1)

You can also view the full syntax and options of the subcommand by typing asadmin help create-node-config at the command line.

Next Steps

After creating a node, you can create instances on the node as explained in To Create an Instance Locally.

Use the list-nodes-config subcommand in remote mode to obtain information about existing CONFIG nodes in a domain.

Example 3-12 Listing Basic Information About All CONFIG Nodes in a Domain

This example lists the name, type, and host of all CONFIG nodes in the current domain.

Example 3-13 Listing Detailed Information About All CONFIG Nodes in a Domain

This example lists detailed information about all CONFIG nodes in the current domain.

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line:

Use the delete-node-config subcommand in remote mode to delete a CONFIG node.

Deleting a node removes the node from the configuration of the DAS. The node’s directories and files are deleted when the last Eclipse GlassFish instance that resides on the node is deleted.

Before You Begin

Ensure that no Eclipse GlassFish instances reside on the node that you are deleting. For information about how to delete an instance that resides on a CONFIG node, see To Delete an Instance Locally.

Example 3-14 Deleting a CONFIG Node

This example confirms that no instances reside on the CONFIG node cfg01 and deletes the node cfg01.

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line:

Use the update-node-dcom subcommand in remote mode to update a DCOM node.

Options of this subcommand specify the new values of the node’s configuration data. If you omit an option, the existing value is unchanged.

Before You Begin

Ensure that the following prerequisites are met:

Example 3-15 Updating a DCOM Node

This example updates the host that the node wpmdl1 represents to wj01.

See Also

update-node-dcom(1)

You can also view the full syntax and options of the subcommand by typing asadmin help update-node-dcom at the command line.

Use the update-node-ssh subcommand in remote mode to update an SSH node.

Options of this subcommand specify the new values of the node’s configuration data. If you omit an option, the existing value is unchanged.

Before You Begin

Ensure that the following prerequisites are met:

Example 3-16 Updating an SSH Node

This example updates the host that the node sj01 represents to adc01.example.com.

See Also

update-node-ssh(1)

You can also view the full syntax and options of the subcommand by typing asadmin help update-node-ssh at the command line.

Use the update-node-config subcommand in remote mode to update a CONFIG node.

Options of this subcommand specify the new values of the node’s configuration data. If you omit an option, the existing value is unchanged.

Before You Begin

Ensure that the node that you are updating exists.

Example 3-17 Updating a CONFIG Node

This example updates the host that the node cfg02 represents to adc02.example.com.

See Also

update-node-config(1)

You can also view the full syntax and options of the subcommand by typing asadmin help update-node-config at the command line.

The subcommands for updating a node can also be used to change the type of a node.

Changing the type of a CONFIG node enables remote communication for the node. The type of the node after the change determines the protocol over which the node is enabled for remote communication:

As part of the process of changing the type of a node, you can also change other configuration data for the node.

Options of the subcommands for updating a node specify the new values of the node’s configuration data. For most options, if you omit the option, the existing value is unchanged. However, default values are applied in the following situations:

Before You Begin

Ensure that the following prerequisites are met:

Example 3-18 Changing a CONFIG Node to an SSH Node

This example changes the CONFIG node cfg02 to an SSH node.

See Also

You can also view the full syntax and options of the subcommand by typing the following commands at the command line.

You can specify that GMS should use one of the following combinations of protocol and transport for broadcasting messages:

Even if GMS should use UDP multicast for broadcasting messages, you must ensure that TCP is enabled. On Windows systems, enabling TCP involves enabling a protocol and port for security when a firewall is enabled.

If GMS should use UDP multicast for broadcasting messages and if Eclipse GlassFish instances in a cluster are located on different hosts, the following conditions must be met:

If GMS should use TCP without multicast, you must configure GMS to locate the instances to use for discovering the cluster. For more information, see Discovering a Cluster When Multicast Transport Is Unavailable.

Eclipse GlassFish has the following types of GMS settings:

The following GMS configuration settings are used in GMS for group discovery and failure detection:

The heartbeat frequency, maximum missed heartbeats, peer-to-peer connection-based failure detection, and the verify timeouts are all needed to ensure that failure detection is robust and reliable in Eclipse GlassFish.

For the dotted names for each of these GMS configuration settings, see Dotted Names for GMS Settings. For the steps to specify these settings, see To Preconfigure Nondefault GMS Configuration Settings.

Below are sample get subcommands to get all the GMS configuration settings (attributes associated with the referenced mycfg configuration) and GMS cluster settings (attributes and properties associated with a cluster named mycluster).

The last get subcommand displays only the properties that have been explicitly set.

For the steps to specify these settings, see To Preconfigure Nondefault GMS Configuration Settings and To Change GMS Settings After Cluster Creation.

You can preconfigure GMS with values different than the defaults without requiring a restart of the DAS and the cluster.

See Also

You can also view the full syntax and options of a subcommand by typing asadmin help subcommand at the command line.

To avoid the need to restart the DAS and the cluster, configure GMS configuration settings before cluster creation as explained in To Preconfigure Nondefault GMS Configuration Settings.

To avoid the need to restart the DAS and the cluster, configure the GMS cluster settings during cluster creation as explained in To Create a Cluster.

Changing any GMS settings using the set subcommand after cluster creation requires a domain administration server (DAS) and cluster restart as explained here.

See Also

You can also view the full syntax and options of a subcommand by typing asadmin help subcommand at the command line.

The get-health subcommand only works when GMS is enabled. This is the quickest way to evaluate the health of a cluster and to detect if cluster is properly operating; that is, all members of the cluster are running and visible to DAS.

If multicast is not enabled for the network, all instances could be running (as shown by the list-instances subcommand), yet isolated from each other. The get-health subcommand does not show the instances if they are running but cannot discover each other due to multicast not being configured properly. See To Validate That Multicast Transport Is Available for a Cluster.

Example 4-1 Checking the Health of Instances in a Cluster

This example checks the health of a cluster named cluster1.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help get-health at the command line.

Before You Begin

To test a specific multicast address, multicast port, or bind interface address, get this information beforehand using the get subcommand. Use the following subcommand to get the multicast address and port for a cluster named c1:

Use the following subcommand to get the bind interface address of a server instance named i1 that belongs to a cluster named c1, if this system property has been set:

For information on how to set this system property, see Using the Multi-Homing Feature With GMS.

Check whether multicast transport is available for a cluster by using the validate-multicast subcommand.

Example 4-2 Validating That Multicast Transport Is Available for a Cluster

This example checks whether multicast transport is available for a cluster named c1.

Run from host sr1:

Run from host sr2:

Next Steps

As long as all machines see each other, multicast is validated to be working properly across the machines. If the machines are not seeing each other, set the --bindaddress option explicitly to ensure that all machines are using interface on same subnet, or increase the --timetolive option from the default of 4. If these changes fail to resolve the multicast issues, ask the network administrator to verify that the network is configured so the multicast messages can be seen between all the machines used to run the cluster.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help get-health at the command line.

When multicast transport is unavailable, Eclipse GlassFish instances that are joining a cluster cannot rely on broadcast messages from GMS to discover the cluster. Instead, an instance that is joining a cluster uses a running instance or the DAS in the cluster to discover the cluster.

Therefore, when multicast transport is unavailable, you must provide the locations of instances in the cluster to use for discovering the cluster. You are not required to provide the locations of all instances in the cluster. However, for an instance to discover the cluster, at least one instance whose location you provide must be running. To increase the probability of finding a running instance, provide the locations of several instances.

If the DAS will be left running after the cluster is started, provide the location of the DAS first in the list of instances. When a cluster is started, the DAS is running before any of the instances in the cluster are started.

The locations of the instances to use for discovering a cluster are part of the configuration data that you provide when creating the cluster. How to provide this data depends on how instances are distributed, as explained in the following subsections:

Multi-homing enables Eclipse GlassFish clusters to be used in an environment that uses multiple Network Interface Cards (NICs). A multi-homed host has multiple network connections, of which the connections may or may not be the on same network. Multi-homing provides the following benefits:

Use the create-cluster subcommand in remote mode to create a cluster.

To ensure that the GMS can detect changes in cluster membership, a cluster’s GMS settings must be configured correctly. To avoid the need to restart the DAS and the cluster, configure a cluster’s GMS settings when you create the cluster. If you change GMS settings for an existing cluster, the DAS and the cluster must be restarted to apply the changes.

When you create a cluster, Eclipse GlassFish automatically creates a Message Queue cluster for the Eclipse GlassFish cluster. For more information about Message Queue clusters, see Using Message Queue Broker Clusters With Eclipse GlassFish.

Before You Begin

If the cluster is to reference an existing named configuration, ensure that the configuration exists. For more information, see To Create a Named Configuration. If you are using a named configuration to preconfigure GMS settings, ensure that these settings have the required values in the named configuration. For more information, see To Preconfigure Nondefault GMS Configuration Settings.

If you are configuring the cluster’s GMS settings when you create the cluster, ensure that you have the following information:

If the DAS is running on a multihome host, ensure that you have the Internet Protocol (IP) address of the network interface on the DAS host to which GMS binds.

Example 4-6 Creating a Cluster for a Network in Which Multicast Transport Is Available

This example creates a cluster that is named ltscluster for which port 1169 is to be used for secure IIOP connections. Because the --config option is not specified, the cluster references a copy of the named configuration default-config that is named ltscluster-config. This example assumes that multicast transport is available.

Example 4-7 Creating a Cluster and Setting GMS Options for a Network in Which Multicast Transport Is Available

This example creates a cluster that is named pmdcluster, which references the existing configuration clusterpresets and for which the cluster’s GMS settings are configured as follows:

This example assumes that multicast transport is available.

Next Steps

After creating a cluster, you can add Eclipse GlassFish instances to the cluster as explained in the following sections:

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line:

Use the list-clusters subcommand in remote mode to obtain information about existing clusters in a domain.

Example 4-8 Listing All Clusters in a Domain

This example lists all clusters in the current domain.

Example 4-9 Listing All Clusters That Are Associated With a Node

This example lists the clusters that contain an instance that resides on the node sj01.

See Also

list-clusters(1)

You can also view the full syntax and options of the subcommand by typing asadmin help list-clusters at the command line.

Use the delete-cluster subcommand in remote mode to remove a cluster from the DAS configuration.

If the cluster’s named configuration was created automatically for the cluster and no other clusters or unclustered instances refer to the configuration, the configuration is deleted when the cluster is deleted.

Before You Begin

Ensure that following prerequisites are met:

Example 4-10 Deleting a Cluster

This example confirms that the cluster adccluster is stopped and contains no instances and deletes the cluster adccluster.

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line:

Use the create-instance subcommand in remote mode to create a Eclipse GlassFish instance centrally. Creating an instance adds the instance to the DAS configuration and creates the instance’s files on the host where the instance resides.

If the instance is a clustered instance that is managed by GMS, system properties for the instance that relate to GMS must be configured correctly. To avoid the need to restart the DAS and the instance, configure an instance’s system properties that relate to GMS when you create the instance. If you change GMS-related system properties for an existing instance, the DAS and the instance must be restarted to apply the changes. For information about GMS, see Group Management Service.

Before You Begin

Ensure that following prerequisites are met:

If any of these prerequisites is not met, create the instance locally as explained in To Create an Instance Locally.

If you are adding the instance to a cluster, ensure that the cluster to which you are adding the instance exists. For information about how to create a cluster, see To Create a Cluster.

If the instance is to reference an existing named configuration, ensure that the configuration exists. For more information, see To Create a Named Configuration.

The instance might be a clustered instance that is managed by GMS and resides on a node that represents a multihome host. In this situation, ensure that you have the Internet Protocol (IP) address of the network interface to which GMS binds.

Example 5-1 Creating a Clustered Instance Centrally

This example adds the instance pmd-i1 to the cluster pmdclust in the domain domain1. The instance resides on the node sj01, which represents the host sj01.example.com.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-instance at the command line.

Next Steps

After creating an instance, you can start the instance as explained in the following sections:

Use the list-instances subcommand in remote mode to obtain information about existing instances in a domain.

Example 5-2 Listing Basic Information About All Eclipse GlassFish Instances in a Domain

This example lists the name and status of all Eclipse GlassFish instances in the current domain.

Example 5-3 Listing Detailed Information About All Eclipse GlassFish Instances in a Domain

This example lists detailed information about all Eclipse GlassFish instances in the current domain.

See Also

list-instances(1)

You can also view the full syntax and options of the subcommand by typing asadmin help list-instances at the command line.

Use the delete-instance subcommand in remote mode to delete a Eclipse GlassFish instance centrally.

Deleting an instance involves the following:

Before You Begin

Ensure that the instance that you are deleting is not running. For information about how to stop an instance, see the following sections:

Example 5-4 Deleting an Instance Centrally

This example confirms that the instance pmd-i1 is not running and deletes the instance.

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line:

Use the start-cluster subcommand in remote mode to start a cluster.

Starting a cluster starts all instances in the cluster that are not already running.

Before You Begin

Ensure that following prerequisites are met:

If any of these prerequisites is not met, start the cluster by starting each instance locally as explained in To Start an Individual Instance Locally.

Example 5-5 Starting a Cluster

This example starts the cluster pmdcluster.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help start-cluster at the command line.

Next Steps

After starting a cluster, you can deploy applications to the cluster. For more information, see Eclipse GlassFish Application Deployment Guide.

Use the stop-cluster subcommand in remote mode to stop a cluster.

Stopping a cluster stops all running instances in the cluster.

Example 5-6 Stopping a Cluster

This example stops the cluster pmdcluster.

See Also

stop-cluster(1)

You can also view the full syntax and options of the subcommand by typing asadmin help stop-cluster at the command line.

Troubleshooting

If instances in the cluster have become unresponsive and fail to stop, run the subcommand again with the --kill option set to true. When this option is true, the subcommand uses functionality of the operating system to kill the process for each running instance in the cluster.

Use the start-instance subcommand in remote mode to start an individual instance centrally.

Before You Begin

Ensure that following prerequisites are met:

If any of these prerequisites is not met, start the instance locally as explained in To Start an Individual Instance Locally.

Example 5-7 Starting an Individual Instance Centrally

This example starts the instance pmd-i2, which resides on the node sj02. This node represents the host sj02.example.com. The configuration of the instance on this node already matched the configuration of the instance in the DAS when the instance was started.

See Also

start-instance(1)

You can also view the full syntax and options of the subcommand by typing asadmin help start-instance at the command line.

Next Steps

After starting an instance, you can deploy applications to the instance. For more information, see the Eclipse GlassFish Application Deployment Guide.

Use the stop-instance subcommand in remote mode to stop an individual instance centrally.

When an instance is stopped, the instance stops accepting new requests and waits for all outstanding requests to be completed.

Example 5-8 Stopping an Individual Instance Centrally

This example stops the instance pmd-i2.

See Also

stop-instance(1)

You can also view the full syntax and options of the subcommand by typing asadmin help stop-instance at the command line.

Troubleshooting

If the instance has become unresponsive and fails to stop, run the subcommand again with the --kill option set to true. When this option is true, the subcommand uses functionality of the operating system to kill the instance process.

Use the restart-instance subcommand in remote mode to start an individual instance centrally.

When this subcommand restarts an instance, the DAS synchronizes the instance with changes since the last synchronization as described in Default Synchronization for Files and Directories.

If you require different synchronization behavior, stop and start the instance as explained in To Resynchronize an Instance and the DAS Online.

Example 5-9 Restarting an Individual Instance Centrally

This example restarts the instance pmd-i2.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help restart-instance at the command line.

Troubleshooting

If the instance has become unresponsive and fails to stop, run the subcommand again with the --kill option set to true. When this option is true, the subcommand uses functionality of the operating system to kill the instance process before restarting the instance.

Use the create-local-instance subcommand in remote mode to create a Eclipse GlassFish instance locally. Creating an instance adds the instance to the DAS configuration and creates the instance’s files on the host where the instance resides.

If the instance is a clustered instance that is managed by GMS, system properties for the instance that relate to GMS must be configured correctly. To avoid the need to restart the DAS and the instance, configure an instance’s system properties that relate to GMS when you create the instance. If you change GMS-related system properties for an existing instance, the DAS and the instance must be restarted to apply the changes. For information about GMS, see Group Management Service.

Before You Begin

If you plan to specify the node on which the instance is to reside, ensure that the node exists.

For information about how to create a node, see the following sections:

If you are adding the instance to a cluster, ensure that the cluster to which you are adding the instance exists. For information about how to create a cluster, see To Create a Cluster.

If the instance is to reference an existing named configuration, ensure that the configuration exists. For more information, see To Create a Named Configuration.

The instance might be a clustered instance that is managed by GMS and resides on a node that represents a multihome host. In this situation, ensure that you have the Internet Protocol (IP) address of the network interface to which GMS binds.

Example 5-10 Creating a Clustered Instance Locally Without Specifying a Node

This example adds the instance kui-i1 to the cluster kuicluster locally. The CONFIG node xk01 is created automatically to represent the host xk01.example.com, on which this example is run. The DAS is running on the host dashost.example.com and listens for administration requests on the default port.

The commands to list the nodes in the domain are included in this example only to demonstrate the creation of the node xk01. These commands are not required to create the instance.

Example 5-11 Creating a Clustered Instance Locally

This example adds the instance yml-i1 to the cluster ymlcluster locally. The instance resides on the node sj01. The DAS is running on the host das1.example.com and listens for administration requests on the default port.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-local-instance at the command line.

Next Steps

After creating an instance, you can start the instance as explained in the following sections:

Use the delete-local-instance subcommand in remote mode to delete a Eclipse GlassFish instance locally.

Deleting an instance involves the following:

Before You Begin

Ensure that the instance that you are deleting is not running. For information about how to stop an instance, see the following sections:

Example 5-12 Deleting an Instance Locally

This example confirms that the instance yml-i1 is not running and deletes the instance.

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line:

Use the start-local-instance subcommand in local mode to start an individual instance locally.

Example 5-13 Starting an Individual Instance Locally

This example starts the instance yml-i1 locally. The instance resides on the node sj01.

See Also

start-local-instance(1)

You can also view the full syntax and options of the subcommand by typing asadmin help start-local-instance at the command line.

Next Steps

After starting an instance, you can deploy applications to the instance. For more information, see the Eclipse GlassFish Application Deployment Guide.

Use the stop-local-instance subcommand in local mode to stop an individual instance locally.

When an instance is stopped, the instance stops accepting new requests and waits for all outstanding requests to be completed.

Example 5-14 Stopping an Individual Instance Locally

This example stops the instance yml-i1 locally. The instance resides on the node sj01.

See Also

stop-local-instance(1)

You can also view the full syntax and options of the subcommand by typing asadmin help stop-local-instance at the command line.

Troubleshooting

If the instance has become unresponsive and fails to stop, run the subcommand again with the --kill option set to true. When this option is true, the subcommand uses functionality of the operating system to kill the instance process.

Use the restart-local-instance subcommand in local mode to restart an individual instance locally.

When this subcommand restarts an instance, the DAS synchronizes the instance with changes since the last synchronization as described in Default Synchronization for Files and Directories.

If you require different synchronization behavior, stop and start the instance as explained in To Resynchronize an Instance and the DAS Online.

Example 5-15 Restarting an Individual Instance Locally

This example restarts the instance yml-i1 locally. The instance resides on the node sj01.

See Also

restart-local-instance(1)

You can also view the full syntax and options of the subcommand by typing asadmin help restart-local-instance at the command line.

Troubleshooting

If the instance has become unresponsive and fails to stop, run the subcommand again with the --kill option set to true. When this option is true, the subcommand uses functionality of the operating system to kill the instance process before restarting the instance.

The --sync option of the subcommands for starting an instance controls the type of synchronization between the DAS and the instance’s files when the instance is started. You can use this option to override the default synchronization behavior for the files and directories of an instance. For more information, see To Resynchronize an Instance and the DAS Online.

On the DAS, the files and directories of an instance are stored in the domain-dir directory, where domain-dir is the directory in which a domain’s configuration is stored. The default synchronization behavior for the files and directories of an instance is as follows:

Resynchronizing an instance and the DAS updates the instance with changes to the instance’s configuration files on the DAS. An instance is resynchronized with the DAS when the instance is started or restarted.

Example 5-16 Resynchronizing an Instance and the DAS Online

This example determines that the instance yml-i1 is stopped and fully resynchronizes the instance with the DAS. Because neither DCOM nor SSH is set up, the instance is started locally on the host where the instance resides. In this example, multiple nodes are defined for the Eclipse GlassFish installation that is running on the node’s host.

To determine whether the instance is stopped, the following command is run in multimode on the DAS host:

To start the instance, the following command is run in single mode on the host where the instance resides:

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line.

asadmin help list-instances asadmin help start-instance asadmin help start-local-instance

To ensure that library files are resynchronized correctly, you must ensure that each library file is placed in the correct directory for the type of file.

See Also

deploy(1)

You can also view the full syntax and options of the subcommands by typing the command asadmin help deploy at the command line.

Configuration files in the domain-dir/config directory that are resynchronized are resynchronized for the entire domain. If you create a custom configuration file for an instance or a cluster, the custom file is resynchronized only for the instance or cluster.

Example 5-17 Updating the Option for Locating a Configuration File

This example updates the option for locating the server.policy file to specify a custom file for the instance pmd.

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line.

asadmin help create-jvm-options

asadmin help delete-jvm-options

A change to the config/domain.xml file is required to cause the DAS to resynchronize instances' files. If other files in the domain directory are changed without a change to the config/domain.xml file, instances are not resynchronized with these changes.

The following changes are examples of changes to the domain directory without a change to the config/domain.xml file:

See Also

By default, Eclipse GlassFish synchronizes only the following configuration files:

If you require instances in a domain to be resynchronized with additional configuration files for the domain, you can specify a list of files to resynchronize.

In the config directory of the domain, create a plain text file that is named config-files that lists the files to resynchronize.

In the config-files file, list each file name on a separate line.

Example 5-18 config-files File

This example shows the content of a config-files file. This file specifies that the some-other-info file is to be resynchronized in addition to the files that Eclipse GlassFish resynchronizes by default:

When the DAS resynchronizes an instance’s files, the DAS deletes from the instance’s cache any files that are not listed for resynchronization. If an application creates files in a directory that the DAS resynchronizes, these files are deleted when the DAS resynchronizes an instance with the DAS.

Put the files in a subdirectory under the domain directory that is not defined by Eclipse GlassFish, for example, /export/glassfish7/glassfish/domains/domain1/myapp/myfile.

Resynchronizing an instance and the DAS offline updates the instance’s cache without the need for the instance to be able to communicate with the DAS. Offline resynchronization is typically required for the following reasons:

Example 5-19 Resynchronizing an Instance and the DAS Offline

This example resynchronizes the clustered instance yml-i1 and the DAS offline. The instance is a member of the cluster ymlcluster. The archive file that contains the instance’s configuration data is created on the host where the instance resides.

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line.

asadmin help export-sync-bundle

asadmin help import-sync-bundle

Automatic migration of EJB timers is enabled by default for clustered server instances that are stopped normally. If the Group Management Service (GMS) is enabled and a clustered instance is stopped normally, no further action is required for timer migration to occur. The procedure in this section is only necessary if you want to enable automatic timer migration for clustered server instances that have stopped abnormally.

Before You Begin

Automatic EJB timer migration can only be configured for clustered server instances. Automatic timer migration is not possible for standalone server instances.

Enable delegated transaction recovery for the cluster.

This enables automatic timer migration for failed server instances in the cluster.

For instructions on enabling delegated transaction recovery, see "Administering Transactions" in Eclipse GlassFish Administration Guide.

EJB timers can be migrated manually from a stopped source instance to a specified target instance in the same cluster if GMS notification is not enabled. If no target instance is specified, the DAS will attempt to find a suitable server instance. A migration notification will then be sent to the selected target server instance.

Note the following restrictions:

Before You Begin

The server instance from which the EJB timers are to be migrated should not be active during the migration process.