This chapter describes the Sun Java System Application Server administration. Application Serveradministration includes many tasks such as deploying applications, creating and configuring domains, server instances and resources, controlling (starting and stopping) domains and server instances, monitoring and managing performance, and diagnosing and troubleshooting problems. This chapter contains following sections:
The Sun Java System Application Server provides a Java 2 Platform, Enterprise Edition (J2EE platform) 1.4 compatible platform for developing and delivering server side Java applications and Web services. Key features include scalable transaction management, container-managed persistence runtime, performant web services, clustering, high availability, security, and integration capabilities.
The Application Server is available in the following editions:
The Platform edition is free and is intended for software development and department-level production environments.
The Enterprise edition is designed for mission-critical services and large-scale production environments. It supports horizontal scalability and service continuity with a load balancer plug-in and cluster management. The Enterprise edition also supports reliable session state management with the high-availability database (HADB).
This section contains the following topics:
The Application Server is a platform that supports services from Web publishing to enterprise-scale transaction processing, while enabling developers s to build applications based on JavaServer Pages (JSP), Java servlets, and Enterprise JavaBeans (EJB) technology.
The Application Server Platform Edition is free for development, production deployment, and redistribution. For more information on redistribution, please visit http://www.sun.com/software/products/appsrvr/appsrvr_oem.xml.
The Application Server Enterprise Edition provides advanced clustering and failover technologies. The Application Server infrastructure supports the deployment of many types of distributed applications and is an ideal foundation for building applications based on Service Oriented Architectures (SOA). SOA is a design methodology aimed at maximizing the reuse of application services. These features enable you to run scalable and highly available J2EE applications.
Scalability - Scalability is achieved through clustering. A cluster is a group of application server instances that work together as one logical entity. Each Application Server instance in a cluster has the same configuration and the same applications deployed to it.
Horizontal scaling is achieved by adding Application Server instances to a cluster, thereby increasing the capacity of the system. It is possible to add Application Server instances to a cluster without disrupting service. The HTTP, RMI/IIOP, and JMS load balancing systems distribute requests to healthy Application Server instances in the cluster.
High Availability - Availability refers to the failover capability. If one server instance goes down, another server instance in a cluster takes over the sessions of the failed instance and continues to serve the clients in a seamless manner. Session information is stored in the high-availability database (HADB). HADB supports the persistence of HTTP sessions and stateful session beans.
This section describes Figure 1–1, which shows the high-level architecture of the Application Server.
Containers - A container is a runtime environment that provides services such as security and transaction management to J2EE components. Figure 1–1 shows the two types of J2EE containers: Web and EJB. Web components, such as JSP pages and servlets, run within the Web container. Enterprise Java Beans run within the EJB container.
Client Access - At runtime, browser clients access Web applications by communicating with the Web server via HTTP, the protocol used throughout the internet. The HTTPS protocol is for applications that require secure communication. Enterprise Java Bean clients communicate with the Object Request Broker (ORB) through the IIOP or IIOP/SSL (secure) protocols. The Application Server has separate listeners for the HTTP, HTTPS, IIOP, and IIOP/SSL protocols. Each listener has exclusive use of a specific port number.
Web Services - On the J2EE platform, it is possible to deploy a Web application that provides a Web service implemented by Java API for XML-Based RPC (JAX-RPC). A J2EE application or component can also be a client to other Web services. Applications access XML registries through the Java API for XML Registries (JAXR).
Services for Applications - The J2EE platform was designed so that the containers provide services for applications. Figure 1–1 shows the following services:
Naming - A naming and directory service binds objects to names. A J2EE application locates an object by looking up its JNDI name. JNDI stands for the Java Naming and Directory Interface API.
Security - The Java Authorization Contract for Containers (JACC) is a set of security contracts defined for the J2EE containers. Based on the client’s identity, the containers restrict access to the container’s resources and services.
Transaction management - A transaction is an indivisible unit of work. For example, transferring funds between bank accounts is a transaction. A transaction management service ensures that a transaction either completes fully or is rolled back.
The J2EE platform enables applications to access systems that are outside of the application server. Applications connect to these systems through objects called resources. One of the responsibilities of an administrator is resource configuration. The J2EE platform enables access to external systems through the following APIs and components:
JDBC - A database management system (DBMS) provides facilities for storing, organizing, and retrieving data. Most business applications store data in relational databases, which applications access via the JDBC API. The information in databases is often described as persistent because it is saved on disk and exists after the application ends. The Application Server bundle includes the Java DB database management system.
Messaging - Messaging is a method of communication between software components or applications. A messaging client sends messages to, and receives messages from, any other client. Applications access the messaging provider through the Java Messaging Service (JMS) API. The Application Server includes a JMS provider.
Connector - The J2EE Connector architecture enables integration between J2EE applications and existing Enterprise Information Systems (EIS). An application accesses an EIS through a portable J2EE component called a connector or resource adapter.
JavaMail - Through the JavaMail API, applications connect to an SMTP server in order to send and receive email.
Server Administration - The lower right-hand corner of Figure 1-1 shows administration interfaces of the Application Server. Administration tools communicate with the Application Server using these interfaces.
Various different tools and APIs are available to administer the Sun Java System Application Server:
The Administration 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 Administration Console. You need the administration server hostname and port number to launch the Administration Console. The default administration server port number for the default administration server is 4849. You also need the administration username and password to login to the Administration Console. Consult the section for more detailed information.
To start the Administration Console, in a web browser type:
https://hostname:port |
For example:
https://kindness.sun.com:4849 |
If the Administration Console is running on the machine on which the administration server is running, you can specify localhost for the host name.
On Windows, start the Application Server Administration Console from the Start menu.
The asadmin utility is a command-line interface for the Sun Java System Application Server. You can perform the same set of administrative tasks offered by the Administration Console. The asadmin utility can be invoked from a command prompt in the shell, or called from other scripts or programs. The asadmin utility is installed in install-dir/bin directory. The default Sun Java System Application Server installation root directory on Solaris is /opt/SUNWappserver.
To start the asadmin utility, go to the install-dir/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 on the Web at Sun Java System Application Server Enterprise Edition 8.2 Reference Manual.
In the Java 2, Platform Standard Edition 5.0, the Java Monitoring and Management Console (JConsole) was introduced. JConsole is used to monitor the Sun Java System Application Server. You can use either the JConsole remote tab, or the advanced tab to connect to the Application 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.
The Application Server Management eXtension is an API that exposes all of the Application Server configuration and monitoring JMX managed beans as easy-to-use client-side dynamic proxies implementing the AMX interfaces.
For more information on using the Application Server Management Extension, see Chapter 16, Using the Java Management Extensions (JMX) API, in Sun Java System Application Server Enterprise Edition 8.2 Developer’s Guide .
The Sun Java System Application Serverconsists 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 following topics:
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 administration boundary, domain provide a 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 Application 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 Java System Application 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 4849. The installer also queries for the administration username and password. After installation, additional administration domains can be created.
Each domain has its own Domain Administration Server (DAS) with a unique port number. The Administration Console communicates with a specific DAS to administer the associated domain. Each Administration 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 Java System Application Server installation and can be used for deployments. The DAS is simply a server instance with additional administration capabilities.
Each Administration Console session allows you to configure and manage a single domain. If you created multiple domains, you must start an additional Administration Console session to manage the other domains. When specifying the URL for the Administration Console, be sure to use the port number of the DAS associated with the domain to be administered.
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.
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.
The server instance is a single J2EE compatible Java Virtual Machine hosting a J2EE 1.4 Application 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 application, resource, 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.
Application server instances form the basis of an application deployment. Each instance belongs to a single domain. Every server instance, other than the DAS, must contain a reference to a node agent name defining the machine on which the instance will reside.
If your topology includes remote server instances (server instances other than the DAS), 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 commands to set up node agents. Figure 1–2 shows an application server instance in detail.
The Sun Java System Application 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 Application 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 12, 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.
Administration of the Application Server includes tasks such as creation, configuration, control and management of domains, clusters, node agents, and server instances. This section contains the following topics:
Domains are created using the create-domain command. The following example command creates a domain named mydomain. The administration server listens on port 1234 and the administrative user name is hanan. The command prompts for the administrative and master passwords.
$ asadmin create-domain --adminport 80 --adminuser hanan mydomain |
To start the Administration Console for mydomain domain, in a browser, enter the following URL:
http://hostname:80 |
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.
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 |
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.
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.
From the Windows Start Menu, select Programs -> Sun Microsystems -> Application Server -> Start Admin Server.
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 Administration 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.
From the Start menu select Programs -> Sun Microsystems -> Application Server-> Stop Admin Server.
Restarting the server is the same as restarting the domain. To restart the domain or server, stop and start the domain.
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.
A cluster is started using the start-cluster command. The following example starts the cluster named mycluster. The command prompts for the administrative password.
$ asadmin start-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 start-cluster. When a cluster is started, all the server instances in the cluster get started. A cluster without instances cannot be started.
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.
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 prompts 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.
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.
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.
A server instance is created using the create-instance command. The following example creates an instance named myinstance. The administration server host is myhost, the administration server port is 1234, and the administrative username is admin. The command prompts for the administrative passwords.
The following example creates a clustered server instance named myinstance. The command prompts for the administrative passwords.
$ asadmin create-instance --host myhost --port 1234 --user admin --cluster mycluster --nodeagent mynodeagent myinstance |
myhost is the administrative server host, the administrative port is 1234, the administrative username is admin, the cluster this server instance belongs to is mycluster, the node agent managing this server instance is mynodeagent.
For the full syntax, type asadmin help create-instance.
To create a standalone server instance do not specify the --cluster option.
The following example creates a standalone server instance named myinstance managed by the node agent named mynodeagent.
$ asadmin create-instance --host myhost --port 1234 --user admin --nodeagent mynodeagent myinstance |
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.
A server instance is stopped using the stop-instance command. The following example stops the 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.
To restart server instance, stop and start the instance.
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.
The following steps are required to migrate the Domain Administration Server from the first machine (machine1) to the third machine (machine3).
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.
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.
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 install-dir and domain-root-dir on both machines).
Copy the backup ZIP file from the first machine into the domain-root-dir on the third machine. You can also FTP the file.
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.
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.
Change the host values for the properties in the domain.xml file for the third machine:
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/>...
Change:
<jms-service... host=machine1.../>
to:
<jms-service... host=machine3.../>
Start the restored domain on machine3:
asadmin start-domain --user admin-user --password admin-password domain1 |
Change the DAS host values for properties under node agent on machine2.
Change agent.das.host property value in install-dir/nodeagents/nodeagent/agent/config/das.properties on machine2.
Restart the node agent on machine2.
Start the cluster instances using the asadmin start-instance command to allow them to synchronize with the restored domain.
To reset the administrator password, you must stop all the node agents in the domain. This stops all the associated server instances. All the server instances and node agents are now stopped and only the Domain Administration Server (DAS) is running.
Now you can change the administrative user's password as follows:
Change the admin password using the Command-line interface:
asadmin update-file-user --authrealmname admin-realm ... --userpassword newpassword <admin-user-name>
Change the admin password using the Admin console:
Select the admin-server's configuration node > Security > Realms > admin-realm > Edit File Realm User.
A message indicating that you have successfully changed the administrator password is displayed.
Restart the Domain Admin Server (DAS) with the new password as follows:
Using the Command-line interface: asadmin start-domain --user admin --password newpassword domain1
Assuming the following configuration: a domain with two node-agents (i1na, c1-na), and three instances (c1i1 and c1i2 are in the same cluster named c1 and a standalone server instance i1).
Restart Node Agent without starting the instances with the new password.
For example:
asadmin start-node-agent --user admin --password newpassword --startinstances=false i1-na asadmin
asadmin start-node-agent --user admin --password newpassword --startinstances=false c1-na
Restart the Servers and Clusters.
asadmin start-node-agent --user admin --password newpassword ... c1
asadmin start-node-agent --user admin --password newpassword i1
The Sun Java System Application Server configuration is stored in the domain.xml file. The domain.xml is a document that represents the configuration state of the Application Server. It is the central repository for a given administrative domain. The document contains an XML representation of the Application Server domain model. The contents of domain.xml are governed by the specification expressed in the form of the domain DTD.
This section contains the following topics:
When making any of the following configuration changes, restarting the server is required for the changes to take effect:
Changing JVM options
Changing port numbers
Managing HTTP, IIOP, and JMS services
Managing thread pools
For instructions, see Restarting the Domain.
When making any of the following configuration changes, if dynamic configuration is enabled, restarting the server is NOT required for the changes to take effect:
Deploying and undeploying applications
Adding or removing JDBC, JMS, and Connector resources and pools
Changing logging levels
Adding file realm users
Changing monitoring levels
Enabling and disabling resources and applications
Note that the asadmin reconfig command has been deprecated and is no longer necessary. Configuration changes are applied to the server dynamically.
The following table describes the port listeners of the Application Server.
Table 1–1 Application Server Listeners that Use Ports
Listener |
Default Port Number |
Description |
---|---|---|
Administrative server |
4849 |
A domain’s administrative server is accessed by the Administration Console and the asadmin utility. For the Administration Console, specify the port number in the URL of the browser. When executing an asadmin command remotely, specify the port number with the --port option. |
HTTP |
8080 |
The Web server listens for HTTP requests on a port. To access deployed Web applications and services, clients connect to this port. |
HTTPS |
8181 |
Web applications configured for secure communications listen on a separate port. |
IIOP |
3700 |
Remote clients of enterprise beans (EJB components) access the beans through the IIOP listener. |
IIOP, SSL |
3820/3890 |
Another port is used by the IIOP listener configured for secure communications. |
IIOP, SSL and mutual authentication |
Another port is used by the IIOP listener configured for mutual (client and server) authentication. |
|
JMX |
8686 |
Another port is used by the JMX connector to communicate with the DAS. |
The Application Server relies on the Java 2 Standard Edition (J2SE) software. When the Application Server was installed, the directory for the J2SE software was specified. For instructions on changing the J2SE software, see Chapter 17, Java Virtual Machine and Advanced Settings.