Resynchronizing GlassFish Server Instances and the DAS

Configuration data for a GlassFish Server instance is stored as follows:

In the repository of the domain administration server (DAS)
In a cache on the host that is local to the instance

The configuration data in these locations must be synchronized. The cache is synchronized in the following circumstances:

Whenever an asadmin subcommand is run. For more information, see Impact of Configuration Changes in Oracle GlassFish Server 3.1 Administration Guide.
When a user uses the administration tools to start or restart an instance.

Default Synchronization for Files and Directories

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:

applications

This directory contains a subdirectory for each application that is deployed to the instance.

By default, only a change to an application's top-level directory within the application directory causes the DAS to synchronize that application's directory. When the DAS resynchronizes the applications directory, all the application's files and all generated content that is related to the application are copied to the instance.

If a file below a top-level subdirectory is changed without a change to a file in the top-level subdirectory, full synchronization is required. In normal operation, files below the top-level subdirectories of these directories are not changed and such files should not be changed by users. If an application is deployed and undeployed, full synchronization is not necessary to update the instance with the change.

config

This directory contains configuration files for the entire domain.

By default, the DAS resynchronizes files that have been modified since the last resynchronization only if the domain.xml file in this directory has been modified.

Note - If you add a file to the config directory of an instance, the file is deleted when the instance is resynchronized with the DAS. However, any file that you add to the config directory of the DAS is not deleted when instances and the DAS are resynchronized. By default, any file that you add to the config directory of the DAS is not resynchronized. If you require any additional configuration files to be resynchronized, you must specify the files explicitly. For more information, see To Resynchronize Additional Configuration Files.

config

config/config-name

This directory contains files that are to be shared by all instances that reference the named configuration config-name. A config-name directory exists for each named configuration in the configuration of the DAS.

Because the config-name directory contains the subdirectories lib and docroot, this directory might be very large. Therefore, by default, only a change to a file or a top-level subdirectory of config-name causes the DAS to resynchronize the config-name directory.

config/domain.xml

This file contains the DAS configuration for the domain to which the instance belongs.

By default, the DAS resynchronizes this file if it has been modified since the last resynchronization.

Note - A change to the config/domain.xml file is required to cause the DAS to resynchronize an instance's files. If the config/domain.xml file has not changed since the last resynchronization, none of the instance's files is resynchronized, even if some of these files are out of date in the cache.

docroot

This directory is the HTTP document root directory. By default, all instances in a domain use the same document root directory. To enable instances to use a different document root directory, a virtual server must be created in which the docroot property is set. For more information, see the create-virtual-server(1) help page.

The docroot directory might be very large. Therefore, by default, only a change to a file or a subdirectory in the top level of the docroot directory causes the DAS to resynchronize the docroot directory. The DAS checks files in the top level of the docroot directory to ensure that changes to the index.html file are detected.

When the DAS resynchronizes the docroot directory, all modified files and subdirectories at any level are copied to the instance.

If a file below a top-level subdirectory is changed without a change to a file in the top-level subdirectory, full synchronization is required.

generated

This directory contains generated files for Java EE applications and modules, for example, EJB stubs, compiled JSP classes, and security policy files. Do not modify the contents of this directory.

This directory is resynchronized when the applications directory is resynchronized. Therefore, only directories for applications that are deployed to the instance are resynchronized.

java-web-start

This directory is not resynchronized. It is created and populated as required on each instance.

lib

lib/classes

These directories contain common Java class files or JAR archives and ZIP archives for use by applications that are deployed to the entire domain. Typically, these directories contain common JDBC drivers and other utility libraries that are shared by all applications in the domain.

The contents of these directories are loaded by the common class loader. For more information, see Using the Common Class Loader in Oracle GlassFish Server 3.1 Application Development Guide. The class loader loads the contents of these directories in the following order:

