Oracle GlassFish Server provides a server for developing and deploying Java Platform Enterprise Edition (Java EE) applications and web Java Web Services.
As an administrator ofGlassFish Server, 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:
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.1.2, the default administrator login is admin, with no password, which means that no login is required. For Oracle GlassFish Server, you are prompted to provide a password for the admin user when you start the domain for the first time.
Table 1-1 Default Administration Values
| Item | Default |
|---|---|
|
Domain Name |
|
|
Master Password |
|
|
Administration User |
|
|
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 |
| Item | Default |
|---|---|
|
Command-line Utility ( |
as-install |
|
Configuration Files |
domain-dir |
|
Log Files |
domain-dir |
|
Upgrade Tool ( |
as-install |
|
Update Tool and |
as-install-parent |
For information about replaceable items and default paths and files, see Default Paths and File Names.
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:
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:
The initial domain1 is created during installation. Additional configuration tasks might include such tasks as configuring additional domains or setting up automatic restart. See Administering Domains.
The initial tasks for configuring the JVM include creating JVM options and profilers. See Administering the Virtual Machine for the Java Platform.
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 Administering the Logging Service.
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 Administering the Monitoring Service.
System Security. Initial configuration tasks might include setting up passwords, audit modules, and certificates. See "Administering System Security" in Oracle GlassFish Server Security Guide.
User Security. Initial configuration tasks might include creating authentication realms and file users. See "Administering User Security" in Oracle GlassFish Server 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 "Administering Message Security" in Oracle GlassFish Server Security Guide.
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 Administering Database 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 Administering EIS 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 Administering Internet Connectivity.
An initial configuration task might involve creating an IIOP listener. See Administering the Object Request Broker (ORB).
An initial configuration task might involve creating a JavaMail resource. See Administering the JavaMail Service.
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 Administering the Java Message Service (JMS).
An initial configuration task might involve creating a JNDI resource. See 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.
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:
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
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
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
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 domain-dir/config.
Note:
GlassFish Server maintains a backup of the domain.xml file that is named domain.xml.bak. The purpose of this file is solely to enable GlassFish Server to start a domain if the domain.xml file cannot be read. Do not modify or delete the domain.xml.bak file and do not use this file for any other purpose.
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.
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.
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:
Ensure that the DAS is running.
To obtain information about the DAS or an instance, a running server is required.
Do one of the following:
To determine if the DAS requires restart, list the domains in your GlassFish Server installation.
Use the list-domains subcommand for this purpose.
asadmin> list-domains [--domaindir domain-root-dir]
The domain-root-dir is 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 subcommand for this purpose.
asadmin> list-instances instance-name
The instance-name is 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, or 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.
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
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 Security Guide
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
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.
Note:
If you do not know which applications use the changed resources or connection pools, you can apply these changes by restarting the clusters orGlassFish Server instances to which applications are deployed. However, to minimize the disruption to the services that your applications provide, avoid restarting clusters or instances to apply these changes if possible.
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
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:
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.example.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
If the Administration Console is run on a host different from the host where GlassFish Server was installed, a secure connection (https instead of http) is used. Some browsers do not display pages on secure connections by default and must be configured to permit secure protocols (SSL and TLS).
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 UtilityThe 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 Reference Manual.
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.
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.
The Update Tool graphical utility can either be run in the Administration Console, or invoked from the command line by using the updatetool command. You can use either tool to add components. However, to update or remove existing components, you must use the standalone version. Instructions for using the graphical versions of the Update Tool are contained in the Administration Console online help and the standalone Update Tool online help.
The pkg command is the command-line version of Update Tool. Instructions for using the pkg command with add-on components are contained in Extending and Updating GlassFish Server.
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 the Oracle GlassFish Server Upgrade Guide.
The OSGi module management subsystem that is provided with GlassFish Server is the Apache Felix OSGi framework. To administer this framework, use the either of the following tools:
Apache Felix Gogo remote shell. This shell is provided with GlassFish Server. The shell uses the Felix Gogo shell service to interact with the OSGi module management subsystem.
GlassFish OSGi Administration Console. This console is distributed as an add-on component for GlassFish Server or as a set of files from the Maven GlassFish repository. In both distributions, the GlassFish OSGi Web Console is provided as an extension to the Administration Console and as a standalone web application. The GlassFish OSGi Administration Console is a customized version of the Apache Felix Web Console.
These tools enable you to perform administrative tasks on OSGi bundles such as:
Browsing installed OSGi bundles
Viewing the headers of installed OSGi bundles
Installing OSGi bundles
Controlling the life cycle of installed bundles
By default, the Apache Felix Gogo remote shell in GlassFish Server is disabled. Before using the shell to administer OSGi bundles in GlassFish Server, you must enable the shell.
Enabling the Apache Felix Gogo remote shell in GlassFish Server involves changing the value of the property glassfish.osgi.start.level.final. This property controls whether the OSGi start level service enables the shell when the DAS or a GlassFish Server instance is started.
Ensure that the DAS is running.
Change the value of the glassfish.osgi.start.level.final property from 2 to 3.
If the domain includes clustered or standalone instances on remote hosts, perform this step on each remote host.
You can change this value either by creating a Java system property or by editing a file.
To change this value by creating a Java system property, create the Java system property glassfish.osgi.start.level.final with a value of 3.
asadmin> create-jvm-options --target target -Dglassfish.osgi.start.level.final=3
The target for which you are creating the property.
For the DAS, the target is server.
For a clustered or standalone instance, the target is the name of the instance.
To change this value by editing a file, edit the plain-text file as-install/config/osgi.properties to change the value of the glassfish.osgi.start.level.final property from 2 to 3.
Restart the DAS.
For instructions, see To Restart a Domain.
The Apache Felix Gogo remote shell listens on a port that allows access only from the loopback interface. The shell is available for the DAS or a GlassFish Server instance to telnet clients on the host where the DAS or instance is running.
Ensure that the DAS or the instance for which you want to start the shell is running.
Connect to the Apache Felix Gogo remote shell through the telnet service by using the telnet(1) command as follows:
telnet localhost felix-remote-shell-port
The port for connecting to the Apache Felix Gogo remote shell through the telnet service. The Apache Felix Gogo remote shell is preconfigured to use the following port s for this purpose:
For the DAS, the shell is preconfigured to use port 6666.
For an instance, the shell is preconfigured to use port 26666.
To see a list of the commands that are available in the Apache Felix Gogo remote shell, type help at the prompt for Apache Felix Gogo remote shell.
Example 1-3 Connecting to the Apache Felix Gogo Remote Shell
This example connects to the Apache Felix Gogo 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 '^]'. ____________________________ Welcome to Apache Felix Gogo g!
Example 1-4 Listing All Installed OSGi Bundles
This example runs the Felix Remote Shell Command lb without any arguments to list all installed OSGi bundles. For better readability, some bundles that would be listed by this example are not shown.
g! lb
START LEVEL 1
ID|State |Level|Name
0|Active | 0|System Bundle (3.0.8)
1|Active | 1|jaxb-api (2.2.2)
2|Active | 1|Metro Web Services API OSGi Bundle (2.1.0)
3|Active | 1|javax.annotation API v.1.1 (3.1.0)
4|Active | 1|HK2 OSGi Main Bundle (1.1.0)
5|Resolved | 1|Cluster SSH Provisioning (3.1.0)
6|Resolved | 1|woodstox (0.0.0)
7|Resolved | 1|Web container and GUI plug-in common classes (3.1.0)
8|Resolved | 1|javax.resource API v.1.6 (3.1.0)
9|Active | 1|GlassFish ha-shoal-cache-bootstrap (3.1.0)
10|Installed | 1|Admin Console JDBC Plugin (3.1.0)
...
248|Active | 1|GlassFish JPA Support (rfc #143) for OSGi Bundles (3.1.0)
249|Active | 1|GlassFish JDBC Support (rfc #122) for OSGi Bundles (3.1.0)
250|Active | 1|Apache Felix EventAdmin (1.2.8)
251|Active | 1|GlassFish EJB Container for OSGi Enabled EJB Applications
(3.1.0)
g!
Example 1-5 Determining 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 251 provides.
g! inspect service capability 251
GlassFish EJB Container for OSGi Enabled EJB Applications (251) provides services:
----------------------------------------------------------------------------------
objectClass = org.glassfish.osgijavaeebase.Extender
service.id = 68
----
objectClass = org.glassfish.osgijavaeebase.OSGiDeployer
service.id = 69
service.ranking = -2147483648
The GlassFish OSGi Web Console is distributed as follows:
As an add-on component for GlassFish Server
As a set of files from the GlassFish Maven repository
In both distributions, the GlassFish OSGi Web Console is provided as an extension to the Administration Console and as a standalone web application.
Perform one of the following sets of steps, depending on how you are obtaining the GlassFish OSGi Web Console.
If you are obtaining the console as an add-on component, install the GlassFish OSGi Admin Console component.
For information about tools for installing add-on components, see Extending and Updating GlassFish Server.
If you are obtaining the console from the Maven repository, download and unzip the required files.
Download the following files to the parent of the glassfish3 directory of your GlassFish Server installation.
Unzip the files that you downloaded.
The contents of the files are added to the as-install/modules/autostart directory of your GlassFish Server installation.
Restart the DAS.
For instructions, see To Restart a Domain.
After downloading and installing the GlassFish OSGi Web Console, you can access the console as explained in the following sections:
A tab for the GlassFish OSGi Web Console is provided for the DAS and for every GlassFish Server instance in a domain.
Ensure that the DAS and the instance for which you want to access the GlassFish OSGi Web Console are running.
Start the GlassFish Server Administration Console.
For instructions, see Administration Console.
Open the Administration Console page for the DAS or instance for which you are accessing the GlassFish OSGi Web Console.
For the DAS, in the navigation tree, select the server (Admin Server) node.
For a standalone instance, perform these steps:
In the navigation tree, expand the Standalone Instances node.
Under the Standalone Instances node, select the instance.
For a clustered instance, perform these steps:
In the navigation tree, expand the Clusters node.
Under the Clusters node, select the cluster that contains the instance.
The General Information page for the cluster opens.
In the General Information page for the cluster, click the Instances tab.
The Clustered Server Instances page for the cluster opens.
In the Server Instances table on the Clustered Server Instances page, select the instance.
On the Administration Console page for the DAS or instance, click the OSGi Console tab.
You are prompted for the user name and password of the administrative user of the GlassFish OSGi Web Console.
In response to the prompt, provide the user name and password of the administrative user of the GlassFish OSGi Web Console.
The user name and password of this user are both preset to admin.
The GlassFish OSGi Web Console page opens.
Ensure that the DAS or the instance for which you want to access the GlassFish OSGi Web Console is running.
In a web browser, open the following location:
http://host:http-port/osgi/system/console/
The host where the DAS or instance is running.
The port on which GlassFish Server listens for HTTP requests. The default is 8080.
For example, if the DAS is running on the local host and GlassFish Server listens for HTTP requests on the default port, open the following location:
http://localhost:8080/osgi/system/console/
When prompted, provide the user name and password of the administrative user of the GlassFish OSGi Web Console.
The user name and password of this user are both preset to admin.
keytool UtilityThe keytool utility is used to set up and work with Java Security Socket Extension (JSSE) digital certificates. See "Administering JSSE Certificates" in Oracle GlassFish Server Security Guide for instructions on using keytool.
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.
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:
UNIX: as-install/bin/asadmin
Windows: as-install\bin\asadmin
The following additional documents address specific administration areas:
Installing GlassFish Server software; updating add-on components using the Update Tool
Verifying and deploying applications
Diagnosing and resolving problems