Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide

- Previous: Deploying Node Agents
- Next: Viewing Node Agent Logs

# Node Agent and Domain Administration Server Synchronization

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

- Server Instance Synchronization

- Synchronizing Library Files

- Unique Settings and Configuration Management

- Synchronizing Large Applications

## 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 7–1 Files and directories synchronized among remote server instances

File or directory | Description
--- | ---
`applications` | 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.
`config` | 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`.
`config`/config_name | 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.
`config`/config_name`/lib/ext` | 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.
docroot | 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 | 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`.
lib/ext | 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.

## Synchronizing Library Files

The `--libraries` deploy time attribute for an application can be used to specify runtime dependencies of an application.

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 Classloader in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 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:

- `domains/domain1/lib` - domain wide scope, common class loader, adds the jars automatically.

- `domains/domain1/config/cluster1`, `config/lib` - config wide, update `classpath-prefix` or `classpath-suffix`.

- `domains/domain1/config/cluster1`, `config/lib/ext` - adds to java.ext.dirs automatically.

## 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>-Djava.security.policy=${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
    domain.node-agent.node_agent_name.property.INSTANCE-SYNC-JVM-OPTIONS="JVM_options"

For example:

    asadmin set
    domain.node-agent.node0.property.INSTANCE-SYNC-JVM-OPTIONS="-Xmx32m -Xss2m"

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

For more information, see `http://java.sun.com/docs/hotspot/VMOptions.html`.

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) 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"/>`

`</node–agent>`

- Previous: Deploying Node Agents
- Next: Viewing Node Agent Logs

- © 2010, Oracle Corporation and/or its affiliates