Configuration Tasks

Some configuration tasks must be performed directly after installation for your GlassFish Server environment to work as intended. For example, if you are using a database with GlassFish Server, you need to set up database connectivity right away.

Some configuration situations are ongoing and will require you to make changes many times during the life of your installation. You can use either the Administration Console or the asadmin utility to modify the configuration. Changes are automatically applied to the appropriate configuration file.

The following topics are addressed here:

• Initial Configuration Tasks

• How Dotted Names Work for Configuration

• Configuration Files

• Impact of Configuration Changes

Initial Configuration Tasks

This section maps the common configuration tasks to the command–line procedures in this guide. In some situations, the resource or service is automatically enabled and your configuration tasks involve adjusting or changing the default settings to suit your specific needs.

The following resources and services frequently require configuration immediately after installation:

System Properties

See Administering System Properties.

Domains

The initial domain1 is created during installation. Additional configuration tasks might include such tasks as configuring additional domains or setting up automatic restart. See Chapter 3, Administering Domains.

JVM

The initial tasks for configuring the JVM include creating JVM options and profilers. See Chapter 4, Administering the Virtual Machine for the Java Platform.

Logging

By default, logging is enabled, so basic logging works without additional configuration. However, you might want to change log levels, property values, or the location of log files. See Chapter 7, Administering the Logging Service.

Monitoring

By default, the monitoring service is enabled. However, monitoring for the individual modules is not enabled, so your first monitoring task is to enable monitoring for the modules that you want to monitor. See Chapter 8, Administering the Monitoring Service.

Life Cycle Modules

See Chapter 10, Administering Life Cycle Modules.

Security

• System Security. Initial configuration tasks might include setting up passwords, audit modules, and certificates. See Chapter 1, Administering System Security, in Oracle GlassFish Server 3.1 Security Guide.

• User Security. Initial configuration tasks might include creating authentication realms and file users. See Chapter 2, Administering User Security, in Oracle GlassFish Server 3.1 Security Guide.

• Message Security. Initial configuration tasks might include configuring a Java Cryptography Extension (JCE) provider, enabling default and non-default security providers, and configuring message protection policies. See Chapter 3, Administering Message Security, in Oracle GlassFish Server 3.1 Security Guide.

Database Connectivity

The initial tasks involved in configuring GlassFish Server to connect to the Java DB database include creating a Java Database Connectivity (JDBC) connection pool, creating a JDBC resource, and integrating a JDBC driver. See Chapter 12, Administering Database Connectivity.

EIS Connectivity

The initial tasks involved in configuring GlassFish Server to connect to an enterprise information system (EIS) include creating a connector connection pool, creating a connector resource, editing a resource adapter configuration, creating a connector security map, creating a connector work security map, and creating an administered object (if needed). See Chapter 13, Administering EIS Connectivity.

Internet Connectivity

The initial tasks involved in making deployed web applications accessible by internet clients include creating HTTP network listeners and virtual servers, and configuring the HTTP listeners for SSL (if needed). See Chapter 14, Administering Internet Connectivity.

Object Request Broker (ORB)

An initial configuration task might involve creating an IIOP listener. See Chapter 15, Administering the Object Request Broker (ORB).

JavaMail Service

An initial configuration task might involve creating a JavaMail resource. See Chapter 16, Administering the JavaMail Service.

Java Message Service (JMS)

Initial configuration tasks might include creating a physical destination, creating connection factories or destination resources, creating a JMS host (if the default JMS host is not adequate), adjusting connection pool settings (if needed), and configuring resource adapters for JMS. See Chapter 17, Administering the Java Message Service (JMS).

JNDI Service

An initial configuration task might involve creating a JNDI resource. See Chapter 18, Administering the Java Naming and Directory Interface (JNDI) Service.

Information and instructions for accomplishing the tasks by using the Administration Console are contained in the Administration Console online help.

How Dotted Names Work for Configuration

After the initial configuration is working, you will continue to manage ongoing configuration for the life of your GlassFish Server installation. You might need to adjust resources to improve productivity, or issues might arise that require settings to be modified or defaults to be reset. In some situations, an asadmin subcommand is provided for updating, such as the update-connector-work-security-map subcommand. However, most updating is done by using the list, get, and set subcommands with dotted names. For detailed information about dotted names, see the dotted-names(5ASC) help page.

The general process for working with configuration changes on the command line is as follows:

1. List the modules for the component of interest.

   The following single mode example uses the | (pipe) character and the grep command to narrow the search:

   asadmin list "*" | grep http | grep listener

   Information similar to the following is returned:

   configs.config.server-config.network-config.network-listeners.network-listener.http-listener-1
   configs.config.server-config.network-config.network-listeners.network-listener.http-listener-2
   configs.config.server-config.network-config.protocols.protocol.admin-listener.http
   configs.config.server-config.network-config.protocols.protocol.admin-listener.http.file-cache
   configs.config.server-config.network-config.protocols.protocol.http-listener-1
   configs.config.server-config.network-config.protocols.protocol.http-listener-1.http
   configs.config.server-config.network-config.protocols.protocol.http-listener-1.http.file-cache
   configs.config.server-config.network-config.protocols.protocol.http-listener-2
   configs.config.server-config.network-config.protocols.protocol.http-listener-2.http
   configs.config.server-config.network-config.protocols.protocol.http-listener-2.http.file-cache
   configs.config.server-config.network-config.protocols.protocol.http-listener-2.ssl