lib/classes
lib/*.jar
lib/*.zip

The lib directory also contains the following subdirectories:

applibs: This directory contains application-specific Java class files or JAR archives and ZIP archives for use by applications that are deployed to the entire domain.
ext: This directory contains optional packages in JAR archives and ZIP archives for use by applications that are deployed to the entire domain. These archive files are loaded by using Java extension mechanism. For more information, see Optional Packages - An Overview.

Note - Optional packages were formerly known as standard extensions or extensions.

The lib directory and its subdirectories typically contain only a small number of files. Therefore, by default, a change to any file in these directories causes the DAS to resynchronize the file that changed.

To Resynchronize an Instance and the DAS Online

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.

Note - Resynchronization of an instance is only required if the instance is stopped. A running instance does not require resynchronization.

Ensure that the DAS is running.
Determine whether the instance is stopped.
```
asadmin> list-instances instance-name
```
instance-name

The name of the instance that you are resynchronizing with the DAS.

If the instance is stopped, the list-instances subcommand indicates that the instance is not running.
If the instance is stopped, start the instance.
If the instance is running, no further action is required.
- If SSH is set up, start the instance centrally.
  If you require full synchronization, set the --sync option of the start-instance subcommand to full. If default synchronization is sufficient, omit this option.
```
asadmin> start-instance [--sync full] instance-name
```
  Note - Only the options that are required to complete this task are provided in this step. For information about all the options for controlling the behavior of the instance, see the start-instance(1) help page.
  
  instance-name
  
  The name of the instance that you are starting.
- If SSH is not set up, start the instance locally from the host where the instance resides.
  If you require full synchronization, set the --sync option of the start-local-instance subcommand to full. If default synchronization is sufficient, omit this option.
```
$ asadmin start-local-instance [--node node-name] [--sync full] instance-name
```
  Note - Only the options that are required to complete this task are provided in this step. For information about all the options for controlling the behavior of the instance, see the start-local-instance(1) help page.
  
  node-name
  
  The node on which the instance resides. If only one node is defined for the GlassFish Server installation that you are running on the node's host, you may omit this option.
  
  instance-name
  
  The name of the instance that you are starting.

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 SSH is not set up, the instance is started locally on the host where the instance resides. In this example, multiple nodes are defined for the GlassFish Server 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:

asadmin> list-instances yml-i1
yml-i1   not running  
Command list-instances executed successfully.

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

$ asadmin start-local-instance --node sj01 --sync full yml-i1
Removing all cached state for instance yml-i1.
Waiting for yml-i1 to start ...............
Successfully started the instance: yml-i1
instance Location: /export/glassfish3/glassfish/nodes/sj01/yml-i1
Log File: /export/glassfish3/glassfish/nodes/sj01/yml-i1/logs/server.log
Admin Port: 24849
Command start-local-instance executed successfully.

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 Resynchronize Library Files

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. You must add files in some directories for library files to the class path yourself. Files in other directories are added to the class path automatically.

Place each library file in the correct location for the type of library file as shown in the following table.

Type of Library Files	Location
Common JAR archives and ZIP archives for all applications in a domain.	`domain-dir/lib`
Common Java class files for a domain for all applications in a domain.	`domain-dir/lib/classes`
Application-specific libraries.	`domain-dir/lib/applibs`
Optional packages for all applications in a domain.	`domain-dir/lib/ext`
Library files for all applications that are deployed to a specific cluster or standalone instance.	`domain-dir/config/config-name/lib`
Optional packages for all applications that are deployed to a specific cluster or standalone instance.	`domain-dir/config/config-name/lib/ext`

domain-dir

The directory in which the domain's configuration is stored.

config-name

For a standalone instance: the named configuration that the instance references.

For a clustered instance: the named configuration that the cluster to which the instance belongs references.

For library files for all applications that are deployed to a specific cluster or standalone instance, add the files to the class path prefix or class path suffix of the named configuration that the cluster or standalone instance references.
This type of library file is stored in the domain-dir/config/config-name/lib directory.
For other types of library file, omit this step. Other types of library file are automatically added to the class path by their class loaders.
- To add the files to the class path prefix, perform these steps:
  1. Determine the existing class path prefix.
```
asadmin> get configs.config.config-name.java-config.classpath-prefix
```
    config-name
    
    The named configuration that the cluster or standalone instance references.
  2. Set the class path prefix to the existing class path prefix and the files that you are adding.
```
asadmin> set 
configs.config.config-name.java-config.classpath-prefix=library-file-list
```
    config-name
    
    The named configuration that the cluster or standalone instance references.
    
    library-file-list
    
    A comma-separated list of the files in the existing class path prefix and the files that you are adding.
- To add the files to the class path suffix, perform these steps:
  1. Determine the existing class path suffix.
```
asadmin> get configs.config.config-name.java-config.classpath-suffix
```
    config-name
    
    The named configuration that the cluster or standalone instance references.
  2. Set the class path suffix to the existing class path suffix and the files that you are adding.
```
asadmin> set 
configs.config.config-name.java-config.classpath-suffix=library-file-list
```
    config-name
    
    The named configuration that the cluster or standalone instance references.
    
    library-file-list
    
    A comma-separated list of the files in the existing class path suffix and the files that you are adding.

Next Steps

When you deploy an application that depends on these library files, use the --libraries option of the deploy subcommand to specify these dependencies. For library files in the domain-dir/lib/applib directory, only the JAR file name is required, for example:

asadmin deploy --libraries commons-coll.jar,X1.jar app.ear

For other types of library file, the full path is required.

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 get

asadmin help set

To Resynchronize Custom Configuration Files for an Instance

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.

Place the custom configuration file in the domain-dir/config/config-name directory.
domain-dir

The directory in which the domain's configuration is stored.

config-name

The named configuration that the instance references.
If the instance locates the file through an option of the Java application launcher, update the option.
1. Delete the option.
```
asadmin> delete-jvm-options --target instance-name 
option-name=current-value
```
  instance-name
  
  The name of the instance for which the custom configuration file is created.
  
  option-name
  
  The name of the option for locating the file.
  
  current-value
  
  The current value of the option for locating the file.
2. Re-create the option that you deleted in the previous step.
```
asadmin> create-jvm-options --target instance-name 
option-name=new-value
```
  instance-name
  
  The name of the instance for which the custom configuration file is created.
  
  option-name
  
  The name of the option for locating the file.
  
  new-value
  
  The new value of the option for locating the file.

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.

asadmin> delete-jvm-options --target pmd
-Djava.security.policy=${com.sun.aas.instanceRoot}/config/server.policy
Deleted 1 option(s)
Command delete-jvm-options executed successfully.
asadmin> create-jvm-options --target pmd
-Djava.security.policy=${com.sun.aas.instanceRoot}/config/pmd-config/server.policy
Created 1 option(s)
Command create-jvm-options executed successfully.

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

To Resynchronize Users' Changes to Files

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:

Adding files to the lib directory
Adding certificates to the key store by using the keytool command

Change the last modified time of the config/domain.xml file.
Exactly how to change the last modified time depends on the operating system. For example, on UNIX and Linux systems, you can use the touch(1) command.
Resynchronize each instance in the domain with the DAS.
For instructions, see To Resynchronize an Instance and the DAS Online.

See Also

To Resynchronize an Instance and the DAS Online
touch(1)

To Resynchronize Additional Configuration Files

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

admin-keyfile
cacerts.jks
default-web.xml
domain.xml
domain-passwords
keyfile
keystore.jks
server.policy
sun-acc.xml
wss-server-config-1.0
xml wss-server-config-2.0.xml

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.

Caution - If you specify a list of files to resynchronize, you must specify all the files that the instances require, including the files that GlassFish Server resynchronizes by default. Any file in the instance's cache that is not in the list is deleted when the instance is resynchronized with the DAS.

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 GlassFish Server resynchronizes by default:

admin-keyfile
cacerts.jks
default-web.xml
domain.xml
domain-passwords
keyfile
keystore.jks
server.policy
sun-acc.xml
wss-server-config-1.0.xml
wss-server-config-2.0.xml
some-other-info

To Prevent Deletion of Application-Generated Files

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 GlassFish Server, for example, /export/glassfish3/glassfish/domains/domain1/myapp/myfile.

To Resynchronize an Instance and the DAS Offline

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:

To reestablish the instance after an upgrade
To synchronize the instance manually with the DAS when the instance cannot contact the DAS

Ensure that the DAS is running.
Export the configuration data that you are resynchronizing to an archive file.
Note - Only the options that are required to complete this task are provided in this step. For information about all the options for exporting the configuration data, see the export-sync-bundle(1) help page.

How to export the data depends on the host from where you run the export-sync-bundle subcommand.
- From the DAS host, run the export-sync-bundle subcommand as follows:
```
asadmin> export-sync-bundle --target target
```
  target
  
  The cluster or standalone instance for which to export configuration data.
  Do not specify a clustered instance. If you specify a clustered instance, an error occurs. To export configuration data for a clustered instance, specify the name of the cluster of which the instance is a member, not the instance.
  
  The file is created on the DAS host.
- From the host where the instance resides, run the export-sync-bundle subcommand as follows:
```
$ asadmin --host das-host [--port admin-port]
export-sync-bundle [--retrieve=true] --target target
```
  das-host
  
  The name of the host where the DAS is running.
  
  admin-port
  
  The HTTP or HTTPS port on which the DAS listens for administration requests. If the DAS listens on the default port for administration requests, you may omit this option.
  
  target
  
  The cluster or standalone instance for which to export configuration data.
  Do not specify a clustered instance. If you specify a clustered instance, an error occurs. To export configuration data for a clustered instance, specify the name of the cluster of which the instance is a member, not the instance.
  
  Note - To create the archive file on the host where the instance resides, set the --retrieve option to true. If you omit this option, the archive file is created on the DAS host.
If necessary, copy the archive file that you created in Step 2 from the DAS host to the host where the instance resides.
From the host where the instance resides, import the instance's configuration data from the archive file that you created in Step 2.
Note - Only the options that are required to complete this task are provided in this step. For information about all the options for importing the configuration data, see the import-sync-bundle(1) help page.
```
$ asadmin import-sync-bundle [--node node-name] --instance instance-name archive-file 
```
node-name

The node on which the instance resides. If you omit this option, the subcommand determines the node from the DAS configuration in the archive file.

instance-name

The name of the instance that you are resynchronizing.

archive-file

The name of the file, including the path, that contains the archive file to import.

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.

$ asadmin --host dashost.example.com 
export-sync-bundle --retrieve=true --target ymlcluster
Command export-sync-bundle executed successfully.
$ asadmin import-sync-bundle --node sj01 
--instance yml-i1 ymlcluster-sync-bundle.zip 
Command import-sync-bundle executed successfully.

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

Skip Navigation Links
Exit Print View
	Oracle GlassFish Server 3.1-3.1.1 High Availability Administration Guide