Installation and Setup Instructions for The Finger Server

Introduction

Thanks for taking the time to download The Finger Server. These instructions will walk you through a complete install of the program on your server. Once your Finger Server is installed, you will be able to access the Quick Help section of the Control Panel for help with Control Panel functions.

Please note that the Quick Help will not be fully functional until version 1.0 is actually released.

If you find any errors or inconsistencies in this guide, please let me know so that I can correct them.

Upgrading Over Previous Versions

Preparation / Configuration Backup

Although I do everything I can to make sure new distributions work properly when upgrading over old installations, you should always backup your Finger Server installation before upgrading. If you (or I) made a mistake, you can easily copy the old files back into place.
If you do not backup your entire finger server, at least make a backup copy of your *.cfg files, your banner.ad file, your adminpass.cgi file and your data/users file before upgrading. These files contain your configuration settings and user settings. If you overwrite them, you will have to reconfigure your Finger Server and re-add all users... You don't really want to do that. =)

Upgrading

To upgrade, just copy all files except the *.cfg files, banner.ad, adminpass.cgi and users file to their proper locations on your web server.
Note: You do not need to copy the directories again, only the files inside the directories.
You shouldn't need to reconfigure the file permissions, but it doesn't hurt to make a cursory examination of a few files to make sure their permissions are still set properly. If they are not, you should recheck all files for the correct permissions. See the installation section for proper file and directory permissions.
If you are using your own custom logo and corner graphics, be sure not to overwrite your old ones. Just check for new files in the htdocs directory and only upload those.

Setup

Once you have uploaded the files, you should check your System Setup and Look and Feel for new options available and configure them as needed. New options have a red + next to them to indicate that this is a new option available for this version.
That's it. Your Finger Server should be upgraded and working properly now.

Installation Instructions

First Steps

