IperWeb MANUAL

CHAPTER FOUR - Cgi-bin scripts

Cgi-bin scripts: How do I use them?

4.1) OVERVIEW

4.2) FEEDBACK FORMS, GUESTBOOK & SEARCH

4.3) READY TO RUN SCRIPTS & ALL SITE COUNTERS

4.4) TROUBLESHOOTING

4.1) OVERVIEW

4.1.1) Where should I put cgi-bin scripts?

Put your cgi-bin scripts in the WWW subdirectory named cgi-bin.

If your domain is named company.com, you would then access your scripts as /cgi-company/

4.1.2) What is the path of date, mail, perl ...?

To find the path of the program date, type which date. Do this for any program that you need your cgi-bin script to access.

Common paths

  • Sendmail /usr/sbin/sendmail
  • Perl /usr/bin/perl
  • Date /bin/date
  • Domain Path /www/yourdomain/ (puts you in your we directory)

4.1.3) Charges

More complicated scripts will be installed based on 75.00/hour

4.2) FEEDBACK FORMS AND SIMILAR FORMS

Cgiemail is a program written in the C language that takes the contents of fill-in boxes on a form and emails them to a specified destination. In addition to the form specification in the .html file, a mail specification in a .txt file is required to format the resulting email message.

We provide cgiemail in the cgi-bin directory of each machine. Thus, it would be called with a URI such as /cgi-bin/cgiemail/mail.txt. Details are provided below.

While there are a number of subsections below this one, they all work together and are meant to be read from start to finish.

4.2.1) add.html

If you've never dealt with HTML forms before, don't worry. They're easy to create and understand. (And if you briefly tried that link and thought, noooooo!!! I don't want to read this!, scroll down a bit. The easy examples are at the bottom. You should not need to follow it at all to understand what will be explained presently.)

The form prompts the user for data which is sent to the server as simple key-value pairs. Each <input> tag specifies a record. The key is given by the name attribute, and the value is given by the value attribute. The type attribute tells the browser what kind of data to expect. Now, try looking at the example.

Please note that the hidden items are used to transmit critical info to cgiemail. They provide the location of the success file, the name of the person the results should be sent to, and the subject of the form. When making your own forms, you would definitely (please!) change the e-mail address in the "required-to" field, and likely the subject in the "subject" field. The first item tells cgiemail what to show the user after succesfully completing the form. You can, but don't need to, customize this.

After that come the items that are actually presented to the user. You'll want to use type=text input items with cgiemail; it's a simple tool. The size=60 tells the browser how big to make the box. The name=something is required in each input tag, otherwise the browser wouldn't know how to send the data to the server. The value="" attribute is correct in most cases, unless you want a default value in the form.

Note that if a field begins with required-, cgiemail will require that the user enter a value for this field. This is particularly useful if you want to require a user to submit their e-mail address.

When the user presses the Submit button, the data goes to our machine where cgiemail starts doing something with it. What it does is controlled by ...

4.2.2) Mail.txt

Make sure that you upload mail.txt in ASCII mode.

Failure to upload mail.txt in ASCII mode will generate the message:

Server Error

The server encountered an internal error or misconfiguration and was unable
to complete your request.

Now that we have all this data, what do we do with it? Mail it, of course! But for flexibility, cgiemail requires that you create a mail.txt file to show it what to send. (If you didn't want flexibility you'd use a mailto link.) The program will read in this file, perform substitutions, and pass it to the mail system.

Fred.com might want to put the mail.txt file in his www directory. His form would then start off with 

<form method=post action="http://www.fred.com/cgi-bin/cgiemail/mail.txt">

BTW, there's nothing magical about the name mail.txt. Feel free to call it mail1.txt, or form1.mail, or what suits you, as long as the form has the correct name for what you uploaded.

Here's the mail.txt we used with the form presented earlier. It's pretty simple. Note that the first several lines are mail headers. You probably shouldn't change that part, or the corresponding parts in your form. In particular, there must be a To: header or the mail won't go anywhere!

What cgiemail does is simply replace every string that looks like [key] with the value the user typed in to the field with name=key. That's all. You can lay out your form as is best for your users, but lay out your mail.txt as is best for you to read. You can even insert gobs of text to help format the output. Only the [key] parts will be replaced by cgiemail.

