Administrator's Guide



Chapter 5   Running the Server

This chapter describes how to run the SilverStream Server.

It contains sections on:

Starting the SilverStream Server   Top of page

This section provides platform-specific information for manually starting the SilverStream Server.

NOTE   You can also run the SilverStream Server in the background as a service in Windows NT or as a daemon in UNIX. For more information, see the sections in the Installation Guide on running the server as a service or a daemon.

This section contains the following information:

Starting the server in Windows NT   Top of page

You can start the SilverStream Server using either of the following methods:

Using startup options   Top of page

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

When passing the options that were specified with the plus sign to the JVM, SilverStream changes the pluses to minuses for processing by the JVM.

Example

Say you specify the following command line:

  SilverServer +verbose -port 84 -nodbcheck 

The equivalent command line is:

  java -verbose ServerStartupClass -port 84 -nodbcheck 

Using +options

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

Command

Description

java -?

Lists standard options.

java -X

Lists non-standard options. Note that these options are subject to change without notice.

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

To start the server with command-line options:

  1. Open a DOS command box.

  2. Change your directory to SilverStream\bin.

  3. Type SilverServer.exe and any command-line options.

    Select from the following startup options.

    Server startup option

    Description

    Supported Java options: +<x>
    (These options are passed to the JVM. For more information about the non-SilverStream + options, see your Java documentation.)

    +classic

    SilverStream-specific option.

    You must set this option along with +profile to profile server-side applications when you are running a version of the Sun Microsystems HotSpot JVM that does not support the Java Virtual Machine Profiler Interface (JVMPI).

        For more information, see SilverStream Profiler in the online Tools Guide.

    +cp:a path

    Appends specified path to the class path. This option makes additional Java classes available to SilverStream applications by appending the specified path to the class path.

    NOTE   It is recommended that you use the AGCLASSPATH environment variable to extend Java classes. For more information, see Setting the AGCLASSPATH variable.

    +cp:p path

    Prepends specified path to the class path. Don't use this debugging option without first contacting technical support. Instead, use AGCLASSPATH to make additional Java classes available to SilverStream applications. For more information, see Setting the AGCLASSPATH variable.

    +debug

    SilverStream-specific option.

    You must set this option to debug server-side objects.

        For more information, see the SilverStream Debugger in the online Tools Guide.

    +Djava.compiler=none

    SilverStream-specific option.

    You must use this option with +profile if you want the Profiler Timing tool to provide detailed information about how method duration is distributed across nested calls in server-side processes.

        For more information, see SilverStream Profiler in the online Tools Guide.

    +profile

    SilverStream-specific option.

    You must set this option to profile server-side applications.

        For more information, see SilverStream Profiler in the online Tools Guide.

    +verbose[:class | gc | jni | vmopts]

    Run the JVM verbosely.

    There is a SilverStream-specific option for +verbose:

      +verbose:vmopts 

    Specifying this option tells SilverStream to output the startup options to the console, without all the other output generated in verbose mode.

    +Xms size

    Initial Java heap size within the VM. Default value is 16 MB.

    +Xmx size

    Maximum Java heap size within the VM. Default value is 256 MB.

    You can override +Xms and +Xmx if you want. For example, if you are running a development server that only services one user, you might want to run the server with a lighter memory footprint using the following command line:

      SilverServer +Xms2m +Xmx16m 

    This sets the initial Java heap size to 2 MB and the maximum heap size to 16 MB.

    SilverStream Server options: -<x>
    (These options are passed to the SilverStream Server.)

    -? or -help

    Print usage for SilverServer.exe.

    --a

    Print the server startup properties, then exit without starting the server.

    This debugging option is useful if the server fails to start. You can see what the startup properties are.

    -host hostname

    The full name of host running the server. Not required unless there are problems with host name resolution.

    -jvmversion

    Print information about the Java VM.

    -minspan number

    Use with -retry number: The duration in minutes within which the retries must be made. SilverMonitor ceases to operate after the number of minutes specified by minspan, even if not all retry attempts had been made. The default value is 10.

        For more information, see Using SilverMonitor.

    -nodbcheck

    Don't check database integrity at startup.

    This option is useful when you have a database that is not synchronized. Using this option and noexitondbcheck are the only ways the server will start if the databases are out of synch.

    If you are sure your databases are synchronized, you can also use this option to shorten the server startup time.

    -noexitondbcheck

    Don't exit if the database integrity check fails.

    Use this option to check integrity and allow access to the SMC if the database check fails.

    -nomonitor

    Run without the SilverMonitor background program.

    This option is useful for debugging the server when it fails to start. If the option is not used, the server will keep trying to start.

        For more information, see Using SilverMonitor.

    NOTE   If you start the server with -nomonitor, you will not be able to restart the server from the SMC (or using the API). You will have to shut down the server, then start it again manually.

    -noserverlisteners

    Do not run any business objects.

    This option is useful if there are problems in your business objects.

    -nostartagents

    Do not run ServerStart business objects.

    This option is useful if you are having problems starting the server.

    -p file

    Read startup properties from a specified file.

    Defaults to SilverStream\Resources\httpd.props.

    -retry number

    The number of times SilverMonitor should attempt to restart the server or process before ceasing to operate. The default value is 3.

        For more information, see Using SilverMonitor.

    -trace

    Turn tracing on. Dump tracing information to the default or specified log output.

