Specialized Interfaces

» Direct Access Protocol

» FastCGI, NSAPI, and ISAPI

» Redundant database architecture

Redundant database with 2 mirrors

All of the servers, including the source, can be used to process user requests. In very high-volume sites, the source may be dedicated to synchronizing the various mirror databases.

Each mirror may run as a separate process on the same machine as the source, or on its own machine. Each server, source or mirror, keeps its own copy of the discussion database. TCP/IP connections from the source to each mirror are used to synchronize all of the databases.

The mapping of a user request to a particular Web Crossing server is done outside of Web Crossing. For example, you could use DNS rotation to have domain-name lookups rotate among the various servers, or hardware such as Cisco's LocalDirector to transparently assign each request to an available server.

Because each server keeps its own copy of the database, most requests can be served locally, without accessing the source database. Requests that change the database, such as checking subscriptions or changing user preferences, are passed to the source and then from the source to the other mirrors. Requests that create a new database object, such as posting a message or creating a new discussion, are passed to the source to have the object's unique ID assigned centrally, and are then passed by the source to all mirrors.

Scaling and Load Issues

On modern dual-processor Unix machines, a single process can serve 250,000 to 1,000,000 page views per "day" over a 10-hour duty cycle. The duty cycle takes into account that server load varies dramatically during a 24 hour period, and figures for purposes of determining load capacity that the server is running full-out for 10 hours, idle for the rest.

So on modern dual-processor Unix machines, this means you can serve between 2.5 million and 15 million page views per day with multiple redundant servers, depending on typical post sizes, ratio of page-views to posts, and how much customization you do on the site.

» Configuring redundant servers

With 5T/20T/50T/200T/Enterprise licenses, one license certificate is valid for the entire cluster of redundant servers. With older Standard or Platinum licenses, each redundant server must have its own license certificate.

» Operations with redundant servers

Configure the additional mirror server, either as another process on an existing machine or on a new machine.

On the source server, use the Distributed servers panel to add the mirror server.

On the mirror server, use the Distributed servers panel to configure the mirror and connect it to the source.

Note that the source and mirror synchronize by copying the source's DB over the TCP/IP connection. Copying the source's database can take the source off-line for a few minutes, and it can take a few minutes for the mirror to receive the database and start processing requests. If possible, it is desirable to take the source and mirror off-line during this synchronization. For example, if you are using DNS rotation, the source and mirror Web servers could be configured to transparently forward requests to another server.

You can check on the progress of the synchronization by logging in to the mirror machine as the sysop. For the sysop, all pages include the current synchronization status at the top of the page (except pages served through the webx.tpl file).

The first step is to remove the mirror server from the request rotation. With DNS rotation, this means configuring the mirror's Web server to forward the mirror's requests to another machine.

Once the mirror is off-line, you can shut it down normally, as if it was a stand-alone Web Crossing server.

Moving the source server to one of the mirrors requires that service be shut down for a few minutes. After service is shut down and user requests are no longer being served, you can shut down the source server, configure one of the mirrors to be the source, and then configure the remaining mirrors to connect to the new source.

The new source will synchronize each of its mirrors to its database, and service can then be resumed.

With a large database, it can take a few minutes to make a backup copy. The recommended technique is to temporarily remove one of the mirror servers from the rotation for user requests, do the backup on that mirror server via the sysop Backup command, and then bring that mirror back into service.

The Backup command makes a backup of the current database called webxdb.1. This backup file can be copied to external storage to allow last-resort restarting of the discussion service.

If a mirror server shuts down unexpectedly, you can simply remove it from the rotation. If you are using DNS rotation, this requires a spare machine to forward requests to an available server; if you are using Cisco's LocalDirector or equivalent, the mirror server will be removed from service automatically.

If the source server shuts down unexpectedly, you need to make one of the available mirrors into the new source as described above. When the old source comes back on-line, you can reconfigure it to become a mirror of the new source.

» Shared user directory

You can use this to have a common user community across multiple sites, or to break a single large conference down into smaller pieces so that it can scale to much larger volume.

In this mode, all of the servers share the same member directory information, so that login certificates and preference settings are propagated throughout the cooperating servers.

Scaling with split areas is essentially unlimited, because you can keep splitting the site into smaller pieces as desired.

You configure shared directory service through the Distributed servers sysop control panel.

» Combined redundancy and shared user directory

