Eclipse GlassFish Administration Guide, Release 7

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:

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 Eclipse GlassFish 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:

The bulk of the configuration information about Eclipse GlassFish 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 Eclipse GlassFish domain model. The default location for the domain.xml file is domain-dir/config.

The logging.properties file is used to configure the Java Util Logging system. 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 Eclipse GlassFish environment variables, such as the installation location of the database, Message Queue, and so on.

Some configuration changes require that you restart the DAS or Eclipse GlassFish 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. Eclipse GlassFish 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:

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 Eclipse GlassFish 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:

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

If the Administration Console is run on a host different from the host where Eclipse GlassFish 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 Eclipse GlassFish 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.

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:

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:

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

or

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

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

The OSGi module management subsystem that is provided with Eclipse GlassFish is the Apache Felix OSGi framework . To administer this framework, use the either of the following tools:

These tools enable you to perform administrative tasks on OSGi bundles such as:

The keytool utility is used to set up and work with Java Security Socket Extension (JSSE) digital certificates. See "Administering JSSE Certificates" in Eclipse GlassFish 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 Eclipse GlassFish environment, see Configuring JConsole to View Eclipse GlassFish Monitoring Data.

The asadmin utility is located in the as-install/bin directory. To run the asadmin utility without specifying the path, ensure that this directory is in your path.

The syntax for running the asadmin utility is as follows:

The replaceable items in this syntax are described in the subsections that follow. For full details of this syntax, see the asadmin(1M) help page.

In single mode, you must type a separate asadmin command for each subcommand that you want to use. After the subcommand has run, you are returned to the operating system’s command shell. Any asadmin utility options must be specified in each separate asadmin command that you run. If you require the same asadmin utility options for multiple subcommands, use the asadmin utility in multimode. For more information, see To Start a Multimode Session.

Example 2-1 Running an asadmin Utility Subcommand in Single Mode

This example runs the list-applications subcommand in single mode. In this example, the default values for all options are used.

The example shows that the application hello is deployed on the local host.

Example 2-2 Specifying an asadmin Utility Option With a Subcommand in Single Mode

This example specifies the --host asadmin utility option with the list-applications subcommand in single mode. In this example, the DAS is running on the host srvr1.example.com.

The example shows that the applications basic-ezcomp, scrumtoys, ejb31-war, and automatic-timer-ejb are deployed on the host srvr1.example.com.

Example 2-3 Specifying an asadmin Utility Option and a Subcommand Option in Single Mode

This example specifies the --host asadmin utility option and the --type subcommand option with the list-applications subcommand in single mode. In this example, the DAS is running on the host srvr1.example.com and applications of type web are to be listed.

Eclipse GlassFish provides help information about the syntax, purpose, and options of the asadmin utility and its subcommands. This help information is written in the style of UNIX platform man pages. This help information is also available in the Eclipse GlassFish Reference Manual.

Example 2-4 Displaying Help Information for the asadmin Utility

This example displays the help information for the asadmin utility.

Example 2-5 Displaying Help Information for an asadmin Utility Subcommand

This example displays the help information for the create-jdbc-resource subcommand.

See Also

To display the available subcommands, use the list-commands subcommand. Local subcommands are displayed before remote subcommands. If the server is not running, only local subcommands are displayed.

The asadmin utility can be used in multiple command mode, or multimode. In multimode, you run the asadmin utility once to start a multimode session. During the session, the asadmin utility continues to accept subcommands until you end the session and return to the operating system’s command shell. Any asadmin utility options that you set for your multimode session are used for all subsequent subcommands in the session.

Example 2-6 Starting a Multimode Session With asadmin Utility Options

This example starts a multimode session in which the asadmin utility options --user and --passwordfile are set for the session.

Example 2-7 Starting a Multimode Session by Using the multimode Subcommand

This example uses the multimode subcommand to start a multimode session in which the default asadmin utility options are used.

The asadmin> prompt is displayed on the command line.

Example 2-8 Running a Subcommand in a Multimode Session

This example starts a multimode session and runs the list-domains subcommand in the session.

Starting a Multimode Session From Within an Existing Multimode Session

You can start a multimode session from within an existing session by running the multimode subcommand from within the existing session. After you end the second multimode session, you return to your original multimode session.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help multimode at the command line.

At the asadmin> prompt, type one of the following commands or key combinations:

You are returned to the operating system’s command shell and the asadmin> prompt is no longer displayed. If the asadmin> prompt is still displayed, you might have opened a multimode session within a multimode session. In this situation, repeat this procedure to end the remaining multimode session.

Running a set of asadmin subcommands from a file enables you to automate repetitive tasks.

Example 2-9 Running a Set of asadmin Subcommands From a File

This example contains the following:

The commands_file.txt file contains the asadmin utility subcommands to perform the following sequence of operations:

The content of the commands_file.txt file is as follows:

This example runs the sequence of subcommands in the commands_file.txt file. Because the --portbase option is specified for the create-domain subcommand in the file, the --port asadmin utility option must also be set.

See Also

For more information about the subcommands in the preceding example, see the following help pages:

You can use the --detach option of the asadmin utility to detach asadmin subcommands and run them in the background in detach mode. The asadmin --detach option is useful for long-running subcommands and enables you to run several independent subcommands from one console or script.

Example 2-10 Using the --detach Option in Single Mode

This example uses the asadmin --detach option in single mode to run the create-cluster subcommand.

Example 2-11 Using the --detach Option in Multimode

This example uses the asadmin --detach option in multimode to run the create-cluster subcommand.

Job IDs are assigned to subcommands that are started using the asadmin --detach option or that contain progress information. You can use the list-jobs subcommand to list jobs and their job IDs, the attach subcommand to reattach to a job and view its status, and the configure-managed-jobs subcommand to configure how long information about jobs is kept.

Example 2-12 Listing Jobs

This example runs the list-jobs subcommand in multimode to list jobs and job information.

Example 2-13 Attaching to a Subcommand and Checking Its Status

This example runs the attach subcommand in multimode to attach to the create-cluster subcommand with a job ID of 1. If a subcommand is still in progress, the output displays the current status, such as percentage complete.

Example 2-14 Configuring Managed Jobs

This example runs the configure-managed-jobs subcommand in multimode to set the job retention period to 36 hours. Time periods can be specified in Hh|Mm|Ss for hours, minutes, or seconds.

See Also

For the full syntax and options of the subcommands in the preceding examples, see the following help pages:

Use the create-system-properties subcommand in remote mode to create or update one or more system properties of the domain or configuration. Any configuration attribute can be overwritten through a system property of the corresponding name.

Example 2-15 Creating a System Property

This example creates a system property associated with http-listener-port=1088 on localhost.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-system-properties at the command line.

Use the list-system-properties subcommand in remote mode to list the system properties that apply to a domain, cluster, or server instance or configuration.

Example 2-16 Listing System Properties

This example lists the system properties on host localhost.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-system-properties at the command line.

Use the delete-system-property subcommand in remote mode to delete system properties.

Example 2-17 Deleting a System Property

This example deletes a system property named http-listener-port from localhost.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-system-property at the command line.

Use the create-module-config subcommand to add the default configuration of a module to domain.xml.

Example 2-18 Adding Module Configuration to domain.xml

This example adds the default configuration of the web container module to domain1 in server-config (the default configuration). Use the --dryrun option to preview the configuration before it is added.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-module-config at the command line.

Use the delete-module-config subcommand to remove the configuration of a module from domain.xml and cause the module to use the default configuration included in the module.

Example 2-19 Removing Module Configuration From domain.xml

This example deletes the configuration of the web container module from domain1 in server-config (the default configuration).

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-module-config at the command line.

Use the get-active-module-config subcommand to display the current active configuration of a module.

Example 2-20 Displaying the Current Active Configuration of a Module

This example displays the current active configuration of the JMS service in server-config (the default configuration).

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help get-active-module-config at the command line.

Use the add-resources subcommand in remote mode to create the resources named in the specified XML file. The following resources are supported: JDBC connection pool and resource, JMS, JNDI, and Jakarta Mail resources, custom resource, connector resource and work security map, admin object, and resource adapter configuration.

The XML file must reside in the domain-dir/config directory. If you specify a relative path or simply provide the name of the XML file, this subcommand will prepend domain-dir/config to this operand.

Example 2-21 Adding Resources

This example creates resources using the contents of the resource.xml file on localhost.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help add-resources at the command line.

Use the version subcommand in remote mode to display information about the Eclipse GlassFish version for a particular server. If the subcommand cannot communicate with the server by using the specified login (user/password) and target (host/port) information, then the local version is displayed along with a warning message.

Example 2-22 Displaying Version Information

This example displays the version of Eclipse GlassFish on the local host.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help version at the command line.

Use the list-applications subcommand in remote mode to list the deployed Java applications. If the --type option is not specified, all applications are listed.

Example 2-23 Listing Applications

This example lists the web applications on localhost.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-applications at the command line.

Use the list-containers subcommand in remote mode to list application containers.

Example 2-24 Listing Containers

This example lists the containers on localhost.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-containers at the command line.

Use the list-modules subcommand in remote mode to list the modules that are accessible to the Eclipse GlassFish module subsystem. The status of each module is included. Possible statuses include NEW and READY.

Example 2-25 Listing Modules

This example lists the accessible modules.

Information similar to the following is displayed (partial output):

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-modules at the command line.

Use the list-commands subcommand in remote mode to list the deployed asadmin subcommands. You can specify that only remote subcommands or only local subcommands are listed. By default, this subcommand displays a list of local subcommands followed by a list of remote subcommands.

Example 2-26 Listing Subcommands

This example lists only local subcommands.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-commands at the command line.

The timer service is a persistent and transactional notification service that is provided by the enterprise bean container and is used to schedule notifications or events used by enterprise beans. All enterprise beans except stateful session beans can receive notifications from the timer service. Persistent timers set by the service are not destroyed when the server is shut down or restarted.

Use the list-timers subcommand in remote mode to list the persistent timers owned by a specific server instance. You can use this information to decide whether to do a timer migration, or to verify that a migration has been completed successfully.

Example 2-27 Listing Timers

This example lists the timers in a particular standalone server instance. There is one currently active timer set.

Use the show-component-status subcommand in remote mode to get the status (either enabled or disabled) of the specified deployed component.

Example 2-28 Showing Status of a Component

This example shows the status of the MEjbApp component.

Each object in the configuration and monitoring object trees is represented as a REST resource that is accessible through an HTTP uniform resource locator (URL). Access to REST resources for Eclipse GlassFish monitoring and configuration data requires a running DAS.

The Eclipse GlassFish REST interfaces support methods for accessing objects in the monitoring and configuration object trees.

The following table shows the REST methods for administering monitoring and configuration data and the tasks that you can perform with each method. These methods are HTTP 1.1 primitives. For the detailed specification of these primitives, see Hypertext Transfer Protocol — HTTP/1.1 .

Table 2-1 REST Resource Methods for Administering Monitoring and Configuration Data

The Eclipse GlassFish REST interfaces also support operations other than create, read, update, and delete (CRUD) operations, for example:

These operations are supported through REST resources that represent the asadmin subcommands for performing these operations. Each resource is a child of the resource on which the operation is performed. The child resources do not represent objects in the configuration object tree.

For example, the resource that represents a node provides child resources for the following asadmin subcommands that perform non-CRUD operations on the node:

The Eclipse GlassFish REST interfaces support the following authentication schemes for securing the REST interfaces:

When security is enabled, you must specify https as the protocol in the URLs to REST resources and provide a user name and password.

The Eclipse GlassFish REST interfaces represent resources for configuration objects in the following formats:

Eclipse GlassFish enables you to specify the resource representation through the filename extension in the URL or through the HTTP header:

The Eclipse GlassFish REST interfaces represent resources for monitoring data in the following formats:

The Eclipse GlassFish REST interfaces represent resources for log file details in the following formats:

The Eclipse GlassFish REST interfaces support the following types in the content-type header of a client request:

How to specify the type in the content-type header depends on how you are sending the request. For example, if you are using the cURL utility, specify the type through the -H option as follows:

A Eclipse GlassFish instance is a single Virtual Machine for the Java platform (Java Virtual Machine or JVM machine) on a single node in which Eclipse GlassFish is running. A node defines the host where the Eclipse GlassFish instance resides. The JVM machine must be compatible with the Java Platform, Enterprise Edition (Jakarta EE).

Eclipse GlassFish instances form the basis of an application deployment.

Whenever a domain is created, Eclipse GlassFish creates a default instance that is named server. If a single instance meets your requirements, you can use this instance for deploying applications without the need to administer Eclipse GlassFish instances explicitly. You administer the default instance when you administer its domain.

If you require multiple instances, you must administer the instances explicitly. For more information, see "Administering Eclipse GlassFish Instances" in Eclipse GlassFish High Availability Administration Guide.

For an instance, you can also create virtual servers. Virtual servers do not span instances. For many purposes, you can use virtual servers instead of multiple instances in operational deployments. Virtual servers enable you to offer, within a single instance, separate domain names, IP addresses, and some administration capabilities to organizations or individuals. To these users, a virtual server behaves like a dedicated web server, but without the hardware and basic web server maintenance.

For more information about virtual servers, see Administering Virtual Servers.

A domain is an administrative boundary that contains a group of Eclipse GlassFish instances that are administered together. Each instance can belong to only one domain. A domain provides a preconfigured runtime for user applications. Each domain has its own configuration data, log files, and application deployment areas that are independent of other domains. If the configuration is changed for one domain, the configurations of other domains are not affected.

Domains enable different organizations and administrators to share securely a single Eclipse GlassFish installation. Each organization or administrator can administer the instances in a single domain without affecting the instances in other domains.

At installation time, Eclipse GlassFish creates a default domain that is named domain1. After installation, you can create additional domains as necessary.

When a domain is created, you are prompted for the administration user name and password. If you accept the default, the user admin is created without password. To reset the administration password, see "To Change an Administration Password" in Eclipse GlassFish Security Guide.

The domain administration server (DAS) is a specially designated Eclipse GlassFish instance that hosts administrative applications. The DAS is similar to any other Eclipse GlassFish instance, except that the DAS has additional administration capabilities. The DAS authenticates the administrator, accepts requests from administration tools, and communicates with other instances in the domain to carry out the requests from administration tools.

Each domain has its own DAS with a unique administration port number. The default administration port is 4848, but a different port can be specified when a domain is created.

The DAS has the master copy of the configuration data for all instances in a domain. If an instance is destroyed, for example, because a host failed, the instance can be re-created from the data in the DAS.

The DAS is the default Eclipse GlassFish instance in a domain and is named server. If a single instance meets your requirements, you can use the DAS for deploying applications and for administering the domain.

The graphical Administration Console communicates with a specific DAS to administer the domain that is associated with the DAS. Each Administration Console session enables you to configure and manage only one domain. If you create multiple domains, you must start a separate Administration Console session to manage each domain.

After installing Eclipse GlassFish and creating the default domain (domain1), you can create additional domains by using the local create-domain subcommand. This subcommand creates the configuration of a domain. Any user who has access to the asadmin utility on a given system can create a domain and store the domain configuration in a folder of choice. By default, the domain configuration is created in the default directory for domains. You can override this location to store the configuration elsewhere.

You are required to specify an administrative user when you create a domain, or you can accept the default login identity which is username admin with no password.

Example 3-1 Creating a Domain

This example creates a domain named domain1 . When you type the command, you might be prompted for login information.

To start the Administration Console in a browser, enter the URL in the following format:

For this example, the domain’s log files, configuration files, and deployed applications now reside in the following directory:

domain-root-dir/mydomain

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-domain at the command line.

A custom template enables you to customize the configuration of any domain that you create from the template.