Starting the server on UNIX   Top of page

To start the server on UNIX:

  1. From the command line, change the directory path to /usr/local/silverstream/bin

    (This is the default installation path; adjust the path if you didn't take the default.)

  2. Type ./SilverServer and any command-line options. To print a list of available options, enter the following:

      ./SilverServer -? 

    For more information on providing command-line options, see Using startup options.

Starting the server on a specific IP address or hostname   Top of page

You can set the http-server.com.sssw.srv.host property in silverstream\resources\httpd.props to direct the SilverStream 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 (multi-homing). This feature works identically on Windows NT and UNIX.

For example:

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

Shutting down the SilverStream Server   Top of page

Use the server Stop button on the SMC to shut down the resident or selected server. Use this option to shut down the system when you are taking the machine out of service, or if you need to install a software patch. If you want to stop and restart the server in order to activate properties that you have modified, use the Restart button, described in the next section.

NOTE   You can also shut down the server from the Main Designer. See Main Designer in the online Tools Guide.

To shut down a server:

  1. Invoke the SMC.

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

  3. Select the Stop button. The following confirmation appears.

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

  5. Select OK.

What happens next depends on whether you selected Deactivate server first.

Situation

Result

Deactivate server first is not selected.

The server is immediately shut down or restarted.

Deactivate server first is selected.

No new client sessions can be established, but existing client sessions continue to operate normally. In clusters, the deactivated server is unregistered from the Load Balancer so new sessions will not be dispatched to the server (if you are using a third-party load balancer, SilverStream has 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 shut down or restarted.

    For information on programmatically handling server deactivation, see the chapter on server-triggered business objects in the Programmer's Guide.

Restarting the SilverStream Server   Top of page

Use the Restart button to stop and restart a server. This is the recommended way to stop and restart a server in order to update server property changes that you have made using the SMC.

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

NOTE   You can also restart the server using the Main Designer. See Main Designer in the online Tools Guide.

To restart a server:

  1. Invoke the SMC.

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

  3. Select the Restart button.

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

        For information on starting the SilverStream Server in the background as a service in Windows NT or as a daemon in UNIX, see the sections in the Installation Guide on running the server as a service or a daemon.

Specifying general server properties   Top of page

You can use the SMC's General panel to specify these general server properties:

To specify general server properties

  1. Invoke the SMC.

  2. Select the server you are administering.

  3. Select Configuration options.

  4. Select the General panel.

  5. Edit any of these fields as needed.

    Field

    Description

    Enable HTTP port and Port number

    By default, the SilverStream Server listens to one port at a time for HTTP and one or two ports for HTTPS (if you use SSL). The default ports are 80 for HTTP, 443 for HTTPS (RSA), and 444 for HTTPS (DSA).

        For more information about HTTPS and security, see Setting Security.

    To reset the HTTP listener port, select Enable HTTP port and specify a different port number.

    NOTE   You can also disable HTTP communications. For more information, see Turning off HTTP communications.

    Username for server (UNIX only)

    You can specify the user under whose account the server is started on UNIX. By default, it is root.

    SilverMaster database name

    SilverStream relies on a master database catalog called the SilverMaster for overall system management. This database is specified during installation. By default, it is named SilverMaster35.

    If you need to change the database used as SilverMaster (for example, you are setting up a cluster and need to change all servers in that cluster to use the same SilverMaster), you can change it in the SilverMaster field.

  6. Click Update.

  7. To activate the changes, select the Restart button. For more information, see Restarting the SilverStream Server.

Using server logging    Top of page

SilverStream offers logging options that you can use for various purposes, such as server debugging, general server monitoring, and security auditing. These options allow you to log information to a file or a database or to specify your own custom class to perform the logging. For information about generating and storing server output, see SilverStream Server logging properties when run as a service.

To turn on Logging:

  1. Invoke the SMC.

  2. Select Configuration options.

  3. Select the General panel.

  4. Select the logging option(s) that you want to turn on or off as described in the following table.

    Field

    Description

    Usage

    Database logging

    Log messages to SilverMaster. Messages are stored in the AgLog, AgErrorLog, and AgTraceLog system tables.

    This is the default setting.

    File logging

    Log messages to files that you specify.

    Specify the file names for each option that you activate in the text field next to the option, which is enabled if File logging or User Defined is selected.

    User Defined

    Use a custom Java class to do the logging.

    By default, SilverStream 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, then specify it here.

        To learn how to create and use a custom logging class, see Administration Techniques in the online Application Techniques.

    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.

    The messages are saved in the standard W3C common log file format (see www.s3.org).

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

    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.

    SilverStream recommends that you 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 SilverStream Technical Support uses to track down server issues.

    Turn on this option only if SilverStream Technical Support requests it.

  5. Click Update.

    SilverStream starts logging the specified information.

What you can do

If you are using the built-in logging class, you can view the log in the SMC (see Displaying logs).

If you are logging to the database, you can also use the Form Designer or View Designer to build a form or view to view the log.

NOTE   Log information can expand quickly. Clean out your log tables and log files to keep them manageable (a SilverStream developer can write a timed business object to do this). Use your native database utilities to maintain these tables, or use any editor to shorten or delete extraneous information from log files.

SilverStream Server logging properties when run as a service   Top of page

The SilverStream Server uses the following two startup properties to log information when it is being run as an NT service.

These properties are stored in the httpd.props configuration file located in the silverstream\resources directory on your system. Server logging can help you debug server configuration problems, such as when a database is removed.

    For information about modifying SilverStream properties, see The httpd.props File.

The system.out.log.allowed property

determines whether the SilverStream Server service will log output to System.out and System.err. By default, this property is set to false so that log output is not generated and stored until you want to look at it. When you set this property to true (as in the following example) the server service directs log output to the file specified by the system.out.log.file property.

  http-server.com.sssw.srv.system.out.log.allowed=true 

The system.out.log.file property

specifies the name and location of the file that stores the log output when the system.out.log.allowed property is true. The following is an example of how this property might be set:

  http-server.com.
sssw.srv.system.out.log.file=D\:\\temp\\SilverServerSysOut.txt

NOTE   By default, the log location and file name are silverstream\temp\SilverServerSysOut.txt

Specifying RMI settings   Top of page

You can use the SMC to specify whether you are using RMI and, if so, its transport protocol and name services port.

  1. Invoke the SMC.

  2. Select Configuration options.

  3. Select the General panel.

  4. Specify the RMI options.

    Field

    Description

    Key

    Specifies the transport protocol. Currently, this is required to be the JBroker ORB.

    Name services port

    The port that SilverStream 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

    Specifies whether you want to enable use of RMI in client communications.

    If this is selected, the SilverStream Server exports a remote server object via RMI/IIOP and accepts RMI sessions, so that non-SilverStream clients that want to call invoked business objects (especially EJBs) on the SilverStream Server don't need to get an HTTP session on the server.

    If this option is not selected, the server does not create the RMI object and does not accept RMI sessions.

  5. Click Update.

  6. To activate the changes, select the Restart button. For more information, see Restarting the SilverStream Server.

Running multiple servers on one host   Top of page

You can run more than one SilverStream Server on a host at one IP address. (SilverStream also supports multi-homing where you have multiple IP addresses through multiple network cards on one host; see Starting the server on a specific IP address or hostname).

If you choose to run more than one server on a host with the same IP address, you need to be aware of the following issues:

Specifying unique ports   Top of page

Multiple servers running on one host must be configured to use different ports. You can specify all the ports in the SMC.

Port

Default

Information on setting

HTTP

80

Specifying general server properties

RSA (used with HTTPS/SSL communications with an HTML client)

443

Enabling RSA/DSA ports

DSA (used with HTTPS/SSL communications with a Java client)

444

Enabling RSA/DSA ports

RMI name services

54890

Specifying RMI settings

Properties shared by all servers in a cluster   Top of page

If you are running a cluster with more than one SilverStream Server on the same host using the same IP address, there are some limitations regarding server-level properties. The following properties are actually per-host properties and will be used by all servers in the cluster that are on the same host. That is, if you change one of these properties for a server on a host, the property is changed for all other servers in the cluster running on that host. The properties are settable in the SMC.

Buffer properties

    For more information, see Setting performance parameters.

Cache properties

    For more information, see Managing the server content cache.

Cache Manager properties

    For more information, see Managing failover.

Client connection properties

    For more information, see Managing client connections.

Database properties

    For more information, see Setting the maximum and minimum number of database connections.

Load Manager properties

    For more information, see Managing failover.

UNIX user name property

    For more information, see Specifying general server properties.






Copyright © 2000, SilverStream Software, Inc. All rights reserved.