Administrator's Guide

Chapter 7   Maintaining the Server

This chapter describes how to perform some typical server maintenance tasks. It has sections on the following:

• Administering a SilverStream server remotely

• Setting up mail on the server

• Managing licenses

• Setting the AGCLASSPATH variable

• Maintaining J2EE deployed objects

• Setting Fulcrum full-text properties

• Monitoring server activity

• Integrating with existing Web servers

Administering a SilverStream server remotely

You can use the SilverStream Management Console (SMC) to remotely administer servers. You can administer as many servers as you want from one SMC console. If you are running a server in a cluster, you can choose additional server clusters to administer. For more information about server clusters, see Server clustering.

To choose a server:

1. Verify that the server you want to administer is up and running.

2. Invoke the SMC.

3. Choose the Choose (server) icon.

4. Type the server name and specify the port if it is not the default 80.

   

5. Click OK.

6. Use the SMC to administer the server.

Setting up mail on the server

Handling mail received from clients is an important aspect of Web application development. SilverStream developers might write business objects that trigger when mail is received on the server. To implement this type of object, the SilverStream server must be configured to poll for e-mail in one or more mailboxes from one or more POP3 or IMAP servers.

The Mail option on the SMC allows you to set up mailboxes for this purpose. For example, if a developer needs a business object to automate the maintenance of a mailing list in the database, you would first create a mail account for mailing list maintenance. Then the developer could write a business object that looks at e-mail received at that mailbox for subscribe and unsubscribe requests.

NOTE   You can configure mail-triggered business objects messages in JavaMail format. The JavaMail format enables you to manipulate received messages and send new messages using the standard J2EE mail API.

To poll for mail:

1. Invoke the SMC.

2. Select Configuration options.

3. Select the Mail panel.

   

4. Click New and enter data in the fields. You must provide data for all of the fields displayed on this tab.

   Field	Entry
   Check for mail every n minutes	The time interval for the mail server to check for incoming mail messages. Enter a value or use the spinner control. When set to zero, the server does not check for mail.
   Username	The e-mail ID that the server uses to receive mail. This name is like any other mail account name on your system. Make sure you set up a mail account specifically for the server and not for an individual user. The name is a POP3 or IMAP mail account, and it should be unique to the SilverStream server.
   Password	The password for the mail account.
   Server	The name of the mail server. For example, mail.myCompany.com
   Port	The port number the mail server uses to receive mail. The default port number is 110 (the default for a POP3 server). The default port number for IMAP is 143.
   Protocol	The mail protocol used to receive mail. The default is POP3. You may also choose IMAP.
   Option	The format in which received messages are available: AgoMail or JavaMail. The default mail format is SilverStream AgoMail. You can only use AgoMail with Pop3. JavaMail can use IMAP or POP3.

5. Click Update.

   The new settings take effect immediately.

Once enabled, the SilverStream server acts as a POP3 or IMAP client.

Managing licenses

This section describes how to install or delete SilverStream user licenses.

About licenses

SilverStream uses a license key to administer access to the server. License management is integrated with session management. Each user connection requires a license. The license is held for the duration of the connection.

License keys:

• Have limits on either users or CPUs

• Are tied to a server machine Host ID

You receive an initial encrypted license key when you buy your product. Each product you purchase comes with a certain type of license. You use the Installation program to add this license key to your server. This information is stored in the database.

You may only need the initial user-based license key during your application development cycle. However, when it comes time to deploy your application and go live, you will probably want to call SilverStream and purchase CPU-based licenses for your application server.

If you have a user-based license and your application is put into production, when the number of simultaneous users increase you may see a message like Maximum server sessions exceeded.

You should add new licenses through the SilverStream Installation program.

When you have multiple licenses installed, SilverStream will use the least restrictive license it finds. For example, if you have installed both a single-user license and a CPU-based license, SilverStream uses the CPU-based license.

To add licenses (NT):

1. Shut down the SilverStream server.

2. Run the SilverStream Installation program.

3. From the Setup Function screen, select Add a new server license.

   The License Information screen appears.

4. Fill in the license serial number.

   TIP   If you receive this long encrypted number electronically, paste it into the License number field to avoid typing errors.

5. Specify the requested information for your SilverMaster, where the license information is stored.