4.2.3) How to use Formmail.cgi

The FormMail.pl script does not have to be extensively configured to get
it to work. There are only two variables in the perl file which you will
need to define along with changing the top line of your script to match
the location of you Perl interpreter.

Here's an example:
<FORM METHOD=POST ACTION="http://yourdomain.com/cgi-bin/formmail.cgi">
<input type=hidden name="recipient" value="sales@yourdomain.com">
<input type=hidden name="subject" value="Order">
<input type=hidden name="return_link_url" value="http://yourdomain.com/">
<input type=hidden name="return_link_title" value="Back to Main Page">

The last two line allow a link back to your main page - thus they get a report of what they ordered and a link. We made the modification for you already

yourdomain.com should be replaced with your real domain name

4.2.4) How to use Guestbook

If you have an account that includes a preconfigured guestbook, You simply need to use the following URL to access it.

http://yourdomain.com/Guestbook/guestbook.html

4.2.5) How to use Search.cgi
Search will look at all your html pages for words you enter, and return all pages on a list with links. This program is completly configured and ready to run, just access it with the following URL

http://yourdomain.com/cgi-yourdomain/search.cgi

4.3) COMPLETE WEB SITE COUNTERS

4.3.1)Site Counter using SSI

Very simple to use, first the page which you would like to count must have the extension .shtml or .sht rather than .htm or .html
put the following on the page where you want the count file to appear.
<!--#exec cgi="/cgi-yourdomain/counters/counter.cgi"-->
For Example if your domain is fred.com the call would be
<!--#exec cgi="/cgi-fred/counters/counter.cgi"-->
That all there is to it, this will create a count file for each page the call is placed on, it will just show up as a number when looking at it from a web page.

4.3.2) WWWBoard


The World Wide web Board is already to run, you can call it from a page with the following URL: http://yourdomain.com/bbs/

4.3.3) Secure Orderform calls


NOTE: AT PRESENT WE DON'T HAVE SSL ON OUR SERVERS!

Assume your domain is example.com.

Use the following url to access your pages via the secure server. 

https://machine.safe-order.net/example/anypage.html


The above page would be accessed from the normal web server as: 

http://example.com/anypage.html


Your cgi-bin dir is: 

https://machine.safe-order.net/example/cgi-bin/


*SPECIAL NOTE FOR FORMMAIL.CGI*

If you are using formmail.cgi thru the secure server, you MUST use the following url: 

https://machine.safe-order.net/cgi-bin/formmail.cgi

Here's an example:



<FORM METHOD=POST ACTION="https://machine.safe-order.net/cgi-bin/formmail.cgi">
<input type=hidden name="recipient" value="sales@yourdomain.com">
<input type=hidden name="subject" value="Order">
<input type=hidden name="return_link_url" value="http://yourdomain.com/>
<input type=hidden name="return_link_title" value="Back to Main Page">

The last two line allow a link back to your main page - thus they get a report
of what they oredered and a link. we made the modification for you already

Replace yourdomain with your userid

Replace machine with the name of the system we have you on
this can be found on the FAQ page in your domain http://yourdomain.com/faq.html

4.3.4) Password Protected Web directory

Placed in your WWW directory, you will find a sub directory called secure. This has been setup with the password file in place, and it cannot be entered from the web without first being prompted for a login and password.
You will need a brief knowledge of Telnet in order to build the login file for this directory, the steps are below.

  1. Login to your domain via telnet.
  2. At prompt type pass, this is a script we created to make adding to the file easy
  3. Follow the prompts. enter login and then passwd desired twice.
  4. You may enter as many logins as you like, you may also go back and add when ever you wish.
  5. Just hit enter, when prompted for login to escape program.

4.3.5) Database and search engine

The database program is composed of 5 essential files database.cfg, database, post.htm, search.htm and output.html

database.cfg - this is the configuration file for your database.

  • You need to make sure your unix permissions are set to chmod 666 for this file to work properly
  • The first line is the location of the database, which has the default value of our test database.
  • The second line is what page that it should return to after posting to database, the default value is to return to the post page for another entry.
  • The third line is where you will start listing ay fields you want to have posted to the database.
Example.(just a simple list) 
 

Name

Address

City

State


You may have as many as you like listed for these fields

