WebTen & NetTen -A True Beginner's Guide

Part 5 - Installing your first CGI
by Terry Allen

The advantages of WebTen as a server platform are many, but one of the best advantages is that Tenon have managed to gather the resources of UNIX & the Mac OS together & allow server administrators to use CGI scripts & applications from a variety of sources within WebTen. While you may not have the ability to write your own CGI, there is a huge variety of freely available scripts, especially for the UNIX world & you can use these on your WebTen server.

You aleady saw a CGI at work, as in the last part of this tutorial I covered setting up the built-in ht://Dig search engine which Tenon has set up when you install WebTen. This time around, we're going to install a different CGI, so you can get the feel for installing others. I've chosen the WWWBoard script from Matt's Script Archive (http://www.worldwidemart.com/scripts) Matt Wright's scripts, while not entirely perfect, do provide a great selection of ready to run scripts, with concise, clear instructions & minimal work to get them up & running on your server.

So, now you need to visit Matt's Script Archive & download the latest version of the script, making sure you download the Y2K compliant version from http://www.worldwidemart.com/scripts/wwwboard.shtml There are a number of different versions on that page, but for simplicity's sake, I downloaded the file wwwboard.zip which includes everything you need to get up & running, including the Read Me files which explain how to edit the files. The .zip files are expandable with later versions of Stuffit Expander, so it makes it a lot easier to get the file expanded.

Okay, now you have the file expanded onto your Mac's hard drive (Figure 1), make a complete copy of the files so if you make a mistake on any of the editing which is irrepairable, you'll be able to go back to a fresh copy. First thing's first, open up the Read Me file & have a read through. You now need to decide which text editor you're going to edit your script file with. A few come to mind, such as Appleworks, BBEdit (the lite or full version) or of course, everyone should have a copy of Simpletext on their Mac, so that's a good choice. If by chance you're going to edit your files on a PC, Notepad is sort of the equivalent of Simpletext, so that's another option.

You now need to make a decision as to where your new CGI is going to reside on your server. You most likely already have yourdomain.com set up, so connect to your WebTen server via FTP & go to the location you're goind to put your new message board.

You need to go to your text editor & begin editing the CGI script itself. (Figure 2) Inside the wwwboard.zip archive you expanded, you'll see a file called wwwboard.pl In Simpletext, open this file up & follow the instructions in the Read Me file. Just below the copyright notice in the wwwboard.pl file are the first of the variables you need to enter & this is where a lot of people may get stuck. Most of these are fairly obvious, but the one which is a bit of a problem for some is where the mention of the 'absolute path' gets some Mac users confused & where the UNIX heritage of WebTen comes through.

For those in the dark, the UNIX variants of operating systems use 'paths' for the navigation of the hard drive. If you think of your hard drive as a tree, the very bottom of the tree is the root. In UNIX, the base level, or where you enter is the 'root directory' & is typically viewed as a '/' For example, the root directory of a website (as the world wide web is based on UNIX) is viewed as:
http://yourdomain.com/

If you have any files within the root directory, they would be viewed via your browser as:
http://yourdomain.com/somefile.html

Following this logic, you will have created the directory wwwboard within the root directory - this is known as a 'subdirectory' & viewed like so:
http://yourdomain.com/wwwboard/

However, while the browser thinks you have entered the root directory, the 'absolute path' is seen a little differently from within UNIX. The Mac OS has something similar, but you generally only see the path represented graphically with folders. If you ever load up a web page from your hard drive, you'll see the path of the file listed in the browser's location bar.

In UNIX, the root directory is still seen as '/', but the paths vary because UNIX isn't using the Domain Name System to track the files within the directory. You need to set the $basedir variable within the wwwboard.pl file to the absolute path that your wwwboard directory has been created at. To find this out, the easiest way is to go to the machine you have WebTen running on & select the Display Error Log option from the Log menu, load up a browser (or of course from another machine which can access WebTen & type in the URL where you want to put your wwwboard directory in the browser location bar like so:
http://yourdomain.com/wwwboard/

The server should return a 404 File Not Found Error. Assuming there isn't already a directory called wwwboard, the Error Log window in WebTen will show you an error for the absolute path, which should look like: /usr/local/etc/httpd/WebSites/yourdomain.com/wwwboard/

Now you know what the absolute path is, you can enter it in place of the existing $basedir variable. The others are quite self explanatory & simply need you to enter the appropriate URL for each variable. Again for simplicity, you might want to name the wwwboard.pl file to wwwboard.cgi when you save it, but be sure that you include the .cgi extension when you are changing the $cgi_url variable. There's no need to edit the $date_command variable either, as the standard variable entry is correct for the WebTen UNIX version.

Strictly speaking, there's probably nothing else which really needs to be changed, but it's nice to set things like the $title, FAQ locations & several others unless you're only trialling, but just follow the read me file to the letter & you'll have no problems. Once you've reached the end of editing the wwwboard.pl (or wwwboard.cgi if you're renaming it), save the file & go back through, checking for spelling or typing errors. This is the biggest problem which will kill your script's ability to work, trust me, I've been there.