6. Click Finish.

   SilverStream uses the license number and other information you enter to generate an encrypted license key.

To add licenses (UNIX):

1. Shut down the SilverStream server.

2. Run the upldlic.sh utility, which is at the root directory on the SilverStream CD.

3. When prompted, specify where SilverStream is installed and what the license string is.

   SilverStream generates an encrypted license key.

To access or delete a license:

1. Invoke the SMC.

2. Select Configuration options.

3. Select the Licenses panel.

   The license form displays information about your license.

4. To delete a license, select it and then select Remove License.

Setting the AGCLASSPATH variable

SilverStream supports an environment variable called AGCLASSPATH, which allows you to extend the Java classes used by your application. You can use AGCLASSPATH, for example, when you want to include third-party elements such as database drivers with your application. Use this variable instead of the +cp Java class path option described in Starting the SilverStream server. SilverStream overrides the CLASSPATH variable.

NOTE   When deploying business objects using created Java classes, SilverStream developers should create JAR files using the SilverStream Designer, rather than by setting AGCLASSPATH. For more information, see the Programmer's Guide.

In UNIX, set the environment variable AGCLASSPATH following the appropriate procedure for the shell you are using. For NT, use the following procedure.

To set AGCLASSPATH in NT:

1. From the NT Start menu, choose Settings>Control Panel.

2. Choose the System icon, then select the Environment tab.

   The following screen appears.

   

3. Type AGCLASSPATH in the Variable field, then type a path in the Value field.

4. Click Set.

   The screen above shows AGCLASSPATH with a value of c:\myclasses.

Maintaining J2EE deployed objects

You can use the SMC to view J2EE objects that have been deployed on a server. The only objects that you can enable, disable, or shut down are the EJB JARs that have been deployed in the selected database.

The Deployed Objects panel lists:

• EJB JAR files containing Enterprise JavaBeans (EJBs)

• WAR files containing JSPs and servlets

• EAR files that package other archive files into a full application

• J2EE application-client deployments

    For more information, see the J2EE deployment chapter in the Facilities Guide of the server's Core Help.

To manage the EJBs:

1. Invoke the SMC.

2. Select Configuration options.

3. Select the Deployed Objects panel.

4. Expand the database you want to manage.

   The only objects you can select and act upon in this panel are the EJB JARs (and the beans in the JARs) that have been deployed in the selected database.

   To delete any deployed object (other than EJBs), use the Designer.

   

5. Select an EJB JAR and perform one of the following actions.

   Action	Description
   Enable EJB JAR	Enable a disabled EJB JAR. If a JAR is enabled, the beans in the JAR are available.
   Disable EJB JAR	Disable an enabled EJB JAR. If a JAR is disabled, none of the beans in the JAR are available. Disabling a JAR stops any running EJBs in the JAR. A disabled JAR remains disabled until it is explicitly enabled.
   Shut Down EJB JAR	Shut down the JAR and all its beans for the current server session. When a JAR is shut down, none of the beans in the JAR are available. When the server is restarted, enabled JARs that had been shut down in the previous server session are again available.

Setting Fulcrum full-text properties

You can use the SMC to set some administrative properties used by the Fulcrum SearchServer full-text search engine.

    For more information about Fulcrum SearchServer and how to enable full text search in SilverStream applications, see the full-text search chapter in the Tools Guide of the server's Classic Development Help.

To set Fulcrum full-text properties:

1. Invoke the SMC.

2. Select Configuration options.

3. Select the Advanced panel.

4. Select the Full Text tab.

   

5. Specify values as described below.

   Property	Description
   Indexer interval	Specifies how often Fulcrum SearchServer checks and performs incremental indexing for rows whose full-text-search columns have been modified. The default is 20 minutes. NOTE   Indexing is forced before a query against a modified table is processed.
   Maximum result row count	Maximum number of hits Fulcrum will return for a full text search query. The default is 1000. Set this value to 0 if you don't want any limit to the number of hits returned.
   Enable partial indexing at startup	If this property is selected, SilverStream will not reindex tables marked for full text search at server startup time.     For more information, see Indexing full-text-search tables below.
   Disable indexing before full-text search	If this property is selected, SilverStream will not perform any indexing before a full-text-search even if columns have been modified. This property is useful when you have large tables that don't often change that you want to search. By default, this property is not set.

