WebSTAR 4 Manual & Technical Reference

Manual Contents | Index | Previous Page | Next Page

Web Server Troubleshooting

This chapter helps you locate and fix problems with web serving.

Please note that updated information for all troubleshooting is available at http://www.starnine.com/support/ .

WebSTAR crashes at its first attempt to serve a page

Bad Ethernet card . Some older PCI-based Ethernet cards may not work correctly under Open Transport and may cause WebSTAR to crash upon receipt of the first connection. Contact the manufacturer to see if a driver or hardware update is available.
Poorly written Plug-Ins and CGIs may cause the server to crash. This is especially true of Plug-Ins and CGIs that run as a Router, Filter or Preprocessor.

To determine if a Plug-In is at fault, launch the WebSTAR server with no Plug-Ins installed. If the server responds successfully to a request, try adding them back one at a time until the conflicting Plug-In is found. The WebSTAR server must be restarted each time you add a Plug-In back into the configuration. In severe cases, you may need to restart the server machine as well.

If you are using a CGI to handle the default Index File Name files, it may be causing the problem. In that case, change to a simple text file for testing.

If you have a CGI assigned to handle a particular suffix in the Suffix Mapping Table, test it by changing the Action to "BINARY". If the CGI is at fault, it will no longer be called.

If you can reproduce the crash, you should install the WebSTAR Debug Plug-In . When the module causes the server to crash again, the WebSTAR Debug Log should contain useful information for StarNine. Send an email address explaining the problem, and the WebSTAR Debug Log, to support@starnine.com . Then be sure to remove the WebSTAR Debug Plug-In, as it makes the server substantially slower.

The Browser Admin URL returns "document contains no data"

Make sure that the WebSTAR Admin Plug-In and the WebSTAR Admin Data folder are correctly installed in the Plug-Ins folder. For information, see Installation .
You don't have the WebSTAR SSI Plug-In installed. The browser-based administration pages require WebSTAR SSI .

Plug-In Problems

WebSTAR comes with various useful Plug-ins. In addition, Plug-In developers have created many third-party Plug-Ins to provide additional modules to WebSTAR.

If you have trouble with Plug-Ins, follow these steps:

To activate newly installed Plug-Ins , you must quit WebSTAR and relaunch it.
To confirm that files you wish to have processed by a Plug-In have the correct suffix , check the Suffix Mapping .
Some Plug-Ins require additional RAM to be allocated to the server and may not function without sufficient memory . Consult relevant documentation.
If a Plug-In has previously functioned correctly and is now failing to work, try reinstalling the Plug-In .

Plug-Ins load as part of the server at launch and are more likely to cause crashes than CGIs. If you can substitute a CGI for any of your installed Plug-Ins, it may help in determining which specific Plug-In is problematic.

There are often 3-way conflicts. Try running without any Plug-Ins or CGIs, then add them back in one by one (quitting and relaunching WebSTAR each time), until a culprit is discovered. Then try that Plug-In or CGI alone, to determine if it is problematic by itself or only in combination with others.

If you've written your own CGI or Plug-In, you may need to do some more debugging.

WebSTAR Plug-Ins

Auto BinHex isn't working . For files to be auto-binhexed, they must be in a folder that contains a text file named ".message". Also, make sure that the URL to the file ends with ".hqx". Additionally, this Plug-In can be configured to limit auto-binhexing to files with specified suffixes, so check whether or not the desired file has an allowed suffix.
WebSTAR Byte Server does not appear to work when serving Acrobat PDF files .

Follow the instructions for optimizing the Acrobat files and setting up the browser in Example: Byte-Serving PDF files .
HTTP "Range:" header requests will only be processed when the WebSTAR Byte Server Plug-In is installed.

Directory Indexer listings are not being displayed .

In order for the directory index listing to be displayed for a particular folder, the folder must contain a text file named ".message".

WebSTAR File Upload isn't working .

For file uploading to be allowed, the folder must contains a text file named ".upload".
Check the browser version: only some browsers support uploading via HTTP and HTTPS.
If you are using an upload form, make sure that it has the correct folder path.
Make sure that the file names are 29 characters or shorter. When they are longer, the browser error says that the request failed, and the log contains an entry "File Upload: Count not create upload file".
The Plug-In may be configured to disallow overwriting of existing files.

