WebSTAR Manual & Technical Reference

Previous Page | Manual Contents | Chapter Contents | Next Page

WebSTAR Server Application


The WebSTAR server application is responsible for serving all Web (HTTP), FTP and Proxy connection requests. It is the core application and must be running for your server to be available. To configure the server, use the WebSTAR Admin application.

The WebSTAR server application acts as an umbrella under which all WebSTAR Plug-Ins are loaded. The FTP and Proxy servers are actually implemented as Plug-In modules.

WebSTAR Status and Monitor Windows

The WebSTAR Status window has two parts: a top panel which displays important information about the status of the server as a whole, and a monitor panel which displays initialization messages, error messages, and Web requests. The FTP and Proxy servers also have monitor windows, so you can track those interactions as well.

Status Window Top Panel

 

The title of the WebSTAR Server Status window shows you the web server port number (80, by default).

Some of these elements are also displayed in the Browser Admin Monitor page.

Summary Status

The text at the top left corner, of the Status window displays the following information:

Connections

Open Transport queues up extra requests, so WebSTAR can't effectively track that information.

Memory

The current memory status is shown in the memory meter bar and in the "Mem" status, described above.

Up Since
Minimized Window

The Zoom Box () on the right side of the title bar lets you toggle between standard and minimized modes of this window (as shown above). In minimized mode it will show you the heartbeat LED, the "Mem", "Sent", and "Hits" data, and the Load Histogram.

Log monitoring of HTTP requests and responses is only displayed in the monitor panel when this window is at the standard size: the data is not stored when the window is minimized. However, log data is always stored in the log file.

Status Window Monitor Pane

The Web Monitor pane (below the Server Status Panel) displays server initialization data, error messages, and Web server HTTP and HTTPS requests and responses.

On initialization, you'll see copyright information, TCP/IP status, Plug-In versions, and server settings for such options as File Info caching, Persistent Connections, WebObjects Adaptor, Log Archiving, and Java support.

Web Server Monitoring

Most of the data in the Status window Monitor Panel will be requests using the HTTP protocol. For example, the line:


12/19/97         15:37:59        OK leslie.domain.com   :default.html   2969    

is in the default format. It shows that the browser at the machine "leslie.domain.com" asked for the file default.html on December 19, 1997 at 3:38 in the afternoon, that the machine was allowed to access the host, that the file was returned with a length of 2969 bytes.

When you change your log file format, the monitor window will change too. For more information, see Log Formats .

If your server has errors, you'll see an entry starting with "ERR!" in the Monitor Panel. If the server cannot find a file, or there's a problem with Plug-In that should handle a URL, it will display information about these errors. For more information, see Troubleshooting Guidelines.

If you resize this window to be wider or narrower, the new log entries will wrap to the new width.

As you use more Plug-Ins and CGIs, the messages in this window will be more complex, but they are designed to help you understand what is going on and how to best configure your server.

If you're having trouble with your server, you can specify more detailed messages by selecting Verbose Messages.

FTP Monitor Window

The FTP monitor window shows you information about current connections in the top panel. The monitor panel shows logins, uploads, downloads, and errors. For complete information, see WebSTAR FTP Monitors & Logging.

Proxy Monitor Window

The Proxy monitor window displays information about connections and caching. The logging panel displays each transaction, with information about the URL and the cache status. For complete description, see Proxy Status Window & Log File.

 

WebSTAR Server Menus

The WebSTAR server application is responsible for serving all Web (HTTP or HTTPS), FTP and Proxy connection requests. It includes menu commands for the basic setup of your WebSTAR server. However, to configure and administer the WebSTAR server, you will generally use WebSTAR Admin, described in WebSTAR Admin Application.

File Menu

The Server's File menu lets you open the Status window and the FTP and Proxy Monitor windows, as well as Quit the server application.

Edit Menu

This menu is only enabled when the main WebSTAR Status window is active. If this menu is disabled, click on the Status window to bring it forward, or use the File menu to open that window.

The Undo, Cut, Copy, and Paste commands in this menu mainly work in dialog text fields. In addition, you can select text in the Status window and Copy it to the clipboard.

Admin Password

This dialog allows you to set the password for access to the WebSTAR Admin Application. You can only have one Admin Password: if you open this dialog and enter a new password, you will not be able to use the old password. Note that this password is case-sensitive, so you must always match the upper and lowercase letters. For information on keeping your server secure, see Safe Passwords.

The Admin password is not the same as the Administration Realm password. See Your Browser Admin Password.

Serial Numbers

You must have a unique serial number to enable WebSTAR. If you need to edit or change your serial number, use this menu item to bring up the Serial Number dialog. WebSTAR serial numbers will start with WEB*, WebSTAR/SSL numbers with W*SL. Localized versions may have other prefixes for the serial number.

For information on testing without a permanent serial number, see Temporary Serial Number.

You may have up to five serial numbers, including expiring demonstration numbers and older version serial numbers. Having more than five numbers may cause error messages at startup.

