Table of Contents  | Policies | FAQs | Features Glossary | Tips & Tutorials | Downloads
Support Manual: CGI Scripts
Return to Table of Contents

Preconfigured Scripts
What are all the files and directories in my home directory?
What are all the files and directories in my www directory?
What are all the files and directories in my cgi-bin?
PreInstalled Scripts at Setup
Installed Software and Modules
Installing your own scripts
Troubleshooting CGI-Bin Problems
I Get a Forbidden Error When Trying To Access my Site



Preconfigured Scripts
There are numerous free scripts included with our hosting plans. Since these features require disk space, they are not installed by default. We can not provide technical support for script modifications. If your script becomes corrupt, just reinstall it, this will install the orginal copy of your existing script.

To install any or all of these scripts, go to your Web control. Once logged in select Free Scripts.

 Installation of these scripts is very easy. Simply check off the scripts you wish to add to your account, and click Install Scripts. 

 Once you install a script from the list above, you will need to configure it for your web site. Below are the URLs at which you will find the setup instructions. Please note that in each one, you will need to replace yourdomain.com with your personal domain name.

 That's An Order: http://yourdomain.com/lto.htm

 Visitor Pro Guestbook: http://yourdomain.com/vbpro/docs 

Multi User Forums: http://yourdomain.com/forums/cgi-s/

Pro Links Page: http://yourdomain.com/links/manual.htm

Whois: http://yourdomain.com/cgi-bin/whois.cgi 

Graphic Counter: http://yourdomain.com/counter/ 

Postcards: http://yourdomain.com/cards 

Vote Script: http://yourdomain.com/pollit

Quiz Master:  http://yourdomain.com/quiz 

SFE Page Search: http://yourdomain.com/search/instruct.htm 

PHP4: This script does not need to be setup once it is installed.
(click here for additional instructions)



What are all the files and directories in my home directory?
  • access-log..............More Info
  • error-log............More Info
  • htsdata/..................This is the directory where your non-web access miva data files are stored.
  • infobots/............This is the directory where your autoresponder text files are stored. More Info
  • mallists/..................This is the directory where your maillists are stored. More Info
  • plusmail_pass....This is your username and password to access your webcontrol panel. Do Not Remove This File. Removing this file would allow anyone on the web access to your web control panel. More Info
  • www/......................This is your web directory. Place all your web files in there. More Info
What are all the files and directories in my www directory?
  • cgi-bin/...............This is the directory where you should upload your .cgi and .pl files More Info
  • faq.html..................This is the Table of Contents to the Online Manual and Links to other helpful information. Type in your web browser: http://yourdomain/faq.html
  • forms/................This directory contains the file "order.txt" which is a file used by the example form "order.htm" and cgiemail More Info
  • index.htm...............This is the first page a visitor sees when they access your site. More Info
  • missing.htm.......This is your "404 File Not Found" page. More Info
  • random/...................This directory contains the file "random.txt", which will allow you to display random text on your web pages. More Info
  • order.htm...........This is an example order form using ssl with cgiemail More Info
  • order2.htm..............This is an example order form using ssl with formmail.cgi More Info
  • wusage/..............This directory  More Info
What are all the files and directories in my cgi-bin?
  • cgiemail..................This is a form processing script More Info
  • formmail.cgi.......This is a form processing script. More Info
  • miva........................This file should not be modified. More Info
  • miva.conf...........This is your miva empresa configuration file. More Info
  • sitevars....................This is your "Site Variables File"  for miva empresa. More Info
  • clickgo.cgi..............This script allows you to create HTML form dropdown lists. The dropdown values redirect to other portions of your site without any programming. More Info
  • randomtext.cgi..This script is for your random text files More Info
  • webmail.................This script allows you the ability to send and receive email with a web browser. More Info


PreInstalled Scripts
The Following Scripts are installed on your site at original setup


Click & Go Redirection
The clickgo.cgi script is preinstalled in your cgi-bin directory. To utilize this script, you will need to add the following source code anywhere in your HTML page:

 <FORM METHOD=POST ACTION="http://www.yourdomain.com/cgi-bin/clickgo.cgi">
