Emaze WebThread Freeware:
Installation Instructions

Thank you for checking out the freeware version of Emaze WebThread. If you ever have any comments, questions or suggestions, please let us know. Simply jump to our customer service forum from our home page at http://www.emaze.com or email us at freeware@emaze.com . This freeware version does not expire, but several features included in the commercial version of WebThread 1.0 have been disabled:

Upgrading to the commercial version of WebThread can be done without losing any of your messages, threads, or users. It is a simple process which takes only a couple minutes. WebThread 1.1, which will be released at the beginning of November, costs just $49. To upgrade, simply go to our website at http://www.emaze.com and click on the "Order Now" button. In addition to the features listed above, the commercial version of WebThread 1.1 will include:

IMPORTANT note for NT users: Your web server must be running PerlNT build 110, which was just released on August 13. Win32 Perl is available for free from hip.com.

TABLE OF CONTENTS

Definitions:

auth
usage permission necessary to do certain things; short for authorization

uid
user id; this is how WebThread identifies users; it is unique for each person, and is simply a serial number assigned at the time users are added to the user database

username
login name that is used (along with a password) to access WebThread

post
a single message added by a user to a thread

unpost
to delete a post; can be done either by the user herself (provided her auths allow her to do so) or any user with admin auth

thread
list of posts; an ongoing discussion on a particular topic; users with admin auth can suspend a thread, temporarily removing it from users' thread menus, or delete a thread, permanently removing it from the system

conference
what users log into, each containing multiple threads; a forum for discussion on some broad topic

masking
give or deny a specific auth to all users, temporarily over-riding their individual settings

ticket
logging into a conference gets you a ticket; it's the ticket that actually lets you do things; this prevents repeatedly sending your password across possibly-insecure networks
Back to the Table of Contents

Requirements

To run WebThread, you will need:
  1. Web server running on a MacOS, Unix (any flavor: Solaris, SunOS, linux, etc.) or Windows NT machine. WebThread is not compatible with DOS-based systems that use 8.3 filenames, and it has not been tested on Windows 95 (although it might work).
  2. The ability to install your own cgi scripts. WebThread is a cgi script that must be installed in /cgi-bin, or whatever the moral equivalent is on your system.
  3. Account space outside the web (DocumentRoot) directory. Besides the main cgi script, WebThread has several support files, databases, and the files of the messages themselves. As a result, you will need a directory for them; for security reasons, this directory should not be reachable from the web (i.e., not in public_html).
File permissions:
    The main directory ("FT-dist") must be read-write-executable by a running cgi script. The subdirectories lib/ and bin/ must be executable, and all files in them must be readable. The msgtree1/ subdirectory must be read-write-executable, and all files within msgtree1/ must be readable. The cgi script itself must be readable and executable.
To use WebThread, users will need:
  1. A web browser -- Netscape, Mosiac, lynx, or MS Internet Explorer all work, though certain portions might look strange in lynx or other browsers that do not support tables. Certain screens (the user editor, for example) do not work at all in lynx, at least up to lynx v2.5--fixing this is not a high priority. Some Netscape enhancements are used, but other browsers will simply ignore these non-standard tags with no loss of overall functionality. Browsers must support forms and Location: redirection, but need not support WWW-authenticate: passwords, SSL, Set-cookie: calls, graphics, Java or JavaScript.
  2. A login on WebThread (created by the program) -- Each user is identified by a name/password, and certain users can be granted permission to create new users.
Security Warning:
We have attempted to make WebThread as secure as possible, while at the same time keeping the program efficient and platform- and site-independent. As a result, the built-in security mechanisms provide a reasonable level of protection from remote hackers and most casual intrusions. There are several known shortcomings that could allow a determined individual to gain unauthorized access. While it is not possible to learn someone else's password (except by brute-force dictionary-type attacks), it might be possible (depending on your OS, filesystem, server configuration, etc.) for someone who has access to the WebThread support files to log in as an arbitrary user without knowing that user's password or modify the internal databases and messages.

The patches needed to correct this problem vary with the particulars of each site--there is no universal fix, and detailing the modifications for every possible site configuration is well beyond the scope of this document. If you are concerned about such intrusions at your site, please contact Emaze Technical Support at support@emaze.com and we will advise you on the particular fixes needed.

Back to the Table of Contents

Installation Instructions

These instructions assume you have already unpacked the WebThread distribution. If you log onto your server directly (shell/telnet access), you should now have a directory called FT-dist there. If your server is configured such that you merely ftp files to and from it, the FT-dist directory should now be on your desktop machine.

