test

Oracle GlassFish Server 3.0.1 Administration Guide

Chapter 1 Overview of GlassFish Server Administration

Oracle GlassFish Server 3.0.1 provides an environment for developing and deploying Java applications and web services.

As an GlassFish Server administrator, your main responsibilities are to establish a secure GlassFish Server environment and to oversee the services, resources, and users that participate in that environment. Your key tasks include configuring resources and services, managing GlassFish Server at runtime, and fixing problems that are associated with the server. You might also be involved in installing software, integrating add-on components, and deploying applications.

The following topics are addressed here:

Default Settings and Locations

After installation, you might need to perform some immediate configuration tasks to make your installation function as intended. If configuration defaults have been accepted, some features are enabled and some not. For an overview of initial configuration tasks for GlassFish Server services and resources, see Initial Configuration Tasks.

In addition, you might want to reset default passwords, change names or locations of files, and so on. The following tables list the default administration values.

Note –

For the zip bundle of GlassFish Server 3.0.1, the default administrator login is admin, with no password, which means that no login is required.

Table 1–1 Default Administration Values

Item 

Default 

Domain Name 

domain1

Master Password 

changeit

Administration Password 

admin

Administration Server Port 

4848

HTTP Port 

8080

HTTPS Port 

8181

Pure JMX Clients Port 

8686

Message Queue Port 

7676

IIOP Port 

3700

IIOP/SSL Port 

3820

IIOP/SSL Port With Mutual Authentication 

3920

Table 1–2 Default Locations

Item 

Default 

Command-line Utility (asadmin)

as-install/bin

Configuration Files 

domain-dir/config

Log Files 

domain-dir/logs

Upgrade Tool (asupgrade Command)

as-install/bin

Update Tool and pkg Command

as-install-parent/bin

For information about replaceable items and default paths and files, see Default Paths and File Names.

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

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 9, Administering Life Cycle Modules.

Security
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 14, 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 15, 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 16, Administering Internet Connectivity.

Object Request Broker (ORB)

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

JavaMail Service

An initial configuration task might involve creating a JavaMail resource. See Chapter 18, 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 19, Administering the Java Message Service (JMS).

JNDI Service

An initial configuration task might involve creating a JNDI resource. See Chapter 20, 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.

Note –

Dotted names also apply to monitoring, but the method is different. For information on using dotted names for monitoring, see How the Monitoring Tree Structure Works.

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 server 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. Default location for the domain.xml file is as-install/glassfish3/glassfish/domains/domain-name/config. For details on the domain.xml file, see Oracle GlassFish Server 3.0.1 Domain File Format Reference.

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

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

Note –

Changes are automatically applied to the appropriate configuration file. Do not edit the configuration files directly. Manual editing is prone to error and can have unexpected results.

Impact of Configuration Changes

Configuration changes often require that you restart GlassFish Server for the changes to take effect. In other cases, changes are applied dynamically without requiring that GlassFish Server be restarted. The procedures in this guide indicate when you need to restart the server.

Configuration Changes That Require Server Restart

When making any of the following configuration changes, you must restart the server for the changes to take effect:

Dynamic Configuration Changes

With dynamic configuration, changes take effect while the server is running. To make the following configuration changes, you do not need to restart the server:

Administration Tools

For the most part, you can perform the same tasks by using either the graphical Administration Console or the asadmin command-line utility, however, there are exceptions.

The following GlassFish Server administration tools are described here:

Administration Console

The Administration Console is a browser-based utility that features an easy-to-navigate graphical interface that includes extensive online help for the administrative tasks.

To use the Administration Console, the domain administration server (DAS) must be running. Each domain has its own DAS, which has a unique port number. When GlassFish Server was installed, you chose a port number for the DAS, or used the default port of 4848. You also specified a user name and password if you did not accept the default login (admin with no password).

When specifying the URL for the Administration Console, use the port number for the domain to be administered. The format for starting the Administration Console in a web browser is http://hostname:port. For example:


http://kindness.sun.com:4848

If the Administration Console is running on the host where GlassFish Server was installed, specify localhost for the host name. For example:


http://localhost:4848

For Microsoft Windows, an alternate way to start the GlassFish Server Administration Console is by using the Start menu.

You can display the help material for a page in the Administration Console by clicking the Help button on the page. The initial help page describes the functions and fields of the page itself. Associated task instructions can be accessed on additional pages by clicking a link in the See Also list.

asadmin Utility

The asadmin utility is a command-line tool that runs subcommands for identifying the operation or task that you want to perform. You can run asadmin subcommands either from a command prompt or from a script. Running asadmin subcommands from a script is helpful for automating repetitive tasks. Basic information about how the asadmin utility works can be found in the asadmin(1M) help page. For instructions on using the asadmin utility, see Using the asadmin Utility.

To issue an asadmin subcommand in the standard command shell (single mode), go to the as-install/bin directory and type the asadmin command followed by a subcommand. For example:


asadmin list-jdbc-resources

You can invoke multiple command mode (multimode) by typing asadmin at the command prompt, after which the asadmin> prompt is presented. The asadmin utility continues to accept subcommands until you exit multimode and return to the standard command shell. For example:


asadmin> list-jdbc-resources

You can display a help page for any asadmin subcommand by typing help before the subcommand name. For example:


asadmin> help restart-domain

or


asadmin help restart-domain

A collection of the asadmin help pages is available in HTML and PDF format in the Oracle GlassFish Server 3.0.1 Reference Manual.

REST Interfaces

