Up: Web
Crossing home page
To: Table of contents (please wait while file
loads)
Web Crossing for Unix
Web Crossing implements discussion groups for World-Wide Web servers.
This page gets you started with Web Crossing. It shows how to set up a Web
Crossing server at your Unix site. It describes Web Crossing and includes a
list of problems and solutions. This page was updated on March 7, 1997.
For additional help with Web Crossing, try
Web Crossing stores discussions, folders, user profiles, and configurations in
webx.db. The database is managed by a server process called webx-go.
The server process receives requests from a CGI script called WebX.
The CGI script uses a C program (webx-cgi) and a named pipe (webx.socket)
to contact the server. The server is restarted automatically by a daemon
process called webx-run.
The MULTIPLE version of Web Crossing uses the same architecture. It stores
individual conferences in numbered directories (e.g., webx/conf1/webx.db).
The MULTIPLE configuration is stored in webx/webx.db.
»Table of contents
»Unpack the Web Crossing
distribution
You will need the following:
- webx(vers)-(host).tar.Z or webx-mult(vers)-(host).tar.Z
from
download Web Crossing.
There is a different file for each supported host. If your host is not in the
list, please contact sales@lundeen.com.
- A WWW server with a CGI interface.
- Three megabytes of disk space.
-
Four and half megabytes of virtual memory.
The instructions for the one conference version (webx(vers)-(host).tar.Z)
and the MULTIPLE version (webx-mult(vers)-(host).tar.Z) are the same.
First unpack webx(vers)-(host).tar.Z:
- uncompress webx(vers)-(host).tar.Z
- tar xf webx(vers)-(host).tar
This creates a webx/ directory. See
How Web Crossing works for a full description. The initial
directory contains:
- Makefile
- maintenance commands for Web Crossing. Type 'make' for a list of commands.
See Makefile for further information.
- make.tar
- a tar file of scripts for Run Web Crossing without make.
- Images/
- a directory of images and help files for Web Crossing.
- Images/WBChat/
- a directory of Java code for Web Crossing's chat client.
- html/
- a directory for serving files from Web Crossing. It contains an example
file, test.html.
- WebX.template
- a template for Web Crossing's CGI script, WebX. It invokes
webx-cgi.
- webx-cgi
- a CGI program written in C. It writes a request to
webx-go via a Unix pipe.
- webx-go
- the server for Web Crossing. It receives HTTP requests from webx-cgi
and returns HTML pages.
- webx-run
- a daemon driver for webx-go. It invokes webx-go and
maintains a log file.
- guided.exp
- a Web Crossing export file for "A guided tour to Web Crossing".
You may export and import any section of the database file, webx.db.
- standard.tpl
- the standard Web Crossing template file for advanced users. Most users
will customize Web Crossing via control panels.
If you want to fully customize Web Crossing, copy standard.tpl
to webx.tpl and read the sysop documentation.
- survey.tpl
- a template file for taking a survey.
- README-unix
- a pointer to this file.
- webx-unix.html
- this file.
»Easy install for Web Crossing
To install Web Crossing:
- Set the access rights as described below.
- Install the WebX CGI script.
- Install the Images/ directory.
- Start the Web Crossing server.
- Configure Web Crossing with your browser.
- Backup Web Crossing's database on a regular schedule. It contains all of
your folders, conversations, messages, and access lists. See
How to backup a Web Crossing site.
You will need the 'make' command on your Unix system. If your
system does not include make, see
Run Web Crossing without make.
If you are a super-user:
- Install Web Crossing under the same user-id as your WWW server. You may
need to execute 'chown -R nobody:nobody webx' where "nobody"
is the user-id for WWW.
- Execute 'make cgi'. This creates a CGI script (WebX).
- Move WebX to your cgi-bin directory. You may need to rename it
to WebX.cgi. For the MULTIPLE version, you may make multiple copies of
WebX with different names.
- Move the Images/ directory to your WWW file directory.
- Execute 'make run'. This starts the Web Crossing server.
- With a web browser, load "WebX" -- for example, load "http://(your
site)/cgi-bin/WebX".
-
Follow the instructions to set the images directory, your e-mail address, and
your password.
- Save a copy of your sysop password.
- Backup Web Crossing's database on a regular schedule. It contains all of
your folders, conversations, messages, and access lists. See
How to backup a Web Crossing site.
If you are not a super-user:
- Execute 'make cgi'. This creates a CGI script (WebX).
- Execute 'make global'. This sets global access permissions.
- Set global read and execute permissions for all higher-level directories.
- Move WebX to your cgi-bin directory. You may need to rename it
to WebX.cgi. For the MULTIPLE version, you may make multiple copies of
WebX with different names.
- Move the Images/ directory to your WWW file directory.
- Execute 'make run'. This starts the Web Crossing server.
- With a web browser, load "WebX" -- for example, load "http://(your
site)/cgi-bin/WebX".
-
Follow the instructions to set your Images directory, e-mail address, and
password.
- Save a copy of your sysop password.
- Backup Web Crossing's database on a regular schedule. It contains all of
your folders, conversations, messages, and access lists. See
How to backup a Web Crossing site.
If something does not work, look at
»Set your Images directory
Installation requires a URL for the Images/ directory. The URL is
used for banners, buttons, and help pages. If it is incorrect, you will not
be able to use Web Crossing.
The third page of the Web Crossing installation is a form for setting the Images/
directory.
The Images/ directory should be a URL (one that starts with "/").
If you use "/Images", Web Crossing will load the login button with:
http://(your site)/Images/login.gif
If you have problems, try loading an image directly -- for example, 'http://(your
site)/Images/import.gif'
If you did not see the login button because of access permissions, you may
need to wait until your WWW server clears its cache of opened files.
»Step-by-step: install Web Crossing
If access permissions are wrong, you will not be able to use Web Crossing.
If you have trouble with easy install, try the following step-by-step
instructions.
»Step-by-step: set up Web Crossing
To install Web Crossing, follow these steps:
- Execute 'make cgi'. This creates WebX -- the CGI
script for Web Crossing. It uses `pwd` to get the working directory.
- Provide access to webx/ from your WWW server. Your WWW server
needs access permission to the webx/ directory and access permission
to some of the files.
If you are not a super-user:
- Execute 'make global' to set global access permission to Web
Crossing. You will also need to set global access permissions (chmod a+rx
...) to all higher-level directories.
If you are a super-user, do one of:
-
Execute 'make global' as above.
- Install Web Crossing under the same user-id as your WWW server.
- As root, change the ownership of the webx/ directory
to your WWW server. For example, if WWW is owned by nobody, execute 'chown
-R nobody:nobody webx'. Then change your user-id to the WWW server's
user-id.
- Move WebX to your cgi-bin directory. Users will invoke Web
Crossing with "http://(your site)/cgi-bin/WebX.". You may rename
WebX to WebX.cgi. For the MULTIPLE version, you may make
multiple copies of WebX with different names.
- Move Images/ to an WWW file directory. The Images/
directory needs to be accessible by a URL, e.g., "http://(your
site)/Images/login.gif".
»Step-by-step: check access
permissions
Double check your access permissions. Do one of:
- Execute 'ls -l' on WebX,
webx/webx-cgi, webx/Client.log,
Images/, Images/WBChat, and webx/Client. Your WWW server
will need read
and execute permission to WebX,
webx/webx-cgi, Images, Images/Chat, and all higher level directories.
It will need read permission to Images/* and Images/WBChat/*.
It will need read, write, and execute permission to webx/Client. It
will need read and write permissions to webx/Client.log. If
webx/Client or webx/Client.log do not currently exist, they
will be created by webx-run or webx-go.
-
Log in as your Web Crossing server and execute 'ls -l' on WebX,
webx/webx-cgi, webx/Client.log, Images/WBChat, and Images/. If
you can not list these files, your access permissions are wrong. The log file,
webx/Client.log, needs write permission as well as read permission.
If you are using global access permissions ('make global'), also check
'ls -ld webx/Client'.
- Log in as another user and execute 'ls -l' on WebX,
webx/webx-cgi, webx/Client.log,
Images/, Images/WBChat, and webx/Client.
You will need global access
permissions ('make global'). If you can not list these files, your
access permissions are wrong. The log file, webx/Client.log, needs
write permission as well as read permission.
If your access permissions are set correctly, you can now run Web Crossing from
your web browser.
»Step-by-step: test Web Crossing
Use the following steps to test Web Crossing and its access permissions. If you
change a file or its access permissions, double check the permissions with 'ls
-l'. Your WWW server may cache opened files. If so, you will either need
to use a different name or wait until the old file is closed.
To start Web Crossing the first time:
- Log in as the owner of the webx/ directory.
- Execute 'make run'. This starts the Web Crossing server.
-
If possible, log in as your WWW server or log in as another user.
-
In the cgi-bin/ directory, execute 'WebX'. You should see
an HTML page from the Web Crossing server. If not,
- webx/ and all higher-level directories may need read and execute
("+rx") permissions
- WebX or webx/webx-cgi may need read and execute ("+rx")
permissions.
- webx/Client/ may need read, write, and execute ("+rwx")
permissions. If 'chmod a+rwx Client' returns "chmod:
WARNING: Group execution not permitted on Client, a lockable file",
execute 'chmod -l Client' to remove the lock flag.
- The Web Crossing server may not be running. Try 'ps' 'ps -x'
or 'ps -e' to list the active processes. You should see webx-go
-daemon -server and
./webx-run -daemon -server. If not, check the
webx/webx.log file for the reason, and re-execute 'make run'.
- WebX may be using the wrong directory for Web Crossing. Check
WEBX_DIR in WebX. If it is wrong, either change it with an editor or
make a new WebX by executing 'make cgi'.
- The Web Crossing server may have generated an error. Check the webx/webx.log
file.
-
In a web browser, load an image from the Images/
directory -- for example, "http://(your site)/Images/import.gif". You
may also try export.gif or smdel.gif. You will use this
directory path to set your Images/ directory in Web Crossing (see
Set Images).
If you can not load an image:
- The URL may be wrong.
- Images/ may be in the wrong directory for WWW.
- Images/ may need read and execute ("+rx") permissions.
- The image file may need read permission.
- The WWW server may be caching a previous attempt. Try another image from
the Images/ directory.
- In a web browser, load "WebX?cgi-test" -- for example, "http://(your
site)/cgi-bin/WebX?cgi-test". You should see a message from WebX. If
not,
- Your WWW server may disallow shell scripts.
- The URL may be wrong.
- WebX may be in the wrong directory for CGI.
- Your WWW server may need read and execute ('+rx') permissions for WebX.
- In a web browser, load "WebX?cgi-echo". You should see a
message from webx/webx-cgi. If not,
- Your WWW server may need read and execute permissions to webx/webx-cgi,
the
webx/ directory, or a higher-level directory.
- In a web browser, load "WebX?cgi-get". You should see an HTTP
header and a page of HTML from the Web Crossing server. If not,
- Your WWW server may need read, write, and execute permissions ("a+rwx")
to the webx/Client/ directory.
- Your system may use an auto-mounter that sets the current directory incorrectly.
Test for the correct directory by trying 'cd' on the directory (if any) in the error message.
Did all of the above tests work? If a test didn't work, retry the test with
an extra path, e.g., 'http://(your site)/cgi-bin/WebX/2?cgi-test. You
may need to wait five minutes to let your WWW server flush its cache of opened
files.
»Step-by-step: run Web Crossing
If all the tests worked, you are ready to run Web Crossing. With your web
browser, load "WebX" -- for example, "http://(your
site)/cgi-bin/WebX". You'll see instructions to:
- Review and accept the Web Crossing license agreement.
- Check the location of the Images directory for user-interface
graphics and help files.
- Set the email address for the sysop.
- Install a certificate (unless you are going to just run in demo mode for
now).
- Choose your sysop password.
- Configure your server as desired using the sysop control panel.
»Step-by-step: stop Web Crossing
To stop the Web Crossing server:
- Select 'Shut down server' in the sysop Control Panel, or
- Run 'make quit', or
- Read the process id (pid) from webx.lock and execute 'kill pid',
or
- Locate the process id (pid) for Web Crossing by 'ps -e | grep webx-run' and
execute 'kill pid'. You may need to use different flags than '-e' to list
daemon processes.
»Upgrade Web Crossing to a new
version
To upgrade your copy of Web Crossing:
- Get the latest webx(vers)-(host).tar.Z or webx-mult(vers)-(host).tar.Z
from
download Web Crossing.
- Shut down your Web Crossing server with Shut down
server in the Sysop control panel. You may also use 'make quit'.
Warning: use ps to make sure that Web Crossing has indeed been shut down.
Installing a new version while the old software is still running can cause a
segment fault and damage your database.
- Make a backup of your webx/ directory and all subdirectories.
- Extract the tar file into your webx/ directory:
- uncompress webx(vers)-(host).tar.Z
- tar xf webx(vers)-(host).tar
- In webx/, run 'make cgi' to create a new copy of WebX.
- Run 'make global' unless you have the same userid as your WWW server.
- Move WebX to your cgi-bin/ directory. You may rename
WebX to WebX.cgi. For the MULTIPLE version, you may make
multiple copies of WebX with different names.
- If you use Web Crossing's image files, replace your previous
Images/ directory with the new one. Otherwise, copy the modified
files listed in Changes to the Unix distribution.
- Double check that your WWW server has access to the image files, WebX,
and webx-cgi.
- Restart Web Crossing with 'make run'.
- If there is a new guided.exp (see Changes ...),
delete the old 'Guided tour of Web Crossing' and import guided.exp.
- Review new notes in
What to do if Web Crossing does not work.
- Backup Web Crossing's database on a regular schedule. It contains all of
your folders, conversations, messages, and access lists. See
How to backup a Web Crossing site.
You may use symbolic links to make upgrades easier. Create a link to your
cgi-bin/ directory to simplify copying WebX. If you use Web
Crossing's image files, replace the directory webx/Images/ with a
symbolic link to the Images/ directory under your HTTP server. Then,
the 'tar' command will automatically update the Images/ directory.
»Move Web Crossing to another server
or directory
To move your copy of Web Crossing to another server or directory:
- Shut down your Web Crossing server with Shut down
server in the Sysop control panel. You may also use 'make quit'.
- Transfer your webx/ and Images/ directories to the new
location. The file webx/webx.db contains all of your folders,
discussions, and settings. For the MULTIPLE version webx/conf*/webx.db
contain the folders, discussions, and settings for each conference.
- Run 'make cgi' to create a new copy of WebX with the new
directory.
- Double check your access permissions. You may need to run 'make global'.
- Move WebX to your cgi-bin/ directory. You may need to
rename or copy WebX as needed for your installation.
- Restart Web Crossing with 'make run'.
- If your Images/ directory has a new URL, you will not be able to
download images. Go to the Sysop control panel with the URL "http://.../cgi-bin/WebX?59@@".
Go to "General settings" and change "Directory for images".
If this doesn't work, try the suggestions under
Images do not appear.
- If you have moved your site, either forward all URLs to the new site, or
return a page that directs users to the new site. Otherwise, the URL for WebX
will use the new site while the URLs for images will use the old site.
- Backup Web Crossing's database on a regular schedule. It contains all of
your folders, conversations, messages, and access lists. See
How to backup a Web Crossing site.
»Custom install
You may automatically start Web Crossing whenever your system reboots.
- Execute 'make start' to create start.webx
- Add to your startup files: 'su userid -c dir/webx/start.webx' where
'userid' is the userid for the webx/ directory and 'dir' is its path.
- When executed, start.webx changes the current directory to webx/
and performs the same command as 'make run'.
You may edit webx/Makefile to specify the Web Crossing directory. For
example, you may use a link from your WWW server to
webx/. If you use a link, use a hard link instead of a symbolic link.
Many WWW servers will not follow symbolic links.
You may run multiple instances of Web Crossing on the same computer. Each
server needs its own Web Crossing directory and CGI script. You may edit
webx/Makefile and set WEBX_SCRIPT. This will identify Web Crossing in
a 'ps' listing. You will need a separate certificate for each server.
With the MULTIPLE version, you may run multiple conference with one Web Crossing
server. Each conference uses a separate directory (e.g., webx/conf1/)
and either a CGI script or conference code.
You may edit webx/Makefile to set the CLOCK_SKEW or to specify
NO_LOCK. See Makefile for further directions.
You can invoke webx/webx-go, webx/webx-run, and webx/webx-cgi
directly. Typing 'webx-go' or 'webx-run' gives a list of
command options. The '-syslog' option writes error messages to syslog()
instead of webx.log. The first argument to webx/webx-cgi is
the full pathname of the
webx/ directory. Without arguments, webx/webx-cgi assumes
'/usr/webx'.
»How to manage a Web Crossing site
This section contains several suggestions for managing a Web Crossing site.
See Salon's site for a good
example.
- Backup Web Crossing's database on a regular schedule. It contains all of
your folders, conversations, messages, and access lists. See
How to backup a Web Crossing site.
- Hosts should respond frequently. This is especially true in the earlier
stages of setting up a site.
- Keep the site organized. Move inactive conversations to an archive folder
for eventual deletion. Reorganize a folder if it becomes too large. Encourage
users to create conversations for new topics.
- Use one-level or two-level folders. Either you or your hosts should create
and manage the folders. If users can create folders directly, the site may
become disorganized and hard to read.
- Allow users to create their own conversations.
- Distinguish the header of a conversation from the messages. The header
provides the context for a conversation.
- Encourage short headers since they appear on every screen. The first
message is a good place for a full introduction.
- The header of a conversation or folder can summarize the contents. You can
edit the headers periodically. They may include pointers to items of interest.
- If most users have modems, consider not using user pictures. Most users
are hesitant about submitting a picture. Pictures take time to display.
- If you have a large site, turn off searching from the top-level folder.
A top-level search reads every message from disk.
- If a conversation attracts more than a thousand messages, archive it and
start a new one. Long conversations take a while to search.
- If users express confusion about the site, do what you can to remedy the
problem.
- Let us know about your solutions.
»How to backup a Web Crossing site
Backup Web Crossing's database on a regular schedule. It
contains all of your folders, conversations, messages, and access lists.
The database
is easily lost. Your hard disk could crash, or you could have a fire. The
operating system could crash while the Web Crossing is updating its database --
perhaps corrupting the database and making it unusable. We had one customer
whose ISP deleted the database without making a backup. The technician thought
he was supposed to execute 'rm webx.db'.
A system crash or a bug in Web Crossing could corrupt the database.
We have changed Web Crossing to make this less likely, but it still
may occur.
A corrupted database may be indicated by the following error in
webx.log:
Thu Aug 22 06:26:02 1996 ChFiReadPg-- page table index
If the database is corrupted or webx.db is lost, you will need
to recover webx.db from a backup. We recommend
automatic backup and recovery (new in Web Crossing 2.0). This uses a
snapshot of the database and a rollforward log of modifications to
the database.
You start the snapshot with
the backup panel in sysop controls. Web Crossing
creates a snapshot of the database in webxdb.1 and a rollforward
log in webxroll.1. Web Crossing renames the old snapshot
to webxdb.2 and webxroll.2, and deletes the oldest snapshot.
To restore the database from a snapshot and rollforward log:
- Shut down Web Crossing.
- Double check that 'ps -x' [or the equivalent on your
system] does not indicate a Web Crossing process.
- Rename webx.db to a temporary name.
- Start Web Crossing. When webx.db does not exist, Web Crossing
automatically copies webxdb.1 to webx.db and applies
all the changes from webxroll.1.
You may make copies of webxdb.1 and webxroll.1 at any time.
Keep at least one copy off-site. You may copy webx.db if Web
Crossing is not running. Do not copy webx.db while Web Crossing
is running. If you do, the copy may be corrupted.
For more information see Backup and recovery.
»How Web Crossing works
Web Crossing uses these processes:
- webx-cgi is a client process for the WWW CGI interface. A shell
script, WebX, invokes webx-cgi.
webx-cgi reads a request from its environment variables and standard
input. It writes the request to webx.socket and waits for a reply.
It echoes the reply to standard output. It uses socket Client/idNNNNN
for process NNNNN.
- webx-go -daemon -server is a server process that reads a request
from webx.socket. It uses webx.db to handle the request. It
returns the results to webx.socket.
webx-go has two child processes. They have the same arguments
in a 'ps' listing. They convert between Internet IP addresses and domain names.
The MULTIPLE version of webx-go is nearly the same. It stores
configuration information in webx.db. From the URL and conference code
(the first word after '?') it determines the corresponding conference (e.g.,
conf2). It uses webx/confNN/webx.db to handle the request.
It returns the results to webx.socket.
- ./webx-run -daemon -server is a daemon process that runs webx-go
as a child process. If webx-go fails, webx-run automatically
restarts webx-go. It waits at least two minutes between restarts.
webx-go may run as a daemon server without using webx-run.
webx-run constructs these files:
- webx.log shows when webx-go was started or restarted. It
contains error messages from webx-run and webx-go. It is
used for daemon processes (-daemon). Non-daemon processes write error
messages to stderr. You may use -syslog instead.
- webx.socket is a Unix-domain socket file for communicating between
webx-go and webx-cgi.
- Client is a directory for storing client sockets. Sockets are
automatically deleted if no error occurs. Web Crossing checks that a client
socket was recently created. If your WWW server and Web Crossing server run on
different machines, you may need to set the '-clock' parameter (see CLOCK_SKEW
in
webx/Makefile). Your HTTP server needs read and
write access to webx/Client/.
- Client.log contains error reports from webx-cgi. For
example, if a user can not reach the Web Crossing server, an error is returned
to the user and appended to Client.log. The log lists the date,
process id, IP address, and message for each error. Errors from the Web
Crossing server are not listed. Your HTTP server needs write access to
webx/Client.log.
- webx.lock is a lock file to prevent duplicate servers. It contains
the process id of the Web Crossing server. If your operating system does not
support record locks, set the -nolock parameter (see NO_LOCK in
webx/Makefile). With -nolock, Web Crossing uses
an exclusive open of webx.lock to prevent duplicate servers.
- webx.testNNNNN is a temporary socket to test for duplicate servers.
webx-go constructs or uses these files:
The easiest way to shut down WebX is the 'shut down' option on the
Sysop Control Panel. You can also shut down Web Crossing with 'make quit',
or a termination signal to
webx-run.
»Makefile
Makefile defines several commands to get you started with Web
Crossing. Once started, you will use Web Crossing itself for configuration and
management (log into Web Crossing as sysop and select the Control
Panel).
Makefile defines these commands:
- make [help]
- List the make commands.
- make cgi
- Write a new CGI script for Web Crossing -- WebX.
- make global
- Set global access permissions for Web Crossing, Images/, Client/ and WebX.
- make run
- Start the Web Crossing server.
- make server
- Start a non-daemon server for Web Crossing and report errors to stderr.
- make start
- Create start-webx for automatically starting Web Crossing.
- make resetmem
- Reset the memory configuration of Web Crossing to the minimum
configuration.
- make echo
- Start an echo server for WebX and webx-cgi.
- make stdio
- Start an interactive session for Web Crossing (try 'help').
- make quit
- Stop a server.
- make version
- Report the Web Crossing version along with commands for webx-run.
Makefile contains the following variables for
Custom install. These effect how Web
Crossing works. Most users do not need to change Makefile.
- WEBX_DIR
- Web Crossing directory. This directory contains webx-go,
webx-run, webx.log, and Client.log. WEBX_DIR
should be an absolute Unix pathname, e.g., /usr/webx.
- CGI_SCRIPT
- CGI script for URLs. This identifies the Web Crossing server in a 'ps'
listing. It also sets the CGI path for 'webx -stdio'.
- CLOCK_SKEW
- Clock skew between server and client in seconds (-skew). If a client
socket is older than CLOCK_SKEW seconds, Web Crossing refuses the connection.
The default is five minutes.
- NO_LOCK
- Do not use record locking (-nolock). Web Crossing normally uses record
locking to prevent more than one server running at the same time. With NO_LOCK,
it uses an exclusive open to prevent multiple servers. If the operating system
crashes, you will need to delete webx.lock. Be sure that only one
server is running in a directory -- otherwise the Web Crossing database may be
corrupted. Web Crossing uses webx.testNNNNN as an additional test for
duplicate servers.
»Run Web Crossing without make
Some Unix systems do not include the make command. You can
maintain Web Crossing without make. The following provides the
equivalent Unix commands for webx/Makefile. The
tar file, make.tar, provides shell scripts for these commands.
Use 'make' if you need to customize the makefile -- the customization options
effect multiple commands.
- make cgi -- create a CGI script for Web Crossing
sed "s&WEBX_DIR=.*&WEBX_DIR=`pwd`&" <WebX.template >WebX
chmod +x WebX
You may also copy WebX.template to WebX, and replace "/usr/webx"
with the full pathname of your Web Crossing directory.
- make global -- provide global access permissions to Web Crossing
chmod -R a+r Images webx-unix.html
chmod a+rx webx-cgi WebX
chmod a+rx Images
chmod a+rx Images/WBChat
touch Client.log
chmod a+w Client.log
mkdir Client
chmod a+rwxt Client
chmod a+rx `pwd`
- make run -- start the Web Crossing server as a daemon process
./webx-run -daemon -server
- make server -- start the Web Crossing server
./webx-go -server &
- make start -- create start-webx for automatic start of Web Crossing
echo cd `pwd` >start-webx
echo ./webx-run -daemon -server >>start-webx
chmod +x start-webx
Add the following line to your system initialization files:
su `whoami` -c `pwd`/start-webx
- make echo -- start the echo server for testing Web Crossing
./webx-go -echo
- make resetmem -- reset minimum memory configuration
./webx-go -resetmem -server
- make stdio -- start a stdio session for testing Web Crossing
./webx-go -stdio
- make quit -- stop the Web Crossing server
kill `cat webx.lock`
You may also list the Web Crossing process with 'ps -e | grep
webx-run' and 'kill' the process id for webx-run.
- make version -- report the current version of Web Crossing
./webx-run
»What to do if Web Crossing does not
work
Here is a list of problems and possible solutions. New and modified items
are first.
»Report a problem with Web Crossing
If you can not identify the cause of a problem, please let us know. Send
email to support@lundeen.com with the
following information
- a description of the problem.
- a copy of webx/webx.log and webx/Client.log.
- the name of the downloaded file for Web Crossing, e.g.,
webx1.1.5-solaris2.4.tar.Z.
- your computer and operating system.
- a list of Web Crossing processes (e.g., 'ps -ef | grep webx').
- if a core file was generated, a stack trace from the 'where'
command from sdb, dbx, or gdb (e.g., 'sdb webx-go
core').
»New problems and solutions
- Apache hits the system child process limit and Web Crossing won't run.
You will see "couldn't spawn child process" in the Apache error log.
-
You can check the child process limit by running webx-res.
Under BSDI, you can modify /usr/src/sys/sys/syslimits.h
and change CHILD_MAX from 64 to some higher number, such as
#define CHILD_MAX 250 /* max simultaneous processes (var) */
(Thanks to Keith Rowland.)
- Users get frequent "Server Error" or "Cannot connect to chat room" errors
-
This can be due to system limits on the number of sockets per process.
Many Unix systems default to 64 sockets per process.
You can check the number of free sockets per process by running webx-res.
Each chat client plus
each simultaneous CGI request use one of these sockets, and
a busy Web Crossing server can easily require more than 64 sockets.
If the problem is due to chat service, you can alleviate this
situation by running multiple Web Crossing chat
fanout servers, with each fanout server limited to 50 connections.
The best solution is to configure the system to allow
more sockets per process.
On Solaris, this setting is in /etc/system:
set rlim_fd_cur = 1024
set rlim_fd_max = 1024
Do not set these values larger than 1024 due to a bug in select().
- Users complain of timing out whenever they do a search.
-
When performing a search, Web Crossing reads each message from disk.
This can take a while with a large database. During a search, other
users can not access Web Crossing. You should turn off searching
from the top-level folder (see General Controls). You should
keep all conversations under a thousand messages. Old, long
conversations should be moved out, or searching should be turned
off.
- webx/webx.log reports "ChFiReadPg-- page table index"
-
The database is corrupted. This may happen due to a power failure.
You will need to recover from a backup.
See How to backup a Web Crossing site.
- Web Crossing on Solaris 2.4 (or earlier) may crash under heavy
load.
-
Solaris 2.4 appears to have a connect queue bug with Unix domain
sockets. You should make sure that the TCP/IP parameter
tcp_conn_req_max is at least 1024. You may need a patch to version 2.4,
or an upgrade to a later version.
You can reduce load on the server
but turning off searches in General Controls of the sysop control panel
(also see problem
report).
D. Prichet made these recommendations (Sept. 1996):
- tcp_close_wait_interval (read and write) 240000
This should be 30000 for a web server.
-
tcp_rexmit_interval_min (read and write) 200
If you have a lot of traffic from 14.4 modems, move this value up to 1000.
-
tcp_fin_wait_2_flush_interval (read and write) 675000
Sun doesn't recommend changing this (they don't recommend against it...they
are silent) but SGI backs this number down to 3 minutes instead 10+. (The
value is in milliseconds). We have left it alone, but our Solaris box is
not a very busy web server.
- Everything works fine until you try to access Web Crossing with your
browser. Your browser reports that Web Crossing is not running even though
you can see it in the 'ps' listing.
- Either the permissions are wrong or the directory is wrong. If the message
reports a directory, try to 'cd' to that directory. If you can't, then that
is the source of your problem. If a directory is not listed, there may be
a permissions problem. Look at the Step-by-step sections and
Test each component of Web Crossing.
»Problems with buttons and images
- You've moved the Images/ directory and can no longer use Web
Crossing.
-
Go to the Sysop control panel with the URL ".../WebX?59@@". Go to "General
settings" and change "Directory for images". If this doesn't
work, try the suggestions under "Images do not appear".
- Some buttons or icons are missing.
- This may happen when you update Web Crossing to a new version. Either an
image file is missing or the server needs read access to a modified image file.
See Changes to the Unix distribution for a list of new
images and help files. Check the access permissions for
Images/*.gif. They should either have global read permission or be
owned by your WWW server.
- Images do not appear
-
If images do not appear, double check your access permissions to Images/
and its files. Try loading an image with a URL (e.g., <http://.../Images/login.gif>).
Try multiple images to avoid caching. Some WWW servers require capitalized
names for directories. Many WWW servers do not allow a symbolic link to your
Images/ directory.
- The buttons and icons are formatted badly.
-
Did you change "Custom Buttons and Icons" in the Control Panel?
If so, there may be a mistake in the height and width of a button. The text is
passed directly to the browser. To restore the default value, delete the
corresponding text in "Custom Buttons and Icons".
- 'Sysop documentation' looks out-of-date.
- You may need to update Images/syshelp.htm from the Web Crossing
distribution. Double check that your WWW server has access permission to syshelp.htm.
»Problems with starting Web Crossing
See also access permission problems.
- To automatically start Web Crossing:
- See Custom Install for instructions about adding
start.webx to your system initialization files.
- You have just changed the memory configuration of Web Crossing. The
program does not initialize, or it reports "server could not accept file 5".
webx-go is using a lot of virtual memory.
- You've set the memory configuration larger than the amount of physical
memory [the setting is for kilobytes of memory]. Since initialization touches
every page of allocated memory, it may take a long time to access all of virtual
memory.
To recover, stop the program with 'make quit' and reset the memory configuration
with 'make resetmem'. It may take a minute for the program to quit.
- When you start Web Crossing, it reports an error. Two minutes later it
reports another error.
- The error occurred during the initialization of webx-go. Since
webx-run automatically restarts webx-go, the error occurs
repeatedly. To stop the loop, execute 'make quit'. Please report these
problems since they should be caught before webx-go is executed.
- Web Crossing reports that it is already running, but 'make quit' has no
effect.
- Web Crossing performs several checks to insure that only one copy is
running in a directory. Web Crossing records its process id in webx.lock.
To list all Web Crossing processes, execute
- ps -ef | grep webx, or
- ps -x | grep webx
You may use the Unix 'kill' command to remove these processes. If you
remove a webx-run process, the corresponding webx-go process
is removed automatically. If you run multiple copies of Web Crossing, you may
use CGI_SCRIPT in Makefile to distinguish the copies.
- When you execute 'make run' or './webx-go', the shell reports "file
not found".
-
This can occur if you are running Linux 1.1. Web Crossing is an ELF program
that runs on Linux 1.2 or higher.
- Your browser shows a page of code when you first contact Web Crossing.
- The WWW server may be returning the contents of WebX instead of
executing WebX as a shell script. For example, Netscape servers may
need WebX.cgi instead of WebX.
»Problems with Sysop Control Panel
- You can not set the background color for your pages (Sysop General
Controls).
- You may have background color turned off in your browser. In Netscape
check General Controls, Color, Colors, let document override.
- You have lost your sysop password.
- Before this happens to you, place a copy of your password in a safe deposit
box. If it does happen, contact Lundeen & Associates.
»Problems reported by browser
See also access permission problems.
- You use tables to format your pages and reducing the width of the table
does not make the page narrower.
- Netscape uses the width of text areas to set the minimum width of a table.
To change the width of text areas in Web Crossing, go to "General Controls"
in the "Control Panel" and change "Maximum width in characters
for text and textarea boxes."
- Your folders and conversations do not include links to higher-level
folders.
- You've probably edited the "Title HTML template" in "Sysop
Title ... Settings" in the Control Panel. The links are inserted
by the "%%backpath%%" substitution variable. To restore the default
appearance, replace "Title HTML template" with
<P><B>%% backpath%%</b><P><h1><ul>%% pathTitle%%</ul></h1><p>
- When a user posts a message, the rest of the conversation is badly
formatted.
- Are you using custom headers? If so, the user's post may include an HTML
tag that conflicts with your header. Web Crossing automatically removes table
tags from posted messages. If a user tag conflicts with one of your tags, add
it to the list of tags in Sysop General Controls.
- When you try to read subscriptions, the connection times out or your
browser reports an inaccessible server.
-
Your HTTP server may be setting the incorrect site address for the SERVER_NAME
CGI variable. Web Crossing uses SERVER_NAME to generate a Location: URL. This
redirect allows the user to reread a subscription without generating a new
'read subscriptions' request. To set the correct address, change 'Sysop server
address' in the
Sysop General Controls panel.
- Browser reports "no data returned"
- The WebX client did not return an HTTP header with "Content-type:"
and data. First try "http://(your site)/cgi-bin/WebX?webx-get". You
may now see an error message from the WWW server. You may also check 'ps' to
see if webx is running. Then check the webx.log to see if webx-go
crashed.
- Macintosh browser reports "Network error: broken pipe"
- Try loading the URL directly (e.g., "http://(your
site)/cgi-bin/WebX?79@@"). This submits the request without posting data.
Sometimes the Macintosh network connection will time-out on posted data.
- Browser reports "Server is inactive"
- If you just started Web Crossing, try again: webx-go may still be
initializing. Otherwise, check webx.log to see why webx-run
terminated. Then restart with make run.
»Problems with access permission
- When you first start Web Crossing, the browser reports "Could not
reach the Web Crossing server -- The server is inactive or busy -- "webx.socket".
- Either Web Crossing has stopped running or there is a permissions problem.
Note that the error message lists "webx.socket" without a directory
path. This means that webx-cgi could not read the directory path. [K.
Boehnert]
-
Use the 'ps -x' or 'ps -e' command to determine if webx-go is running.
If it is not, check webx.log to see the reason.
- Try running webx-cgi directly. You should get a page of HTML
from
webx-go.
- Try logging in as another user or as the userid of your HTTP server. Try
webx-cgi again. If you get an error message, there is a permissions
problem.
- Check the permissions of all higher level directories from webx/.
- See Step-by-step: check access permissions.
- Browser reports an access authorization error.
- Check the owner ids and access permissions for the webx/
directory and its files. Your WWW server needs 'rx' access to the webx/
directory, Images/ directory, webx/webx-cgi, and /cgi-bin/WebX.
It needs 'rwx' access to the webx/Client/ directory. It needs 'rx'
access to all directories above the webx/ directory.
WWW servers may cache opened files -- changing a file's permissions may not
immediately fix an access problem even though the change is correct.
- Browser reports "This server has encountered an internal error,"
and the server's log reports an access authorization error.
- See previous answer.
- Browser reports "This server has encountered an internal error,"
and the server's log reports "malformed header for WebX".
- Some WWW servers require "#!/bin/sh" as the first line of a CGI
script. If your server requires a different first line, you will need to edit
WebX. For example, if 'whereis sh' reports "/sbin/sh",
change the first line of WebX to "#!/sbin/sh".
»Problems reported by the WWW server
See also access permission problems.
- A Netsite server reports: cannot exec [...] httpd/cgi-bin/WebX (Bad
address)
- This may be due to a Netsite bug. You can test it by sending the same query
string to a simple test script that echoes the query. The Netsite bug
is sensitive to
the length and content of the query string. It should disappear if you pick a
different name for your topic or conversation.
»Problems with Client.log
- webx/Client.log is empty, or a client reports an error
but webx/Client.log did not record the error.
- webx/Client.log records client errors such as attempted
connections that failed because Web Crossing was off. If the log file
is empty, Web Crossing may lack permission to write data to the log file.
Check that your HTTP server has write permission for webx/Client.log.
If you use 'make global', it sets global write permission for this file. [R.
Gahl]
- Client.log reports "Address already in
use" or "Connection refused".
- Too many users attempted to connect to Web Crossing at the same time.
Before the 96/5/30 version of Web Crossing, the limit was five. Now the limit
is 1024, but your system may enforce a limit of five. If you see this error,
increase the maximum size of the TCP connect queue by adding
ndd -set /dev/tcp tcp_conn_req_max 1024
to the Unix startup file /etc/rc2.d/S69inet. Your system
may use a different command or a different startup file to set this limit. If
the limit is five under Solaris 4.2 or Irix 5.3, the Web Crossing server may
stop.
»Problems reported in webx.log
- webx-go reports "CxRecFile - file open/create error".
- Web Crossing does not have read or write permission to a log file. Check
the permissions on webx/log*. Web Crossing creates a new log file for
each session. You may turn off logging from the Control Panel.
- webx-go reports "Warning: an exception has been generated,
error code: 3".
- Web Crossing does not recognize webx/webx.db. The file may be
corrupted.
- webx-go reports "Warning: an exception has been generated,
error code: 214".
- Web Crossing reached end-of-file while initializing webx/webx.db.
Was the file truncated?
- Web Crossing reports "client pipe ... was created NN seconds ago.
The maximum age is 30 seconds."
- The clock for your WWW server may be different than the clock for Web
Crossing. If this is the case, set CLOCK_SKEW in
Makefile.
- Web Crossing reports ... "[Socket operation on non-socket]"
-
Under SunOS, and perhaps under other NFS systems, Unix domain sockets must
reside on a disk belonging to the current host. For example, this error occurs
for webx.socket if the webx/ directory is on a BSD system
and Web Crossing is installed on a SunOS system.
- Web Crossing reports ... Error while initializing webx: ChInit -- can not
create transient file
- The Web Crossing server could not create AU000000. Delete the file and
check your access permission for the webx/ directory.
»Test each component of Web Crossing
You can test each component of Web Crossing individually.
- Use 'ps' or 'kill' to remove processes for
webx-go and ./webx-run.
- Execute 'webx-run'. You should see a help message that lists the
available options. If you don't, the executable file is incompatible with your
computer.
- Execute 'webx-go'. You should see a help message that lists the
available options. If you don't, Web Crossing was not able to initialize. For
example, this may occur if webx.db or AU000000 has the wrong
access permissions. You can delete AU000000 and restart Web Crossing.
You can rename webx.db and restart Web Crossing -- it will create an
empty database.
- Execute 'make stdio' or 'webx-go -stdio' to start an
interactive session. Each command ends with a blank line. Try the 'help' and
'get' commands. Use 'quit' and a blank line to exit the interactive session.
- Execute 'webx-cgi . -echo' (note the "." -- it
indicates the current directory). webx-cgi should return a simple
message.
- Execute 'make echo' or 'webx-go -echo&' to start an
echo server. Test the server connection with 'WebX' or 'webx-cgi
.'. Quit the echo server with 'webx-cgi . -quit'.
- Execute 'make server' or 'webx-go -server&' to
start a Web Crossing server. Test the server with 'WebX' or 'webx-cgi
.'.
»Changes to the Unix distribution
This section lists the changes for the Unix distribution of Web Crossing. See
also New problems and solutions. See
Revision history for changes to Web Crossing.
Version 2.0, March 21, 1997
- Fixed webx-cgi to not create an unused Client directory. On some systems,
this create was causing an access error to be reported.
Version 2.0, March 8, 1997
- Fixed webx-cgi to delete its client socket if it is interrupted with
SIGTERM, SIGINT, or SIGHANGUP.
- Fixed webx-run to delete the temporary socket used for checking duplicate
servers (webx/Client/testNNNN).
- Updated make-global in make.tar for
Run Web Crossing without make.
- Added make.tar to
the distribution file.
Version 2.0, March 1, 1997
- Added How to backup a Web Crossing site. This
describes the backup files webxdb.1 and webxroll.1.
- Added notes about searching to How to manage a Web Crossing site.
- Added new buttons to Images/ for better readability and for chat.
Most of the buttons were redone late last year.
- Added webx/survey.tpl as an example template for taking a survey.
- All '/Images/sys*.htm' files have changed.
- Added Java files for chat to Images/WBChat/.
- Renamed webx-isp to webx-mult.
- Added two child processes to webx-go for Internet lookups. See
How Web Crossing works.
- Changed webx/webx.lock to a fixed length number. Fixes 'make quit' after
a reboot.
- Changed webx-cgi to delete the socket in webx/Client/ at exit.
Earlier
versions deleted the socket when webx-cgi successfully connected with webx-go.
- Changed the default clock skew (CLOCK_SKEW) from thirty seconds
to ten minutes.
- Changed the timeout for webx-cgi from thirty seconds
to five minutes.
- Changed the maximum number of repeated errors from six to twenty.
- Added a one second delay between repeated errors.
- webx-run exits if it fails to restart webx-go
more than three times in a row.
Version 1.2.2, July 30, 1996
- All '/Images/sys*.htm' files have changed.
- Added sysmult.htm and mult.gif to 'Images'.
These files are for the MULTIPLE version of Web Crossing.
- Changed webx/standard.tpl.
- Added 'make start' to start Web Crossing at system
initialization. [R. Gahl].
- Added 'make resetmem' to reset the memory configuration of Web Crossing.
- Improved the error message if a client drops a connection while posting
data.
Version 1.2.1, July 3, 1996
- All '/Images/*.htm' files have changed.
- guided.exp has changed. You should delete the old "Guided
Tour of Web Crossing" and import guided.exp
- standard.tpl was added to the webx/ directory. To use
templates, copy standard.tpl to webx.tpl and read the sysop
documentation.
- Added notes to backup webx/webx.db on a regular schedule. [K.
Bates]
Version 1.2.0, June 20, 1996
- Fixed auto-start of Web Crossing via a system's initialization files. Some
systems use a daemon process to start daemon programs such as Web Crossing. To
allow this, a '-nottop' flag was added to webx-go. [J. Perry and F.
McCaughan]
- Folders with access lists may be deleted directly. In previous versions,
you needed to delete the access list before deleting the folder.
Version 1.2.0, June 3, 1996
- Added a timeout of 30 seconds to webx-cgi. [M. Douglass]
- Removed "(client NNN)" from errors since it was uid instead of
pid.
Version 1.2.0, May 30, 1996
- Increased listen() limit to 1024 connects (see problem
report). [F. McCaughan]
- Added option 'webx-go -client ...' to combine server and client logs.
- Added option 'webx-cgi . -log' to log all client requests. [F. McCaughan]
- Removed a memory leak in webx-go error handling.
- Clarified some error messages.
Version 1.2.0, May 24, 1996
- Fixed error in timeout logic. [A. Stellpflug]
- Allow sysops to turn off log files across restarts.
- For users without 'make', download
make.tar for
shell scripts. [C. Zilbersher]
- Restart webx-go if accept errors occur six times in a row.
- Redid '-help' prompt for webx-run
Version 1.2.0, May 21, 1996
Version 1.1.10, May 14, 1996
- Fixed bug when deleting a message.
- Fixed search for unused log file (logNN).
Version 1.1.9, May 10, 1996
- Changed Images/syshelp.htm and Images/edithelp.htm.
- Added Images/chkmoder.gif, Images/search.gif, and Images/preview.gif.
- Added How to manage a Web Crossing site.
- Added Move Web Crossing to another server or directory.
[C. Zilbersher]
- Added notes on reporting problems with Web Crossing.
- Added notes on how to stop Web Crossing.
- Moved old release notes to
webx.lundeen.com.
- Log all client (WebX/webx-cgi) errors to Client.log.
- Removed extra lines from webx.log and added version stamp.
- Changed 'make version' to use webx-run instead of webx-go.
- Always check for access to Client.log and webx.log.
- Added explicit delete of AU000000 during initialization. This
double checks access permissions. [S. Johnson]
- Prevent repeated error exits while quitting Web Crossing.
- Prevent repeated errors when webx-cgi fails.
- Removed delete of core from webx-run initialization.
- Switched to static linking for SunOs and BSD (removes dependency on GNU
libraries).
See old release notes
for earlier release notes.
Brad Barber, Cambridge, MA.
Up: Web Crossing home page
To: Table of Contents
Comments to: support@lundeen.com