Sun GlassFish Enterprise Server v2.1.1 High Availability Administration Guide

Synchronizing Node Agents and the Domain Administration Server

Because configuration data is stored in the Domain Administration Server’s repository (the central repository) and also cached on the node agent’s local machine, the two must be synchronized. The synchronization of cache is always done on a explicit user action through the administration tools.

This section contains the following topics:

Node Agent Synchronization

When a node agent is started for the first time, it sends a request to the Domain Administration Server (DAS) for the latest information in the central repository. Once it successfully contacts the DAS and gets configuration information, the node agent is bound to that DAS.

Note –

By default, the asadmin start-node-agent command automatically starts the remote server instances without synchronizing with DAS. If you are starting a remote server instance that is synchronized with the central repository managed by DAS, specify the --startinstances=false option of the asadmin start-node-agent command. Then use the asadmin start-instance command to start the remote server instance.

If you created a placeholder node agent on the DAS, when the node agent is started for the first time it gets its configuration from the central repository of the DAS. During its initial start-up, if the node agent is unable to reach the DAS because the DAS is not running, the node agent stops and remains unbound.

If changes are made in the domain to the node agent’s configuration, they are automatically communicated to the node agent on the local machine while the node agent is running.

If you delete a node agent configuration on the DAS, the next time the node agent synchronizes, it stops and marks itself as awaiting deletion. Manually delete it using the local asadmin delete-node-agent command.

Server Instance Synchronization

If you explicitly start a server instance with the Admin Console or asadmin tool, the server instance is synchronized with the central repository. If this synchronization fails, the server instance doesn’t start.

If a node agent starts a server instance without an explicit request through the Admin Console or the asadmin tool, the repository cache for the server instance is not synchronized. The server instance runs with the configuration as stored in its cache. You must not add or remove files in the remote server instance's cache.

The remote server instance's configuration are treated as cache (all files under nodeagents/na1/server1) and owned by Application Server. In extreme cases, if user removes all files of a remote server instance and restarts the node agent, the remote server instance (for example, server1) will be recreated and all necessary files will be synchronized.

The following files and directories are kept synchronized by the Application Server.

Table 8–1 Files and directories synchronized among remote server instances

File or directory 



All deployed applications. The parts of this directory (and sub directories) synchronized depend on the applications referred to from the server instance. The Node agent does not synchronize any of the applications because it does not reference any application. 


Contains configuration files for the entire domain. All the files in this directory are synchronized except runtime temporary files, such as, admch, admsn, secure.seed, . timestamp, and __timer_service_shutdown__.dat.


Directory to store files to be shared by all instances using config named config_name. There will be one such directory for every config defined in domain.xml. All the files in this directory are synchronized to the server instances that are using the config_name.


Folder where Java extension classes (as zip or jar archives) can be dropped. This is used by applications deployed to server instances using config named config_name. These jar files are loaded using Java extension mechanism.


The HTTP document root. In out of the box configuration, all server instances in the domain use the same docroot. The docroot property of the virtual server needs to be configured to make the server instances use a different docroot. 


Generated files for Java EE applications and modules, for example, EJB stubs, compiled JSP classes, and security policy files. This directory is synchronized along with applications directory. Therefore, only the directories corresponding to applications referenced by a server instance are synchronized. 

lib, lib/classes

Folder where common Java class files or jar and zip archives used by applications deployed to entire domain can be dropped. These classes are loaded using Application Server's class loader. The load order in class loader is: lib/classes, lib/*.jar, lib/*.zip.


Folder where Java extension classes (as zip or jar archives) used by applications deployed to entire domain can be dropped. These jar files are loaded using Java extension mechanism. 


Place dependent jars under domains/<domain_name>lib/applibs and specify a relative path to the jar file through the libraries option.

For example, asadmin deploy --libraries commons-coll.jar,X1.jar foo.ear


The parts of this directory (and sub directories) are synchronized depending on the applications referred to from the server instance.  

Synchronizing Library Files

The --libraries deploy time attribute for an application can be used to specify runtime dependencies of an application. When a relative path is specified, (only the jar name), Application Server attempts to find the specified library in domain-dir/lib/applibs.

To make a library available to the whole domain, you could place the JAR file in domain-dir/lib or domain-dir/lib/classes. (For more information, see Using the Common Class Loader in Sun GlassFish Enterprise Server v2.1.1 Developer’s Guide. ) This is usually the case for JDBC drivers and other utility libraries that are shared by all applications in the domain.

For cluster-wide or stand alone server wide use, copy the jars into the domain-dir/domain1/config/xyz-config/lib directory. Next, add the jars in classpath-suffix or classpath-prefix element of xyz-config. This will synchronize the jars for all server instances using xyz-config.

In summary:

Unique Settings and Configuration Management

Configuration files (under domains/domain1/config are synchronized across the domain. If you want to customize a server.policy file for a server1-config used by a stand alone server instance (server1), place the modified server.policy file under domains/domain1/config/server1-config directory.

This modified server.policy file will only be synchronized for the stand alone server instance, server1. You should remember to update the jvm-option. For example: <java-config> ...<jvm-options>${com.sun.aas.instanceRoot}/config/server1-config/server.policy</jvm-options></java-config>

Synchronizing Large Applications

When your environment contains large applications to synchronize or available memory is constrained, you can adjust the JVM options to limit memory usage. This adjustment reduces the possibility of receiving out of memory errors. The instance synchronization JVM uses default settings, but you can configure JVM options to change them.

Set the JVM options using the INSTANCE-SYNC-JVM-OPTIONS property. The command to set the property is:

asadmin set"JVM_options"

For example:

asadmin set"-Xmx32m -Xss2m"

In this example, the node agent is node0 and the JVM options are -Xmx32m -Xss2m.

For more information, see

Note –

Restart the node agent after changing the INSTANCE-SYNC-JVM-OPTIONS property, because the node agent is not automatically synchronized when a property is added or changed in its configuration.

Using the doNotRemoveList Flag

If your application requires to store and read files in the directories (applications, generated, docroot, config, lib, java-web-start) that are synchronized by the Application Server, use the doNotRemoveList flag. This attribute takes a coma-separated list of files or directories. Your application dependent files are not removed during server startup, even if they do not exist in the central repository managed by DAS. If the same file exists in the central repository, they will be over written during synchronization.

Use the INSTANCE-SYNC-JVM-OPTIONS property to pass in the doNotRemoveList attribute.

For example:

<node-agent name="na1" ...>


<property name="INSTANCE-SYNC-JVM-OPTIONS" value="-Dcom.sun.appserv.doNotRemoveList=applications/j2ee-modules/<webapp_context>/logs,generated/mylogdir"/>


Setting Timeouts for Starting and Stopping Node Agents

The following properties are available in Enterprise Server for setting the timeouts for starting and stopping the node agents: com.sun.aas.startAgentTimeout and com.sun.aas.startAgentTimeout.

These properties can be added to the as-install/lib/processLauncher.xml file. These properties are defined in milliseconds and they provide graceful starting and stopping of node agents when the --startinstances option is enabled.

If the node agent name is mynodegant1, find the <process name="mynodegant1"> entry in the /processLauncher.xml file and add the following lines:

<sysproperty key="com.sun.aas.startAgentTimeout" value="1500000"/>

<sysproperty key="com.sun.aas.stopAgentTimeout" value="240000"/>