Web Service as a CGI

Please note, this page has not yet been updated for version 5.0

Defining CGI Service
Why Use CGI Mode?
Switching from Direct Web Service to CGI Mode and vice versa
Troubleshooting
Resources

The Web Crossing server can be run in conjunction with another web server, such as Apache, WebSTAR or IIS. Web Crossing can also run by itself, without the need for an external web server.

Defining CGI Service

When Web Crossing runs by itself, without using an external web server, it is referred to as Direct Web Service Mode, or Direct HTTP Mode. This mode of operation is described in detail in the section on Direct Web Service. When Web Crossing runs under another web server it is referred to as CGI Mode. The operation of the Web Crossing Server under CGI Mode is shown conceptually in figure 1.

Figure 1 - CGI Mode

When running in CGI Mode, Web Crossing communicates with the users' browsers via an external web server, such as Apache, WebSTAR or Microsoft IIS (Figure 1-1). Web Crossing serves from its own webx.db database, which contains all the forums and user information, and also can serve ordinary home pages directly from the html directory (Figure 1-2). Ordinary web pages served through Web Crossing, via the external web server, can also contain WCTL, providing dynamic content and access to the Web Crossing database for ordinary web pages, just like it can in direct web service mode.

Although we commonly refer to this mode of serving just as CGI Mode, there are actually various forms of CGI protocol, depending on how your external web server is configured:

Standard CGI Mode is usually possible with all kinds of external web servers using all platforms (Unix, Mac OS and Windows). The main advantage of ordinary CGI Mode is just this compatibility point. It is also easy to setup because no CGI port numbers or extra settings are required. The drawback to this mode, however, is that this is absolutely the slowest way to run your Web Crossing server. While you may not notice any performance problems with a small number of simultaneous accesses, the standard CGI protocol is not really suitable for large numbers of hits and you may notice slowdowns as requests try to get processed via the "CGI bottleneck."

Note: For many situations the CGI bottleneck is not really as dire as all that. We're not afraid to throw out some sample numbers. Doug ran a site with about 12,000 hits/day under CGI Mode for a long time and really did not have any performance problems at all. He eventually switched to Direct Web Service mode because of the other advantages in that mode, such as being able to provide Chats via Port 80, etc. However, if you are talking about a really big site, then you definitely want to run in Direct Web Service mode because CGI Mode will not be able to handle it.

FastCGI is a special CGI protocol that essentially eliminates the CGI bottleneck found in the standard CGI protocol. However, FastCGI is not always available. For example, the current standard downloadable versions of the Apache server do not come with the FastCGI module built-in. You must locate and download the current FastCGI source and rebuild your Apache server (recompile it) yourself to take advantage of FastCGI. Beginners who are not experienced with this process may find it daunting. However, once your external web server is configured to support FastCGI, it is quite easy to set up. All that is required is setting the FastCGI service port number on both the Web Crossing side and web server side. When FastCGI is being used, performance is essentially as fast as direct service mode.

When your Web Crossing server and external web server are being run on different servers and you wish to run your Web Crossing server in CGI Mode, you must use FastCGI.
NSAPI and ISAPI are special FastCGI protocols that are made to run specifically with the Netscape and Microsoft IIS web servers, respectively.
There is also a new CGI protocol just released for Web Crossing that allows faster communication with FastCGI-enabled web servers.

Why Use CGI Mode?

As described in the section on Direct Web Service, the advantages of direct web service are so great, why would you want to bother running Web Crossing in CGI Mode under an external web server? After all, Web Crossing does not require a separate server, and runs faster without it.

In almost all cases, the answer to this question is, "If you can run your server in direct web service mode, by all means do so."

However, in real-life use, there are simply some cases where running as a CGI is more practical:

