Administrator's Guide

CHAPTER 5

Running the Server

This chapter describes how to run the Novell exteNd Application Server. It contains sections on:

• Starting the application server

• Shutting down the application server

• Restarting the application server

• Maintaining processes running as services

• Setting up separate ports

• Specifying general server properties

• Using server logging

• Specifying ORB settings

• Running multiple servers on one host

• Specifying character set encoding

• Running the JMS server

Starting the application server

This section provides platform-specific information for manually starting the application server.

NOTE:   You can also run the application server in the background as a service in Windows or as a daemon in UNIX. For more information, see Installing Novell exteNd.

This section contains the following topics:

• Starting the application server

• Using startup options

• Specifying the JVM to use

• Starting the server on a specific IP address or hostname

Starting the application server

To start the application server in Windows:

• Do one of the following:

  • From Start>Programs>Novell exteNd n.n>AppServer, select Application Server.

  • Run the application server from a DOS command line by issuing the SilverServer command with one or more startup options.

    For more information, see Using startup options below and Specifying the JVM to use.

To start the application server on UNIX or Linux:

1. From the command line, change to the server's \bin directory.

2. Type ./SilverServer and any startup options. To print a list of available options, enter:

     ./SilverServer -?
   

    For more information, see Using startup options below and Specifying the JVM to use.

To start the application server on NetWare:

1. From the system console, type silverserver and any startup options. To print a list of available options, enter:

     silverserver -?
   

   OR

     silverserver -help
   

   Go to the Logger screen to view the options.

2. Press Ctrl+Esc. The application server appears in the menu as exteNd Application Server.

    For more information, see Using startup options below and Specifying the JVM to use.

Using startup options

There are two kinds of startup options you can provide on the command line:

What the server does

When passing the options that were specified with the plus (+) sign to the JVM, the application server changes the plusses to minuses for processing by the JVM. For example, if you specify the following command line:

  SilverServer +verbose -dbcheck

The equivalent command line is:

  java -verbose ServerStartupClass -dbcheck

Displaying +options

To see a list of possible options for the JVM, type the following commands:

NOTE:   The application server automatically adds the following option with the appropriate value to the command line: -Djava.class.path. This option will override any corresponding option you specify on the command line.

Table of options

These are the server startup options:

  +verbose:vmopts

  SilverServer +Xms2m +Xmx16m

Specifying the JVM to use

The HotSpot JVM shipped with the application server comes (on most platforms) in two versions: a client version and a server version. This section describes how the server-side processes (the server, Cache Manager, Load Manager, and Dispatcher) and clients (such as SilverJ2EEClient and the SMC) use these JVMs.

On Windows

On Windows, by default the server-side processes and clients all use the server version of the HotSpot JVM.

To override this behavior on Windows, you can use the following startup options with any of the application server's executables that start a JVM:

On UNIX and Linux

On UNIX and Linux, the JVM usage is different. These are the defaults:

To override this behavior for UNIX and Linux server-side processes, edit the server's .agprofile file. Look for the case statement and update the definition of the native search path for your platform (LD_LIBRARY_PATH) to point to the JVM you want.

On NetWare

On NetWare, by default the server-side processes and clients all use the client HotSpot JVM.

To change the JVM:

1. Stop all running Java applications.

2. Shut down the JVM by typing:

     java -exit
   

3. Choose one of these methods for changing to the server JVM:

   • Type load java -server

   • Set the JAVA_COMPILER environment variable:

       env JAVA_COMPILER=server
     

   • Set the JAVA_COMPILER in the sys:\etc\java.cfg file:

       JAVA_COMPILER=server
     

4. Restart Java by typing:

     load java.nlm
   

5. Restart the application server.

6. Restart other Java applications as desired.

Starting the server on a specific IP address or hostname