<select name="goto" size="1">
<option value="www.yourdomain.com">Home</option>
<option value="www.yourdomain.com/services.htm">Services</option>
</select>
<input type="submit" value="GO!">
</form>

 Replace "yourdomain.com" with your domain name. The only other things you will modify are the option values. The values in " " are the hyperlink addresses of where that option will take your visitor. Of course, change the description of that hyperlink; in this example, you would change "Home" and "Services". You can add as many options as you like.

 Below is what the script looks like after it is set up: 



Formmail.cgi

The script is one from Matt's Script Archive which we have installed and preconfigured for your domain. 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 CGI access.

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:

<FORM METHOD=POST ACTION="http://yourdomain.com/cgi-bin/formmail.cgi">
<input type=hidden name="recipient" value="whoever@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 following are descriptions and proper syntax for fields you can use with FormMail.

Recipient Field

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" value="email@yourdomain.com">

Subject Field

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 Subject">

To allow the user to choose a subject:

<input type=text name="subject">

Email Field

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">

Realname Field

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">

Redirect Field

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 page.

Syntax: To choose the URL they will end up at:

<input type=hidden name="redirect" value="http://yourdomain.com/to/file.html">

To allow them to specify a URL they wish to travel to once the form is filled out:

<input type=text name="redirect">

Required Field

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 'missing_fields_redirect'

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" value="email,phone">

Env_report Field

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" value="REMOTE_HOST,REMOTE_ADDR,HTTP_USER_AGENT">

Sort Field

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" value="alphabetic">

To sort by a set field order:

<input type=hidden name="sort" value="order:name1,name2,etc...">

Print_config Field

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, subject">

Print_blank_fields Field

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.

Syntax: <input type=hidden name="print_blank_fields" value="1">

Title Field

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 Results">
 

Return_link_url Field

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" value="http://yourdomain.com/index.htm">

Return_link_title

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:

Back to Main Page

Syntax: <input type=hidden name="return_link_title" value="Back to Main Page">


Cgiemail

Cgiemail is another form processing script, totally different than FormMail, discussed above. It 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 location. 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 the cgiemail in the cgi-bin directory of your server. You need to have an action in your order.htm file to call it. It should look like this:

<form method=post action="http://www.yourdomain.com/cgi-bin/cgiemail/order.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.

order.htm

Look for a file in your www directory called order.htm. This is our example form we put on your site that shows how a form should be configured to work with Cgiemail. Look at it in a browser, and download it to your hard drive using FTP so you can see how it works. If you've never dealt with HTML forms before, don't worry, they're easy to create and understand.

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 may want to change the email 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 successfully 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 email address.

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

By the way, you can name your HTML form anything you want to.

order.txt

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 this file, perform substitutions, and pass it to the mail system.

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."

There is already an example order.txt document in the "forms" directory in your www directory.

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

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 into 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.

Cgiemail does not report environmental variables like FormMail will, but other than that, it is an excellent program, allowing you more flexibility in the way you want your data returned by the form.


Secure Server Order Forms

Normally, any text (such as your credit card number) sent from your browser to the web server is sent as plain text. This means that a hacker could potentially intercept (however unlikely) the information sent from your browser and read it. However, by using the secure server, the information is encrypted before it is sent from your browser. It would be practically impossible for anyone to decrypt it without knowing the key. Please use the secure server only when necessary, as when requesting sensitive information from your visitors.

The domains hosted by us are housed on any number of computers and all of them have a different machine name. To find out what machine name to use for your secure order access calls, check the faq file of your domain at:

http://www.yourdomain.com/faq.html

Each server has its own safeorders site, and although you will be putting your form on your own domain, it must be called through the safeorders server in order for the form to be secure.

To do this, create your form as usual and put it somewhere in your www directory. You can put your form anywhere you want to, but for this example, let's assume the normal URL for your form can be accessed from a browser with this URL:

http://www.yourdomain.com/signup/secureform.html

To call the form through the secure-order server, you need to use the following URL to access your pages via the secure server (even though your form resides on your own domain space): https://machinename.safeorders.net/yourdomain/signup/secureform.html.

That would be the URL you would put as an <HREF> to link to your form from whatever page you have your visitors link from. Don't forget the "s" in "https."