If you haven't done so already, download a copy of The Finger Server and extract it to an empty directory on your computer. Be sure that when you extract the files, you keep the paths in the archive intact. WinZip (Windows95/NT) and unzip (Unix) should have no problem doing this for you.
Inside of the finger directory, you should have now have two directories, one named cgi-bin and one named htdocs. The cgi-bin directory contains all of the scripts and files that should be uploaded to a cgi-bin directory or any location on the webserver that can execute CGI scripts. The htdocs directory contains all files that should not be placed in a cgi-bin directory. (This is due to the fact that some webservers won't serve html and image content from the cgi-bin directory...)
In the cgi-bin directory, you will find three other directories named admin, user and data. These three contain the administration scripts, user scripts and user data respectively.
Note: some zip utilities (such as WinZip) will not extract the data directory from the Unix version of the distribution. If you do not have a data directory, follow these steps:
1. Create a directory named data inside your cgi-bin directory.
2. Create a new text file named users. Leave it blank and save it in your new data directory.
3. Be sure there is no extension on the users file... The full filename should just simply be users.
You will need to edit the three main CGI scripts and replace the top line in each with your server's path to perl. The scripts currently have #!/usr/bin/perl on the first line. If, for example, your server's path to perl was /bin/perl then you would need to change the top line in each file to #!/bin/perl.
The three scripts you need to edit are:
/cgi-bin/finger.cgi /cgi-bin/admin/admin.cgi /cgi-bin/user/user.cgi
If you are not sure what your server's path to perl is, you can telnet to your server and issue the command whereis perl or ask your system administrator. Note: /usr/bin/perl is the normal path to perl on unix systems, so you probably won't even have to make these changes.
NOTE: If you are uploading these files to a Unix machine and you have edited these three files, be sure to save these files in the unix text format (LF instead of CR/LF). If you do not do this, your scripts will not work! Windows 95/NT users can find an excellent text editor that will save unix text files properly at www.textpad.com.

Uploading Your Files

Before you upload the files to your webserver, you should create two directories. One for the CGI scripts and one for the html files. Create a directory named finger in your cgi-bin directory and a directory named finger in your html path. Feel free to use any directory name you wish, finger is only an example.
Upload all of the files and directories in the cgi-bin directory on your machine to the /cgi-bin/finger directory on your webserver.
Upload all of the files in the htdocs directory on your machine to the html directory, /finger, on your webserver.
In the /cgi-bin/finger directory on your web server, create two additional directories. One should be named plans and the other should be named news.
If your web server is a Unix server, you will need to set the permissions for the directories, scripts and other files in the cgi-bin directory. From the Unix command line or a telnet session, you can issue the chmod command to do this. (type man chmod for details) In addition, all most all Windows 95/NT FTP clients allow you to change the permissions of files on a remote server. See your FTP client documentation for instructions.
All *.cgi, *.pl and *.pm files in all directories should have their permissions set to 0755.
Exception: /admin/adminpass.cgi should be set to 0777.
All *.cfg files should also be set to 0777.
The users file located in /cgi-bin/finger/data/ should also be set to 0777.
The banner.ad file should be set to 0777.
All directories, including the main /cgi-bin/finger directory should be set to 0777.
All other files not mentioned here should be set to 0777.
SECURITY NOTE: The instructions above set several files and directories on your webserver to read, write and execute for `world'. This means that anyone who has ssh or telnet access to your server could possibly modify files under your finger server directories. It is neccessary to set your permissions in this way, because a web server, by default, is run with the lowest possible permissions and generally does not have write access to a user's web pages or cgi scripts.
That said, the Finger Server stores configuration information and plan information in your cgi-bin directories and must have write access to specific locations. If you know that your web server does have write access to your Finger Server files as user or group, you can turn off the write bit for world by issuing this command:
chmod -R o-w *
Please make sure you are in cgi-bin/finger before issuing this command!
It's important that you correctly set the file permissions on your server. If your Finger Server doesn't work in the next section, it's most likely a problem related to file permissions than anything else... seriously.

Configuring Your System Setup

Now that we have uploaded the files and directories, we need to configure the Finger Server from the Control Panel. Point your web browser to the admin.cgi file in your /cgi-bin/finger/admin/ directory.
For example, if you installed the Finger Server in /cgi-bin/finger/, you would point your browser to http://www.yourdomain.com/cgi-bin/finger/admin/admin.cgi
If everything was setup correctly, you will be prompted for a username and password. The default username is admin and the default password is 51channels. Once you have logged on, you should go directly to the System Setup section to configure your system so that the rest of the Control Panel works properly.
Each option in the System Setup has an explanation beneath it. Read each one carefully and fill in the appropriate values. If you are unsure of anything such as the server path to your cgi-bin or html files, contact your system administrator. You can also use the View Environment option in the Control Panel to see some useful information about you web server such as the cgi-bin path, etc.
After configuring your System Setup, all functions in the Control Panel should work properly. If they do not, go back and confirm that you've entered the correct information and that all of your file permissions are correct.

Configuring Your Look and Feel

Next, configure the Look and Feel of your server.. Here, you can customize the server name, color scheme, categories and other information about your server.
Each option in the Look and Feel section has an explanation beneath it. Read each one carefully and fill in the appropriate values. In most cases, the default values should work just fine here and if you are unsure of anything, you can leave it like it is. You can always change it later.
The Homepage "Latest Plan List" Setup section of Look and Feel will be explained below.

Changing Default Password

Now that your System Setup and Look and Feel have been configured, you should change the default password. Each finger server starts with the same default administrative username and password. If you don't change your password, anyone could login to your Finger Server administration script and make changes, or worse, without you knowing.
From the main administration menu, select Change Password.
Enter the new username and password you would like to use.
After the password has been changed, you will need to log back into the server using the link provided.

User Administration

Next, you will want to begin adding users. Select User Administration in the Control Panel. To add or change, or remove a user, select the appropriate action. Newly added users will immediately be able to logon and begin updating their plans.
Note: if you remove a user, you should also delete any plan files that they have created. You can find them in the /cgi-bin/finger/plans/ directory. If you only wish to disable a user account, just change the password.

User Access

Users can logon and update their plans from the User Control Panel. They access this in a similar way that you access the main Control Panel.
To logon, the users should point their web browsers to the user.cgi file in the /cgi-bin/finger/user/ directory.
For example, if you installed the Finger Server in /cgi-bin/finger/, they would point their browsers to http://www.yourdomain.com/cgi-bin/finger/user/user.cgi to update their plans.

Finished

That's it. If you need any help with the other Control Panel sections, refer to the Quick Help section in the Control Panel.

Displaying a List of Latest Plan Updates on Your Home Page

A nice feature of The Finger Server is the ability to display a short list of the latest plan updates on your main web page. You have the choice of displaying the latest updates from all categories, or only the users in the special category.

Preparation

The two scripts that display the latest updates, grablatest.cgi and grabspecial.cgi rely on Server Side Includes (SSI) in order to display the information. A SSI is a tag that the web server parses before the html is ever sent to the browser. This allows the server to do something such as execute a CGI script and insert the the result directly into the web page. SSI tags generally follow the form of

Traditionally, HTML pages that contain SSI tags are named *.shtml instead of *.html. Although, they can be named anything the server admin wishes such as *.ssi or *.shtm. This allows the server to distinguish between a page with SSI tags and one without.
In order to use these two scripts, your server should be able parse SSI tags including the exec SSI tag. If you have trouble, or are not sure, please check with your server admin first.

Setup

You should find two files in your /cgi-gin/finger/ directory on your web server named grablatest.cgi and grabspecial.cgi. Both of these files' permissions should be set to 0755.
The grablatest.cgi script shows the latest updates from all categories and the grabspecial.cgi script only shows the latest updates from the users in the special category.
To insert the scripts in your html page, you will need to first make sure that it's named *.shtml (or whatever your server is configured for). Next, you will need to insert the SSI tag in the exact place you wish the list of updates to appear. If your finger scripts were located in http://www.yourdomain.com/cgi-bin/finger/ you would use one of the following tags:

or

Replace /cgi-bin/finger/grab*.cgi with the correct path for your setup.
Note: the only space in the above SSI tags are between the words exec and the cgi.
That's it! If you point your browser to the *.shtml page on your web server, you should see the list of plans where you put your SSI tag.

Customizing

You can customize the number of plans diplayed, font face, font size and table aligment of the grablatest.cgi and grabspecial.cgi scripts in the Look and Feel section of the Control Panel.
Go to your control panel and select Look and Feel. Scroll down to the section labled Homepage "Latest Plan List" Setup and make any changes that you would like. Submit the changes and they should be reflected the next time you view your *.shtml page.

Displaying a List of Latest Plan Updates on an Affiliated or Hosted Web Site

In addition to dislaying the list of updates on your home page, an affiliated or hosted web site can now also do the same. The getfingerlist.cgi script will display the latest updates from all categories.

Usage

The getfingerlist.cgi script depends on system variables from your finger server to run properly. Each time you make a change to the System Setup, a new getfingerlist.cgi script is written to your /cgi-bin/finger/ directory. You will need to go to your System Setup and submit the page, even if you don't make any changes, to write the script for the first time.
Once you have updated your System Setup, you can distribute this script to the web sites that would like to display the updates from your finger server. Detailed instructions for installation and using the script are written inside the script itself and can be easily read by simply viewing the script in your favorite text editor.