You can set the http-server.com.sssw.srv.host property in the httpd.props file (located in the server's \Resources directory) to direct the application server to start on a specific IP address or hostname. This feature is particularly helpful on machines with multiple network cards and multiple IP addresses (multihoming). This feature works identically on Windows and UNIX.

For example:

  http-server.com.sssw.srv.host=192.101.1.10

Shutting down the application server

Use the server Stop button on the SMC (see procedure below) to shut down the resident or selected server when you are taking the machine out of service or if you need to install a software patch.

NOTE:   If you want to stop and restart the server in order to activate properties you have modified, use the Restart button, as described in Restarting the application server.

To shut down a server:

1. Start the SMC.

2. Select the server you want to stop from the left panel.

3. Click Stop.

   The following confirmation displays:

   

4. (Optional) Select Deactivate server first if you want the server deactivated before it is shut down or restarted (see table below for more information).

5. Select OK.

What happens next depends on whether or not you selected Deactivate server first:

Restarting the application server

Using the Restart button is the recommended way to stop and restart a server to update server property changes you have made using the SMC.

You can restart a server only if it was started with SilverMonitor (the default). For more information, see Using SilverMonitor.

To restart an application server:

1. Start the SMC.

2. Select the application server from the left panel.

3. Click Restart. You are prompted to confirm the restart.

4. (Optional) Select Deactivate server first if you want the server deactivated before it is restarted (see table below for more information).

5. Select OK.

   What happens next depends on whether or not you selected Deactivate server first:

   Situation	Result
   Deactivate server first is not selected	The server is immediately restarted.
   Deactivate server first is selected	No new client sessions can be established, but existing client sessions continue to operate normally. In clusters, the restarted server is unregistered from the Load Manager so that new sessions will not be dispatched to the server (if you are using a third-party load manager, there is no way of notifying it that the server is deactivated). Once the last client session is closed (typically five minutes after the last client connection is closed), the server is declared deactivated and is restarted. NOTE:   The SMC is a client connection to the server, so you must either exit the SMC or remove the server from the SMC before the server can restart.

   The application server restarts using the same startup parameters as when it was originally started and picks up any changes you have made to the server's properties.

Maintaining processes running as services

Instead of manually starting the application server, you can run it as a service (or as a daemon in UNIX), so that it starts automatically when the server machine reboots. For information on installing the server to run as a service, see Installing Novell exteNd.

In addition to running the server as a service, you can also run the following server-side processes as services:

• Load Manager

• Dispatcher

• Cache Manager

To help you manage processes running as Windows services, the server provides SilverServiceUtil, a Windows utility that allows you to:

• Create, list, delete, and stop application server and non–application server services

• Define additional Windows services for application server processes

• Create new console log files each time an application server service is restarted

• Define command-line arguments that will be automatically passed to an application server process when it starts as a Windows service

• Reconfigure an existing application server process when it is running as a service

NOTE:   To initially get the server set up to run as a service, you should use the installation program, as described in Installing Novell exteNd. After you have the server running as a service, you can use SilverServiceUtil to maintain your service environment, including creating additional services on the same machine.

Using SilverServiceUtil

SilverServiceUtil is a command-line utility in the server's \bin directory.

To invoke SilverServiceUtil:

• Change to the \bin directory and enter:

    SilverServiceUtil
  

  You will see usage notes.

The utility has the following actions:

These actions are described next. For complete information about using each of the SilverServiceUtil actions, enter the following:

  SilverServiceUtil -action -help

Defining a dependent service

To make a service dependent on another service:

• Enter the following:

    SilverServiceUtil -addDepend -service serviceName -prereq prereqServiceName 
  

where:

When this dependency has been defined, the Windows service manager will not start serviceName until prereqServiceName has been started.

Creating a service

You can use SilverServiceUtil to create an application server service or a non–application server service.

Creating an application server service   You can use SilverServiceUtil to configure all installed application servers to run as a service.

To create an application server service:

• Enter the following:

    SilverServiceUtil -create -service serviceName -display displayName -program pathToExecutable 
    [-outputDir outputDirectory -maxOutputFiles numFiles -startupOptions options] 
  

where:

  nameOfService.out

  SilverAppServerService4.out

  nameOfService.nnn.out

  SilverAppServerService4.000.out

  SilverAppServerService4.001.out

Creating a generic service   You can also use this option to create a generic Windows service.

To create a generic service:

• Enter the following:

    SilverServiceUtil -create -service serviceName -display displayName -program pathToExecutable -generic 
  

Listing and deleting services

You can list all services defined on the current machine as well as delete any existing service.

To list all services:

• Enter the following:

    SilverServiceUtil -list [-d]
  

If you specify -d, the display name will be listed along with the service name.

To delete a service:

• Enter the following:

    SilverServiceUtil -delete -service serviceName
  

Specify the service name, not the display name. (You are not asked to confirm the deletion.)

Stopping a service

To stop a service:

• Enter the following:

    SilverServiceUtil -stop -service serviceName [-retries numRetries -delay retryDelay] 
  

where:

Reconfiguring a service

To reconfigure an existing application server service:

• Enter the following:

    SilverServiceUtil -update -service serviceName 
    [-outputDir outputDirectory -maxOutputFiles numFiles -startupOptions options] 
  

where the -outputDir, -maxOutputFiles, and -startupOptions arguments are the same as used in the create action.

The update action modifies the Windows registry entry for the corresponding service. The changes won't take effect until the service is restarted. You can start and stop services through the Windows Services control panel (without rebooting the machine).

Setting up separate ports

To restrict access to specific types of application server operations, you can define the following ports:

Each port type excludes URLs and operations that are not associated with it. For example, the administration port only passes administration URLs. The separate ports are designed to work in conjunction with your server permission settings. For example, if your administration and runtime ports are unique, any attempt to run an administration URL on the runtime port will fail. Once a user successfully accesses an administration port, the server checks the user's group permissions to further determine the level of access.

How you configure a public site would probably be different from the way you would configure an e-commerce site that uses credit card transactions. Particularly in an extranet environment, you don't want users attempting to perform administration operations that alter your application data. Configuring multiple server ports in conjunction with your corporate firewall lets you manage internal and external access to your applications.

Using separate ports with your firewall

There are several security advantages to defining separate application server ports for different types of users and operations:

• Opening a single runtime port through your firewall for users outside your organization limits your security risk.

• Separating administration and runtime port access helps prevent unauthorized users from attempting to administer the server. Users connecting to your applications may know the runtime port number, but only administrators need be aware of the administration port.

• Defining an administration port that can only be accessed from inside the firewall helps restrict calls made to that port.

About enabling ports

The server supports administrative and runtime ports for each of these protocols:

By default, only the HTTP port is enabled. The DSA and RSA ports are set to the default values, but not enabled. The server is not listening on the DSA and RSA ports until you enable them.

When the application server starts, it binds a socket to each unique port value you have configured and enabled. The application server does not require unique port values for the different types of access; ports having the same value will share the same socket and allow multiple operations. For example, if you set your HTTP runtime and administration ports to 8080, the application server will use only one socket to accept requests for both.

TIP:   When you install the application server, the HTTP runtime and administrative ports are configured to whatever port number you specify as the default. You will need to update your program shortcut used to launch the SMC if you configure a separate administration port after you install the application server.

    For alternative ways to start the SMC, see Running the SMC.

Clients connecting to an administration port can perform only operations associated with that port. Because many objects involved with administration require runtime support, runtime operations can be performed on any port. However, runtime ports only allow runtime operations.

    For how to enable HTTP ports, see Specifying general server properties. For more information about enabling HTTPS ports, see Enabling RSA/DSA ports.

Port types

The application server can be set to a maximum of six unique port numbers for HTTP/HTTPS communications. The type of operations a port allows and its associated security protocols can be configured independently—that is, you can mix any of the three security protocols with any of the three port types:

All port property names (as defined in the https.props file) begin with http-server. For more information, see Appendix A, "The httpd.props File".

Specifying general server properties

General server properties include:

• HTTP listener ports

• Name of the SilverMaster database

• User account that starts the server on UNIX

To specify general server properties:

1. Start the SMC.

2. Select the server.

3. Select the Configuration icon from the toolbar.

4. Select General:

   

5. Edit any of these fields as needed:

   Field(s)	What to specify
   Enable HTTP runtime port and Port number Enable HTTP Admin port and Port number	To enable HTTP listener ports, select any or all of the HTTP port options and then specify a corresponding port number. By default for all HTTP port types, the application server listens on port: 83 in NetWare 8080 in UNIX 80 in Windows The default port for HTTPS (RSA) and HTTPS (DSA) is 443.     For more information, see Setting up separate ports.     To disable HTTP communications, see Turning off HTTP communications.
   Username for server (UNIX only)	To specify the user under whose account the server is started on UNIX. The default is root.
   SilverMaster database name	To change the SilverMaster database the server uses. For example, you might need to change the name of the SilverMaster database if you are setting up a load balancing cluster. All servers in a cluster must use the same SilverMaster database. You'd use this field to specify the SilverMaster database name.

6. Click Update.

7. To activate the changes, click Restart.

       For more information, see Restarting the application server.

Using server logging

The application server provides logging for things like server debugging, server monitoring, and security auditing. You can log the information to a file or a database, or you can specify your own custom class to perform the logging.

To turn on logging:

1. Start the SMC.

2. Select the Configuration icon from the toolbar.

3. Select General:

   

4. Select the logging option(s) you want to turn on or off as follows:

   Field	Description	Usage
   Database logging	Logs messages to SilverMaster. Messages are stored in the AgLog, AgErrorLog, and AgTraceLog system tables.	This is the default setting.
   File logging	Logs messages to files that you specify.	Specify the file name for each option you activate in the text field next to the option (which is enabled if either File logging or User Defined is selected).
   User Defined	Uses a custom Java class to do the logging.	By default, the application server uses its own internal class to do the logging. If you want to customize the log output—for example, to specify an extended log file format—you can write your own logging class and then specify it here.     To learn how to create and use a custom logging class, see Using the Server Administration API.
   Enable HTTP logging	Writes a line in the AgLog table (or file you specify) for every client request to the server and every server response.	Run in conjunction with error logging. Use standard HTTP logging when you want to see client requests to the server and also when you want to monitor server activity. Use in conjunction with the Statistics/Summary/Request time option in the SMC (see Summary statistics).     For more information, see About HTTP logging.
   Enable Error logging	Records errors and miscellaneous status information in the AgErrorLog table (or the file you specify). If you enable this type of logging, you get more detailed information about server errors and status.	Turn this option on.
   Enable Trace logging	Records server actions. Unlike HTTP logging and error logging, trace logging concentrates on tracking server events as well as error messages. When enabled, the AgTraceLog table (or the file you specify) contains additional tracing information that Technical Support uses to track down server issues.	Turn this option on only if Technical Support requests it.

5. Click Update.

   The application server starts logging the specified information.

About HTTP logging

When you enable HTTP logging, by default the server logs HTTP messages in the standard W3C common log file format (see www.w3.org) to the database. You can redirect the log to a file as described above.

There is also a compound log file format, which is like the common log file format except that it also logs the Referrer (which allows click tracing) and User-Agent (which logs the browser type) fields from each HTTP request. The application server provides built-in support for the compound log file format.

To log using this format:

1. In the SMC, under Server logging select User Defined.

2. In the Java class field, specify the following:

     com.sssw.srv.http.CompoundLogger
   

3. Specify the file to log the HTTP requests to (and optionally, files for error and trace logging, also supported by the CompoundLogger class).

4. Restart the server.

TIP:   Instead of using the SMC, you can also specify compound logging by setting these values in httpd.props and restarting the server:

  http-server.com.sssw.srv.logger=com.sssw.srv.http.CompoundLogger
  http-server.com.sssw.srv.logger.logname=fileName

Viewing the log

If you are using the built-in logging class, you can view the log in the SMC (see Displaying logs). You can also use the SilverCmd PrintLog to view the log in the SilverCmd console window or a file. PrintLog allows you to view the data regardless of whether you are using the built-in logging class or the database.

Maintaining log tables and files

Log information can expand quickly. Clean out your log tables and log files to keep them manageable. You can use SilverCmd ClearLog to delete records. Use your native database utilities to maintain these tables, or use any editor to shorten or delete extraneous information from log files.

Specifying ORB settings

You can use the SMC to specify whether to use RMI—and if so its name services port, whether to use SSL for the remote objects, and the ports to use for IIOP SSL.

To specify ORB settings:

1. Start the SMC.

2. Select the Configuration icon from the toolbar.

3. Select General:

   

4. Specify the RMI options:

   Field	Description
   Name services port	The port the application server starts the RMI name services on (for example, all clients that need to find an EJB use this service). The default is 54890.
   Enable RMI Server	Specifies whether to enable use of RMI for unencrypted client communications. You can enable RMI separately or together with HTTP. If selected, the application server exports a remote server object using RMI/IIOP and accepts RMI sessions, so that non-HTTP clients don't require an HTTP session on the server. If this option is not selected, the RMI server is not created and does not accept RMI sessions. NOTE:   To encrypt a remote transaction, enable the Use SSL for Remote Objects option.
   Use SSL for Remote Objects	Specifies whether to use SSL encryption to secure the RMI Server (if enabled), remote sessions, and the remote user transaction. If selected, remote objects (such as EJBs) can be encrypted and exported by non-HTTP clients using RMI/IIOP.
   IIOP SSL min port	Specifies the lower bounds (in a range) for IIOP SSL communications. If you do not specify a range, the ORB picks the first available port. Use –1 when you do not need to specify a range. You must create an IIOP SSL port range: To allow interoperability with network firewalls. Controlling the range used by IIOP SSL communications allows the firewall administrator to open these ports and configure traffic appropriately. When your environment supports session-level failover for EJBs using IIOP SSL communications. The range must be large enough to allow one port for each unique combination of EJB security attributes used by the beans deployed on your system. The maximum number of combinations of security attributes (and therefore the largest range) is 64 (when using the standard set of cipher suites). A range of 16 is a reasonable number of ports for most common installations.
   IIOP max port	Specifies the upper bound (in a range) for IIOP SSL communications. If you specify –1, there is no upper bound to the range.

5. Click Update.

6. To activate the changes, click Restart. For more information, see Restarting the application server.

Running multiple servers on one host

You can run more than one application server on a host at one IP address. (The application server also supports multihoming, where you have multiple IP addresses through multiple network cards on one host. See Starting the server on a specific IP address or hostname).

Specifying unique ports   Multiple servers running on one host must be configured to use unique ports. You can specify runtime and administration ports in the SMC:

Specifying character set encoding

The application server uses the following server property when URL-encoding and -decoding form content:

  com.sssw.srv.international.UrlEncoding

The encoding property is stored in the AgUserIni.props configuration file, which is located in the server's \Resources directory.

By default, the application server uses utf-8 (Universal Character Set Transfer Format) for URL encoding and decoding. Because utf-8 can encode ASCII characters without requiring modification, utf-8 works well for English and most other Western languages. Because languages using multibyte encodings are not a subset of utf-8, character encoding and decoding will not work properly with them.

When to change the encoding scheme

You typically need to change the encoding scheme only when the majority of client browsers in your environment use character encodings that are not ISO 8859-1 (Latin 1). For example, a Japanese Web site that serves content to its employees using the ShiftJIS encoding may want to change the encoding property to SJIS.

To change from the default utf-8 to another encoding:

1. Add the following line to the AgUserIni.props file (located in the \Resources directory below the application server's root directory):

     com.sssw.srv.international.UrlEncoding=NewEncoding 
   

2. Enter the language mapping needed at your site in place of the NewEncoding variable. If you are unsure about the Java string mapping for your language, check the Sun Web site.

3. Restart the application server.

   URL content will be encoded using the new encoding scheme after you restart the server.

Running the JMS server

The application server includes the Novell exteNd JMS server for its JMS (Java Message Service) implementation. That means the exteNd JMS server provides the JMS server that runs with the application server to support messaging in your J2EE applications.

This section describes some things you need to know about using the Novell exteNd JMS server with the application server:

• Starting the JMS server

• Using JMS servers in clusters

• Displaying JMS server debug messages

    To learn more about the JMS server, see the Novell exteNd Messaging Platform help.

Starting the JMS server

You can start the JMS server in either of two ways:

  http-server.com.sssw.srv.jmsServerLaunch=true

Using JMS servers in clusters

You can increase the reliability of JMS servers in your environment through the use of clusters. Here are some common configurations:

Displaying JMS server debug messages

You can troubleshoot JMS server–related problems at runtime by displaying debug messages to the application server console. To turn on basic JMS server debugging, edit the application server's httpd.props file to specify this property setting:

  http-server.com.sssw.srv.jms.debug=1

For more detailed JMS server debugging, specify a number greater than 1 for this property. To disable JMS server debugging, specify 0 (the default).

Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...