-------------------------------------

Special instructions for using FormMail.cgi with the Secure Server

If you are using formmail.cgi 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: https://machinename.safeorders.net/yourdomain/cgi-bin/formmail.cgi

Here's an example of how the first parts of your form might look:

<FORM METHOD=POST ACTION="https://machinename.safeorders.net/yourdomain/cgi-bin/formmail.cgi">
<input type=hidden name="recipient" value="whoever@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">

It is still important that you call your order page through a secure URL in order to work properly. You must use: https://machinename.safeorders.net/yourdomain/order.htm. If you call formmail.cgi through the secure server, you must also call the order form through the secure server. Otherwise, a "bad referrer" message will result.


Random Text Generator

This script is preconfigured for your server. There is a directory in your www directory called "random." Inside that directory is a file called random.txt. Just download random.txt file to your hard drive and edit it with any random text you would like placed in an html document. Remember to keep the %% separator between quotes. You can use any html formatting tags you want to, including <href> tags so you can configure it as a random link generator. You can put in as many quotes as you wish. Upload the random.txt file to your server in the same location you found it, remembering to upload it in ASCII or text mode.

The script uses SSI (Server Side Includes) so the page you want to use random text on must have the .sht, .shtm, or .shtml extension. On your page, just put this tag wherever you want the random text to appear:

<!--#exec cgi="/cgi-bin/randomtext.cgi"-->

That's all there is to it!


Webmail

Webmail is a way of accessing your site's pop email accounts using your web browser. This easy to use tool allows capabilities such as retrieving email, composing, replying, forwarding sending file attachments, and deleting email messages.

Webmail isn't intended to take the place of your favorite email software. Our webmail script is designed to be a fast, simple alternative so that you can have access to your email when you're away from your computer. As long as you have access to the Internet and a Web Browser, you will be able to get and send your email from anywhere. Important! Remember to LOGOUT After Each Session!

It's easy to use, simply go to the webmail log-in page at http://www.yourdomain.com/webmail and enter your pop username (without the "@") and password.



Installed Software and Modules
The following is the software and modules installed on our servers:
  • Apache 1.3.4 
  • Programming languages
    • Java jdk 1.1.5
    • Python 1.4 
    • TCL 7.6 
    • C++ with compiler access
    • Perl5 
      • Key Perl modules beside the standard ones.
        • mySQLPerl Module
        • DBI 1.06
        • LWP 5.36
        • HTML-parser 2.20
        • CGI.pm 2.49
        • MIME-Base64 2.06
        • MD5 1.7
        • Libnet 1.0605
        • URI 1.04
        • DBD 2.0091 (includes DBD::mysql)
        • GD.pm 1.18
        • MailTools-1.12 
        • IO-stringy-1.203 
        • PHP4
      • Third Party Support
        • VocalTec Internet Phone 
        • TrueSpeech Digital Audio 
        • VRML, Vream - Virtual Reality Authority Software 
        • Voxware, VivoActive 
        • Sizzler 
        • Fractal Image
        • FutureSplash
        • Infinop's wavelet image compression 
        • Macromedia's Shockwave 
        • Midi
        • Wireless Application Protocol (WAP)
Paths to Perl and Other Programs
Here are your paths to the common server resources that CGI scripts often require:

Sendmail: /usr/sbin/sendmail
Perl5.003: /usr/bin/perl --OR--   /usr/local/bin/perl
Perl5.004: /usr/bin/perl5.004
Date: /bin/date
Java: /usr/bin/java
Python:/usr/bin/python
Domain path: /www/fred (puts you in your Web directory)
CGI-bin path: /www/fred/cgi-bin (puts you in your cgi-bin)
Absolute Path: /home/fred/www/

Setting Permissions
Your file permissions are usually correct when you upload files, but sometimes permissions are not established for Group and Other, resulting in a "server error" message when trying to access your page. 

NOTE:
Every time you reupload and overwrite the existing file, its file permissions stay the same.

 Permissions Defined
Permissions are defined as "read", "write", and "execute". There are three levels of accessOwner, Group, and Other. Unix allows users to be placed in Groups so that the control of access is made simpler for administrators. 

Read permission allows you to view the contents of a file. For a directory, having read permission allows you to list the directory's contents. 

Write permission allows you to modify the contents of the file. For a directory, write permission allows you to alter the contents of the directory (i.e., to add or delete files). 

Execute permission allows you to run the file if it is an executable program or script. Execute permission is irrelevant for nonexecutable files.

 To List or Change File/Directory Permissions
The fastest and simplest way to list or change file and directory permissions is to use your Webcontrol. Once logged in, select "Site Manager." Click the folder  or file  icon next to the directory or file you want to view related properties and set permissions for.

 You can also use Telnet/SSH or FTP.

  • Using Telnet/SSH

  •  To list the current permissions of a file or directory, type "ls l <filename or directory>" at the shell prompt. Telnet always displays permissions as non-numeric characters, such as the following:

     rwxrxrx

     "r" refers to Read; "w" refers to Write; "x" refers to Execute; and "" refers to no permission. Each character equals a number:

     r = 4
    w = 2
    x = 1
    = 0

     You have probably seen permissions identified as 755, 775, 666, etc. To convert the non-numeric characters to a numeric format, ignore the first hyphen, then make three groups of three characters each. The first three characters apply to Owner, the second three to Group, and the last three to Other (Everyone). Using our example above, the character groups would look like the following:

     Owner
    rwx

     Group
    rx

     Other (Everyone)
    rx

     As mentioned above, each character equals a number. Add the numbers for cach party (Owner, Group, and Other) together:

     Owner
    4+2+1=7

     Group
    4+0+1=5

     Other (Everyone)
    4+0+1=5

     The permission "rwxrxrx" is the same as "755". Owner has Read, Write, and Execute privileges while Group and Other have Read and Execute privileges only.

     To change your permissions, at the shell prompt type "chmod xxx <filename or directory>", where "xxx" is the permission number and "<filename or directory>" is the filename or directory to be changed.
     

  • Using FTP:
     In WS_FTP just highlight the file you want to change permissions on and right-click on it. A menu will pop-up, then select CHMOD. You will see the window below.

    WS_FTP

     Fetch accomplishes the same task. Go to the file you want to change the permissions on, and highlight it. Under the Remote menu, select Change Permissions. A window will pop-up showing the current permissions for the file you highlighted, as in the figure below. Click on the boxes to change permissions as needed.

    Fetch

CgiwrapSecure Server CGI Wrapper
We have a cgi wrapper for the secure server called cgiwrap. We have configured it to be automatically invoked when you make a call containing "cgi-domain", like this:

 https://machine.safeorders.net/cgi-domain/script.cgi

 You can call cgiwrap explicitly with this call, which does the same thing as the above call:

 https://machine.safeorders.net/cgi-bin/cgiwrap/domain/script.cgi

 This assumes script.cgi is in your cgi-bin. You can also use cgiwrapd in place of cgiwrap to get extra debugging information if there is a problem. 

Troubleshooting CGI-Bin Problems
We don't provide free support for CGI scripts which we did not install on your server. 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. If you are not 
an expert, look for scripts that are very well documented and come with step-by-step instructions.

Below are solutions to some of the more common CGI script problems, in question and answer format. If your plan type includes error logs, you can check the log for help in troubleshooting your scripting problems. The error-log is located in your /home directory.

 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 your request."
This error usually means that the file permissions are not set at 755. If you have your script within a subdirectory other than "cgi-bin" make sure that the subdirectory is also set at 755.

 If you still get the error, then there is a problem with the script itself. You can pinpoint the exact problems in your script by executing it from the shell prompt. At the shell prompt, change to the directory where your script resides. At the prompt, type "perl script_name" (Perl being the language interpreter in this case) or "script_name". For example, if the script name is links.pl, you would type "perl links.pl" or "links.pl".

 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 receive 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 e-mail address. 

I am getting the message, "POST not implemented."
You are probably using the wrong reference for cgiemail. Use the reference, /cgi-bin/cgiemail/order.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 text file.

I'm Getting a Forbidden Error When Trying to Access my Website
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 at the shell prompt. If you wish to FTP this file onto your site, go to the home/yourdomain directory.