Creating your NMIA website

Overview

NMIA serves user cgi scripts via a wrapper program. The wrapper program executes a user's script using the user's uid as its effective uid. In other words, the cgi script has the same `permissions' as the user that owns it. The script can do anything that the user could normally do.

Getting started

You can serve cgi scripts, but there are some dire warnings you should know about first. It is possible to write a simple script which will destroy everything in your account directory, or make very subtle changes in it that would be difficult to diagnose. That is, you should know a good bit about unix and shell programming and possibly about perl or other languages you intend to use, before setting scripts loose to be run by strangers through your web site.

But, if you wish to proceed you should:

create a cgi-bin directory in your public_html directory if one doesn't exist

copy a script there called test-cgi which you can use to test the cgi setup.

You can find this file at: /home/common/html/cgi/test-cgi

send mail to www saying that you've read the warnings and want to serve cgi scripts anyway

know that all cgi scripts must be run under the cgiwrap program

Using the wrapper to call your scripts

After your cgi-bin directory has been enabled, you can access scripts under it with a URL like: http://www.nmia.com/cgi-bin/cgiwrap/YOUR_USERNAME/YOUR_SCRIPT Where YOUR_USERNAME is your username and YOUR_SCRIPT is the path to your script relative to your public_html/cgi-bin directory. For example, if the user named foo wanted to execute the test-cgi script in ~foo/public_html/cgi-bin, she would use: http://www.nmia.com/cgi-bin/cgiwrap/foo/test-cgi You can put cgi scripts in subdirectories of your public_html/cgi-bin directory. If part of the path is a program instead of a directory, it will be executed with the rest of tha path passed to it as PATH_INFO (like a normal, unwrapped cgi).

Debugging your cgi scripts

You can use cgiwrapd in place of cgiwrap to produce helpful debugging info.

If you get a 500 Server Error error message, your script has generated an invalid HTTP reply to a client's request for your script. The most common mistakes are:

• Transferring files using the wrong ftp transfer mode.
• Not generating a Content-Type header or not leaving a blank line after your HTTP headers.
• Making a programming mistake which leads to an error message (often interpreted as a bad HTTP header).

Programming resources

The most popular programming language for CGI applications is Perl. NMIA has support for Perl version 5 including the Perl module CGI.pm which greatly simplifies the writing of CGI scripts.

If you're going to program in Perl, or simply want to confidently configure Perl scripts that you find on the web, you will find the O'REILLY books on Perl and CGI very helpful.

You can find Perl scripts on the web at a number of locations. A good place to start looking is the Yahoo CGI Perl script section.

3.2 Adding a Page Counter on NMIA

To add a page counter, simply add a line to your html file of the form:

<img src="http://www.nmia.com/cgi-bin/counter?TAG"> where TAG is a unique identifier for your page. An example of this is if you username is "foo" then enter: <img src="http://www.nmia.com/cgi-bin/counter?foo"> If you need a separate counter on another page, use a different name like <img src="http://www.nmia.com/cgi-bin/counter?foo2"> To reset a counter back to zero, just rename it to a different unique name.

For example, the following:

<img src="http://www.nmia.com/cgi-bin/counter?counter.html"> produces the following counter: which shows how many times this page has been accessed.

For more information about the counter see ssd's counter page.

3.3 Using Forms on NMIA

Forms allow you to collect information from people that look at your page. Form interfaces are simple and easy to use.

For Mail, we provide our users with:

Mail Interface

This interface sends form data as mail to addresses that you specify. If you want to send your form data via email, this is the recommended way to do it.

To do this, you'll need to know how to write an html form. A good place to start learning about forms is An Instantaneous Introduction to CGI scripts and HTML Forms.

If you have questions about forms in general, your best bet is to post to one of the www newsgroups.

3.4 FormMail

What is FormMail?

FormMail is a freely available script available from Matt's Script Archive. It is highly configurable and is recommended over the older form-mail (note the dash ) script.

How to use formmail

To use Formmail, you must do two things. First, you must use the following URL as the value of the action attribute of your form:

                http://www.nmia.com/cgi-bin/formmail

Second, you must add input tags in the form section of your page that modify the behavior of the formmail script.

If you wish to send these messages using a domain that we host, you must email 'help@nmia.com' and let us know. Otherwise, your messages will not be allowed.

Only one input tag is required. You must have an input tag that has the name recipient and your email address as its value.
For example:

                ‹input type=hidden name="recipient" value="devnull@nmia.com"›

If you want to send to multiple recipients, just make the value a list of email address separated by commas (no spaces). For example:

                ‹input type=hidden name="recipient" value="addr1@nmia.com,addr2@foo.com,add3@bar.com"›

For a description of the optional input tags that you can use to customize the behavior of formmail, take a look at the formmail documentation.

3.5.1 Access Control

Access control on our http server is controlled by directory. All files in a particular directory have the same authorization requirements.

There are two forms of access control, user authentication and host filtering. User authentication involves setting up a password file, assigning usernames, and assigning passwords. If you want someone to access your page, you tell them to use a particular username/password combination. Host filtering simply allows access to some hosts and denies access to others.

In order to control access by user authentication, you'll need to create a file containing user/password correspondences and tell our server to use that file to authenticate users.

You create the file by using the htpasswd program. To tell our server to use user authentication in a particular directory, you just create a file named .htaccess in the directory that you want to protect and put in the appropriate access control directives.

If you just want to jump in without reading the documentation, you can probably modify the following example to suit your needs. Otherwise, visit this site for more detail. Suppose that I want to create a directory where I can put files to be accessed only by people who have a password that I've given them. Here's what I'd do:

Create the directory

I'll call my diretory `private' and put it directly under my public_html directory: mkdir ~/public_html/private chmod go+x ~/public_html/private

