Chapter 3 - CGI Scripts
3.1 Pre-installed Scripts
CGI-SCRIPTS are computer programs running on the webserver that can be
invoked from a web page in the browser. These programs adds
functionality to web pages that are not possible with just HTML.
www.msextoys.com, Inc. provides 5 popular and useful CGI-SCRIPTS.
These come already pre-installed on your account under your cgi-bin
Suppose you want to have an order form on your web page whose result
would be emailed to you, follow instructions below:
- Create a file called "order.txt" using a text editor
such as Notepad in your local PC.
- Type following lines. Of course, you can add more fields to
fit your specific needs.
Subject: Order from [name]
Customer Contact Information
Product Purchased: [product]
IMPORTANT: You MUST have the To:
and the font color="blue">Subject: line followed by the
blank line. Those three lines MUST be on the FIRST THREE lines.
That is the file that will be sent to email@example.com
Now, cgiemail will automatically replace [name], [phone],
anything in the brackets with the corresponding user supplied info
from the web form.
- Save this file in plain text mode. Upload it to your main www/public_html
folder via WinSCP
- You need to create a web form in html.Here is a part of the
web form page called "order.html"
IMPORTANT: The name of the form field (e.g.
name="name") must exactly match the what you put within
the bracket in your order.txt file for it be replaced with the
value your customer enters. For example, if you have
<....name="name"> in your
order.html and name: [Name], it will not
- If you want to have your own customized "success" page,
place the following line in your form page:
<input TYPE="hidden" NAME="success"
It will then redirect to somepage.html.
FormMail is a generic www form to e-mail gateway, which will parse the
results of any form and send them to the specified user. This
script has many formatting and operational options, most of
which can be specified through the form, meaning you don't
need any programming knowledge or multiple scripts for
multiple forms. This also makes FormMail the perfect
system-wise solution for allowing users form-based user
feedback capabilities without the risks of allowing freedom of
There is only one form field that you must have in your form, for
FormMail to work correctly. This is the recipient field. Other
hidden configuration fields can also be used to enhance the
operation of FormMail on your site. The action of your form
needs to point towards this script (obviously), and the method
must be POST in capital letters.
Here's an example of the form fields to put in your form:
<input type="hidden" name="recipient"
<input type="hidden" name="subject"
name="return_link_title" value="Back to Main
The following are descriptions and proper syntax for fields
you can use with FormMail.
Description: This form field allows you to specify to whom you
wish for your form results to be mailed. Most likely you will want to
configure this option as a hidden form field with a value
equal to that of your email address.
Syntax:<input type=hidden name="recipient"
Description: The subject field will allow you to specify the
subject that you wish to appear in the email that is sent to you after
this form has been filled out. If you do not have this option turned
on, then the script will default to a message subject:
"WWW Form Submission".
Syntax: If you wish to choose what the subject is: <input
type=hidden name="subject" value="Your
To allow the user to choose a subject:
<input type=text name="subject">
Description: This form field will allow the user to specify
their return email address. If you want to be able to return e-mail to
your user, I strongly suggest that you include this form field and
allow them to fill it in. This will be put into the From: field of the
message you receive. If you want to require an email address with
valid syntax, add this field name to the 'required' field.
Syntax: <input type=text name="email">
Description: The realname form field will allow the user to
input their real name. This field is useful for identification purposes
and will also be put into the From: line of your message header.
Syntax: <input type=text name="realname">
Description: If you wish to redirect the user to a different
URL, rather than having them see the default response to the fill-out
form, you can use this hidden variable to send them to a pre-made HTML
Syntax: To choose the URL they will end up at:
<input type=hidden name="redirect"
To allow them to specify a URL they wish to travel to once the
form is filled out:
<input type=text name="redirect">
Description: You can require certain fields in your form to be
filled in before the user can successfully submit the form. Simply
place all field names that you want to be mandatory into this field,
separated by commas. If the required fields are not filled in,
the user will be notified of what they need to fill in, and a
link back to the form they just submitted will be provided.
To use a customized error page, see
Syntax: If you want to require that they fill in the email and
phone fields in your form, so that you can reach them once you have
received the mail, use the syntax like:
<input type=hidden name="required"
Description: Allows you to have Environment variables included
in the email message you receive after a user has filled out your form.
Useful if you wish to know what browser they were using, what domain
they were coming from or any other attributes associated with
environment variables. The following is a short list of valid
environment variables that might be useful:
REMOTE_HOST - Sends the hostname making the request.
REMOTE_ADDR - Sends the IP address of the remote host.
HTTP_USER_AGENT - The browser the client is using.
(Note: In our case, both REMOTE_HOST and REMOTE_ADDR are the same,
since our servers don't do the reverse DNS lookup needed to
generate the true REMOTE_HOST string).
Syntax: If you wanted to find all the above variables, you
would put the following into your form:
<input type=hidden name="env_report"
Description: This field allows you to choose the order in which
you wish for your variables to appear in the email form that FormMail
generates. You can choose to have the field sorted
alphabetically or specify a set order in which you want the
fields to appear in your mail message. By leaving this field
out, the order will simply default to the order in which the
browsers send the information to the script (which is usually
the exact same order as they appeared in the form). When
sorting by a set order of fields, you should include the
phrase "order:" as the first part of your value for
the sort field, and then follow that with the field names you
want to be listed in the email message, separated by commas.
Syntax: To sort alphabetically:
<input type=hidden name="sort"
To sort by a set field order:
<input type=hidden name="sort"
Description: print_config allows you to specify which of the
config variables you would like to have printed in your e-mail
message. By default, no config fields are printed to your
email. This is because the important form fields, like email,
subject, etc. are included in the header of the message.
However some users have asked for this option so they can have
these fields printed in the body of the message. The config
fields that you wish to have printed should be in the value
attribute of your input tag separated by commas.
Syntax: If you want to print the email and subject fields in
the body of your message, you would place the following form tag:
<input type=hidden name="print config" value="email,
Description: print_blank_fields allows you to request that all
form fields are printed in the return HTML, regardless of whether or
not they were filled in. FormMail defaults to turning this off, so
that unused form fields aren't emailed.
Description: This form field allows you to specify the title
and header that will appear on the resulting page if you do not
specify a redirect URL.
Syntax: If you wanted a title of 'Feedback Form Results':
<input type=hidden name="title" value="Feedback Form
Description: This field allows you to specify a URL that will
appear, as return_link_title, on the following report page. This field
will not be used if you have the redirect field set, but it is
useful if you allow the user to receive the report on the
following page, but want to offer them a way to get back to
your main page.
Syntax: <input type=hidden name="return_link_url"
Description: This is the title that will be used to link the
user back to the page you specify with return_link_url. The two fields
will be shown on the resulting form page as:
Syntax: <input type=hidden name="return_link_title"
value="Back to Main Page">
||This form field allows you to specify a URL that users will
be redirected to if there are fields listed in the required
form field that are not filled in. This is so you can
customize an error page instead of displaying the
Using FormMail.pl via Secure Server
If you are using FormMail.pl through the secure server, you can
still place your form anywhere on your webspace you want to,
but you MUST use the following URL as the ACTION of your form:
Here's an example of how the first parts of your form might look:
<input type=hidden name="recipient"
<input type=hidden name="subject"
<input type=hidden name="return_link_url"
<input type=hidden name="return_link_title"
value="Back to Main Page">
It is still important that you call your order page through a
secure URL in order to work properly. For example:
find out the name of the secure server you should be using.
3.1.3 Page counter
We have installed a different counter program on your account. For
each counter, there is a data file that is created in your home
By modifying the data file you can change the value of your counter.
Please use the following code in your page:
It will automatically create a data file called counter1.dat in
your home directory.
For more examples, see
Board is a threaded World Wide Web discussion forum and message board,
which allows users to post new messages, follow-up to existing ones and
more. It is already preconfigured for your server. Just go to
http://YOURDOMAIN.com/wwwboard to post your messages there.
There are several options you may want to configure. First of all,
the index.htm file in the wwwboard directory can be customized
any way you wish as long as you leave the method and input
tags the way they are.
Additionally, here are some options contained in the wwwboard.pl script
itself (located in your cgi-bin directory) which you may want
to change, depending on your needs:
$show_faq = 1;
This option allows you to choose whether or not you want to display
a link to the FAQ on every individual message page or not. It
defaults to 1 and the link will be put in at the top of the
message along with links to Followups, Post Followup and Back
to $title. Setting this to 0 will turn it off, and keeping it
at 1 will keep the link. You need to create a faq.html file
and put it inside the wwwboard directory. The FAQ can contain
any information you want to give your visitors about how the
board works, your organization, types of postings that will be
$allow_html = 1;
This option lets you choose whether or not you want to allow HTML
mark-up in your posts. If you do not want to allow it, then
everything that a user submits that has <>'s around it
will be cut out of the message. Setting this option to 1 will
allow HTML in the posts and you can turn this option off by
setting it to 0.
$quote_text = 1;
By keeping this option set to 1, the previous message will be
quoted in the followup text input box. The quoted text will
have a ':' placed in front of it so you can distinguish what
had been said in the previous posts from what the current
poster is trying to get across. Setting this option to 0 will
leave the followup text box empty for the new poster.
$subject_line = 0;
There are three options for the way that you can display the subject
line for the user posting a followup. Leaving this option at 0
which is the default value, will put the previous subject line
into the followup form and allow users to edit the subject
however they like. Setting this option to 1, however, will
quote the subject, but simply display it to the user, not
allowing him or her to edit the subject line. The third and
final option can be achieved by setting the $subject_line
variable to 2. If it is set to 2, the subject will not be
quoted and instead the user will be prompted with an empty
subject block in their followup subject line.
$use_time = 1;
This option allows you to choose whether or not you want to use the
hour:minute:second time with the day/month/year time on the
main page. Day/Month/Year will automatically be placed on the
main wwwboard.html page when a new entry is added, but if you
leave this variable at 1, the hour:minute:second time will
also be put there. This is very useful for message boards that
get a lot of posts, but if you would like to save space on
your main page, you can set this to 0, causing the
hour:minute:second display not to be added.
Guestbook allows you to set up your own comments page. From there,
visitors can add entries to your guestbook and they will be
displayed with the most recent at the top and scrolling down,
or vice versa. Other options include the ability to limit HTML
in the entry, link to e-mail address with mailto tag, use a
log to log entries, redirect to a different page after
signing, emailing whenever a new entry is added, and much
Guestbook is already set up for use on your server. You can simply use
the following URL to access it:
If you want to change any of the configuration options, locate
the guestbook.pl file in your cgi-bin directory (inside
your www directory). Download it to your hard drive in ASCII
mode, and save it somewhere safe. Create a copy of the file
and give it the same name, then edit the options as specified
below. Keep your backup of the original guestbook.pl in case
you run into problems.
Option 1: $mail
This option will allow you to be notified via an E-mail address
when a new entry arrives in your guestbook. The entry will be
mailed to you as a notification. If you should choose to turn
this variable on you will need to fill in the 2 variables that
go along with it:
$recipient - Your email address, so that the mailing program will know
who to mail the entry to.
$mailprog - The location of your sendmail program on your host
Option 2: $uselog
This will allow you the ability to use the short log feature. It is
already turned on so you will have to change it to 0 if you do
not wish to use it. It has been implemented since there are
probably many people who feel no need to have a log when
people are making entries to a file anyway. Keep in mind that
it will show errors which is one nice aspect about it.
Option 3: $linkmail
Turning this option on will make the address links in your guestbook
become hyperlinked. So instead of simply having (firstname.lastname@example.org)
it will put (<a href="mailto:email@example.com">name@somehost</a>
so that anyone can simply click on the address to email them.
Option 4: $separator
This allows you to choose whether you want guestbook entries to be
separated by a Paragraph Separator <p>, or a Horizontal
Rule <hr>. By changing the 0 in the script to a 1, you
will turn on the <hr> separator and turn off the
<p> separator. The 0 option will do the reverse of that;
turn on the <p> and turn off the <hr>.
Option 5: $redirection
By choosing 1 you will enable auto redirection and 0 will return
a page to the user telling them their entry has been received
and click here to get back to the guestbook.
Option 6: $entry_order
Set this option to 0 and the newest entries will be added below
the rest of the entries. Keep this option at 1 and the
guestbook will add the newest entries at the top.
Option 7: $remote_mail
Many users of the guestbook have requested that a form letter be
automatically sent to the remote user when they fill in the
guestbook. Turning this option on will tell the script to
automatically mail any user who leaves an email address. You
can specify the contents of the mail message by editing the
section of the script that sends mail to the remote user. By
default it sends a message that says, "Thank you for
adding to my guestbook." and then shows them their entry.
If you should choose to turn this variable on, you will need
to fill in the 2 variables that go along with it:
$recipient - Your email address so that the mailing program will know
who to mail the entry to.
$mailprog - The location of your sendmail program on your host
Option 8: $allow_html
This option allows you to turn on or off the use of HTML tags by
users of your guestbook. Setting this variable to 1 allows
users to embed html tags such as <b> or <H1> or
<a href=" "></a> into your html
document. Setting this variable to 0 will not allow them to
use any html syntax in their comments or any other field. You
can still link to their comments or any other field. You can
still link to their email address by turning $link_mail to 1.
There is also the ability for users to add their own URL and then
their name is referenced to their URL in the guestbook.html
file. This helps to eliminate the need for allow_html to be
turned on, and lets users point you to a spot that will tell
you more about them. Several users of the guestbook script
have asked for this option. If you wish to disable the option,
simply delete the following line from your addguest.html file:
URL: <input type=text name=url size=50><br>
These are the rest of the important guestbook files found in your
This is the file that you will link to that will contain the
Guestbook Entries. You may want to edit the title and heading
spaces and customize the look any way you desire. Do not
delete the line <!--begin--> from this guestbook, or
else the script will have no way of knowing where to begin the
editing. The <!--begin--> line is the only necessary
line in your guestbook.html file, but the link to the
addguest.html file is also a good idea. :-)
3.2 Installing Your Own CGI-SCRIPTS
CGI-SCRIPTS are computer programs running on the webserver that can be
invoked from a web page in the browser. These programs
adds functionality to web pages that are not possible with
CGI scripts need to be saved in ASCII format and uploaded to your
server's cgi-bin in ASCII or text format. This is very
www.msextoys.com does not provide free support for CGI scripts which did
not come installed on your account. So if you are not already
familiar with CGI scripting, you may want to read a book on
the subject or find places on the Internet with CGI scripting
information. There are many good resources for CGI scripts
found on the web. The scripts at Matt's Script Archive
found at http://www.worldwidemart.com/scripts/ are very good.
Many of our scripts come from here. Another excellent resource
is The CGI Resource Index found at http://www.cgi-perl.com/
-- if you are not an expert, look for scripts that are very
well documented and come with step-by-step instructions, or
contact us for help or installation.
3.2.1 Running your own CGI program
a.) Put your CGI programs in the cgi-bin directory.
When calling the programs from the web page, you must use the
alias for the cgi-bin directory. The alias is
"cgi-[yourdomain]". If your domain is example.com,
then the alias is cgi-example. Note that ".com" is
not included. So the action line from your form page would
look like action="/cgi-example/program".
b.) Put your CGI programs anywhere outside of the cgi-bin
directory. In this case, the program name must end in
3.2.2 Paths to Date, Sendmail, Perl, etc
Here are your paths to the common server resources that CGI scripts
||(puts you in your web directory)
||(puts you in your cgi-bin)
3.2.3 Setting Permissions
The following is a simple explanation of file permissions in Unix.
To list the access permissions of a file or directory, telnet
to your server, then:
to change the directory until you are either in the directory
above the file you are interested in, or above the directory
you are checking.
Type: ls -l filename
and you will see what the current permission settings are for that
file, along with a bunch of other stuff.
Examples of using chmod:
|u = the file's user (you)
||r = read access
|g = the file's group
||x = execute access
|o = others
||w = write access
|a = the user, the group, and others
To change permissions for a file named filename.cgi, you need to
chmod the file (change mode). For example, when you type this:
chmod u=rwx,g=rx,o=rx filename.cgi
read, execute, and write access to the user (that's you)
read and execute access to the group and
read and execute access to others
Some scripts will tell you to chmod 775 (for example). Doing the
above is the same thing as typing chmod 775. You can use
either method with our Unix servers. Let me explain:
When using the numeric system, the code for permissions is as
r = 4 w = 2 x = 1 rwx = 7
The first 7 of our chmod 775 tells Unix to change the user's
permissions to rxw (because r=4 + w=2 + x=1 adds up to 7. The
second 7 applies to the group, and the last number 5, refers
to others (4+1=5).
When doing an ls -l on the file, telnet always shows the
permissions this way:
Ignore the first dash, then break up the above into three groups of
letters. If there's a dash where a letter should be, it means
that there is no permission for those people.
Remember: the first 3 apply to user, the second 3 apply to group, and
the third 3 apply to others.
Some FTP clients support changing permissions in a more graphical
3.3 CGI-SCRIPT Troubleshooting Guide
Below are solutions to some of the more common CGI script problems,
in question and answer format.
When I activate my CGI program, I get back a page that says
"Internal Server Error. The server encountered an
internal error or misconfiguration and was unable to complete
This is generally caused by a problem within the script. Log in via
Telnet and test your script in local mode to get a better idea
of what the problem is. To do this, go into the directory in
which your script is located, then execute the script. To
execute the script, you can do it by two ways:
- Type "perl myscript.pl" (Perl being the language
interpreter in this case).
- Or simply type "myscript.pl" alone, that will work
if the first line is well written to indicate the location of
The first one is useful to see if there's any error IN your
script. The second one is useful to test if your "calling
line" (the first line of the script) is okay, i.e. if you
entered the right location of Perl.
Cgi-bin scripts and executables must have the proper permissions
or an internal server error will occur. The directory (and all the
cgi's within it) must NOT be world writable. This is the most common
See http://www.apache.org/docs-1.2/suexec.html for more details.
I am being told "File Not Found," or "No Such
File or Directory.
Upload your Perl or CGI script in ASCII mode, not binary mode.
When I test my Perl script in local mode (by Telnet), I have the
following error: "Literal @domain now requires backslash
at myscript.pl line 3, within string. Execution of myscript.pl
aborted due to compilation errors.
This is caused by a misinterpretation by Perl. You see, the
"@" sign has a special meaning in Perl; it
identifies an array (a table of elements). Since it cannot
find the array named domain, it generates an error. You should
place a backslash (\) before the "@" symbol to tell
Perl to see it as a regular symbol, as in an email address.
I am getting the message "POST not implemented.
You are probably using the wrong reference for cgiemail. Use the
reference /cgi-bin/cgiemail/mail.txt. Another possibility is
that you are pointing to a cgi-bin script that you have not
put in your cgi-bin directory. In general, this message really
means that the web server is not recognizing the cgi-bin
script you are calling as a program. It thinks it is a regular
It's saying I don't have permission to access / (1)
This error message means that you are missing your index.htm file.
Note that files that start with a "." are hidden
files. To see them, type ls -al. If you wish to FTP this file
in, go to the home/YOURDOMAIN directory.
It's saying I don't have permission to access/(2)
Your cgi-script is probably set as world writable. Our cgi
scecurity mechanism prevents execution of such cgi-scripts. To
ensure that the permssion setting for your cgi-script is
correct issue following command.
"chmod 755 yourcgiscript " in the directory where your
cgi-script is located.
Also the directory in which your script is located must be set to
same permission setting. Use same method as described just