Sun ONE logo     Previous      Contents      Index      Next     
Sun ONE Application Server 7, Update 1 Administrator's Guide



Using Application Server Instances

This module describes how to create, delete, configure, start, and stop Sun ONE Application Server instances.

This module includes the following topics:

About Application Server Instances

Sun 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 "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 "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 Instance

A 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.


Note

On UNIX, some Sun ONE Application Server installations may require access to more memory and/or file descriptors than your operating system allows by default. If you are unable to start the server, check the resource limits imposed by your operating system using the ulimit command. Your operating system's ulimit man page should provide more information.


Using the Start and Stop Buttons in the Administration Interface

To start and stop the server using the Administration interface:

  1. In the left pane, under App Server Instances, click the name of the instance to start or stop.

  2. In the right pane, click Start or Stop; or in the General Tab, click Start or Stop.

  3. You see a message when the application server instance is started or stopped successfully.

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 "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:

  1. In the Control Panel click Administrative Tools.

  2. Click Services.

  3. Scroll through the list of services and double-click the service for your server.

    4. It is called Sun Application Server (domain_name:instance_name). For example, Sun Application Server (domain1:server1).

  4. Click Start or Stop.

  5. Click OK.

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.


Note

If the server is already running, the startserv command will fail. You must stop the server first, then use the startserv command. Also, if the server startup fails, you should kill the process before trying to restart it.

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 Mode

You can run the application server instance in debug mode if developers want to debug their J2EE applications.

To start the server in debug mode:

  1. Access the Administration interface and click the name of the application server instance you want to start in debug mode.

  2. Click the General tab.

  3. Click the checkbox next to Run in Debug Mode.

  4. Restart the application server instance.

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 Timeout

When 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:

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.


Caution

Leaving the SSL-enabled server's password in plain text in the server's startserv script is a large security risk. Anyone who can access the file has access to the SSL-enabled server's password. Consider the security risks before keeping the SSL-enabled server's password in plain text.

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:

  1. In the left pane, under App Server Instances, click the name of the instance to restart.

  2. In the right pane, click Restart.

  3. You see a message when the application server instance is restarted successfully.

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 "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 Watchdog

The 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:

  • Starts the server

  • Stops the server

  • If SSL/TLS is enabled, prompts the administrator for the trust database password when the server starts

  • Restarts the server if it goes down

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.


Note

appservd Processes on UNIX Platforms: Although you will notice that there is a single appservd process started for each application server instance on Windows, there are two appservd processes started per application server instance on UNIX systems.

On UNIX, one appservd process is referred to as the "primordial" process while the second appservd process is referred to as the "worker" process. The worker process is the process that carries out the actual processing of application requests while the primordial process acts as an overarching controller. In a future release of the application server, you will have the option to define the number of worker processes for each application server instance. In the initial release of the product, only one worker process is supported per application server instance.

Adding an Application Server Instance

To add an application server instance using the Administration interface:

  1. Access the Administration interface and click App Server Instances in the left pane.

  2. Click the General tab.

  3. On the Application Server Instances page, click New.

  4. On the Create New Instance page, provide an instance name and a port number.

    5. 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.

  5. 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 "Using the Command Line Interface."

Deleting an Application Server Instance

You 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:

  1. Access the Administration interface and click the name of the application server instance you want to remove.

  2. Click the General tab.

  3. Click Delete.

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 "Using the Command Line Interface."

Applying Changes to an Application Server Instance

When 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.

   Warning Icon
This figure shows the triagular yellow icon that appears when you need to apply changes.

To apply changes to an application server instance using the Administration interface:

  1. Access the Administration interface and click the name of the application server instance you want to reconfigure.

  2. Click the General tab.

  3. Click Apply Changes.

    4. When the changes are applied, the screen displays a message.

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 "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 Status

You 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:

  1. In the left pane, click the application server instance name.

  2. In the right pane, click the General tab.

    3. You see whether the server is running or not running, as well as the hostname, port number, installation directory, and the version of the Sun ONE Application Server software.

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 "Using the Command Line Interface."

Configuring JVM Settings

You 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:

  1. In the left pane, click the application server instance name.

  2. In the right pane, click the JVM tab.

  3. Click General.

  4. Set the Java Home.

    5. 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.

  5. Choose whether to enable debugging and set debug options.

    6. A list of debug options is available at http://java.sun.com/products/jpda/doc/conninv.html#Invocation.

  6. Choose rmic options.

    7. 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.

  7. Click Save.

Configuring Path Settings

To configure the JVM's path settings in the Administration interface:

  1. In the left pane, click the application server instance name.

  2. In the right pane, click the JVM tab.

  3. Click Path Settings.

  4. Choose a suffix for the system's classpath.

  5. Choose whether to ignore the environment classpath.

    6. 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.

  6. Set a native library path prefix and suffix.

    7. 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.

  7. Click Save.

Configuring JVM Options

To set JVM command-line options in the Administration interface:

  1. In the left pane, click the application server instance name.

  2. In the right pane, click the JVM tab.

  3. Click JVM Options.

  4. To add a JVM option, type it in the text field at the top of the screen and click Add.

  5. To delete a JVM option, click the checkbox next to it and click Delete.

  6. 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:

  1. In the left pane, click the application server instance name.

  2. In the right pane, click the JVM tab.

  3. Click Profiler.

  4. Specify the name of the profiler, its classpath and native library path, and whether it is enabled.

  5. To add a JVM option for the profiler, type it in the text field at the top of the screen and click Add.

  6. To delete a JVM option for the profiler, click the checkbox next to it and click Delete.

  7. 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 "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 "Using the Command Line Interface."

Configuring Logging Setting and Monitoring Settings

The settings on the Logging and Monitoring tabs are Logging and Monitoring settings are covered in separate chapters. For information on logging, see "Using Logging." For information on Monitoring and SNMP settings, see "Monitoring the Sun ONE Application Server."

Changing Application Server Instance Advanced Settings

An 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:

  1. In the left pane, click the application server instance name.

  2. On the application server instance's page, click the Advanced tab.

  3. Enter the desired value in the fields.

  4. Click Save.

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 "Using the Command Line Interface."

Previous      Contents      Index      Next     
Copyright 2003 Sun Microsystems, Inc. All rights reserved.

Last Updated March 24, 2003