We realize the length of these instructions may look intimidating, but rest assured that it should only take a few minutes to install WebThread. We have tried to make it as simple as possible by giving you detailed instructions.

1. The main file you have to edit is FreeThread, which is in the main FT-dist directory. You should never edit this file directly, since you might need to refer back to it later. Rather, always work on a copy of the file. In case you do accidentally overwrite a part of the FreeThread file, we have also included a backup, FreeThread.BAK .

Make a copy of the FreeThread file, and rename it anything you want. If your system requires an extension such as .cgi or .pl, be sure to include the extension. The name of the file will be part of the URL people use to run WebThread, so you could make the name indicate what will be discussed in this conference.

For the purposes of the installation instructions, we will continue to refer to the file as FreeThread, even though we mean for you to be editing your copy, not the actual file. If you do want FreeThread to be the name of the script, you can simply rename the original FreeThread file to something else, such as free-wt2, and edit your new FreeThread file.

2. Open the FreeThread file (in the FT-dist directory) in any text editor or word processor. FreeThread is the configuration file which gives the FreeThread system the information it needs to run properly. The file also allows you to customize the look and feel of your conference.

There are several variables you can change in this file, and they are each in blocks beginning with "### user config ###." We use line numbers to give you some idea where these variables are located, but the line numbers themselves are not actually in the file (and please do not add them). The instructions have you edit the variables in the order in which they appear anyway.

If you want to get WebThread up and running quickly, you only have to edit the following critical variables: perl and projectDIR (on lines 1 and 27, respectively). These 2 variables should not be changed after installation.

The errorLog variable on lines 37-39 affects WebThread's functionality. It is optional to edit now, but can be changed later if you so desire. Finally, there are 5 look-and-feel variables that may be edited now and can be changed later at any time and as often as you'd like: exitURL, lnf_name, lnf_bodytag, and lnf_button (on lines 32, 45, 48-52, and 56-82).