If you are running Web Crossing on a shared rental server somewhere, rather than on its own dedicated server machine, then you probably don't have a choice. Unless you want to run Web Crossing on a non-standard port number (a port other than 80) and risk isolating visitors who access from behind firewalls, you may not be able to run Web Crossing in direct web service mode without conflicting with an already-existing web server. In other words, while some Internet Service Providers allow you to run CGI, they probably won't allow you to take over port 80 and run your own web server on a shared machine. In this case, running Web Crossing as a CGI eliminates this difficulty.
Even on your own dedicated machine, you may simply find it more convenient to run Web Crossing as a CGI under an already-running web server that is already serving your current site's web pages. Installing Web Crossing as a CGI is simple, so you may decide that unless a large amount of traffic is causing a performance problem that it is just easier to "leave things as they are" and just add Web Crossing as a CGI to add extra features to your existing web server.

Note: Under Unix (for example, Linux) both Web Crossing and your external Apache server can run in direct service mode, both on port 80. How, you ask, can you accomplish this without creating a separate server machine? The answer is IP Aliasing. (Under Linux it is particularly easy to create an IP Alias using the linuxconf command.)

If you run Web Crossing under one IP address and Apache under a second IP address, neither server will conflict with each other even when Web Crossing is in direct web service mode.

If you do this, you can create a "www" domain for your Apache server and a separate "Web Crossing" domain for your Web Crossing server, take advantage of some useful Apache directives, such as "redirect" and maintain all the conveniences of running in direct web service mode.

You might want to just think about this alternative before using CGI Mode.

Switching from Direct Web Service to CGI Mode

When you install Web Crossing using the installer program, you can select between running in direct web service or in CGI Mode.

If you decide after installing to switch a direct web service Web Crossing server to run in CGI Mode, go to Control Panel > Direct Web service and uncheck the box labeled Enable direct Web (HTTP) service from Web Crossing.

Then just:

Stop Web Crossing in the usual way (Unix: by entering the "make quit" command; Windows NT: by stopping the server in the configuration program, or by uninstalling the service; Mac: by just quitting the application)
Move the WebX file to the cgi-bin or scripts file of your external web server and the Images folder to the root of your external web server.
Restart Web Crossing server in the usual way (Unix: by entering the "make run" command; Windows NT: by installing as a service in the configuration program; Mac: by double-clicking on the application)

If you're running NT and you have trouble with this method, you might want to just rerun the installer to ensure that all the proper settings are changed.

To reverse the process - switch from CGI Mode to Direct Web Service, just check the Enable direct Web service box, stop Web Crossing, then reverse the steps listed in #2, and restart the server as described above.

Troubleshooting

Web Crossing is conflicting with an another web server and won't start up. I keep on getting "port already in use" errors.

Web Crossing is attempting to start up in Direct Service Mode. You need to force it into CGI Mode as follows:
1. Make sure that you have stopped the Web Crossing server by entering the "make quit" command.
2. Edit the webx.set file in the webx system directory and change the entry for webPort from 80 to 0 (zero).
3. Restart the Web Crossing server with the "make run" command.

When I start Web Crossing in CGI Mode, none of my buttons seem visible. I am just getting broken images.

Your Images folder must be in the root directory of your external web server. For example, if you are using Apache in Unix and the Apache root directory is /home/httpd/www/html then you can move your Images folder to the correct location with the command mv Images /home/httpd/www/html. After moving the Images folder you should be able to see your buttons.

I followed all the instructions to set up Web Crossing as a CGI under Microsoft IIS, but I still can't see the server when I try to access with the URL http://mydomain.com/scripts/webx.dll? - what am I doing wrong?

99.9% of the time when this happens the cause is that you have not turned on "execute" permission for your IIS scripts folder. Refer to your IIS manual for how to make this setting change. After you do so you should be able to access your server just fine.

Resources

Sysop Documentation

syshelp.htm#CGI

Sysop Control Panel

Customization
- General Settings
  - CGI Settings
  - Fast CGI Settings

Web Crossing FAQ: