This is a first stab a Web interface to the PTS database.  Much of
it is done, but it's not a complete product yet.  Currently you still
need xpts available, particularly for your sysops.


What will it do for you?
-----------------------

*  It provides a CGI program that will allow your users to REPORT problems
	using Netscape, Mosaic, or most other Web browsers.  They are
	presented with a form to fill out.  When they choose to submit
	their problem it is entered into your PTS database immediatly.

*  It provides a way to build a WAIS index of your PTS database, which your
	users can either SEARCH or BROWSE using Netscape or other browser.

*  It gives your users a text-mode method of reporting problems, since
	text-mode browsers like Lynx exist.  Your users finally have a
	way to report problems without having X!

*  It provides a way to report problems from other platforms other
	than Unix systems, since Netscape and other Web browsers are
	available on other platforms (i.e. Windows & MacOS).
	Your users will finally be able to easily report problems
	from these type of systems.

*  It has that "gee wiz" factor associated with the Web.  Many users
	will be more likely to report problems if they have a Web-based
	tool than other types of tools.

*  It slices, it dices, it even helps you MAKE MONEY FAST (tm)...
	

What should you be aware of?
---------------------------

*  IT IS YOUR RESPONSIBILITY TO CONFIGURE SECURITY FOR YOUR WEB AND
	WAIS SERVERS.

	Let me emphasize that again:

	IT IS _YOUR_RESPONSIBILITY_ TO CONFIGURE SECURITY.

	Even then, most (all?) free server software only provides
	very minimal security, as far as I know, so you must decide
		(A) what the risks are for your site, and
		(B) what to do about it.
	If you are the least bit unsure, do NOT set this software up
	until you know what to do, even if your boss is yelling at you.
	(You can tell 'em I said so... :-)  You most certainly do not
	want Joe User to be able to spew garbage into your database
	across the Internet from the other side of the planet.
	(No offense intended to users named "Joe"...)

	As a rule of thumb I would NOT even begin to consider setting
	up this version unless I was sitting behind a firewall,
	AND I trusted my users to provide their true e-mail addresses
	when reporting problems.  Not to sound overly paranoid,
	(who me?! :-) but even then there are security issues (for
	example, if any account on your systems is compromised and
	that account has access to a Web browser [Lynx in particular]
	they will be able to spoof problem reports.)  Be Warned.

	Enhancing the security capabilities is high on the TO-DO list.
	Primarily this will consist of documenting what you can do
	with your web server to make things more secure.

*  The HTML files that users browse and search are not always current.
	This stems from the fact that the HTML pages and WAIS index
	are not generated on-the-fly, but are gererated in a periodic
	fashion using cron.  It's up to you to decide how often to
	regenerate the HTML and WAIS data.  You can generate them more
	often and pay the price in CPU cycles.

*  The HTML files generated have some Netscape 1.1 enhancements,
	but will work fine with other Web browsers.  Netscape 1.1 is
	strongly recommended if you can use it.

*  Netscape's "Dynamic Documents" are used.  With this its possible
	to tell the browser to check back in a few minutes to see if
	the problem being viewed has been updated.  This is highly
	desirable if you are updating your HTML files very often.
	Netscape is not required, but other viewers are more likely
	to get out of sync, especially if they do some sort of caching.
	If you disable the dynamic documents and you are using Netscape
	you need to tell Netscape to verify documents every time
	while accessing the PTS database since it caches documents.

*  The Web interface currently does NOT provide a way to solve
	or reopen problems.  (On the plus side, no other PTS interface
	has the search capabilities that this one does.)

*  You really need to become familiar with your Web server and WAIS
	server before attempting to set this up.

*  "xmkmf", "make", and "make install" must be executed seperatly
	for this part of the package.  Doing it at the top of the
	source tree skips this part.

*  Since an HTML file is created for each problem in your database,
	you need about twice as much disk storage space.  The WAIS
	index program temporarily needs even more.

	
How does it work?
----------------

A program is executed periodically with cron which reads in each problem
in your PTS database and outputs a corresponding HTML file.  An index is
created for each leaf in the problem tree (in this case we're talking just
a list of HTML pages, not a WAIS index.) 

Once all the HTML data is ready, the WAIS indexer is invoked to build
an index of the HTML files.  It performs a full-text index, meaning
you will be able to search for words imbedded in problem logs,
not just subject lines or filenames.  

At this point the data is moved into the public access areas, and
your HTTP daemon and WAIS server need to be either running or configured
to start via inetd (I don't recommend starting the WAIS server with
inetd since it tends to be slow to start up.)

Most of the work is done in batch mode.  This has good and bad points.
It's good because when people start querying your database the HTML
files are ready to go and do not need to be regenerated each and every
time someone reads a problem.  It's also good because it's simple to do.
It's bad since you always stand the risk of being a little out of date.
How critical this is to you will determine if this feature currently
meets your needs.  (Remember, you also have Xpts to get a truely current
look at the database.)

It was set up this way since it was the simplest way to do it, and this
is my first time working with CGI programs and WAIS.  I'm sure I'm doing
a lot of things wrong, and I'm sure it will be greatly improved upon
in the "near" future, (especially with your help!).

This whole Web thing started as an experiment, since I was curious whether
it could be done.  Originally it was going to be very simple.  Well, I 
got carried away since HTML/WAIS is so much fun, and before I knew it
I had most of it working.  It kinda threw off my plans for PTS version 1.1,
but I hope it was worth it.


Compatability
-------------

This an overview of the current development system:

	* Linux w/ kernel 1.2.x
	* XFree86 3.1.1 (X11R6)
	* GCC 2.5.8
	* either one of:
		+ CERN's httpd version 3.0
		+ NCSA's httpd version 1.3R
	* WAIS 8.b5
	* Netscape 1.1N

No attempt has yet been made to test compatability with other
HTML and WAIS servers.   (This is left as an exercise for the reader
for now...)  Either the CERN or NCSA httpd will work fine.  The 
author currently prefers the CERN server since the security and
other things seem more configurable, but either server works great.

Other browsers should work fine too, they just won't be as pretty.


Future Development
------------------

*  On-the-fly HTML page and WAIS index generation.  When someone updates
	a problem in the PTS database the HTML/WAIS data could be updated
	in a more timely manner.  The current process requires the HTML/WAIS
	data be updated every so often (hourly? every-other-hour?  daily?).

*  Optimization of the HTML page and WAIS index gereration.  Tied to the
	item above.  The current process generates a new HTML page for
	each problem in the database, regardless of whether or not
	it has changed since it was last generated (an inefficient process
	indeed.)  I'm certain this will not scale well at all.

*  Compatability with other HTML and WAIS servers.  Netscape's Web server
	would be a nice addition because of it's security features, but alas,
	I doubt I will have access to it anytime soon.  Please consider
	helping out here if you have access to such a server.

*  Security issues must be thoroughly investigated.  So far the emphasis
	has been on "getting something basic to work".

*  More documentation.  Setting this up is more challenging than setting
	up the rest of PTS, since it requires httpd and waisserver
	be configured.  For now, you're on your own to get your HTTP
	server and your WAIS server up and running.

*  Pick a name.  I'm leaning towards "Wept", as in WEb PTs...
	(Appropriate, eh?  :-)  For when your users come crying to you...
	Recommendations are welcome!


Final Comments
--------------
The value of allowing your users to report problems with Netscape
and the like is reason enough to look at this new portion of
the PTS package, regardless of whether you get into the rest of
this.  

Let me know what ya think.



Tue Jun 13 21:35:12 PDT 1995
----------------------------------------------------------------------
Dean Collins					      Redmond, WA, USA
dean@halcyon.com		      "Peace, Love, Empathy." - Cobain
http://www.halcyon.com/dean/