Image Map isn't working .

The image map must be in NCSA format, and the suffix must be ".map ". To test the Plug-in, try the image map files in the Tools and Examples folder.

Form Mail form is not working or the mail is not going through

The Form Mail Plug-In only supports simple forms with 4 fields: To, From, Subject and Body. If your form is more complex, you will need to write your own CGI or use one of the 3rd party forms-to-files or forms-to-email products.
you may have an incorrect form "action" or "method."
check the SMTP host information.
the form must have both the To or From fields.
the time-out value may be too short relative to the speed of your mail server.

Try the Form Mail example from the Tools & Examples folder to see if you have the Plug-In installed correctly.You can also use this as a model for your own Form Mail form.

SSI isn't working .

Always view the source of the processed page to see what has been generated.
Check syntax carefully.
Be sure that your page has the correct suffix so that it will be processed by SSI. The default suffix is .ssi .
When testing, remember that the file must be served through WebSTAR and SSI in order for the commands to be processed, opening it locally in a browser won't work.
Try the SSI example from the Tools & Examples folder to see if you have the Plug-In installed correctly.You can also use this as a model for your own SSI commands.

Third-Party Plug-ins

If you suspect a third-party Plug-In is causing trouble, take it out of the Plug-Ins folder and restart your server. The file must be out of the folder entirely, not stored in a subfolder within the Plug-Ins folder. If the symptoms go away, it was probably that Plug-In: contact the developer for support.

Web pages aren't being served correctly

If the pages serve correctly when you are using a browser on the same machine , that indicates that WebSTAR is serving pages correctly. The problem may be with the TCP or browser settings on the client machine, your LAN, router, DNS or connection to the internet. Below are some suggestions for things to try to determine where the problem lies.

Determine if the server machine can be seen over your AppleTalk network.
On an internal network, the TCP/IP settings for all machines need to have the same setting for the "Connect via" field.
Confirm that ethernet cables are installed.
Determine if the server machine can see out to the Internet from a browser.
Determine if the client machine can access other web sites.
If you have changed the IP number on the server, this might necessitate reconfiguring and/or restarting your router.
If you're not sure about your IP Address or host name, see Identifying Your Site: IP, Host Name and DNS .
Try "pinging" the server using an application like MacTCPWatcher.
Trace the packets using a tool for this purpose.

It works when I use my IP number, but not when I use my domain name . That indicates that there is a problem with DNS.

Confirm registration of your domain with InterNIC, or the local DNS authority for your geographic region. Confirm your Domain-Name-Service from your upstream internet service provider or if you run in-house DNS, check the settings and confer with your network administrator.

My home page isn't being served --I keep getting the WebSTAR default page instead.

Make sure that you have replaced default.html with your preferred home page. If you're using a different name, make sure you have the new file in the WebSTAR root folder, and have set WebSTAR to see the correct name.

Some default pages are not served : pages named "default.html" work fine but those named "index.html" can't be found.

Check using the WebSTAR Admin Web Settings, File Names panel to make sure that you set the Default Names .
Make sure that WebSTAR Data Cache Plug-In and WebSTAR Virtual Host Plug-In are in the Plug-Ins folder. They are both necessary to allow multiple default page names.

Request for particular pages return "Document contains no data" . This is usually because the file has a suffix which has an action that will be processed by a CGI or Plug-In, and the CGI or Plug-In is not configured or installed correctly.
There may be material included in the page, such as Java or video images, which the client browser version doesn't support.
Check your HTML very carefully . There are a number of utilities available for this. You can find some listed on the Extending WebSTAR pages at <http://www.starnine.com/extendingwebstar.html> .
If the page is being cut off partway through :

There may be a problem with the file itself. Make sure there are no unmatched quotes or closing HTML tags. If you are using BBEdit, open the file and select `Zap "Gremlins"' from the Edit menu.
If the page is not being processed by a Plug-In or CGI, and it has a different suffix (not .html or .txt), try setting the suffix entry to BINARY.

If you just modified the page , make sure you have flushed the cache in WebSTAR after saving the modified file (Command-F in either the WebSTAR server or Admin applications). You might also want to clear the browser's cache or do a forced reload.
Misplaced links are a common problem with WYSIWYG web page editors or if you've moved the site or reorganized folders. You may need to open the file in a text editor and change the links yourself. Some HTML editors let you specify a "root" folder as part of their preferences--if so, choose the WebSTAR folder.
My audio/video/Excel/etc., files are not serving correctly . Any files which are not the standard types served by HTTP servers--HTML, GIF, JPEG--will usually require configuration on both the server and browser end.

For testing purposes, substitute a plain HTML file and see if it serves correctly.

If even a plain file does not serve correctly, carefully check the path to the file in your HTML..

If a plain HTML file serves correctly, check to see that there is a Suffix Mapping entry for the specific file type you are trying to serve.

If you can successfully serve the file from WebSTAR, and can correctly view/hear/open it with your own browser, it is more likely that the browser of the user who is reporting problems needs configuration, rather than the server.

Requested pages return "file not found" messages . The usual cause for this is that the path specified in the HTML link to this file is incorrect. Place the file directly in the root WebSTAR folder--then in your browser, open the location

 
http://www.domain.com/the-file-you-want-served

(replacing www.domain.com with your host name): does it work? If so, move the file to the location where you want it, and check your HTML to see that the path to the file includes all folders in the path.

If the file doesn't serve correctly upon a direct request while it is located in the root WebSTAR folder, you may have a more serious hard drive or file system problem. You should run a disk utility and rebuild the Desktop file.

Some HTML files are truncated .

WebSTAR has no file size limit, but some CGIs or Plug-Ins may. If you have a special Action for that file's suffix, try serving the file with an action of BINARY. If that works, consult the publisher of the CGI or Plug-In to determine the limitations of the product.
Some HTML files may have a NULL character (ASCII 0) in the text. This is an "end of file" character for many servers and clients: use BBEdit's Zap Gremlin's commands or otherwise make sure you have no control characters in the files.

If you're getting broken files --flush the cache, Command-F in either the WebSTAR server or Admin applications.

You have Java files containing "$" in the filename, WebSTAR cannot serve those files. A "$" as part of a URL is interpreted as something to be processed by a CGI or Plug-In. See WebSTAR JRun Servlet Runner for more information on how to get your Java working.

Images served from WebSTAR are broken or cut off in the browser

The image files themselves may be corrupted . Try opening the files locally in the browser, or in a graphics application, to make sure that they display properly.
If you have specified an exact size in your HTML , make sure that the actual dimensions for the image file correspond to the size given in HTML code.
If possible, reduce the image file size . Many images can be set to a web-compatible palette, compressed or otherwise shrunken. This allows visitors on slow connections to view the files properly.
The browser may not have enough memory allocated to it, or it may have corrupted cache files. Try increasing the amount of RAM allocated to the browser, clear the cache or move the browser's cache folder to the Trash and restart the browser.
WebSTAR may not have enough connections assigned for sending out data.

A page that contains text, 8 graphics and 1 background image will require WebSTAR to open 10 different connections if persistent connections is not enabled. The WebSTAR Web server is shipped with a default setting of 12 Max Connections. If your site is set for this default and two clients connect at the same time, one or both of the clients may get broken image icons. You'll need to increase the number of connections, and the memory allocation for WebSTAR as well.

Do the images load properly if the person clicks reload in the browser? If so, it is probably due to the number of persistent connections (keep-alive) or slow PPP or modem connection on the browser side.

For each Persistent Connection (keep-alive) you allow, you should increase the Maximum Connections setting, and WebSTAR's memory allocation by two to three times. The server maintains a particular browser's connection for a longer period of time, meaning that additional browser requests may not encounter enough open connections on your server to get everything on the page at the first try.

If you've modified the file but not flushed the cache , the server may not send the entire file. You can set the Data Cache to always check the file modification date while you are making changes.
There may be hard disk or file system problems preventing WebSTAR from sending out the complete file. You can check to see if WebSTAR is serving out the complete file by comparing the size of the file against the number of bytes being sent out.

Make sure you are set to log the BYTES_SENT field. Compare the actual number of bytes sent to the byte size of the graphic listed in the Get Info dialog box under the File menu in the Finder. (Keep in mind that only the data fork of a file is served out, so you may need to get information on the file with an application like ResEdit if the file has a custom icon or other data stored in the resource fork).
If the byte count matches, WebSTAR is serving out the entire file and the problem is likely a client related issue.
If the numbers are different, there is a problem with the Macintosh file system. To correct this, rebuild the Desktop file. Once the desktop has been rebuilt, restart the server. If this does not resolve the problem, try running a hard drive diagnostic utility such as Disk First Aid or Norton Disk Doctor.

People report that their browser crashes when they view certain pages

Some sound files, animated gifs or Java scripts may cause some browsers, or browser versions to crash.
You may have image files that are actually larger than the size specified in the HTML.
It may be a browser Plug-In causing the problem. When you include files on your site that require Plug-Ins or helpers on the client side, it is helpful to provide information about which version(s) work best and, if possible, a link for downloading the appropriate Plug-In.

The WebSTAR status window is displaying lots of strange error messages

If you have " verbose messages " enabled, turn it off. Most of those messages are of interest only for debugging during CGI or Plug-In development.
After turning off verbose messaging, if you're still getting error messages which are not explained on StarNine's support web pages at <http://www.starnine.com/support/> , contact StarNine technical support.

After moving WebSTAR to a new machine, Java doesn't work anymore.

To move your WebSTAR server and site to a new machine, all you have to do is copy the WebSTAR folder and all its contents. WebSTAR keeps all its files, such as settings, log, etc., in its own folder. This is what makes it possible to run more than one copy on a single machine with each copy having different settings.

If you have placed aliases within the WebSTAR folder which reference files or folders outside the WebSTAR folder or if you have used SSI included files which are referenced by explicit path, you will have to reconfigure those on the new machine as well.

Browsers are getting "broken pipes" messages

This message comes up when the browser-to-server connection has broken, rather than being disconnected in the correct way. There are many reasons this can happen, for example, the browser could be on a machine that has lost its Internet connection.
WebSTAR Web server version 4 has a special header that works around some versions of this problem: make sure you are using the most recent version.
If it's happening often, and to different browser machines, check on the list at

 
http://www.starnine.com/extendingwebstar.html

for tools that enable you to watch the connection and monitor packets being sent. This can help determine where things are getting lost in the path from browser to server and back to the browser.

V irtual Hosts requests are not being routed properly

You must register the domain names and work with your DNS service provider to make sure that requests for your hosts are being directed to your browser.
The browser's request must match the Virtual Hosts entry exactly in order for the request to be routed to the correct folder. For example, if the entry has all the fields filled in:

 
192.1.1.1  	www.domain.com  	English	  :widget:

the browser must connect to the IP address "192.1.1.1" and pass to the server a Host: field of "www.domain.com" and include the English language field, in order for the request to get routed to the correct root folder.

If you only have one host for this IP address, it's better to just use the IP Address field, like this:

 
192.1.1.1	  Any             	Any  	    :widget:

This entry routes all browser requests for the IP address "192.1.1.1" to the folder domain located inside the WebSTAR folder.

Virtual Host entries are order dependent. For example, if you wanted to route browser requests to a specific folder based upon the language specified in the browser, the specific Virtual Host entry for that language should be listed before the more generic entry. The proper order to make this works would be:

 
192.1.1.1  	Any             	French  	:mechanisme:

 
192.1.1.1	  Any	             	Any	     :widget:

Make sure you've set your Virtual Host files to the correct names and file paths. For information on these settings, see Virtual Host Options .
The "Server Name" field is the name that the server uses when sending redirects when a user has connected to the server but has failed to append a trailing "/". Always set it to the host name for that virtual host.

Problems configuring Open Transport to support multiple IP addresses

For information, see IP Multihoming: Special Configuration .

You must be running Open Transport 1.3 or later in order to use IP multihoming.
You will need to restart the machine after entering additional IP addresses or making changes to the IP Secondary Addresses file.
If subnet mask and router address information is entered for one IP address in the IP Secondary Addresses file, then subnet mask and router information must be entered for all secondary IP addresses. If all subnet mask and router information is excluded from the file, Open Transport will use the defaults entered into the TCP/IP Control Panel. Try removing that information and rebooting.