2. Get the attributes that apply to the module you are interested in.

   The following multimode example gets the attributes and values for http-listener-1:

   asadmin> get server-config.network-config.network-listeners.network-listener.http-listener-1.* 

   Information similar to the following is returned:

   server.http-service.http-listener.http-listener-1.acceptor-threads = 1
   server.http-service.http-listener.http-listener-1.address = 0.0.0.0
   server.http-service.http-listener.http-listener-1.blocking-enabled = false
   server.http-service.http-listener.http-listener-1.default-virtual-server = server
   server.http-service.http-listener.http-listener-1.enabled = true
   server.http-service.http-listener.http-listener-1.external-port =
   server.http-service.http-listener.http-listener-1.family = inet
   server.http-service.http-listener.http-listener-1.id = http-listener-1
   server.http-service.http-listener.http-listener-1.port = 8080
   server.http-service.http-listener.http-listener-1.redirect-port =
   server.http-service.http-listener.http-listener-1.security-enabled = false
   server.http-service.http-listener.http-listener-1.server-name =
   server.http-service.http-listener.http-listener-1.xpowered-by = true

3. Modify an attribute by using the set subcommand.

   This example sets the security-enabled attribute of http-listener-1 to true:

   asadmin> set server.http-service.http-listener.http-listener-1.security-enabled = true

Configuration Files

The bulk of the configuration information about GlassFish Server resources, applications, and instances is stored in the domain.xml configuration file. This file is the central repository for a given administrative domain and contains an XML representation of the GlassFish Server domain model. The default location for the domain.xml file is as-install/domains/domain-name/config.

The logging.properties file is used to configure logging levels for individual modules. The default logging.properties file is located in the same directory as the domain.xml file. For further information on the logging.properties file, see Logging Properties.

The asenv.conf file is located in the as-install/config directory. Its purpose is to store the GlassFish Server environment variables, such as the installation location of the database, Message Queue, and so on.

Impact of Configuration Changes

Some configuration changes require that you restart the DAS or GlassFish Server instances for the changes to take effect. Other changes are applied dynamically without requiring that the DAS or instances be restarted. The procedures in this guide indicate when a restart is required. GlassFish Server enables you to determine whether the DAS or an instance must be restarted to apply configuration changes.

Some changes to resources or connection pools affect the applications that use the resources or connection pools. These changes do not require restart. However, any applications that use the resources or connection pools must be disabled and re-enabled or redeployed for the change to take effect.

The following topics are addressed here:

• To Determine Whether the DAS or an Instance Requires Restart

• Configuration Changes That Require Restart

• Dynamic Configuration Changes

• Changes That Affect Applications

To Determine Whether the DAS or an Instance Requires Restart

1. Ensure that the DAS is running.

   To obtain information about the DAS or an instance, a running server is required.

2. Do one of the following:
   • To determine if the DAS requires restart, list the domains in your GlassFish Server installation.

     Use the list-domains(1) subcommand for this purpose.

     asadmin> list-domains [--domaindir domain-dir]

     domain-dir

     The directory that contains the directories in which individual domains' configuration is stored. The default is as-install/domains, where as-install is the base installation directory of the GlassFish Server software.

     If the DAS requires restart, a statement that restart is required is displayed.

   • To determine if an instance requires restart, list information about the instance.

     Use the list-instances(1) subcommand for this purpose.

     asadmin> list-instances instance-name

     instance-name

     The name of the instance for which you are listing information.

     If the instance requires restart, one of the following pieces of information is displayed:

     • A statement that restart is required

     • A list of configuration changes that are not yet applied to the instance

Example 1-1 Determining if the DAS Requires Restart

This example determines that the DAS for the domain domain1 requires restart to apply configuration changes.

asadmin> list-domains
domain1 running, restart required to apply configuration changes
Command list-domains executed successfully.

Example 1-2 Determining if an Instance Requires Restart

This example determines that the instance pmd-i1 requires restart to apply configuration changes.

asadmin> list-instances pmd-i1
pmd-i1   running;  requires restart  
Command list-instances executed successfully.

See Also

• list-domains(1)

• list-instances(1)

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

• asadmin help list-domains

• asadmin help list-instances

Configuration Changes That Require Restart

The following configuration changes require restart for the changes to take effect:

• Changing JVM options

• Changing port numbers

  ---

  Note - Changes to some port numbers, for example HTTP listener ports, do not require restart.

  ---

• Changing log handler elements

• Configuring certificates

• Managing HTTP, JMS, IIOP, JNDI services

• Enabling or disabling secure administration as explained in Running Secure Admin in Oracle GlassFish Server 3.1 Security Guide

Dynamic Configuration Changes

With dynamic configuration, changes take effect while the DAS or instance is running. The following configuration changes do not require restart:

• Adding or deleting add-on components

• Adding or removing JDBC, JMS, and connector resources and pools (Exception: Some connection pool properties affect applications.)

• Changing a system property that is not referenced by a JVM option or a port

• Adding file realm users

• Changing logging levels

• Enabling and disabling monitoring

• Changing monitoring levels for modules

• Enabling and disabling resources and applications

• Deploying, undeploying, and redeploying applications

Changes That Affect Applications

Some changes to resources or connection pools affect the applications that use the resources or connection pools. These changes do not require restart. However, any applications that use the resources or connection pools must be disabled and re-enabled or redeployed for the change to take effect.

The following changes affect applications:

• Creating or deleting resources (Exception: Changes to some JDBC, JMS, or connector resources do not affect applications.)

• Modifying the following JDBC connection pool properties:

  • datasource-classname

  • associate-with-thread

  • lazy-connection-association

  • lazy-connection-enlistment

  • JDBC driver vendor-specific properties

• Modifying the following connector connection pool properties:

  • resource-adapter-name

  • connection-definition-name

  • transaction-support

  • associate-with-thread

  • lazy-connection-association

  • lazy-connection-enlistment

  • Vendor-specific properties