GlassFish Server provides representational state transfer (REST) interfaces to enable you to access monitoring and configuration data for GlassFish Server, including data that is provided by newly installed add-on components. For more information, see Using REST Interfaces to Administer GlassFish Server.

Update Tool

GlassFish Server provides a set of image packaging system (IPS) tools for updating software on a deployed GlassFish Server. Typical updates include new releases of GlassFish Server, and new or revised releases of GlassFish Server add-on components or modules.

Two distributions are supported for GlassFish Server: the Web Profile and the Full Platform. After installation, you can view the modules on your system by using the graphical Update Tool or the pkg command.

Note –

If you chose the Web Profile, you can change to the Full Platform by selecting the comparable Full Platform package in Update Tool. All dependent modules are automatically added.

You can add and delete individual modules from a distribution, but such configurations are not supported.

If you need information on upgrading your domain configuration data to work with a new version of GlassFish Server, see Oracle GlassFish Server 3.0.1 Upgrade Guide.

OSGi Module Management Subsystem

The OSGi module management subsystem that is provided with GlassFish Server is the Apache Felix OSGi framework. To enable you to administer this framework, the Apache Felix Remote Shell is enabled by default in GlassFish Server. This shell uses the Felix shell service to interact with the OSGi module management subsystem, and enables you to perform administrative tasks such as:

The Apache Felix Remote Shell is accessible to telnet clients from anywhere in the network. To connect to the Apache Felix Remote Shell through the telnet service, use the telnet(1) command as follows:


telnet host felix-remote-shell-port
host

The host where the DAS is running.

felix-remote-shell-port

The port for connecting to the Apache Felix Remote Shell through the telnet service. GlassFish Server is preconfigured to use port 6666 for this purpose.

To see a list of the commands that are available in the Apache Felix Remote Shell, type help at the Apache Felix Remote Shell prompt.

To exit the Apache Felix Remote Shell, type exit at the Apache Felix Remote Shell prompt.

Example 1–1 Connecting to the Apache Felix Remote Shell

This example connects to the Apache Felix Remote Shell for a domain that is running on the local host and that uses the preconfigured port for connecting to this shell through the telnet service.


telnet localhost 6666

After the connection is established, the following information is displayed:


Connected to localhost.
Escape character is '^]'.

Felix Remote Shell Console:
============================

->
Example 1–2 Listing All Installed OSGi Bundles

This example runs the Felix Remote Shell Command ps without any arguments to list all installed OSGi bundles. For better readability, some bundles that would be listed by this example are not shown.


-> ps
START LEVEL 1
   ID   State         Level  Name
[   0] [Active     ] [    0] System Bundle (2.0.2)
[   1] [Active     ] [    1] HK2 OSGi Main Bundle (1.0.0)
[   2] [Installed  ] [    1] AMX V3 Core (3.0.0.SNAPSHOT)
[   3] [Active     ] [    1] GlassFish Rest Interface (3.0.0.SNAPSHOT)
...
[ 217] [Installed  ] [    1] Admin Console JDBC Plugin (3.0.0.SNAPSHOT)
[ 218] [Resolved   ] [    1] stats77 (3.0.0.SNAPSHOT)
[ 219] [Active     ] [    1] Apache Felix Declarative Services (1.0.8)
[ 220] [Active     ] [    1] GlassFish Web Container (rfc #66) for OSGi Enabled 
Web Applications (3.0.0.SNAPSHOT)
->
Example 1–3 Finding an OSGi Bundle With a Specified Name

This example runs the Felix Remote Shell Command find to find all OSGi bundles whose names contain the text rfc.


-> find rfc
START LEVEL 1
   ID   State         Level  Name
[ 220] [Active     ] [    1] GlassFish Web Container (rfc #66) for OSGi Enabled 
Web Applications (3.0.0.SNAPSHOT)
->
Example 1–4 To Determine the Services That an OSGi Bundle Provides

This example runs the Felix Remote Shell Command inspect with the service option and the capability option to determine the services that OSGi bundle 220 provides.


-> inspect service capability 220 
GlassFish Web Container (rfc #66) for OSGi Enabled Web Applications (220) provides services:
--------------------------------------------------------------------------------------------
objectClass = org.glassfish.osgiweb.Extender
service.id = 30
----
objectClass = org.osgi.service.url.URLStreamHandlerService
service.id = 31
url.handler.protocol = webbundle
->

keytool Utility

The keytool utility is used to set up and work with Java Security Socket Extension (JSSE) digital certificates. See Administering JSSE Certificates for instructions on using keytool.

Java Monitoring and Management Console (JConsole)

Java SE provides tools to connect to an MBean server and view the MBeans that are registered with the server. JConsole is one such popular JMX Connector Client and is available as part of the standard Java SE distribution. For instructions on implementing JConsole in the GlassFish Server environment, see Configuring JConsole to View GlassFish Server Monitoring Data.

Application Server Management Extension (AMX)

The application server management eXtension (AMX) API exposes all of the GlassFish Server configuration and monitoring JMX managed beans as easy-to-use client-side dynamic proxies implementing the AMX interfaces.

Instructions for Administering GlassFish Server

Information and instructions on performing most of the administration tasks from the command line are provided in this document and in the asadmin utility help pages. For instructions on accessing asadmin online help, see To Display Help Information for the asadmin Utility or a Subcommand).

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

Note –

Instructions written for the GlassFish Server tools use standard UNIX® forward slashes (/) for directory path separators in commands and file names. If you are running GlassFish Server on a Microsoft Windows system, use backslashes (\) instead. For example:

The following additional documents address specific administration areas: