Chapter 1 Enterprise Server Overview

Sun GlassFish Enterprise Server administration includes many tasks such as deploying applications, creating and configuring domains, server instances and resources; controlling (starting and stopping) domains and server instances, managing profiles and clusters, monitoring and managing performance, and diagnosing and troubleshooting problems.

Enterprise Server provides a Java EE compatible server for the development and deployment of Java EE applications and Java Web Services. Key features include scalable transaction management, container-managed persistence runtime, performant web services, clustering, high availability, security, and integration capabilities.

Enterprise Server Overview and Concepts

This section contains the following topics:

• Enterprise Server Overview

• Tools for Administration

Enterprise Server Overview

You can configure and monitor Enterprise Server instances and clusters securely and remotely, from a web-based central administration console. The command line interface (CLI) can be used to script and automate processes. A stable JMX API is made available to programmatically monitor the server, query configuration and change configuration data. Monitoring is supported through JMX and SNMP interfaces. Monitoring level may be varied dynamically from OFF to LOW and high, changing the amount of information that is collected.

You can configure and optimize Enterprise Server for a particular type of use by specifying the appropriate profile when you create the application server domain.

Enterprise Server includes the Metro web services stack (http://metro.dev.java.net). Metro implements important WS-* standards and WS-I standardized interoperability profiles in order to assure interoperability between Java and .NET web services.

Enterprise Server includes the implementation of Java Business Integration (JBI) specifications. JBI is a Java standard for structuring business systems according to a Service-Oriented Architecture (SOA).

Tools for Administration

The Enterprise Server provides the following administration tools and APIs:

• Admin Console

• Command-line Interface (asadmin Utility)

• JConsole

Admin Console

The Admin Console is a browser-based tool that features an easy-to-navigate interface and online help. The administration server (also called the Domain Administration Server or DAS) must be running to use the Admin Console. To, launch the Administration Console, you must know the administration server hostname and port number. When the Enterprise Server was installed, you chose a port number for the server, or used the default port of 4848. You also specified a user name and master password.

To start the Admin Console, in a web browser type:

http://hostname:port

For example:

http://kindness.sun.com:4848

If the Admin Console is running on the machine on which the Enterprise Server was installed, specify localhost for the host name.

On Windows, start the Enterprise Server Admin Console from the Start menu.

The installation program creates the default administrative domain (named domain1) with the default port number 4848, as well as an instance separate from the domain administration server (DAS). After installation, additional administration domains can be created. Each domain has its own domain administration server, which has a unique port number. When specifying the URL for the Admin Console, be sure to use the port number for the domain to be administered.

If your configuration includes remote server instances, create node agents to manage and facilitate remote server instances. It is the responsibility of the node agent to create, start, stop, and delete a server instance. Use the command line interface (CLI) commands to set up node agents.

Command-line Interface (asadmin Utility)

The asadmin utility is a command-line interface for the Sun GlassFish Enterprise Server. Use the asadmin utility and the commands associated with it to perform the same set of administrative tasks offered by the Admin Console. The default installation root directory on Solaris is /opt/SUNWappserver.

To start the asadmin utility, go to the as-install/bin directory and enter:

$ ./asadmin

To list the commands available within asadmin:

asadmin> help

It is also possible to issue an asadmin command at the shell’s command prompt:

$ asadmin help

To view a command’s syntax and examples, type help followed by the command name. For example:

asadmin> help create-jdbc-resource

The asadmin help information for a given command displays the UNIX man page of the command. These man pages are also available in HTML and PDF format in the Sun GlassFish Enterprise Server 2.1.1 Reference Manual.

JConsole

JConsole is used to monitor the Sun GlassFish Enterprise Server. You can use either the JConsole remote tab, or the advanced tab to connect to the Enterprise Server.

• Remote Tab: identify the username, password, administration server host, and JMS port number (8686 by default), and select Connect.

• Advanced Tab: identify the JMXServiceURL as service:jmx:rmi:///jndi/rmi://host:jms-port/jmxrmi and select Connect. The JMXServerURL is printed in the server.log file as well as output in the command window of the domain creation command.

Enterprise Server Concepts

The Enterprise Server consists of one or more domains. A domain is an administrative boundary or context. Each domain has an administration server (also called Domain Administration Server or DAS) associated with it and consists of zero or more standalone instances and/or clusters. Each cluster has one or more homogeneous server instances. A server instance is a single Java Virtual Machine (JVM) that runs the Application Server on a single physical machine. Server instances (whether standalone or clustered) in a domain can run on different physical hosts.

This section contains the following topics:

• Domain

• Domain Administration Server (DAS)

• Usage Profiles

• Cluster

• Node Agent

• Server Instance

Domain

A domain is a group of instances that are administered together. However, an application server instance can belong to just one domain. In addition to the administration boundary, a domain provides the basic security structure whereby different administrators can administer specific groups (domains) of application server instances. By grouping the server instances into separate domains, different organizations and administrators can share a single Enterprise Server installation. Each domain has its own configuration, 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.

The Sun GlassFish Enterprise Server installer creates the default administrative domain (named domain1). It also creates an associated domain administration server (named server). You must provide the administration server port number. The default administration server port is 4848. The installer also queries for the administration username and master password. After installation, additional administration domains can be created.

Domain Administration Server (DAS)

Each domain has its own Domain Administration Server (DAS) with a unique port number. The Admin Console communicates with a specific DAS to administer the associated domain. Each Admin Console session allows you to configure and manage the specific domain.

The Domain Administration Server (DAS), is a specially-designated application server instance that hosts the administrative applications. The DAS authenticates the administrator, accepts requests from administration tools, and communicates with server instances in the domain to carry out the requests. The DAS is sometimes referred to as the admin server or default server. It is referred to as the default server because it is the only server instance that gets created on Sun GlassFish Enterprise Server installation and can be used for deployments. The DAS is simply a server instance with additional administration capabilities.

Each Admin Console session allows you to configure and manage a single domain. If you created multiple domains, you must start an additional Admin Console session to manage the other domains. When specifying the URL for the Admin Console, be sure to use the port number of the DAS associated with the domain to be administered.

Usage Profiles

Every administrative domain is associated with a usage profile, which identifies the capabilities of that domain. Enterprise Server provides the following profiles:

• Developer: Use this profile if you are running your domain in a development environment and if your applications do not need the NSS keystore or clustering features, such as load balancing, and session persistence.

• Cluster: Use this profile if you need to create clusters but do not require the high-availability database (HADB) or the NSS keystore.

  ---

  Note –

  In the cluster and developer profile, the DAS is set to be in non-secure mode, by default. While running asadmin commands, use --secure=false, wherever required. Do not use this flag if you have made changes to set DAS to secure mode.

  ---

• Enterprise:: Use this profile if you need HADB and NSS. This profile is usable only if you install HADB and NSS separately or if you install Enterprise Server as part of enterprise offerings, such as Java Enterprise System (JES). For information on how you can use the enterprise profile with Enterprise Server, see Using the Enterprise Profile

The domain provides a preconfigured runtime for the user applications. Usage profiles facilitates the distinction between the Application Server binaries and the runtime configuration. Profiles enable you to use the same installation of Enterprise Server to create different domains with profiles that suit specific needs. For example, a developer may want to use the Enterprise Server to get to know the latest Java EE specifications. This developer does not need stringent security settings. Another user who wants to deploy applications in a production environment needs an inherently secure environment.

Table 1–1 lists the features available with each profile:

Cluster

A cluster is a named collection of server instances sharing the same set of applications, resources, and configuration information. A server instance can belong to exactly one cluster. A cluster facilitates server instance load-balancing through distribution of a load across multiple machines. A cluster facilitates high availability through instance-level failover. From an administrative perspective, a cluster represents a virtualized entity in which operations on a cluster (e.g. deployment of an application) act on all instances that make up the cluster.

Horizontal scaling is achieved by adding Enterprise Server instances to a cluster, thereby increasing the capacity of the system. It is possible to add Enterprise Server instances to a cluster without disrupting service. The HTTP, RMI/IIOP, and JMS load balancing systems distribute requests to healthy Enterprise Server instances in the cluster.

High Availability - Availability allows for failover protection of Enterprise Server instances in a cluster. If one application server instance goes down, another Enterprise Server instance takes over the sessions that were assigned to the unavailable server. Session information is stored using the session replication feature or by using the high-availability database (HADB). HADB supports the persistence of HTTP sessions and stateful session beans.

Node Agent

A lightweight agent (e.g. hosting a JMX runtime only) is required on each node in the domain to facilitate remote lifecycle management of instances. Its primary purpose is to start, stop, and create server instances as instructed by the DAS. The Node Agent also acts as a watchdog and restarts failed processes. Like the DAS, the Node Agent should only be required for certain administrative operations and should not be expected to be highly available. However, the Node Agent is an “always on” component, and must be configured to be started by the native O/S node bootstrap (e.g. Solaris/Linux inetd, or as a Windows service). A Node Agent is not required for the DAS.

Server Instance

The server instance is a single Java EE compatible Java Virtual Machine hosting an Enterprise Server on a single node. Each server instance has a unique name in the domain. A clustered server instance is a member of a cluster and receives all of its applications, resources, and configuration from its parent cluster; ensuring that all instances in the cluster are homogeneous. An unclustered server instance does not belong to a cluster and as such has an independent set of applications, resources, and configuration. The following figure shows an application server instance in detail. The application server instance is a building block in the clustering, load balancing, and session persistence features of the Enterprise Server.

Figure 1–1 Enterprise Server Instance

The Sun GlassFish Enterprise Server creates one application server instance, called server, at the time of installation. For many users, one application server instance meets their needs. However, depending upon your environment, you might want to create one or more additional application server instances. For example, in a development environment you can use different application server instances to test different Enterprise Server configurations, or to compare and test different application deployments. Because you can easily add or delete an application server instance, you can use them to create temporary sandbox area for experimentation purposes.

In addition, for each application server instance, you can also create virtual servers. Within a single installed application server instance you can offer companies or individuals domain names, IP Addresses, and some administration capabilities. For the users, it is almost as if they have their own web server, without the hardware and basic server maintenance. These virtual servers do not span application server instances. For more information about virtual servers, see Chapter 13, Configuring the HTTP Service.

In operational deployments, for many purposes you can use virtual servers instead of multiple application server instances. However, if virtual servers do not meet your needs, you can also use multiple application server instances. On stopping, application server instance stops accepting new connections, then waits for all outstanding connections to complete. If your machine crashes or is taken offline, the server quits and any requests it was servicing may be lost.

Ports in the Enterprise Server

The following table describes the port listeners of the Enterprise Server.

Basic Enterprise Server Commands

Administration of the Enterprise Server includes tasks such as creation, configuration, control and management of domains, clusters, node agents, and server instances. This section contains the following topics:

• Creating a Domain

• Deleting a Domain

• Listing Domains

• Starting the Domain

• Starting the Default Domain on Windows

• Stopping the Domain

• Stopping the Default Domain on Windows

• Restarting the Domain

• Creating a Cluster

• Starting a Cluster

• Stopping a Cluster

• Creating a Node Agent

• Starting a Node Agent

• Stopping a Node Agent

• Starting an Instance

• Stopping an Instance

• Restarting an Instance

• Recreating the Domain Administration Server

Creating a Domain

Domains are created using the create-domain command. The following example command creates a domain named mydomain. The administration server listens on port 5000 and the administrative user name is admin. The command prompts for the administrative and master passwords.

$ asadmin create-domain --adminport 5000 --adminuser admin mydomain

To start the Admin Console for mydomain domain, in a browser, enter the following URL:

http://hostname:5000

In Enterprise Server 9.1, every domain has a profile associated with it. For information on profiles, see Usage Profiles. You can choose the profile of a domain only during creation. Use the --profile option with the create-domain command to specify a profile for the domain. If you do not use the --profile option to explicitly specify a profile, the default profile is associated with the domain. The AS_ADMIN_PROFILE variable in the asadminenv.conf file defines the default profile.

Do not create an enterprise domain unless you have HADB and the Network Security Services (NSS) keystore. You will not be able to start an enterprise domain unless you have HADB and NSS.

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

domain-root-dir/mydomain

To create the domain’s directory in another location, specify the --domaindir option. For the full syntax of the command, type asadmin help create-domain or the create-domain(1).

Deleting a Domain

Domains are deleted using the asadmin delete-domain command. Only the operating system user (or root) who can administer the domain can execute this command successfully. To delete a domain named mydomain, for example, type the following command:

$ asadmin delete-domain mydomain

Listing Domains

The domains created on a machine can be found using the asadmin list-domains command. To list the domains in the default domain-root-dir directory, type this command:

$ asadmin list-domains

To list domains that were created in other directories, specify the --domaindir option.

Starting the Domain

When starting a domain, the administration server and application server instance are started. Once the application server instance is started it runs constantly, listening for and accepting requests. Each domain must be started separately.

To start a domain, type the asadmin start-domain command and specify the domain name. For example, to start the default domain (domain1), type the following:

$ asadmin start-domain --user admin domain1

If there is only one domain, omit the domain name. For the full command syntax, type asadmin help start-domain. If the password data is omitted, you are prompted to supply it.

Starting the Default Domain on Windows

From the Windows Start Menu, select Programs -> Sun Microsystems -> Enterprise Server -> Start Admin Server.

Stopping the Domain

Stopping a domain shuts down its administration server and application server instance. When stopping a domain, the server instance stops accepting new connections and then waits for all outstanding connections to complete. This process takes a few seconds because the server instance must complete its shutdown process. While the domain is stopped, the Admin Console or most asadmin commands cannot be used.

To stop a domain, type the asadmin stop-domain command and specify the domain name. For example, to stop the default domain (domain1), type the following:

$ asadmin stop-domain domain1

If there is only one domain, then the domain name is optional. For the full syntax, type asadmin help stop-domain.

Consult the Admin Console online help to stop the domain through the Admin Console.

Stopping the Default Domain on Windows

From the Start menu select Programs -> Sun Microsystems -> Enterprise Server-> Stop Admin Server.

Restarting the Domain

Restarting the server is the same as restarting the domain. To restart the domain or server, stop and start the domain.

Creating a Cluster

A cluster is created using the create-cluster command. The following example creates a cluster named mycluster. The administration server host is myhost, the server port is 1234, and the administrative username is admin. The command prompts for the administrative passwords.

$ asadmin create-cluster --host myhost --port 1234 --user admin mycluster

For the full syntax, type asadmin help create-cluster.

Starting a Cluster

A cluster is started using the start-cluster command. The following example starts the cluster named mycluster. The command prompts for the administrative passwords.

$ asadmin start-cluster --host myhost --port 1234 --user admin mycluster

For the full syntax, type asadmin help start-cluster.

Stopping a Cluster

A cluster is stopped using the stop-cluster command. The following example stops the cluster named mycluster. The command prompts for the administrative passwords.

$ asadmin stop-cluster --host myhost --port 1234 --user admin mycluster

myhost is the administrative server host, 1234 is the administrative port, admin is the administrative username.

For the full syntax, type asadmin help stop-cluster. When a cluster is stopped, all the server instances in the cluster get stopped. A cluster without instances cannot be stopped.

Creating a Node Agent

A node agent is created using the create-node-agent command. The following example creates node agent named mynodeagent. The administration server host is myhost, the administration server port is 1234, and the administrative username is admin. The command normally prompts for the administrative passwords; however, if the --savemasterpassword option is not specified or false, the command does not prompt for the administrative passwords.

$ asadmin create-node-agent --host myhost --port 1234 --user admin mynodeagent

For the full syntax, type asadmin help create-node-agent.

Starting a Node Agent

A node agent is started using the start-node-agent command and specifying the node agent name. For example, to start the node agent mynodeagent, type the following:

$ asadmin start-node-agent --user admin mynodeagent

For the full syntax, type asadmin help start-node-agent.

Stopping a Node Agent

A node agent is stopped using the stop-node-agent command and specifying the node agent name. For example, to stop the node agent mynodeagent, type the following:

$ asadmin stop-node-agent mynodeagent

For the full syntax, type asadmin help stop-node-agent.

Starting an Instance

A server instance is started using the start-instance command. The following example starts the server instance named myinstance. The command prompts for the administrative passwords.

$ asadmin start-instance --host myhost --port 1234 --user admin myinstance

The administrative server host is myhost, the administrative port is 1234, the administrative username is admin. The server instance myinstance can be clustered or standalone.

For the full syntax, type asadmin help start-instance.

Stopping an Instance

A server instance is started using the stop-instance command. The following example stops the server instance named myinstance. The command prompts for the administrative passwords.

$ asadmin stop-instance --host myhost --port 1234 --user admin myinstance

The administrative server host is myhost, the administrative port is 1234, the administrative username is admin. The server instance myinstance can be clustered or standalone.

For the full syntax, type asadmin help stop-instance.

Restarting an Instance

To restart server instance, stop and start the instance.

Recreating the Domain Administration Server

For mirroring purposes, and to provide a working copy of the Domain Administration Server (DAS), you must have:

• One machine (machine1) that contains the original DAS.

• A second machine (machine2) that contains a cluster with server instances running applications and catering to clients. The cluster is configured using the DAS on the first machine.

• A third backup machine (machine3) where the DAS needs to be recreated in case the first machine crashes.

You must maintain a backup of the DAS from the first machine. Use asadmin backup-domain to backup the current domain.

To migrate the DAS

The following steps are required to migrate the Domain Administration Server from the first machine (machine1) to the third machine (machine3).

1. Install the application server on the third machine just as it is installed on the first machine.

   This is required so that the DAS can be properly restored on the third machine and there are no path conflicts.

   1. Install the application server administration package using the command-line (interactive) mode. To activate the interactive command-line mode, invoke the installation program using the console option:

      ./bundle-filename -console

      You must have root permission to install using the command-line interface.

   2. Deselect the option to install default domain.

      Restoration of backed up domains is only supported on two machines with same architecture and exactly the same installation paths (use same as-install and domain-root-dir on both machines).

2. Copy the backup ZIP file from the first machine into the domain-root-dir on the third machine. You can also FTP the file.

3. Execute asadmin restore-domain command to restore the ZIP file onto the third machine:

   asadmin restore-domain --filename domain-root-dir/sjsas_backup_v00001.zip domain1

   You can backup any domain. However, while recreating the domain, the domain name should be same as the original.

4. Change domain-root-dir/domain1/generated/tmp directory permissions on the third machine to match the permissions of the same directory on first machine.

   The default permissions of this directory are: ?drwx------? (or 700).

   For example:

   chmod 700 domain-root-dir/domain1/generated/tmp

   The example above assumes you are backing up domain1. If you are backing up a domain by another name, you should replace domain1 above with the name of the domain being backed up.

5. Change the host values for the properties in the domain.xml file for the third machine:

6. Update the domain-root-dir/domain1/config/domain.xml on the third machine.

   For example, search for machine1 and replace it with machine3. So, you can change:

   <jmx-connector><property name=client-hostname value=machine1/>...

   to:

   <jmx-connector><property name=client-hostname value=machine3/>...

7. Change:

   <jms-service... host=machine1.../>

   to:

   <jms-service... host=machine3.../>

8. Start the restored domain on machine3:

   asadmin start-domain --user admin-user --password admin-password domain1

9. Change the DAS host values for properties under node agent on machine2.

10. Change agent.das.host property value in as-install/nodeagents/nodeagent/agent/config/das.properties on machine2.

11. Restart the node agent on machine2.

    ---

    Note –

    Start the cluster instances using the asadmin start-instance command to allow them to synchronize with the restored domain.

    ---