Sun ONE Application Server 7 Administrator's Guide |
Chapter 4
Using Application Server InstancesThis chapter describes how to create, delete, configure, start, and stop Sun ONE Application Server instances.
This chapter includes the following topics:
About Application Server InstancesSun ONE Application Server creates one application server instance, called server1, when you install the unbundled version of the software. You can delete the server1 instance and create a new instance with a different name if you prefer.
If you are using the Solaris 9 bundled version of the software, you must create your own server instance. For more information, see "Configuring the Bundled Solaris Version".
Each application server instance has its own J2EE configuration, J2EE resources, application deployment areas, and server configuration settings. Changes to one application server instance have no effect on other application server instances. You can have many application server instances within one administrative domain. Within a domain, all the server instances have the same Administration Server. For more information on domains, see Chapter 3, "Configuring Administrative Domains."
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 Sun ONE 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” areas to experiment with while developing.
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 15, "Using Virtual Servers."
In operational deployments, for many purposes you can use virtual servers instead of multiple application server instances. However, if virtual servers don’t meet your needs, you can also use multiple application server instances.
Starting and Stopping an Application Server InstanceA Sun ONE Application Server instance is not started automatically. Once you start an instance, it the instance runs until you stop it. When you stop an application server instance, it 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.
You can start and stop the application server instance using one of several methods, covered in the following topics:
If you have a server certificate installed, the Sun ONE Application Server prompts the administrator for the key database password before starting up. If you want to be able to restart an unattended Sun ONE Application Server, you need to save the password in a password.conf file. Only do this if your system is adequately protected so that this file and the key databases are not compromised. For more information on creating and using password.conf, see the Sun ONE Application Server Administrator’s Configuration File Reference.
Using the Start and Stop Buttons in the Administration Interface
To start and stop the server using the Administration interface:
Using the start-instance and stop-instance Commands
Using the command-line interface utility asadmin, you can start and stop your application server instances either from the command prompt or from a script. Use the commands start-instance and stop-instance.
These commands have the following syntax:
start-instance [--user admin_user] [--password admin_password] [--host admin_host] [--port admin_port] [--local=true/false] [--domain domain_name] [--debug=true/false] [--passwordfile file_name] [--secure | -s] instance_name
stop-instance [--user admin_user] [--password admin_password] [--host admin_host] [--port admin_port] [--local=true/false] [--domain domain_name] [--passwordfile file_name] [--secure | -s] instance_name
These commands have a local option which you can use to start or stop the server without going through the Administration Server. If you use the local option, you do not need to specify the host, port, user, and password (or passwordfile) options.
For information on the syntax of these commands, use the asadmin help. For information on using asadmin, see Appendix A, "Using the Command Line Interface."
Using the Windows Services (Windows)
You can start the server by using the Services Control Panel in Windows.
Follow these steps:
Using the startserv and stopserv Scripts
To use the startserv and stopserv scripts, at the command-line prompt go to the directory:
instance_dir/bin
where install_dir is the directory where you installed the server, domain_dir is the domain directory, and instance_dir is the name of the instance you want to start.
For UNIX, type:
./startserv
Log in as root if the server runs on ports with numbers lower than 1024; otherwise, log in as root or with the server’s user account.
You can use the optional parameter -i at the end of the line. The -i option runs the server in inittab mode, so that if the server process is ever killed or crashed, inittab will restart the server for you. This option also prevents the server from putting itself in a background process.
For Windows, type:
startserv
To stop the server manually, at the command-line prompt go to the directory:
instance_dir/bin
where install_dir is the directory where you installed the server and instance_dir is the name of the instance you want to start.
For UNIX, type:
./stopserv
If you used the /etc/inittab file to restart the server you must remove the line starting the server from /etc/inittab and type kill -1 1 before you try to stop the server. Otherwise, the server restarts automatically after it is stopped.
For Windows, type:
stopserv
Starting the Application Server Instance in Debug ModeYou can run the application server instance in debug mode if developers want to debug their J2EE applications.
To start the server in debug mode:
Debug mode changes the JVM settings. Debug Enabled is set to true, and the Debug Options change. For more information on the JVM Debug options, see the Java Platform Debugger Options documentation at http://java.sun.com/products/jpda/doc/conninv.html.
To start the application server instance in debug mode from the command-line interface, use the asadmin utility’s start-instance command with the debug option set to true. For more information on the command syntax, see the online help for the command-line interface.
Setting the Termination TimeoutWhen you stop an application server instance, it stops accepting new connections. Then it waits for all outstanding connections to complete. The time the server waits before timing out is configurable in the init.conf file, which can be found in instance_dir/config/. By default it is set to 30 seconds. To change the value, add the following line to init.conf:
TerminateTimeout seconds
where seconds represents the number of seconds the server will wait before timing out.
The advantages to configuring this value is that the server will wait longer for connections to complete. However, because servers often have connections open from nonresponsive clients, increasing the termination timeout may increase the time it takes for the server to shut down.
Restarting an Application Server Instance Automatically (UNIX)You can restart an application server instance using one of the following methods:
- Automatically restart it with daemons in /etc/rc2.d when the machine reboots.
- Restart it manually. See "Starting and Stopping an Application Server Instance" and "Deleting an Application Server Instance".
This section contains the following topics:
About Restarting Automatically
Because the installation scripts cannot edit the /etc/rc.local or /etc/inittab files, you must edit those files with a text editor. If you do not know how to edit these files, consult your system administrator or system documentation.
Normally, you cannot start an SSL-enabled server with either of these files because the server requires a password before starting. Although you can start an SSL-enabled server automatically if you keep the password in plain text in a file, this is not recommended.
The server’s startserv script, key pair file, and the key password should be owned by root (or, if a non-root user installed the server, that user account), with only the owner having read and write access to them.
Restarting Automatically with /etc/inittab (UNIX)
To restart the server using inittab, put the following text on one line in the
/etc/inittab file:http:2:respawn:install_dir/path_to_domain_dir/instance_dir/bin/startserv -start -i
where install_dir is the directory where you installed the server, path_to_domain_dir is the path to the domain and instance_dir is the server’s directory.
The -i option prevents the server from putting itself in a background process.
You must remove this line before you stop the server, otherwise the server automatically restarts.
Restarting Automatically with the System RC Scripts (UNIX)
If you use /etc/rc.local, or your system’s equivalent, place the following line in /etc/rc.local:
install_dir/path_to_domain_dir/instance_dir/bin/startserv
Replace install_dir with the directory where you installed the server, path_to_domain_dir with the path to the domain, and instance_dir with the name of the application server instance.
Restarting an Application Server Instance Manually (UNIX)On UNIX, you have the option of restarting the server instance manually. Unlike stopping the server instance, then starting it, a restart does not stop the watchdog program. For information about the watchdog, see "About the Watchdog".
Note
If you have made manual changes to your configuration files by editing them, you must apply changes before your restart the server, either by using the Apply Changes button in the Administration interface, or by using the asadmin reconfig command with the keepmanualchanges option set to true. For more information on applying changes, see "Applying Changes to an Application Server Instance".
There are three ways to restart the server instance, covered in the following topics:
Restarting the Server Instance Using the Restart Button (UNIX)
To restart the server instance using the Administration interface:
Restarting the Server Instance Using the restart-instance Command (UNIX)
Using the command-line interface utility asadmin, you can start and stop your application server instances either from the command-line or from a script. Use the commands restart-instance. This command has the following syntax:
restart-instance [--user admin_user] [--password admin_password] [--host admin_host] [--port admin_port] [--local=true/false] [--domain domain_name] [--passwordfile file_name] [--secure | -s] instance_name
This command has a local option which you can use to restart the server instance without going through the Administration Server.
For information on the syntax of these commands, use the asadmin help. For information on using asadmin, see Appendix A, "Using the Command Line Interface."
Restarting the Server Instance Using the restartserv Script (UNIX)
To use the restartserv script, at the command-line prompt go to the directory:
instance_dir/bin
where install_dir is the directory where you installed the server, domain_dir is the domain directory, and instance_dir is the name of the instance you want to start.
Type:
./restartserv
Log in as root if the server runs on ports with numbers lower than 1024; otherwise, log in as root or with the server’s user account.
About the WatchdogThe watchdog (appserv-wdog on UNIX, appservd-wdog.exe on Windows) is a program that is shipped with your Sun ONE Application Server. It performs the following tasks:
The watchdog runs in the background, without user intervention. You should never have to configure or otherwise change it. One watchdog runs for each application server instance, including the Administration Server.
On UNIX, each watchdog spawns a process for the primordial application server (appservd) process, which in turn spawns the appservd process that accepts requests. Since it starts the server, the watchdog process ID is shown in the pid log file in instance_dir/logs.
Adding an Application Server InstanceTo add an application server instance using the Administration interface:
- Access the Administration interface and click App Server Instances in the left pane.
- Click the General tab.
- On the Application Server Instances page, click New.
- On the Create New Instance page, provide an instance name and a port number.
The instance name must be unique for this Administration Server and domain. The port number must not be used by any other process on the machine.
If you are using UNIX, you can also specify a UNIX user for the instance to run as.
- Click OK.
For more information, see the online help.
To add another application server instance using the command-line interface, use the asadmin utility’s create-instance command, which has the following syntax:
asadmin create-instance [--user admin_user] [--password admin_password] [--host host] [--port port] [--sysuser sys_user] [--domain domain_name] [--local=true/false] [--passwordfile file_name] [--secure | -s] --instanceport instance_port instance_name
This command has a local option which you can use to restart the server instance without going through the Administration Server. The sysuser option is only for UNIX.
For more information on command syntax, see the command-line interface help. For more information on using asadmin, see Appendix A, "Using the Command Line Interface."
Deleting an Application Server InstanceYou can delete an application server instance from your administrative domain. Be sure that you don’t need the application server instance anymore before you delete it, since this process cannot be undone.
To delete an application server instance from your machine using the Administration interface:
For more information, see the online help.
To delete an application server instance from your machine using the command-line interface, use the asadmin utility’s delete-instance command, which has the following syntax:
asadmin delete-instance [--user admin_user] [--password admin_password] [--host admin_host] [--port admin_port] [--domain domain_name] [--local=true/false] [--passwordfile file_name] [--secure | -s] instance_name
This command has a local option which you can use to delete the server instance without going through the Administration Server.
For more information on command syntax, see the command-line interface help. For more information on using asadmin, see Appendix A, "Using the Command Line Interface."
Applying Changes to an Application Server InstanceWhen you change configuration information using the Administration interface or the command-line interface, the changes are not applied immediately, but are saved into special files, located in server_instance/config/backup. The Administration interface and command-line interface display configuration values stored in files in the above directory. Until the changes you make are applied they do not take effect. Applying changes is also called reconfiguring the server. When you apply your changes, all changes made to the configuration since the last time you applied changes take effect. Note that restarting the instance does not apply the changes automatically.
If you’ve made changes to the server instance configuration that require you to apply changes, a yellow icon appears next to the application server instance in the left pane’s tree view, in the banner when you access the server instance, and on the server instance’s main page.
Figure 4-1 Warning Icon
To apply changes to an application server instance using the Administration interface:
To reconfigure an application server instance using the command-line interface, use the asadmin utility’s reconfig command, which has the following syntax:
asadmin reconfig --user admin_user [--password admin_password] [--host admin_host] [--port admin_port] [--passwordfile file_name] [--secure | -s] [--discardmanualchanges=true/false | --keepmanualchanges=true/false] instance_name
If you have made manual changes to the configuration files by editing them by hand, you must use keepmanualchanges=true to keep those edits during the reconfiguration (the option defaults to false). If you set discardmanualchanges=true, you discard any changes made manually. Setting discardmanulchanges=false (the default) does not mean the same thing as keepmanualchanges=true. Instead, setting it to false it is the equivalent of not specifying the discardmanualchanges option.
For more information on command syntax, see the command-line interface help. For more information on using asadmin, see Appendix A, "Using the Command Line Interface."
For some properties, you need to restart the server, as well as apply changes, in order for your changes to take effect. These properties include all properties set in the configuration files init.conf and obj.conf, and some properties in server.xml. For information about these files, see the Sun ONE Application Server Administrator’s Configuration File Reference.
Your server will warn you if the changes require restart by putting a yellow warning icon next to the server instance left pane’s tree view, in the banner when you access the server instance, and on the server instance’s main page. The messages in the banner and on the page indicate that a restart is required. Once you restart the server instance, the yellow warning icons disappear.
The server.xml settings that do not require a restart include the following:
- Deploying, undeploying, and redeploying J2EE applications (EAR files), EJB modules (JAR files), web modules (WAR files), connectors (RAR files). Note that these settings also don’t require Apply Changes.
- Enabling and disabling J2EE applications (EAR files), EJB modules (JAR files), web modules (WAR files), and connectors (RAR files).
- Creating, updating, and deleting resources.
- Setting monitoring enabled to true/false for the EJB container or MDB container.
- Changes to HTTP and web-container features (that is, in server.xml, changes to http-service and web-container and their sub-elements).
Viewing Application Server Instance StatusYou can view whether a server is started or stopped, as well as basic application server instance settings, using the Administration interface.
To view application server instance status:
To view the application server instance’s status using the command-line interface, use the asadmin utility’s show-instance-status command. The status is starting, started, stopping, or stopped. The command has the following syntax:
asadmin show-instance-status --user admin_user [--password admin_password] [--host admin_host] [--port admin_port] [--passwordfile file_name] [--secure | -s] instance_name
For more information on command syntax, see the command-line interface help. For more information on using asadmin, see Appendix A, "Using the Command Line Interface."
Configuring JVM SettingsYou can configure Java Virtual Machine (JVM) settings for you application server instance. These settings include the location of your Java home, compiler options, debugging options, and profiler information. One reason to configure these settings is to improve performance. For more information on performance see the Sun ONE Application Server Performance and Tuning Guide.
This section describes the following topics:
Configuring General Settings
To configure the JVM’s general options in the Administration interface:
- In the left pane, click the application server instance name.
- In the right pane, click the JVM tab.
- Click General.
- Set the Java Home.
The Java Home is the path to the directory where the Java Developer’s Kit (JDK) is installed. Sun ONE Application Server supports the Sun JDK 1.4.0_02 or higher.
- Choose whether to enable debugging and set debug options.
A list of debug options is available at http://java.sun.com/products/jpda/doc/conninv.html#Invocation.
- Choose rmic options.
The rmic options field shows the rmic options passed to the RMI compiler at application deployment time. The -keepgenerated option saves generated source for stubs and ties. For more information about the rmic command, see the Sun ONE Application Server Developer's Guide to Enterprise Java Beans.
- Click Save.
Configuring Path Settings
To configure the JVM’s path settings in the Administration interface:
- In the left pane, click the application server instance name.
- In the right pane, click the JVM tab.
- Click Path Settings.
- Choose a suffix for the system’s classpath.
- Choose whether to ignore the environment classpath.
If you do not ignore the classpath, the CLASSPATH environment variable is read and appended to the Sun ONE Application Server classpath. The CLASSPATH environment variable is added after the classpath-suffix, at the very end.
For a development environment, the classpath should be used. For a production environment, this classpath should be ignored to prevent environment variable side effects.
- Set a native library path prefix and suffix.
The native library path is the automatically constructed concatenation of the Application Server installation relative path for its native shared libraries, the standard JRE native library path, the shell environment setting (LD_LIBRARY_PATH on UNIX), and any path specified in the profiler element. Since this is synthesized, it does not appear explicitly in the server configuration.
- Click Save.
Configuring JVM Options
To set JVM command-line options in the Administration interface:
- In the left pane, click the application server instance name.
- In the right pane, click the JVM tab.
- Click JVM Options.
- To add a JVM option, type it in the text field at the top of the screen and click Add.
- To delete a JVM option, click the checkbox next to it and click Delete.
- To edit a JVM option, edit the text in the JVM Option field and click Save.
For information about specific JVM options, see http://java.sun.com/docs/hotspot/VMOptions.html
Configuring the JVM Profiler
To configure the JVM Profiler in the Administration interface:
- In the left pane, click the application server instance name.
- In the right pane, click the JVM tab.
- Click Profiler.
- Specify the name of the profiler, its classpath and native library path, and whether it is enabled.
- To add a JVM option for the profiler, type it in the text field at the top of the screen and click Add.
- To delete a JVM option for the profiler, click the checkbox next to it and click Delete.
- To edit a JVM option for the profiler, edit the text in the JVM Option field and click Save.
For more information about profilers, see the Sun ONE Application Server Developer's Guide.
Configuring JVM Settings Using the Command-Line Interface
To configure JVM Settings using the command-line interface’s asadmin utility, use the following commands:
To get all the attributes from an instance:
asadmin> get server_instance.java-config.*
To get an attribute called classpathprefix in server1:
asadmin> get server1.java-config.classpathprefix
To set an attribute called classpathprefix in server1:
asadmin> set server1.java-config.classpathprefix=com.sun
The above examples all assume you have already set the user, password, host, and port in your environment variables. For a full list of attributes, see Appendix A, "Using the Command Line Interface."
To set JVM options using the command-line interface’s asadmin utility, use the following commands:
asadmin> create-jvm-options --user admin_user [--password admin_password] [--host host] [--port port] [--secure | -s] [--instance instance_name] [--profiler=true/false] (jvm_option_name=jvm_option_value)[:jvm_option_name=jvm_option_name]*
asadmin> delete-jvm-options --user admin_user [--password admin_password] [--host host] [--port port] [--secure | -s] [--instance instance_name] [--profiler=true/false] (jvm_option_name=jvm_option_value)[:jvm_option_name=jvm_option_name]*
Note: you can enter more than one JVM option separated by colon. If the options are used by the profiler, set --profiler to true.
For more information on command syntax, see the command-line interface help. For more information on using asadmin, see Appendix A, "Using the Command Line Interface."
Configuring Logging Setting and Monitoring SettingsThe settings on the Logging and Monitoring tabs are Logging and Monitoring settings are covered in separate chapters. For information on logging, see Chapter 5, "Using Logging." For information on Monitoring and SNMP settings, see Chapter 6, "Monitoring the Sun ONE Application Server."
Changing Application Server Instance Advanced SettingsAn application server instance has additional settings showing the instance’s locale (which determines settings such as the character set and language), the path to the server’s log files, the path to the directory for deployed applications, and the path to the session store directory where passivated beans and persistent HTTP sessions are stored.
In addition, you enable application reloading and poll interval for how often to reload. Dynamic application reloading automatically checks applications for changes, and serves the updated version automatically if they have been changed. In general, you should enable dynamic reloading in a development environment and not in a production environment. The poll interval specifies the interval at which the Application Server checks the applications for updates.
To change the application server instance’s settings using the Administration interface:
To change the server instance’s advanced setting using the command-line interface’s asadmin utility, you use the get and set commands. When you get all the attributes for a server instance
To get all the attributes from an instance:
asadmin get instance_name.*
For example:
asadmin get server1.*
To get an attribute called logRoot for server1:
asadmin get server1.logRoot
To set an attribute called logRoot for server1:
asadmin set server1.logRoot=/space/log
The above examples all assume you have already set the user, password, host, and port in your environment variables. For more information on command syntax, see the command-line interface help. For more information on using asadmin, see Appendix A, "Using the Command Line Interface."