Now, you need to put this into your WebTen cgi-bin directory, so go back to your FTP application, navigate your way into the cgi-bin & upload your edited script. the cgi-bin is located within the WebTen main folder, so you'll see a whole pile of other files & directories. Once you're there, simply upload the edited file.

Now, continuing on through the Read Me file, there are instructions for entering the CGI location in the <FORM Action=> tags within the wwwboard.html file (I renamed it to index.html so the URL would be shorter for people to remember), plus of course things like the page <Title> & <H1> fields. This file of course can be changed from within your favourite HTML editor, making things easier, or you can edit it in Simpletext like I did. When you've finished, you can save this file, with only a couple more to go.

The other files include the faq.html, /messages/ directory & data.txt files, though the faq.html is the only one which will need editing if you have enabled the option within the wwwboard.pl file If not, don't bother. Now, head on back to your FTP application. You now need to navigate your way back into the location you specified within the wwwboard.pl file & create a directory called wwwboard in the root directory of your domain's folder. Once you've done that, you can navigate into that new directory & upload (Figure 3) the faq.html, wwwboard.html, data.txt files & also create a new directory called messages.

Now, we're almost ready to check out if your new CGI is working, but there's one very important step that must be done first - set the 'permissions' (Figure 4) on all of your new files. A permission is your web server's way of keeping things in order & preventing something from happening without it's permission. Think of it as a school principal - the teachers are allowed to teach particular subject, the students are limited to learning these subjects. In a similar way, the server lets certain file types perform certain tasks. Without setting the permissions, your script won't be allowed to execute.

Now you have everything you need to get your WWWBoard running on your WebTen server, head on over to that machine & go into WebTen via the Finder. From the Admin menu, select the Shell Window option, which will open a new window with a # mark & a cursor. Here, you're about to enter some real UNIX commands & it's a proper UNIX environment, with a limited set of UNIX commands. Now enter:
# cd /WebTen_Folder

Remember that unlike Mac OS, case is important, so ensure you type the upper & lower case characters as shown above after which the server will respond with:
//Server/WebTen v3.0

Now enter:
# ls

The server will respond with something that looks like (Figure 5)

The 'cd' command means 'Change Directory' The 'ls' command means to show a listing of the files in the current directory & as you can see from the list it's shown you, the cgi-bin directory is in there, so you need to go into that directory like so:
# cd cgi-bin

Now, you can do another ls command & you'll see the wwwboard.pl file here, assuming you've put it in here (or of course wwwboard.cgi if that's what you saved it as)

Now, we set the permissions with a 'chmod' command, which means to 'Change the mode of the file' As noted in the Read me file, you need to set the permission on the file to 755, so at the shell prompt, we type:
# chmod 755 wwwboard.pl

When you hit enter, if you got the filename correct, the server will simply give you another # prompt, indicating you've been successful in setting the chmod command. Now we have the other files to set permissions on, so at the # prompt, you need to cd into the root directory for your website, so:
# cd /WebTen_Folder/WebSites/yourdomain.com/

Now, you need to set the directory permission to 777 & then cd into the directory & set the permission for each of these files also, being sure to set the permission for the messages directory. Once that's done, you can type exit at the # prompt & go back to a web browser. Type in the URL for your wwwboad.html file like so:
http://yourdomain.com/wwwboard/wwwboard.html

Voila! You should now see the index page of your new message board. (Figure 6) Go down to the Post A Message form & fill out a test message & hit submit. All being well, you should now see your new message. If by chance you get a screen which says Internal Server Error 500, the most likely cause is that you have either made a typing error or you've missed out on setting the permissions on one or more of the files. If this isn't the case, check the Error Log window on WebTen which sould show you where the error lies.

If everything comes up as expected, you have one thing left to go & that's to set up the wwwadmin.pl script. The process is very similar to getting the main script running, but this one lets you delete messages & otherwise administrate your message board. Once again, it's a matter of setting up the variables within the wwwadmin.pl file, uploading it into the cgi-bin & setting the permission on this file. The passwd.txt file simply needs to be uploaded into the wwwboard directory & the permission set to 777 This is al detailed in the Admin_Read me file.

The final thing you need to do is go back to your web browser & call your admin script like so:
http://yourdomain.com/cgi-bin/wwwadmin.pl (or .cgi if you've given the file that extension)

Assuming you set the permissions & variables within that file, the script will run, giving you options to change passwords, delete messages by thread, date, author etc..(Figure 7) I'd be changing the password obviously first, which is explained in detail in the Admin_Read Me file.

Now you're set, with your new message board running correctly. You can expand WWWBoard with many add-ons linked both from Matt's Script archive & other sites. There are other Message Boards which you may want to check out, but for my purposes, WWWBoard works extremely well & has the best layout. You're also well armed with the knowledge of how to access & set up the vast array of CGI scripts available for many platforms & usable in conjunction with your WebTen server application.

You've gained some valuable knowledge which will help you to expand the range of possibilities of the WebTen application which stands you in good stead for finding out more about what CGI can do for you. There are thousands of freely available scripts, some resources listed on the Tenon resource page at http://www.tenon.com/resources/mac.cgis.shtml but you may need to find a solution which you'll need to purchase. I hope this article will help you on to a world of knowledge in setting up CGIs & expanding the capabilities of your WebTen server.