You must have a different serial number for each copy of the WebSTAR server machine that you are running. If you launch a second copy on another machine, you must enter a different serial number.

The serial number is stored in the WebSTAR Settings File , so if you remove your settings file, or it becomes corrupted, you will have to re-enter your serial number.

To avoid losing your serial number, write it in your WebSTAR manual and save it in your Mac's Note Pad.

Entering and Editing WebSTAR Serial Numbers

The "Serial Numbers" command in the WebSTAR server's Edit menu opens a dialog in which you can view, add, or delete serial numbers for WebSTAR. The buttons in the Serial Number Maintenance window let you add, delete, or get more information about a number. 

Type your serial number and then press the "OK" button. Be sure to type the number exactly as you see it on the serial number sheet or message, with dashes, capital letters, numbers and no spaces. If you make a mistake in typing, WebSTAR will show you an error message and let you try again.

If you have the serial number in a message or on the Note Pad, you can copy and paste it into this dialog (be sure to delete any new line or return characters).

Options Menu

Items in the Options menu let you change the behavior of the server. All selections made in this menu are saved in the server's WebSTAR Settings file and restored the next time the server is launched. The Options menu in WebSTAR Admin and the WebSTAR server application are identical.

 
Verbose Messages

When this option is checked, WebSTAR displays additional connection and diagnostic information. The information is displayed in the Status window but not recorded in the log. You can also set this in the Browser Admin, Controls Page.

Displaying the Verbose Messages makes the server run more slowly. For normal operations, make sure this option is not checked.

Many of the messages produced by checking this option pertain to low-level HTTP, FTP, Proxy or TCP/IP internal state information. If you are not familiar with these protocols, these messages may seem quite obscure. However, some of the verbose messages can be useful for watching the details of client requests and for troubleshooting.

Errors reported with Verbose Messages enabled should not be reported to StarNine Technical Support.

Suspend Logging

When this option is checked, WebSTAR temporarily closes its log file, allowing you to open and examine the file with a text editor. No incoming connection data will be logged to the file while this option is checked. You can also set this in the Browser Admin, Controls Page.

Hide Window in Background

When this option is checked, the WebSTAR Status window is hidden when other applications are active in the foreground.

Monitor windows and Plug-In status windows will not be hidden.

Refuse New Web Connections

When you check this option, WebSTAR will refuse all new HTTP requests, until the option is unchecked. However, it will finish servicing all currently queued requests.

You can also set this in the Browser Admin Controls page

Incoming connections are still reported in the statistics area of the Status window, but those connections are just "knocking at the door"-- they are not being allowed in and the clients are notified that their connection is refused.

This option is useful for gracefully shutting down a server, or for allowing you to change HTML documents while the server continues to run.

Restrict CGIs to CGI-BIN

This menu command works just like the checkbox in WebSTAR Admin: see Restrict CGIs to CGI-BIN.

Flush Cache

Forces WebSTAR to flush the memory caches. You can also flush the caches in the Browser Admin Controls page.

Flushing the cache flushes the file, data and DNS caches, and sends a message to Plug-Ins to flush their caches as well (although not the Proxy Cache). For more information, see Flushing the Cache

Be sure to flush the cache whenever you change data on your disk..

Plug-Ins Menu

The Plug-Ins menu displays the names of all installed WebSTAR server Plug-Ins. When you select a Plug-In from this menu, it may display a configuration interface, status information or version information. The exact action will depend on the Plug-In.

Most WebSTAR Plug-Ins display their version and copyright information, along with a contact URL. Three WebSTAR Plug-Ins also display information windows: WebSTAR Data Cache, WebSTAR SSI, and WebSTAR Proxy Server.

Help Menu

WebSTAR help is in the form of this document, available for printing in Acrobat PDF format and viewing in HTML. To view locally, open your Web browser and choose Open from the File menu, then open this manual from the Documentation folder.

Allocating Memory to WebSTAR

WebSTAR 3, with default settings, is set to a preferred size of 5632K (slightly lower if you are running Virtual Memory on a Power Macintosh). The default setting allows12 maximum connections, each, for the HTTP, FTP and Proxy servers, 50 K for the default the File Info cache, and 256 K for the default Data Cache.

WebSTAR requires at least 2048 K of memory to run. If your machine does not have enough memory free, WebSTAR will not run.

Memory Allocation Guidelines

Web
FTP
Proxy
Plug-Ins

How to Change WebSTAR's Memory Allocation

  1. Quit the WebSTAR server if it is running.
  2. Select the WebSTAR icon and choose Get Info from the File menu.
  3. Increase or decrease the number in the "Preferred Size" field. To have a noticeable effect, increment by at least 100 K.
  4. Close the Get Info window.

When you restart WebSTAR, it will request the changed amount of memory from the Mac OS.

Optimizing WebSTAR for Best Performance