Create the password database

I'll add a couple of users, one for me and one for my friend, Opus:

        htpasswd -c ~/.my_passwd_file ron
        htpasswd ~/.my_passwd_file opus

In each case, I'll be prompted to for a password. The first command has a -c. That tells htpasswd that we're starting a new password file. Don't use it on subsequent commands unless you want to wipe your old password file.

Tell the server

To tell the server to use authentication, I'll create a .htaccess file in ~/public_html/private. To do this, I'll use my a text editor and I'll put the following in it: AuthUserFile /home/foo/.my_passwd_file AuthGroupFile /dev/null AuthName "Foobar's Private Area" AuthType Basic <Limit GET> order deny,allow require valid-user </Limit> For a complete explanation, of these directives, take a look at the access configuration docs. The two important lines are the ones beginning AuthUserFile and AuthName. The AuthUserFile line tells the server to use my password file to authenticate users. The AuthName is just a string that is used when the client prompts for a password. It lets the user know what username and password she should use. If it contains spaces, it must be surrounded by double quotes.

Now, when I try to access:

                http://www.nmia.com/~foo/private/

I'll be prompted for a password. When playing around with passwords, remember that your client probably remembers passwords so that once you give a valid password, you won't be prompted again until you restart the client.

Back to the top of the page.

PHP is a preprocessor for HTML.

There are two ways to run a php stript on our system. The script can be placed in your cgi-bin, or run from any location under your public_html.

To process one of your pages with PHP, it is a good idea to put the page under your cgi-bin directory, but it is not necessary. If you choose to put the php script in you cgi-bin the first line of the script must be:

#!/usr/local/bin/php

You would reference the page as:

http://www.nmia.com/cgi-bin/cgiwrap/USERNAME/SCRIPTNAME

where USERNAME is your username and SCRIPTNAME is the path to your page relative to your cgi-bin directory.