These become your input fields and they must be associated with the input statements on your posting page for each of the above, you should have a matching input statement that looks like the following on your post page:

<input = text name = "name" size = "25" > <input = text name = name = "address" size = "25">

Database - This is nothing more than the actual data being stored after it is posted from your posting page.

Post.htm - This page is used to write to the database from a webpage. You should have an input statement for each field used in the database .cfg file. You may also use Query boxes, + Radio buttons. The formation for this page should be as follows:

<form method post action = "http://your domain.com/cgi-bin/database.cgi">

For better understanding look at the sample files in the database directory on you domain.

Email - You may activate this feature by adding the following.
<input type="hidden" name="email" value="youremailaddress"> When active each time someone posts to the database you will receive a email of the content

Search.htm - this is the page that reads the actual database file based on the criteria you would like to search. A good example of this page at work would be

http://cyberlands.com/mall/ this utilizes many of the features this program offers.

The form action for this page should be as follows:

<form method = post action = "http://your domain.com/cgi-bin/dsearch.cgi"> use the preconfigured example as a template that is in the database directory of your domain.

There are several ways to setup searches for your database.

1. Click on names (see http://cyberlands.com/mall/.)

This will allow a nice interface for your customer or client, that eliminates the need for a submit button

Use the following call:
EX:

The items before the ? mark call the script, this should always be the same. The first item after the ? mark is the word you are using for the search, then you will notice a & sign the listing after the & sign is the location of the database file (it's directory) in the above cyberlands/mall/ in the default sample set your domain, it would be domainname/database/:

2. The other way to do a search page is through checkboxes, radio button, query lists, and straight type in text. You may search by as many different mediums as you like. Look at http://winedine.com/nycsrch.htm

For an example of different criteria being used, there are only two variable names you will use in your search page. Keywords and Keywords-predefined.

a. Keywords would be used for a single text entry search.
b. Keywords-predefined is used for multiple inputs where you are searching several words as our example with winedine.

Output.html

  • You must make sure the unix permissions are set to chmod 666 for this file to work properly
  • Use the page example placed on your domain as an example.
    • Each field you want printed in the output page is inclosed in [ test]
    • These may be layed out anywhere on the page, this effectively becomes a printout template for your file.
    • You may surround theses variables with as much normal text as you would like to have printed with these records

4.4) TROUBLESHOOTING

(This section will grow as we remember to add what we
keep doing every day anyway.)

"When I activate my CGI program, I get back a page that says 'Server Misconfigured'".

Log on and go to your www/cgi-bin directory. Try running the program manually to see what errors you get. Remember that when a CGI program produces error output, that output is discarded and you get the non-specific page you saw. To check on it, you'll have to run it yourself.

If you get something like


bash: ./search.pl: No such file or directory

and you know you typed the name correctly, it's almost certain you uploaded the script from your PC or Macintosh in binary mode. Perl scripts are ASCII text and must be transferred in ASCII mode. (So are shell scripts and any other kind of script that starts with '#!' on the first line.) You know it's this if ./search.pl doesn't work and perl search.pl does. Assuming you don't have any legitimate carriage returns in the program (doubtful), this will fix it: 

mv search.pl search.pl.txt && tr -d '\r' <search.pl.txt>search.pl

Then there's this response:


Literal @iperweb now requires backslash at ./bigones line 16, within string

Many scripts that you'll find widely distributed are still
written for Perl, version 4.  Our /usr/bin/perl is version 5,
which is 99.9% compatible with version 4, along with many
improvements.  You've found the other 0.1%.

In Perl 4, you could get away with a statement like


$mailaddress = "joe@schmoe.com";

because Perl didn't think the '@' sign was special in a
string.  Perl 5 does, so you need to escape it, like
so:

$mailaddres = "joe\@schmoe.com";

You can't just change all the '@' signs to '\@', only
the ones in strings.  To speed your search, however, Perl
gives you the line number of the problem line(s) in its
error message.  (To check for them without accidentally running
the program, if that would be a problem, use
perl -c script.)
Fix them, and see if it works.

Tom Christianson (well-known in the Perl world) has written The Idiot's Guide to Solving Perl CGI problems for the comp.lang.perl.misc newsgroup. Not everything in there is correct for the iperweb setup, but it's useful.

This page maintained by IperWeb.

Return To Menu