|
SUPERIOR WEB HOSTING SOLUTIONS | " we make it work " |
 |
|
|||||||||||
|
|
Part 5 - CGI ScriptsThe following topics are discussed further below:
CGI stands for "Common Gateway Interface," referring to computer programs running on the Web server that can be invoked from a WWW page at the browser. The "bin" part alludes to the binary executables that result from compiled or assembled programs. It is a bit misleading because CGIs can also be Unix shell scripts or interpreted languages like Perl. CGI scripts need to be saved in ASCII format and uploaded to your server's CGI-bin in ASCII (text) format. This is very important. We don't provide free support for CGI scripts that we did not install. So, if you are not already familiar with CGI scripting, you may want to read a book on the subject or refer to our Tips & Tutorials section. Put your CGI-bin scripts in the www subdirectory named "cgi-bin." If you prefer to put your scripts elsewhere, you can as long as the name ends with .cgi. Paths to Perl and Other Programs Here are your paths to the common server resources that CGI scripts often require: Sendmail: /usr/sbin/sendmail
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 re-upload 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 access: Owner, 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 Web Control Panel. To access it, go to http://www.yourdomain.com/cgi-bin/plusmail. Once logged-in, select "Site Manager," then click a folder or file icon to view related properties and set permissions. You can also use Telnet (SSH, Protocol Version 2) or FTP. Cgiwrap - Secure 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://YourMachineName.safe-order.net/cgi-YourDomainName/script.cgi Note: 'YourDomainName' should not include the domain name's extension - leave off the .com, .net etc. You can call cgiwrap explicitly with this call, which does the same thing as the above call: https://YourMachineName.safe-order.net/cgi-bin/cgiwrap/YourDomainName/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. For nph-style scripts, use nph-cgiwrap or nph-cgiwrapd instead. Preconfigured, Preinstalled Scripts To setup your discussion forums, just go to http://www.yourdomain.com/forums/cgi-s Once you have created your forum, access it by going to http://www.yourdomain.com/forums/name_of_your_forum If you need to re-install this script, login to your Web Control Panel, select Free Scripts, then select Multi User Forums. Cgiemail is a form processing script, totally different from Formmail. It is a program written in the C language that takes the contents of fill-in boxes on a form and e-mails 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 e-mail 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 put on your site to show 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 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 successfully completing the form. This form is customizable. Next are the items that are actually presented to the user. You'll want to use type=text input items with cgiemail; it's a simple method. 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 server where cgiemail starts processing it. What is does is controlled by the order.txt file discussed below. 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 an order.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 order.txt in ASCII mode. Failure to upload order.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 as name=key. That's all. You can lay out your form as is best for your users, but lay out your order.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 does, but other than that, it is an excellent program, allowing you more flexibility in the way your data can be returned by the form. The clickgo.cgi script is preinstalled in your cgi-bin directory. To utilize this script, you will need to add the following syntax to your HTML page: <FORM METHOD=POST ACTION="http://www.yourdomain.com/cgi-bin/clickgo.cgi"> Replace "yourdomain.com" with your domain address. 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 "About". You can add as many options as you like. Below is what the script looks like after it is set up: Also, see Secure Server Order Forms This 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 inherent in granting full 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 refer to the location of the script, and the method used must be "POST", expressed in capital letters. Here's an example of the form fields to put in your form: <FORM METHOD=POST ACTION="http://YourDomainName.com/cgi-YourDomainName/formmail.cgi"> 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 your e-mail 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 e-mail 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 entitled, "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"> E-mail Field Description: This form field will allow the user to specify their return e-mail address. If you want to be able to return e-mail to your user, you should 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 e-mail address with valid syntax, add this field name to the "required" field (see below). 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 premade 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 (no spaces in between). 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. Syntax: To require that they fill in the e-mail and phone fields in your form: <input type=hidden name="required" value="email,phone"> Env_report Field Description: Allows you to have environment variables included in the e-mail message you receive after a user has filled out your form. This is 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: REMOTE_HOST—Sends the hostname making the request NOTE: In our case, REMOTE_HOST and REMOTE_ADDR are the same, since our servers do not perform the reverse DNS lookup needed to generate the true REMOTE_HOST string. Syntax: To determine all the above variables: <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 your variables will appear in the e-mail form that Formmail generates. You can choose to have the field sorted alphabetically or specify a set order in which the fields will 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 fields into a specific order, 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 e-mail message, separated by commas. Syntax: To sort alphabetically: <input type=hidden name="sort" value="alphabetic"> To sort into a specific 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 will be printed in your e-mail message. By default, no config fields are printed to your e-mail. This is because the important form fields, like e-mail, 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: To print the e-mail and subject fields in the body of your message: <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 be printed in the return HTML, regardless of whether they were filled in. Formmail defaults to turning this off, so that unused form fields aren't e-mailed. 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: To specify a title of "Feedback Form Results", you would include the following form tag:: <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"> Free-For-All-Links Page allows you to set up a Web page which your users can then add links to in specified categories. Newest links are added to the top of each category. A running total of the number of links present as well as the time when the last link was added is shown at the top of the page. Your preconfigured Free-For-All-Links page is already set up on your server at http://www.yourdomain.com/links/links.htm. The only configuration you may want to change is to customize the look of the links.htm page. Just leave the method and input tags the way they are. If you decide to change the category names, you must do so in the links.htm document, AS WELL AS in the links.pl file in your cgi-bin. If you need to re-install this script, login to your Web Control Panel, select Free Scripts, then select Pro Links page. There are three different types of page counters you can place on your pages. The first is a no-frills graphical counter which looks like this:  To use this one, put the following tag somewhere on your page, but change the yourpage.htm to the address of the actual page you are putting this counter on. The width=5 part refers to the number of digits in your counter. This counter is not as reliable as the others mentioned. <img src="/cgi-bin/nph-count?width=5&link=http://yourdomain/yourpage.htm"> The second is the Virtual Publisher Counter (Not available on accounts established after June 1999). It is another graphical counter, but it will give you all kinds of stats such as time and date of visits, and domains that your visitors came from, etc. It looks like this:  To put this counter on your page, insert the following tag somewhere—please note that the line had to be broken up to fit on this page, but the line should not be broken up on your page. <img src="http://yourdomain.com/cgi-bin/counter/counter.cgi?fnam=testcount&viz=yes&isinv=yes&setup=/home/www/yourdomain/cgi-bin/counter/setup.txt"> Where you see fnam=testcount, replace "testcount" with the name of the page you want to put the counter on. The viz=yes part tells the counter script whether your counter should be invisible or not. If you want the counter to be visible, leave it as "yes." If you want it to be invisible, change it to "no." The "isinv=yes" lets you choose whether you want the counter to be inverted (white against black background) or not. If you want the number to be black against a white background, change it to isinv=no. Another great thing about this one is that you can access the log files for each page you have the counter on, and also reset the count to any number you wish. To see the instruction page, go to: http://yourdomain.com/counter/ Please be aware that a count file will not be created until a page is accessed for the first time. Text-Based Page Counter (uses SSI) Finally, the third and simplest kind of page counter is a text-based counter. It uses SSI, so the page you are putting it on must have the .sht, .shtm, or .shtml extension. You may assign the counter's text and size attributes. The tag looks like this: <!--#exec cgi="/your_cgi-bin/counters/counter.cgi"--> Replace "/your_cgi-bin" with the relative path to your cgi-bin from the page where you place the counter. After you've placed the counter on your page, look at it with your browser. If you don't see the counter the first time, hit reload or refresh. Then you should see the number 1. If you want to change the page count, FTP to your site, and look in the counters directory in your cgi-bin. There will be a file there with the name of the page you placed this counter on. Edit this file—change the starting number and re-upload the file (in ASCII format). Once the file is re-uploaded, hit reload or refresh to reset the number. To install this script, go to your Web Control Panel (http://www.yourdomain.com/cgi-bin/plusmail), select Free Scripts, then select Postcards. Once the script is installed (wait 15 minutes before trying to access the script), you can access it by going to http://www.yourdomain.com/cards. To install this script, go to your Web Control Panel (http://www.yourdomain.com/cgi-bin/plusmail), select Free Scripts, then select Quiz Master. Once the script is installed (wait 15 minutes before trying to access the script), you can access it by going to http://www.yourdomain.com/quiz. 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 this 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, including The script uses Server-Side Includes (SSI), 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"--> With normal, non-secure submission forms, any text 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. By using a secure server, however, 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 (such as billing and contact information) from your visitors. The domains hosted by us are housed on any number of computers, and each of them has a different machine name (server name). The machine name you are to use for your secure order access calls was included in your Welcome e-mail from us. Your Web Control Panel also lists your machine name. Each server has its own safe-order site, and although you will be putting your form on your own domain, it must be called through the safe-order 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, but for this example, let's assume the normal URL for your form can be accessed from a browser with this URL: http://www.YourDomainName.com/signup/secureform.html To call the form through the secure-order server, you need to use the following URL (even though your form resides on your own domain space). Don't forget the "s" in "https." https://YourMachineName.safe-order.net/YourDomainName/signup/secureform.html This is the URL you would use as the <a href> link to your form. To use the secure server with a cgi-bin script, the call would be as follows: https://YourMachineName.safe-order.net/cgi-YourDomainName/YourCGIscript.cgi 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 Web space you want, but you MUST use the following URL as the ACTION of your form: https://YourMachineName.safe-order.net/cgi-YourDomainName/formmail.cgi Here's an example of how the first parts of your form might look (replace "YourMachineName" with your actual machine's name, given to you in our 'Welcome' email and also listed in your web control panel): <FORM METHOD=POST ACTION="https://YourMachineName.safe-order.net/cgi-YourDomainName/formmail.cgi"> It is still important that you call your order page through a secure URL in order for it to work properly. For example: https://YourMachineName.safe-order.net/YourDomainName/order.htm. PageSearch (On older accounts) To install this script, go to your Web Control Panel (http://www.yourdomain.com/cgi-bin/plusmail), select Setup Scripts. Choose "Power Search" from the list of available scripts to install. Once the script is installed (wait 15 minutes), follow the instructions at http://www.yourdomain.com/pagesearch Your login is the same as the one for your Web Control Panel. If you have problems logging in, reset your Web Control password. Go to http://www.yourdomain.com/cgi-bin/plusmail, type your Username and Password, then press "Change Password" instead of "Login." Perlfect Search (Our former Power Search) Contact us in order to request installation of this script. Detailed instructions can be found at the Perlfect Search web site. On older accounts, you may already have this installed. Follow the instructions at http://www.yourdomain.com/search_instructions.htm for configuration options. To install this script, go to your Web Control Panel (http://www.yourdomain.com/cgi-bin/plusmail), select Free Scripts, then select SFE PageSearch. Once the script is installed (wait 15 minutes), follow the instructions at http://www.yourdomain.com/search/instruct.htm Simple Site Search (On older accounts) Simple Site search will look at all your HTML pages for words you enter, and return all pages on a list with links. This program is completely configured and ready to run, but for search.cgi to return a response, it needs to be activated. This is easily done by logging in via Telnet and, at the prompt after log-in, typing the following command: chmod +r /www/yourdomain Now you can access search.cgi with the following URL: http://yourdomain.com/cgi-bin/search.cgi. To add the Simple Site Search to an existing page, add the following source code: <FORM ACTION="cgi-bin/search.cgi" METHOD="POST"> There is a configuration file called search_define.pl which accompanies search.cgi and sets up the variables for it. You can customize which files you wish to exclude from searches and also the cosmetics of the search and results pages. For instructions on setting up your shopping cart, go to http://www.yourdomain.com/lto.htm If you need to re-install this shopping cart, login to your Web Control Panel, select Free Scripts, then select "That's An Order." Ideas: By integrating an adbanner rotator, you can rotate promotional banners, calling attention to special promotions, and electronic couponing. For instructions on setting up your guestbooks, go to http://www.yourdomain.com/vbpro If you need to re-install this script, login to your Web Control Panel, select Free Scripts, then select Visitor Pro Guestbook. To install this script, go to your Web Control Panel (http://www.yourdomain.com/cgi-bin/plusmail), select Free Scripts, then select Vote Script. Once the script is installed (wait 15 minutes), you can access it by going to http://www.yourdomain.com/pollit To install this script, go to your Web Control Panel (http://www.yourdomain.com/cgi-bin/plusmail), select Free Scripts, then select "Whois." Once the script is installed (wait 15 minutes), you can access it by going to http://www.yourdomain.com/cgi-bin/whois.cgi To add the whois script to an existing page, add the following source code: <FORM ACTION="cgi-bin/whois.cgi" METHOD="GET"> Permissions on Preinstalled Scripts Below is a table of the permissions assigned to our preconfigured, preinstalled scripts:
How to Test Your CGI Scripts Using Telnet You can pinpoint the exact problems in your CGI scripts using Telnet (Secure Shell, Protocol Version 2). To test your script, you must execute it from the shell prompt. In order to do this, the permissions for that script must allow Owner Execute privileges. (Refer to Setting Permissions above.) 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". After you have located the problem, you can edit the script from the shell prompt by using PICO. Troubleshooting CGI-Bin Problems Below are solutions to some of the more common CGI script problems, in question and answer format. Also, check out our Online FAQ on CGI-Scripts and Programming Langauges. 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."
I am being told, "File Not Found," or "No Such File or Directory."
When I test my Perl script in local mode (by Telnet/SSH), 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."
I am getting the message, "POST not implemented."
It's saying I don't have permission to access /
Some of the text referring to CGI scripts was taken directly or adapted for our use from ReadMe files provided by the script designers. Many thanks to the folks at Matt's Script Archive for their excellent documentation! Please support Matt's Scripts. Their scripts are free, but that doesn't mean they are cheap. Much time went into the development of each script, and Matt is one of the best scripters around! Consider visiting our Technical Reference section for books on cgi, and other languages. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
 |
HOME | |  |
CONTACT | |  |
ORDER & BILLING | |  |
SUPPORT & HELP | |
Copyright Notice | Policies & Guidelines | Privacy Statement | Site Map
Copyright © 1998-2012 PeoplesWare.com. All Rights Reserved.