Using PHP with the cgiwrap program causes the script to run using your user id, rather than the web process. Running PHP scripts without the cgiwrapper works as one would normally expect, but causes the script to run with the id of the web process. If any sensitive information is being processed by the php script, running as the web process is a dangerous proposition and may allow any other user on our systems to access that same data, since any script they might write will also run as the web process and thereby have the same privilege as your script.

If you are processing sensitive information, we would suggest that you also understand Unix file permissions, as this is an important part of protecting your data. There are a number of good books on Unix that include information about file permissions, and there are probably a good number of informational web sites that might be found by doing a search on google. We would also be happy to discuss the subject with you further if you like.

How to do it

Most people find out about web pages by using one of the popular search engines like Lycos or a large catalogue like Yahoo.

Here are some ways to add links to various places:

• Yahoo
• Lycos
• AltaVista

You can also use the Submit It! form to register your page with several sites at once.

If you come across a page where you think that a link to your page would be appropriate, there's no harm in sending email to the owner of the page asking for a link. Most pages contain author contact information.

Many people have a pointer to their home page in the signature that they use for Usenet news postings and email.

How not to do it

You should avoid simply announcing your page on a Usenet newsgroup, particularly if it's a commercial page. If you maintain a page with information that answers a question that you see asked in a newsgroup, it's acceptable to post a pointer to that page.

The same holds true for mailing lists.

4.2 WWW Newsgroups

Newsgroups are uncensored collections of information on any topic you can think of. You can access those groups by going to Deja News or by getting a news group client. Such clients are later versions of Netscape Navigator, Outlook Express, or Forte Inc's Free Agent.

The following newsgroups have information about the WWW:

• comp.infosystems.www.servers.ms-windows
• comp.infosystems.www.authoring.html
• comp.infosystems.www.browsers.mac
• comp.infosystems.www.browsers.misc
• comp.infosystems.www.browsers.x
• comp.infosystems.www.browsers.ms-windows
• comp.infosystems.www.servers.unix
• comp.infosystems.www.authoring.cgi
• comp.infosystems.www
• comp.infosystems.www.users
• comp.infosystems.www.providers
• comp.infosystems.www.misc
• comp.infosystems.www.announce
• comp.infosystems.www.servers.misc
• comp.infosystems.www.advocacy

When connected to NMIA you do not need to login or supply a username and password to get the newsgroups that are on our server. Just use the server news.nmia.com.

4.3 Instructions for tracking Web page accesses

This page refers to commands. The commands must be entered at a UNIX (or "shell") prompt. To get to such a prompt, you need to SSH from your machine to the NMIA machine plato.nmia.com.

Raw Data

You can keep track of http accesses to your files, or `hits', with the command: httpd_hits The command httpd_hits prints out a raw log to your terminal. The command: httpd_hits >log.txt will create a file in your current working directory named `log.txt'. You can download that file and analyze it on your home computer or use standard unix tools on NMIA machines.

The output of httpd_hits is updated once an hour. At the end of every month, the logs are saved and a new log file starts. You can retrieve the old log file until the end of the month by invoking httpd_hits with the -o:

httpd_hits -o >log.txt

Summary of Hits

You can get a basic summary of your hits with the command: httpd_hits_summary If the output scolls off your screen, you can page through it: httpd_hits_summary | more or redirect it to a file: httpd_hits_summary >file.txt

Options

Either command will take -o as an argument in which case it will display information corresponding to the previous month. httpd_hits_summary -o httpd_hits_summary -o | more httpd_hits_summary -o >file.txt

httpd_hits will take -c as an argument in which case it will print hits in the NCSA Combined format. This option is useful for producing a file that can be read by standard log file analyzer programs:

Format

The format of the data presented by httpd_hits is NCSA Combined Servername. In general, you only need to know the format if you are using a commercial log analyzer. Not all log analyzer programs understand this format. See the -c option above for an alternate format.

Back to the top of the page.

Maintained by NMIA.
All rights reserved. Last modified: Dec 2002