Linux Tutorial: CGI Shell scripts and ISINDEX

Introduction:

This tutorial covers the basics of using bash shell scripts for web server CGI. Default Red Hat Linux directory configurations for Apache are used in this tutorial. The HTML ISINDEX tag is used for data input to the script.

CGI uses two methods to pass data between the browser and the web server, GET and POST. The GET method passes data in the URL and is the method employed here. The web server will pass environment variables into the execution environment of the CGI shell script which also may be used.

Simple output of a text file:

CGI Shell script to output a text page: /var/www/cgi-bin/cat-a-text-page

#!/bin/bash
CAT=/bin/cat
COLCRT=/usr/bin/colcrt

echo Content-type: text/plain
echo ""

if [[ -x $CAT && -x $COLCRT ]]
then
        $CAT $1 | $COLCRT
else
        echo Cannot find command on this system.
fi

Usage: <A HREF="/cgi-bin/cat-a-text-page?/home/user1/public_html/text-file.txt">Text of link</A>

Note:

the permissions on the shell script must changed to make the script executable: chmod +x cat-a-text-page
the shell /bin/sh was often used in older systems and was a link to /bin/bash (most Red Hat Linux systems). The behavior of shells other than Bash is not covered in this tutorial. Debian currently softlinks /bin/sh to /bin/dash which does not behave the same. It is best to specify the Bash shell explicitly: #!/bin/bash

Simple example to output a text file formatted as HTML:

CGI Shell script: /var/www/cgi-bin/Output-text-as-html

#!/bin/bash

echo Content-type: text/html
echo ""

/bin/cat << EOM
<HTML>
<HEAD><TITLE>File Output: /home/user1/public_html/text-file.txt </TITLE>
</HEAD>
<BODY bgcolor="#cccccc" text="#000000">
<HR SIZE=5>
<H1>File Output: /home/user1/public_html/text-file.txt </H1>
<HR SIZE=5>
<P>
<SMALL>
<PRE>
EOM

/bin/cat /home/user1/public_html/text-file.txt

CAT << EOM
</PRE>
</SMALL>
<P>
</BODY>
</HTML>
EOM

Usage: <A HREF="/cgi-bin/Output-text-as-html">Text of link</A>

Using the ISINDEX HTML tag for script input:

The Web Page:

Test of ISINDEX HTML tag:

HTML Source:

<HTML>
<HEAD><TITLE>Test ISINDEX HTML tag</TITLE></HEAD>
<BODY bgcolor="#cccccc" text="#000000">
<H2>Test ISINDEX HTML tag</H2>
<ISINDEX prompt="Enter value:" action="http://localhost/cgi-bin/catpage">
</BODY>
</HTML>

Text entered: /tmp/text-file.txt
The following will get generated: http://localhost/cgi-bin/catpage?%2Ftmp%2Ftext-file.txt
The CGI will then spit out the text page specified.

[Potential Pitfall]: Currently Mozilla 1.2.1 (Also default Red Hat 8.0 and 9.0) browsers have a bug which prevents this from operating properly. Konqueror, Netscape, Lynx all work properly.

Shell script using ISINDEX in simple search:

In this case the script will generate all displayed interfaces. This example is the easiest form of a simple on-line database. (Grep/search a file and output the results of the search)

CGI Script:

CGI Shell script: /var/www/cgi-bin/isindex-search

#!/bin/bash

echo Content-type: text/html
echo ""

if [ $# = 0 ]
then
/bin/cat << EOM1
  <HTML>
  <HEAD><TITLE>Text search </TITLE>
  </HEAD>
  <BODY bgcolor="#cccccc" text="#000000">
  <HR SIZE=5>
  <H1>Text search </H1>
  <P>
  <ISINDEX prompt="Enter search string: " action="http://localhost/cgi-bin/isindex-search">
  <P>
  </BODY>
  </HTML>
EOM1
else
/bin/cat << EOM2
  <HTML>
  <HEAD><TITLE>Search results for $* </TITLE>
  </HEAD>
  <BODY bgcolor="#cccccc" text="#000000">
  <HR SIZE=5>
  <H1>Search results for $* </H1>
  <HR SIZE=5>
  <P>
  <PRE>
EOM2

grep -i "$*" /home/user1/file-to-search.txt

/bin/cat << EOM3
  </PRE>
  <P>
  </BODY>
  </HTML>
EOM3
fi

Results:

Usage: http://localhost/cgi-bin/isindex-search
Enter text string to search for and press enter:

Text search

[Potential Pitfall]: ISINDEX is getting old and is less supported in modern browsers. The above example may not render properly in your browser as it is also the second ISINDEX statement in this page.
The script will spit out the search results of the grep in an HTML page.

Environment variables:

The web server will execute the CGI script in its own process space but will set some usefull environment variables. To view these use the following script: /var/www/cgi-bin/env.sh

#!/bin/bash

echo Content-type: text/html
echo ""

/bin/cat << EOM
<HTML>
<HEAD><TITLE>File Output: /home/user1/public_html/text-file.txt </TITLE>
</HEAD>
<BODY bgcolor="#cccccc" text="#000000">
<P>
<SMALL>
<PRE>
EOM

/bin/env

CAT << EOM
</PRE>
</SMALL>
<P>
</BODY>
</HTML>
EOM

Make script executable: chmod ugo+x env.sh

Test: http://localhost/cgi-bin/env.sh

Output: (example)

SERVER_SIGNATURE=
Apache/2.0.40 Server at localhost Port 80


UNIQUE_ID=DErk6n8AAAEAAAblFQEAAAAD
HTTP_USER_AGENT=Mozilla/4.8 [en] (X11; U; Linux 2.4.18-27.8.0 i586)
SERVER_PORT=80
HTTP_HOST=localhost
DOCUMENT_ROOT=/var/www/html
HTTP_ACCEPT_CHARSET=iso-8859-1,*,utf-8
SCRIPT_FILENAME=/var/www/cgi-bin/env.sh
REQUEST_URI=/cgi-bin/env.sh
SCRIPT_NAME=/cgi-bin/env.sh
HTTP_CONNECTION=Keep-Alive
REMOTE_PORT=32984
PATH=/sbin:/usr/sbin:/bin:/usr/bin:/usr/X11R6/bin
PWD=/var/www/cgi-bin
SERVER_ADMIN=root@localhost
HTTP_ACCEPT_LANGUAGE=en
HTTP_ACCEPT=image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */*
REMOTE_ADDR=127.0.0.1
SHLVL=1
SERVER_NAME=localhost
SERVER_SOFTWARE=Apache/2.0.40 (Red Hat Linux)
QUERY_STRING=
SERVER_ADDR=127.0.0.1
GATEWAY_INTERFACE=CGI/1.1
SERVER_PROTOCOL=HTTP/1.0
HTTP_ACCEPT_ENCODING=gzip
REQUEST_METHOD=GET
_=/bin/env

These environment variables provided by the web server can be used in your script to suit your needs.

Links:

W3.org: CGI security FAQ

Books:

	"Learning the Bash Shell" by Cameron Newham, Bill Rosenblatt O'Reilly & Associates, ISBN# 1565923472 This book is a great bash shell script book.
	"Classic Shell Scripting" by Arnold Robbins, Nelson H.F. Beebe O'Reilly & Associates, ISBN# 0596005954
	"Wicked Cool Shell Scripts" by Dave TAylor No Starch Press, ISBN# 1593270127