As shipped, WebSTAR provides very good performance for medium-sized sites. However, you may wish to optimize your server for your particular site. For general information on hardware, software and networking, see System Requirements; for memory allocation guidelines, see Allocating Memory to WebSTAR; and to set the file and data cache sizes, see Caching.

In addition, the WebSTAR Performance Tech Note will give you updated suggestions for the most current techniques to optimize your server.


  

Restarting After Open Transport Errors

WebSTAR servers (including WebSTAR BG and WebSTAR/SSL) will automatically shut down if they get errors from Open Transport. They will try to launch a Restart Server application, if there is one in the WebSTAR folder, by sending an Apple event.

Once launched, the included Restart Server application will quit the WebSTAR server and wait for 30 seconds. Once the 30 seconds are up, the Restart Server application will re-launch WebSTAR and then gracefully quit itself.

For information on other server restart applications that are not limited to Open Transport errors, see the Extending WebSTAR page.

You can use the included Restart Server application, write an AppleScript restart script, or install a third-party replacement application for more flexibility and power, and to automatically restart after other problems.

Developing a Restart Server Application

You can create your own Restart Server application using whatever programming tools you have available. The easiest way is to write one in AppleScript.

For instance, you could develop a custom Restart Server application to backup your server whenever a TCP/IP error occurs, quit other server applications running on the same machine, etc.

Make sure that any replacement for this application is named "Restart Server", has a creator code starting with "WWW", and is located in the WebSTAR folder. In addition to launching an application called "Restart Server" in the same folder as WebSTAR, the server also sends an AppleEvent to the "Restart Server" application. This allows a single application to perform multiple tasks (and already be running when the server sends the restart event). The event WebSTAR sends passes the FSSpec as a parameter, but expects no reply. It's simply intended as a trigger for applications that can restart the server which may already be running. The event class is WebSTAR's WWW and the event code is REST. The application's creator has been changed from "aplt" to "WWW" for security reasons (you don't want someone requesting a script named "Restart Server"). If your replacement Restart Server file is an AppleScript applet, you need to change the creator code back to "aplt"to edit it, and then back to a creator starting with "WWW".

WebSTAR Background Server

The background-only versions of the WebSTAR server, "WebSTAR BG" and "WebSTAR/SSL BG", run in the background, providing no access to the server's menus or other interface elements. Because there is no user interface, others cannot access the background-only applications, so they can't change or quit the server by accident. The background servers will respond to Web (HTTP and HTTPS, respectively), FTP and Proxy requests just like the standard WebSTAR servers.

To install WebSTAR BG, launch the WebSTAR Installer and choose "Custom Install". Then choose "WebSTAR BG" from the list of options and install it in the same folder as the WebSTAR application.

Before you can use WebSTAR BG, you must first run the WebSTAR foreground server to enter the product's serial number, and admin password. This initial launch and configuration of the foreground server creates a valid WebSTAR Settings file in the same folder as the WebSTAR application. WebSTAR BG will not run properly without a preconfigured Settings file.

After launching and configuring the foreground server, you can begin using the background-only server by quitting the foreground server and launching WebSTAR BG. Both applications can reside in the same folder, but you cannot run them both at the same time. Typically, you would place an alias to WebSTAR BG in your Startup Items folder so it is launched automatically when you start your computer.

Once the WebSTAR BG application is running, you can communicate with it and configure it further by using the WebSTAR Admin Application. To quit WebSTAR BG, use the WebSTAR Admin Options menu's Quit WebSTAR command.

There are no server monitor windows, but the background servers report any errors which may have caused the WebSTAR BG application to quit unexpectedly in the WebSTAR.Messages File.

Running Multiple Servers On The Same Machine

If you want to have a Web site that has some public and some private pages and you don't want to use security realms, you can run multiple WebSTAR servers on a single computer, using a different TCP/IP port number. One server can be set up with no access restrictions, while another restricts access to specified hosts.

See also: Virtual Hosts: Hosting Multiple Web Sites

All port numbers lower than 1024 are reserved for well-known services. WebSTAR uses port 80 for the web server by default (it also uses 20 and 21 for FTP and 8000 for Proxy). If you are running multiple servers, you need to assign a different port number for the additional servers. Although you can use any unreserved, available port numbers, the convention is to use ports in the 8500 range (such as 8501) for additional WebSTAR servers.

See Setting the Web Server Portfor details on specifying an alternate port number for a selected WebSTAR server. When multiple servers are set up, URLs to the alternate servers (those not using port 80) must specify the appropriate port number. For example:

http://www.domain.com:8502/privatedoc.html

would use the same machine as "www.domain.com", but an alternate web server.

If you want to run multiple servers on different computers, they each need a unique serial number.

FTP and Proxy Servers: Single Instance

Although WebSTAR allows you to run multiple copies of the server, you cannot run multiple FTP and Proxy servers . Therefore, to reduce memory usage and avoid confusion, you should remove the FTP and Proxy Plug-Ins from the alternate web server's Plug-Ins folder.


Previous Page | Manual Contents | Chapter Contents | Next Page