perl
Make the first line reflect where perl is installed on your web server. The line must be the first line of the file, the shebang (#!) is required, and no spaces are permitted. If you do not know this, ask your webmaster or Internet Service Provider. It is possible that the default value is correct anyway.

projectDIR
On line 27, 'projectDIR' is the directory where you will place the WebThread files on your server. This can be anywhere as long as it is executable by a cgi script. We recommend that you do not place this in the public_html directory though, since outside users should not have access to these files. (That would be a bad thing.) If you want, you can change the FT-dist directory name to something else, such as 'wt' or 'webthread'. If you do change the directory name, be sure that the directory exists on your webserver (if not, create it).

Regardless of the directory name you choose, you need to tell the script where to look for the files. Please note that this is not simply the directory, but the full path name to that directory. The first character should be a slash (/) but the last character should not. The full path name should also be in single quotes, e.g.: '/home/users/company/FT-dist' . For operating systems which use backslashes (NT) or colons (Mac), use them instead of the slash (Unix).

OPTIONAL VARIABLES: CAN BE EDITED AT ANY TIME
exitURL
Set the exitURL variable on line 32 to the URL where you want your users to be transferred after clicking on the logout button. Suggested URLs include your home page or customer service page. It is preset to http://www.emaze.com/, but we understand if you want to change it. Just be sure to put the URL in single quotes, as it is now. You do not need to use the <href> tag, just the URL.

errorLog
The errorLog variable on lines 37-39 determines how detailed error messages should be recorded on the server. To choose one, simply uncomment the line you want by deleting the number sign (#) and placing a number sign in front of the others. The default is WT-error-log, meaning a file by that name will be created in the projectDIR directory. You can change the file name in this option, or select one of the other options if you desire. Here is an explanation of each option: lnf_name
The lnf_name variable on line 45 is the name of that conference. It is what will appear in the <title> tag, and thus at the top of the browser, of all WebThread pages other than error pages. It is preset to 'howdy', but you might want to change it. Just be sure that the text is in the single quotes.

lnf_bodytag
The lnf_bodytag variable on lines 48-52 determines the information found in the <body> tag. The default is a white background and the standard black text and blue hypertext. You are welcome to change it, but please keep in mind that some colors are difficult to read. To change any of the options, just enter the new choice. The choices need to be in single quotes as they are now (even though you typically use full quotes). Also, be sure to change the text color if you change the background to black or some other color.

lnf_button
The lnf_button variables on lines 56-82 are the text which appear in the buttons used to navigate through WebThread. While there is no reason to change them, you may want to capitalize them or change them to a different language.

Close the FreeThread file.

3. If the operating system of your web server is Unix or linux, please skip this step. If not, open the CGI.pm file, which is in the FT-dist/lib directory, in any text editor or word processor. Scroll down to lines 34-38, which are below the following line:

# ------------------ START OF THE LIBRARY ------------

Lines 34-38 look like the 5 lines below this paragraph. The file is preset to Unix, so if you are using Unix (and decided to keep reading even though we told you not to), you do not have to change anything. If you are using one of the other operating systems, first add a number sign and blank space (# ) before the first line to make it look like the other lines. Then just delete the number sign and space on the line with your operating system. (Note that WebThread has never been tested on Windows 95 or VMS, although they might work.)

$OS = 'UNIX';
# $OS = 'MACINTOSH';
# $OS = 'WINDOWS';
# $OS = 'NT';
# $OS = 'VMS';

4. As ASCII text, ftp the bin, doc, lib and msgtree1 (or whatever you renamed it) directories to the projectDIR directory. The lib/compat_NT/auto/Fcntl.pll file must be ftp'd as a binary file rather than ASCII text, so you must overwrite the ASCII version you just ftp'd with the correct binary version. Just switch to the lib/compat_NT/auto directory, and ftp the Fcntl.pll file as binary to overwrite the ASCII file. (Sorry about the confusion, but we promise this is the only binary file.)

Finally, as ASCII text, ftp the FreeThread file (or whatever you renamed it) to the cgi-bin directory, or whatever directory you normally put cgi scripts on your system.

There is no need to put MANIFEST, COPYRITE, FreeThread.BAK, WT-FAQ.htm, or INSTALL.htm (this file) on your webserver. However, you should keep them on your own personal computer (i.e., not the webserver) so that you can refer back to them later. It is also not necessary to keep the WebThread files in the bin, lib, doc and msgtree1 directories on your computer, but it can't hurt.

5. Using your web browser, access WebThread to initialize it by jumping to the URL of the script. The URL is simply the URL you use to access cgi scripts, followed by the name of the WebThread configuration file. Here are a few examples of what it might look like: 
   http://www.yourdomain.com/cgi-bin/FreeThread
   http://www.yourdomain.com/cgi-bin/cgiwrap/~username/FreeThread

Note that the first example is if you have your own web server, while the 2nd example is if you use an Internet Service Provider to host your web page. The 'FreeThread' at the end is merely the name of the configuration file, which is FreeThread, unless you changed the name.

6. WebThread will tell you whether it has been installed correctly. If not, please re-read these instructions and check to make sure that you followed them precisely. Do not worry though since you can always start over and overwrite the old files. One of the most common errors is to accidentally delete a quote or semi-colon, or transfer the files as binary instead of ASCII. Also, be sure that you did not change the init variable on line 19 from 1 to 0 yet.

If installed correctly, WebThread will present a username and password to you. The username will be 'master' and the password will be a ridiculously-long string of numbers (damn those development people). Write these down! The master username is automatically given every auth; master is also needed when you create additional conferences. WebThread will also tell you the URL to use to access the system (i.e., reach the login screen) which is basically what you just entered to initialize WebThread. Do not try to log in yet though.

7. FTP the FreeThread file (or whatever you renamed it) to your computer and open it in your text editor again. Change the init variable on line 19 from one to zero, i.e.: 
   FROM:  $init=1;
     TO:  $init=0;

Changing the 1 to a 0 tells WebThread that it will now be ready for normal use rather than initialization. FTP the FreeThread file back to the cgi directory of your webserver to overwrite the old copy. Again, please be sure to ftp the file as an ASCII text file, not binary.

8. Now access the system again using the same URL as before. Login using the 'master' username and the ridiculous password. You can now add new users, set the default auths for new users, and do anything else you want. For a list of options, see WT-FAQ.htm .

While you no longer have to follow our instructions, we suggest you create a new superuser with the username you want. You should also change the password for master to something you will remember. You will need master again if you create additional conferences (if you upgrade to the commercial version) or accidentally deny access to all users.

You may also want to customize the 3 files in the msgtree1 directory:
login.html -- top of the page which your user first sees to log into WebThread
intro.html -- top of the main screen page, or the page user sees just after logging in
add.html -- top of web page for adding new users; when click on 'Add a new user' button

If you have any questions, just email us at support@emaze.com . You can also check out our Customer Service forum. Just go to our home page at http://www.emaze.com and click on 'Customer Service' at the bottom.

Back to the Table of Contents
Copyright © 1996, Emaze Software Corporation