6. Click Update.

Indexing full-text-search tables   If the Enable partial indexing at startup property is not selected, at startup time the SilverStream server deletes all previous full-text indexing from all tables that have full index search enabled, then reindexes all the tables from scratch. After the initial indexing, the tables are marked for incremental indexing only when updates are made to them within SilverStream.

Full reindexing of tables consumes resources unnecessarily if the tables are never updated outside SilverStream.

You can select the Enable partial indexing at startup property (which is selected by default) to turn off full reindexing when the server starts. This means that at server startup, previous indexes will be maintained, tables will be marked for incremental indexing, and incremental indexing for SilverStream-modified tables will continue.

If Enable partial indexing at startup (or Disable indexing before full-text search) is not selected, full-text search tables will be indexed from scratch each time the server starts.

NOTE   If you set Enable partial indexing at startup but still have some tables that are updated outside SilverStream, you can specify full indexing for these tables: open the SilverStream Business Object Designer and create a business object that will fire when the server is started. Add the following line of code for each table that you want to be reindexed:

  com.ssw.srv.agents.AgFullText.index("db", "table");

Monitoring server activity

The SMC provides several options that allow you to easily monitor server activity. These options are described in the following sections:

• Displaying charts of server activity

• Displaying logs

• Displaying views of server statistics

Displaying charts of server activity

You can display real-time charts of various server statistics.

To display a chart of server activity:

1. Select the server or cluster you are administering.

2. Select Monitor options.

3. Select the Charts panel.

   An empty chart displays.

   

4. Click Add Plot.

   The Add Plot dialog displays, allowing you to choose which statistics you want to chart. The statistics are divided into categories.

5. Select a statistic you want to chart and click Add. Statistics marked with are counts; statistics marked with record changes.

   The statistic is added to the table below the chart. The current value of the statistic is shown, as is the color of the plot line that will be generated.

6. Select additional statistics if you want, clicking Add after each one.

7. When you have selected all the statistics you are interested in, click Close.

What happens   SilverStream plots all the statistics you have specified and displays the exact values in the table below the chart. By default, the values are updated every five seconds.

Changing the scale and refresh rate

You can change the scale of the Y-axis by specifying a new value in the Scale field (the default is 100). You can also change how often SilverStream updates the values by changing the value in the Refresh interval field (the default is every five seconds).

Removing a plot

To remove a plot:

• Select a plot and click Remove plot.

Editing a plot

It may be that you are plotting different statistics with very different scales but want them to appear clearly in the chart. To do this, you can change the multiplier for particular plots to equalize the values and make the chart easier to read.

To edit a plot:

1. Double-click the plot in the table.

   The Change Plot Detail dialog displays.

2. Change the multiplier used to plot the value.

3. Click OK.

Saving a statistics set

Once you have charted a set of statistics that you are interested in, you can save the specification of the statistics set in a file so that you can easily view the set of statistics later.

NOTE   The file stores the list of statistics that are plotted. It does not store the statistics' values.

To save a statistics set:

1. Display the statistics you want to save as a set.

2. Click Save.

   The Save dialog displays.

3. Specify the file you want to save the statistics set in. If you don't provide an extension, SilverStream gives the file the extension META.

4. Click Save.

   The specifications for the chart are saved in a file. You can view the statistics set later by clicking Load, as described next.

Loading a statistics set

To view a statistics set you saved previously:

1. Click Load.

   The Open dialog displays.

2. Select the file that defines the statistics set you want to view and click Open.

   The chart is updated to show the statistics set that had been saved in the file.

Displaying logs

If you have enabled server logging and are using the built-in SilverStream logging class to log to the database, you can display the log(s) in realtime in the SMC. (If you are logging to a file or using a custom class to do the logging, you can't display the log in the SMC.)

    For more information about server logging, see Using server logging.

To display a log:

1. Select the server or cluster you are administering.

2. Select Monitor options.

3. Select the Logs panel.

4. Select the tab corresponding to the logging you have enabled and which you want to view.

   The log displays.

What you can do   You can:

• Update the log by clicking Refresh (the log does not update automatically).

• Sort a log by clicking a column's header.

• Resize a column by placing your mouse pointer on the column's right border and dragging the mouse.

Displaying views of server statistics

You can display in the SMC tabular views of server statistics related to individual sessions and threads, as well as a summary of server activity.

To access server statistics in a view:

1. Select the server or cluster you are administering.

2. Select Monitor options.

3. Select the Statistics tab.

   

4. Select the tab for the category you want.

   Statistics are updated dynamically.

What you can do   You can:

• Force an update by clicking Refresh.

• Resize a column by placing your mouse pointer on the column's right border and dragging the mouse.

About the statistics   The following sections describe the statistics that are displayed.

Session statistics

This tab displays statistics for each current client session.

Session statistic	Description
ID	Displays the session ID returned by a call to the AgiSession internal system table.
User name	Displays the user name of the person or entity logged on to this session. If unknown, displays Anonymous.
State	The state of the connection.
Logged in	Displays true if the user has logged in (for example, from the browser's login or the SilverStream Designer menu item). Otherwise, displays false.
Host	Displays the host of the client source, if known.
Idle time	Displays the time elapsed (in seconds) since the last client connection on this session ended.
Protocol version	Displays the SilverStream protocol used for the session.

Viewing statistics in a browser   You can also display these statistics in a browser: point your browser at http://server/SilverStream/Sessions.

Thread statistics

This tab displays statistics for each server thread.

Following is a description of each of the fields.

Thread statistic	Description
Name	Non-client threads are used for various internal tasks, such as cleaning up server data structures, indexing full-text tables, and so on. Client threads handle incoming requests. There should be at least as many client threads as there are MAXCLIENTCONNS listed in the SMC Connections panel (see Client connection parameters). ResultBuffer threads are prefetch buffer threads as defined in the SMC (see Setting performance parameters). They are dynamically added as needed, but should not exceed the number defined in the SMC.
State	A brief description of the current state of the thread.
Start date	The start date for the thread. In many cases this date is the same as when the server was started. However, for dynamically allocated threads (such as prefetch buffers) this value will be different.
Busy time	The elapsed time (in seconds) since the thread has been actively working, as opposed to waiting. This value reflects how busy the server is in general.
Session	An internal session ID for this thread. See the Sessions tab to determine user/host information.

Summary statistics

This tab provides access to different types of category summaries. The following describes the items for each tab selection.

• Server statistics

  Server statistic	Description
  Server load	Provides a scaled value, based on overall server activity.
  Total number of hits since server was last started	The number of HTTP message requests the server has received since it started.
  Date/time server was started	The date and time the server was started.
  Number of bytes emitted by server	The number of bytes returned by the server since it started.

• Request time statistics. The statistics for this tab are enabled only when HTTP logging is enabled. For a description of HTTP logging, see Using server logging.

  Request time statistic	Description
  Minimum request processing time	The minimum elapsed time to process any HTTP request, from when the server receives the header until it transfers the reply.
  Minimum request URL	The URL of the request that took the least amount of processing time (see previous item).
  Maximum request processing time	The maximum elapsed time to process any HTTP request, from when the server receives the header until it transfers the reply.
  Maximum request URL	The URL of the request that took the most processing time (see previous item).
  Mean request processing time	The mean (average) of the processing times for all requests received by the server.

• Memory statistics. The statistics for this option apply to the Java Virtual Machine (JVM).

  Memory statistic	Description
  Free memory	The result for the JAVA call Runtime.freeMemory()
  Total memory	The result of the JAVA call RunTime.totalMemory()
  GC count	The total number of times the JAVA Garbage Collector has run since the server has started. This number indicates how hard the server is being hit, how many objects are allocated, and how much memory pressure the server is under.

• Thread statistics. This option provides statistics about Client threads, which handle incoming client connections.

  Thread statistic	Description
  Free thread count	The current number of threads not associated with a client connection and available for immediate use.
  Idle thread count	The number of threads associated with a client connection, but not currently handling a user request.
  Total thread count	The total number of client threads allocated. This number should be equal to the Maximum number of client connections in the SMC Connections panel (see Client connection parameters).

Viewing statistics in a browser   You can also display most of these summary statistics in a browser: point your browser at http://server:port/SilverStream/Statistics. The page updates itself automatically every five seconds.

Integrating with existing Web servers

SilverStream provides two techniques that allow you to redirect requests for selected pages served by your Web server to a SilverStream server. The original technique is implemented by SilverJunction, an NSAPI/ISAPI module that can be installed on Microsoft Internet Information Server or Netscape Enterprise/Fast Track Web servers.

The newer technique--using SilverStream Web Server Integration (WSI) modules-- supersedes SilverJunction and addresses limitations found in SilverJunction. You should use the WSI modules instead of SilverJunction to integrate a SilverStream server with your Web server. See Using the Web Server Integration Modules.

If for some reason you want to use SilverJunction, however--read the following section.

Using SilverJunction

    For information on installing SilverJunction, see the Installation Guide.

Through the use of HTTP redirect mechanisms, SilverJunction allows for one-time redirects from standard Web servers. SilverStream uses two HTTP redirect calls: 302 for 1.0 implementations and 307 for 1.1 implementations. These implementations are executed at the browser level and are hidden from the user.

The example in this section describes a typical implementation of the SilverJunction plug-in. ABCDE Company has an IIS server that is accessible by clients at the host http://www.ABCDE.com. The company catalog resides at http://www.ABCDE.com/catalog. The catalog has been redesigned and improved using SilverStream, and now runs on a SilverStream server at the following URL:

  http://s2.ABCDE.com/productdb/Pages.

ABCDE's Webmaster does not want to break any existing links that may point to the old location of the catalog, so the Webmaster installs a SilverJunction filter (plug-in) for IIS on the original Web server. Then the Webmaster writes a configuration file specifying that all requests that come to the Web server at www.ABCDE.com and whose relative URL portion looks like "/catalog/*" should be redirected to http://s2.ABCDE.com/productdb/Pages/*.

Given this setup, an HTTP 1.1 browser pointed to:

  http://www.ABCDE.com/catalog/main.html

receives a temporary redirect (HTTP code 307) to:

  http://s2.ABCDE.com/productdb/Pages/main.html

If the SilverStream server is running as part of a cluster, the Dispatcher will redirect the request to an appropriate SilverStream server.

Once the user has been redirected to the SilverStream server, subsequent calls will go directly to the SilverStream server and not to the original Web server. The SilverJunction mechanism may mask the URL on the first redirect; but since the user has been fully redirected to the SilverStream server, the URL may not be masked on subsequent requests.

The following shows how SilverJunction works using a standalone SilverStream server. The initial client request directed at the IIS server is redirected back to the client to be re-sent directly to the SilverStream server.

The following shows how SilverJunction works in a clustered server environment. In this case the client request is redirected twice. The first redirect goes to the Dispatcher, which then redirects the request to an appropriate server. For more information, see Administering a Cluster.

To configure SilverStream as a plug-in:

1. Open the metadata file called SilverJunction.jdl, located in SilverStream/resources.

   By default, the configuration file SilverJunction.jdl is found in the Silverstream/resources directory. The IIS version of SilverJunction will always look for it in this location.

   For an NSAPI (NetScape) version, the location of the configuration file is determined by initialization parameters specified in the obj.conf file. This is done by inserting the following lines:

     Init fn=init_redirect
     conf_file="SilverStream/Resources/SilverJunction.jdl"
   

       For more information, see the Netscape Server documentation.

   The following is an example of a setup in SilverJunction.jdl:

     SILVER_JUNCTION
        TARGET_SERVER
           /Host  'machine.domain.com'
           /Port   8002
        endobj
        MAP 
           /From  '/S2/'
           /To    '/'
        endobj
        MAP
           /From  '/demo1'
           /To    '/silverstream1/db2/user3'
        endobj
     endobj
   

2. Edit the values as follows:

   You must enter a TARGET_SERVER. Both /Host and /Port properties must be defined.

   • The /Host property indicates the name of the machine to which redirects are sent

   • The /Port property indicates the port on which a dispatcher (in a cluster environment) or the SilverStream server is running.

   Specify at least one MAP. When specifying a MAP, both /From and /To properties must be defined:

   • The /From property indicates the prefix of the URLs that are redirected.

   • The /To property indicates the prefix that replaces that prefix when a request is forwarded to the redirect target.

Example   Given the settings in the preceding file, a request for /demo1/main.htm is redirected to:

  http://machine.domain.com:8002/silverstream1/db2/user3/main.htm

Administrator's Guide

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