» FastCGI

FastCGI must be used when running Web Crossing on a different host than the Web server.

» Configuring Web Crossing for FastCGI

Web Crossing will then be accessible via both FastCGI and the standard CGI script.

» Configuring Apache for FastCGI

FastCGI is enabled by configuring Apache to map a file on the Web server to the Web Crossing FastCGI service:

   cd [your CGI dir]

   touch WebX.fcgi

   chmod a+x WebX.fcgi

   # FastCGI connections to Web Crossing

   ExternalAppClass /[absolute path of your CGI dir]/WebX.fcgi -host 127.0.0.1:8879

   <Location /[your CGI dir]/WebX.fcgi>

   SetHandler fastcgi-script

   </Location>

This ExternalAppClass directive maps WebX.fcgi to a Web Crossing server running on the same host as Apache. To map to a Web Crossing server on a different host, give the host's IP address in place of 127.0.0.1. You must use the same port number (8879 here) as that specified on the Web Crossing General Settings page. The Location and SetHandler directives tell Apache to find and use the FastCGI service for requests for WebX.fcgi.

» NSAPI

The Web Crossing NSAPI to FastCGI interface is a custom Netscape Application Programming Interface program which allows for the use of FastCGI responder type applications with Netscape Web Servers.

This FastCGI interface connects to a FastCGI compliant application through TCP/IP. It then forwards all of the appropriate server information from a request to the FastCGI application and then correctly formats the response, sending it back to the browser. This NSAPI/FastCGI interface will work with most FastCGI compliant applications

Once installed, all access to your Web Crossing Server will be exactly as it was except that all access is now being provided by the FastCGI interface.

NOTE: This NSAPI Service acts also as a "Filter" and will only run for the URL that has the "Script" name specified in the obj.conf file at the end of the URI.

» Configuring NSAPI FastCGI

Installation of the FastCGI interface involves four separate steps:

1. Copying the FastCGI application to the appropriate directory
2. Editing the configuration files for your particular Netscape Server using a simple text editor
3. Apply and restart the Netscape server to reflect the changes in the configuration files and to allow loading of the shared program, FastCgi.
4. Editing the General Settings in the Web Crossing sysop control panel to allow FastCgi access.

» Windows NT Configuration

The Windows NT installation consists of a single ".dll" file called "FastCgi.dll" and this help file.

1. Copy the file "FastCgi.dll" your Netscape Server's bin directory, e.g. "<server root>/bin/httpd/FastCgi.dll". This is typically located in "c:\netscape\server\bin\httpd\*".
2. Modify your server's obj.conf file to reflect the following changes. This file is usually located in the directory "c:\netscape\server\<NameOfYourServer>\config\obj.conf".

obj.conf Modifications:

At the beginning of obj.conf in the Init section, add the following line::
Init fn=load-modules shlib=FastCGI.dll funcs=fastcgi

Inside an object in obj.conf add the following to the BEGINNING of the other Service directives:
Service method=(GET|HEAD|POST) type=* fn=fastcgi IP=xxx.yyy.zzz.www Port=3000 Script=/WebX

The IP parameter must be the IP address of the machine that is running the Web Crossing Server.
The Port parameter must be the port number that is set in the Web Crossing Sysop control panel, FastCGI settings.
The Script parameter is the script that you are currently using to access Web Crossing.
NOTE: This file MUST exist in the correct place on your server, even if the file is empty, as this bypasses the internal Netscapes checks to see if a file exists prior to executing the Service directives.

3. Restart your Netscape server to reflect the changes to the obj.conf and to allow the loading of the shared FastCgi.dll program. You might also need to "Apply" the changes through the administration portion of your server.
4. Edit the General Settings of the Web Crossing sysop control panel to reflect the port that you chose in step 2.

» Unix Platform NSAPI Installation

The Unix installation consists of a single ".so" file called "fastcgi.so" and this help file.

1. Copy the file "fastcgi.so" your Netscape Server's bin directory, e.g. "<server root>/bin/httpd/fastcgi.so". This is typically located in "/netscape/server/bin/httpd/*".
2. Modify your server's obj.conf file to reflect the following changes. This file is usually located in the directory "\netscape\server\<NameOfYourServer>\config\obj.conf".

obj.conf Modifications:

At the beginning of obj.conf in the Init section, add the following line::
Init fn=load-modules shlib=fastcgi.so funcs=fastcgi

