Administrator's Guide
|
|
Administrator's Guide |
This chapter describes how to run the SilverStream server.
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:
You can start the SilverStream server using either of the following methods:
From Start>Programs>SilverStream version, select SilverStream Server.
Run the SilverStream server from a DOS command line by issuing the SilverServer command with one or more startup options, as described next.
There are two kinds of startup options you can provide on the command line with SilverServer:
Options passed directly to the JVM or handled by the SilverServer executable to launch the JVM. Specify these options using the plus (+) sign.
SilverStream-specific options passed to the SilverStream class that starts the server. Specify these options using the minus (-) sign.
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 -nodbcheck
The equivalent command line is:
java -verbose ServerStartupClass -nodbcheck
Using +options To see a list of possible options for the JVM, type the following commands:
|
Command |
Description |
|---|---|
Lists nonstandard 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:
Type SilverServer.exe and any command-line options.
Select from the following startup options.
|
Server startup option |
Description |
|---|---|
|
(These options are passed to the JVM. For more information about the non-SilverStream + options, see your Java documentation.) | |
|
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).
| |
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. | |
Prepends specified path to the class path. Don't use this debugging option without first contacting Customer Support. Instead, use AGCLASSPATH to make additional Java classes available to SilverStream applications. For more information, see Setting the AGCLASSPATH variable. | |
|
You must set this option to debug server-side objects.
| |
|
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.
| |
|
You must set this option to profile server-side applications.
| |
|
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. | |
Initial Java heap size within the VM. Default value is 16 MB. | |
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. | |
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. | |
The full name of the host running the server. Not required unless there are problems with hostname resolution. | |
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.
| |
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 sync. If you are sure your databases are synchronized, you can also use this option to shorten the server startup time. | |
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. | |
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.
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. | |
Do not run any business objects. This option is useful if there are problems in your business objects. | |
Do not run ServerStart business objects. This option is useful if you are having problems starting the server. | |
The number of times SilverMonitor should attempt to restart the server or process before ceasing to operate. The default value is 3.
| |
Turn tracing on. Dump tracing information to the default or specified log output. | |
To start the server on UNIX or Linux:
From the command line, change the directory path to SilverStreamInstallDir/bin.
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.
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 (multihoming). This feature works identically on Windows NT and UNIX.
http-server.com.sssw.srv.host=192.101.1.10
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, as described in Restarting the SilverStream server.
NOTE You can also shut down the server from the Main Designer. See Main Designer in the Tools Guide of the server's Classic Development Help.
Click Stop. The following confirmation appears.
Select Deactivate server first if you want the server deactivated before it is shut down or restarted (see below for more information).
What happens next depends on whether you selected Deactivate server first.
For information on programmatically handling server deactivation, see the chapter on server-triggered business objects in the Programmer's Guide of the server's Classic Development Help.
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 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 Tools Guide of the server's Classic Development Help.
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.
To restrict access to specific types of SilverStream server operations, you can define the following three types of ports:
A runtime port allows users to run Java and HTML application objects such as EJBs, JSPs, forms, views, pages, and so on using HTTP, HTTPS, or RMI.
A design port allows developers to build, test, and deploy applications by having the ability to read and write the design information for an EJB, page, form, business object, and so on. The design port is required for anyone running the SilverStream Designer, SilverCmd, or a third-party IDE.
An administration port allows administrators to set or modify server administration settings such as the ability to read and write server settings, security, license information, certificates, and so on. The administration port is required for anyone making Server Administration API calls using the SMC, SilverCmd, a SilverStream administration object, or third-party application.
Each port type excludes URLs and operations that are not associated with it. For example, the administration port only passes administration URLs. Similarly, you cannot make application design changes with the administration port. The separate ports are designed to work in conjunction with your server permission settings. For example, if your administration, design, and runtime ports are unique, any attempt to run an administration URL on any port other than the administration 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. The administration port is required for any user running the SMC or making Server Administration API calls.
How you configure a public site would probably be different from an e-commerce site that uses credit card transactions. Particularly in an extranet environment, you don't want users attempting to perform administration operations or design tasks that will alter your application data. Configuring multiple server ports in conjunction with your corporate firewall lets you manage internal and external access to your applications.
There are several security advantages to defining separate SilverStream 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.
You can set port properties using the SMC or by editing the httpd.props file. You can also use the Administration API to manage server port properties. For more information, see Using the Server Administration API.
The server supports ports for runtime, design, and administrative access for each of the following three protocols: HTTP, HTTPS-RSA, and HTTPS-DSA. The default ports are 80 for HTTP, 443 for HTTPS (RSA), and 444 for HTTPS (DSA). After installation, 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 enabled them.
When the SilverStream server starts, it binds a socket to each unique port value you have configured and enabled. The server does not require unique port values for the different types of access; ports having the same value will share the same socket and will allow multiple operations. For example, if you set your HTTP runtime and HTTP design ports to 8080, the server will use only one socket to accept requests for both.
TIP When you install the SilverStream Application Server, all three HTTP runtime, design, and administrative ports are configured to whatever port number you specify as the default. You will need to update your NT program shortcut used to launch the SMC if you configure a separate administration port after you install the SilverStream server.
See
Running the SMC for alternative ways to start the SMC.
Clients connecting to a design or administration port may perform only operations associated with that port. Because many application and server objects involved with design or 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.
The administration port is required to:
Use SilverCmd-- only for commands that will add/delete databases or change security properties
Add or remove databases in the Designer
You will not see any databases you have added in the Designer until you click Refresh (or press F5) for each configured port.
TIP To run the SMC from the Designer (using the Manage Server icon), be sure that you have already added the server to the Designer using the Administration port.
For more information, see the section on adding a database in the Main Designer chapter of the Tools Guide of the server's Classic Development Help, or see AddDatabase in the SilverCmd Reference in the Facilities Guide of the server's Core Help.
The SilverStream server can be set to a maximum of nine 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 The httpd.props File.
|
Port property name |
Connection description |
Default |
|---|---|---|
NOTE Although the server port number defaults in the table match the configuration settings of earlier releases, the older port property names have been deprecated and should not be used.
General server properties include the:
To specify general server properties:
Edit any of these fields as needed:
|
Field(s) |
Description |
|---|---|
Enable HTTP runtime port and Port number | To enable HTTP listener ports, select any or all of the three HTTP port options and then specify a corresponding port number. You can enable up to three HTTP ports. By default, the SilverStream server listens to port 80 for all three HTTP port types. The default ports are 443 for HTTPS (RSA) and 444 for HTTPS (DSA).
|
You can specify the user under whose account the server is started on UNIX. By default, it is root. | |
The SilverStream server relies on a master database catalog called the SilverMaster for overall system management. This database is specified during installation. You can change the database used as SilverMaster (for example, if you are setting up a cluster and need to change all servers in that cluster to use the same SilverMaster) by setting the SilverMaster field. |
To activate the changes, click Restart.
For more information, see
Restarting the SilverStream server.
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.
Select the logging option(s) you want to turn on or off as described in the following table.
|
Field |
Description |
Usage |
|---|---|---|
Logs messages to SilverMaster. Messages are stored in the AgLog, AgErrorLog, and AgTraceLog system tables. | ||
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. | ||
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.
| ||
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). | |
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. | ||
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. |
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.
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 SilverStreamInstallDir\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 This 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 This 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 SilverStreamInstallDir\temp\SilverServerSysOut.txt.
You can use the SMC to specify whether to use RMI--and if so, its transport protocol, name services port, and whether to use SSL for the remote objects.
To activate the changes, click Restart. For more information, see Restarting the SilverStream server.
You can run more than one SilverStream server on a host at one IP address. (SilverStream 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).
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:
Multiple servers running on one host must be configured to use unique ports. You can specify runtime, design, and administration ports in the SMC.
|
Ports |
Default |
Information on setting |
|---|---|---|
RSA (used with HTTPS/SSL communications with an HTML client) | ||
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 means 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. Unless otherwise noted, you can configure the following properties using the SMC.
|
Cluster properties |
Shared server settings |
|---|---|
| |
| |
| |
| |
| |
| |
|
The SilverStream server uses the following server property when URL-encoding and -decoding form content:
http-server.com.sssw.srv.international.UrlEncoding
NOTE SilverStream stores the encoding and other server startup properties in the httpd.props configuration file, which is located in the SilverStreamInstallDir\resources directory. For more information, see The httpd.props File.
By default, the SilverStream 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 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 its SilverStream server's encoding property to SJIS.
To change the encoding scheme:
To change from the default utf-8 to another encoding, add the following line to the httpd.props file (located in the resources directory beneath the SilverStream root directory):
http-server.com.sssw.srv.international.UrlEncoding=NewEncoding
Enter the language mapping needed at your site in place of the NewEncoding variable. Check the Sun Web site if you are unsure about the Java string mapping for your language.
Restart the SilverStream server.
URL content will be encoded using the new encoding scheme after you restart the server.
|
|
Administrator's Guide |
Copyright © 2001, SilverStream Software, Inc. All rights reserved.