Inside an object in obj.conf add the following to the BEGINNING of the other Service directives:
Service method=(GET|HEAD|POST) type=* fn=fastcgi IP=xxx.yyy.zzz.www Port=3000 Script=/WebX

The IP parameter must be the IP address of the machine that is running the Web Crossing Server.
The Port parameter must be the port number that is set in the Web Crossing Sysop control panel, FastCGI settings.
The Script parameter is the script that you are currently using to access Web Crossing.
NOTE: This file MUST exist in the correct place on your server, even if the file is empty, as this bypasses the internal Netscapes checks to see if a file exists prior to executing the Service directives.

3. Restart your Netscape server to reflect the changes to the obj.conf and to allow the loading of the shared FastCgi.so program. You might also need to "Apply" the changes through the administration portion of your server.
4. Edit the General Settings of the Web Crossing sysop control panel to reflect the port that you chose in step 2.

» Custom Options

You may add an optional parameter to the "obj.conf" file to perform some error and timestamp logging to a file by inserting the following parameter: LogRequests=1 to the Service Directive parameters.

e.g.:
Service method=(GET|HEAD|POST) type=* fn=fastcgi IP=xxx.yyy.zzz.www Port=3000 Script=/WebX LogRequests=1

When this parameter is present, errors and timestamps are written to a log file named fastcgi.log.

»Web Crossing ISAPI Interface

Web Crossing Internet Information Server (IIS) API Interface is a plug-in module designed exclusively to work with Microsoft's IIS in conjuction with Web Crossing Server. This dynamically loaded library (.dll) provides the interface between the Web Crossing Server and the requests from users through their WWW browers. Initial tests have shown at least a 2X improvement in speed and access of the discussion forums in Web Crossing. It also allows a much larger message to be posted, bypassing the problems in IIS in terms of the length of posted messages.

The ISAPI version of the script program also acts as a filter for incoming URL requests to your server. This is activated through the NT Registry settings and is designed to allow older saved or cached bookmarks to continue to work without any effort of your users. It takes the old script name and converts it into the new name automatically. You will notice that eventually all of the links in Web Crossing will incorporate the new URL with "webx.dll".

Installation consists of copying the new file "webx.dll" into the same directory as the previous script file "webx.exe". This effectively replaces the standard method of accessing Web Crossing. Some settings in the NT registry must also be modified to work with Microsoft IIS.

» Copying WebX.dll to the right location

The file "webx.dll" that came with this distribution must be copied to the right location in your normal server document directory. If your site URL is something like: http://www.yoursite.com/scripts/webx.exe? then you must copy the file "webx.dll" into the directory specified by your virtual directory "/scripts" on your hard disk. This is probably something like: "c:\inetsrv\scripts\*". This should be the same location as your existing file "webx.exe".

» Editing NT Registry Settings

A few changes must be made to the NT registry settings to allow the filter portion of the WebX.dll to work correcly. If you do not require the filter, then you may skip this section and the filter will not be activated.

Edit NT Registry Settings through Web Crossing Configuration

1. Run "Web Crossing Configuration" and select the "ISAPI" tab. Note: if you do not see this tab, then you must upgrade to a newer version of Web Crossing.
2. Edit the "Currently Installed IIS Filters" box to add the FULL path to the "webx.dll" file that was previously installed into your "scripts" directory. Make sure to separate this new path from the others with a comma (,). Don't erase any of the other settings that are already installed.
3. Edit the "Old Web Crossing Script Name" to match the URL portion of your site which directed users to Web Crossing, usually "/scripts/webx.exe"
4. Edit the "New Web Crossing Script Name" to match the new URL to your site, usually "/scripts/webx.dll"
5. Close the Configuration program and move to the next step, Restarting Microsoft IIS.

Edit NT Registry Settings Manually

1. Run "regedt32.exe" from the command line or from the "Start -> Run" menu. This is usually located in your NT system32 directory.
2. Open the Registry for the computer on which Web Crossing and your IIS server is running
3. Open the setting for : System/CurrentControlSet/Services/W3SVC/Parameters
4. Edit the value "Filter DLLs and edit the list of filters to add the FULL pathname of the location of the "webx.dll" file that was copied in the earlier step. NOTE: All of the installed filters must be separated by a ',' (comma).
5. Use the "Edit -> Add Key" menu to add a key called "WebX". Leave the "class" box empty.
6. Open this newly created "WebX" Registry folder
7. Use the "Edit ->Add Value" menu to add two values called "OldScript" and "NewScript" as the value names and the URL portion of each for the string box. ie. OldScript would be "/scripts/webx.exe" and NewScript would have the value "/scripts/webx.dll"
8. Verify that these settings are correct and close the Registry Editor.

» Restart Microsoft IIS

You must restart Microsoft IIS WWW server so that the settings will be loaded correctly. Use the "Internet Service Manager" or the NT Services Control panel to stop and start the server.

»Command Syntax

A final blank line terminates a command or response, except when the response includes a Content-Length keyword. Then the blank line is followed by additional raw data bytes as specified by the Content-Length value.

Note that data values cannot include CRLF because this is the end-of-value delimiter. So, all incoming or outgoing values will be URL-quoted when they contain CR or LF characters. Any field that is URL quoted is sent as "fieldname/u:value".

»Status Responses

»Command Directory

• "/" is a CRLF delimiter between parameter keyword:values
• --> means "returns"
• [...] is optional

Session

Users

NOTE: "user" is either "USER:username" or "ID:userid"
"fieldlist" is an optional comma-delimited list of fields

AUTH/USER:/PASS:	checks to authenticate a user
NEW/USER:name/field1:value1... --> ID:/TYPE:USER	creates a new user
GET/user: -->ID:/TYPE:USER	returns information about a user
GET/user:/FIELDS:fieldlist --> ID:/TYPE:USER/field1:value1...	returns information about a user FIELDS:fieldlist is optional
GETFIELDS/user: --> ID:/TYPE:USER/FIELDLIST:	get list of available fields for a user
PUT/user:/field1:value1...--> ID:/TYPE:USER	set information about a user.
EXISTS/USER:name	checks for existence of a user, returns OK or error
DELETE/user:	deletes a user

Groups

NOTE: "group" is either "GROUP:groupname" or "GROUPID:groupid"
"member" is either "MEMBER:name" or "MEMBERID:id" where "id" is for a group or user
"fieldlist" is an optional comma-delimited list of fields
"type" is either USER or GROUP

NEW/GROUP:groupname --> ID:/TYPE:GROUP/SIZE:	creates a new group and returns its ID
GET/group --> ID:/TYPE:GROUP/SIZE:	(none)
GET/group/FIELDS:fieldlist -->ID:/TYPE:GROUP/SIZE:/field1:value1...	gets a group's ID, current size, and field data
GET/group/ITEM:itemIx --> ID:/TYPE:/SIZE:	(none)
GET/group/ITEM:itemIx/FIELDS: --> ID:/TYPE:/SIZE:/field1:value...	returns the member user or group at an index "itemIx" is a 0-origin index into the group, which is sorted by last name. Note that member indexes are not static: they change as members are added and removed.
GET/group/member: --> ID:/TYPE:/SIZE:	checks for a member by name or userId
GETFIELDS/group --> ID:/TYPE:/SIZE:/FIELDLIST:	gets fields available for a group or item
PUT/group/field1:value1...	sets field values for the group, including its name
PUT/group/member	adds a user or group to the group if not already present
DELETE/group	deletes a group
DELETE/group/member	deletes a user or group from a group

Locations

NOTES "location" is "LOCATION:pathname" or "LOCATION:locationId," and can have an optional "ITEM:itemIx"
"type" is "folder," "discussion," "link," "response," or "chat."

"GET/location --> ID:locationId/TYPE:/SIZE:	check for existence of a location and its type. The returned size is the number of nested items at this location.
GET/location/FIELDS:fieldlist --> ID:locationId/TYPE:/field1:...	get values from a location. This is either a location itself (no index) or a member of the location (with INDEX:itemIx)
GETFIELDS/location --> ID:locationId/TYPE:/FIELDLIST:	get a list of fields available at a location
PUT/location/field1:value1... --> ID:locationId/TYPE:	set information associated with a location
NEW/location/TYPE:/field1:value1... --> ID:locationId/TYPE:	create a new object. The parent is the location, which can be a folder, discussion, or message depending on the type of object to be created
DELETE/location	deletes a location.

Chat

  --> run
  --> macro: test1
  -->
  <-- 210 OK
  <-- Content-Length: 13
  <-- Hello there