Creating CGI Programs with Bash: Getting Started

<-- Page 1: Introduction | Page 3 - Handling POST Data -->

Beginning a Bash Script

Shell scripts start with a line identifing the file as a script and telling the operating system what script interpreter to use. Since we're using Bash, we'll tell the system to use Bash as the script interpreter:

The #! on the first line tells the system that the file is a shell script, and everything after the ! is the path to the interpreter to use to process the script. On most systems, the path to Bash is /bin/bash, but it may be something else on your particular system. If /bin/bash doesn't work, try /usr/bin/bash, and if that doesn't work, ask your system administrator or host provider what the path to Bash is on your system.

The rest of a Bash script consists of either Bash code or other programs. While programming in Bash, you will use many other programs found on the system to accomplish tasks not built into Bash, such as text parsing or sending HTML back to the browser.

Variables in Bash

Variables in Bash can be created at any time and have no specific type. The following code creates several variables: In this example a variable VARIABLE is created which holds "This is a variable" while a variable named ANOTHER is created that holds the output of the command wc -l /tmp/example
Capturing the output of a command and saving it in a variable is a very important tool in Bash. To do so, use VARIABLE_NAME=`command`

To reference a variable (ie get its value), put a dollar sign in front of the variable, as in the example below: Which outputs

In this example, the command echo is used to output text. The outputted text is VARIABLE= and then the content of the variable VARIABLE, which is referenced with $VARIABLE.

Creating an Extremely simple CGI in Bash

Below is an extremly simple CGI program in Bash. All it does is show the user a webpage that says "Welcome to your Bash CGI!"

This Bash program, when run by the web server, will send a page that says "Welcome to your Bash CGI!" to a browser window. The output looks like the screenshot below:

The most important lines in this file are: These two lines tell your browser that the rest of the content comming from the program is HTML, and should be treated as such. Leaving these lines out will often cause your browser to download the output of the program to disk as a text file instead of displaying it, since it doesn't understand that it is HTML!

This program uses the echo program to send text to a browser. Normally, echo prints whatever comes after it to the screen, but in Bash CGIs, it instead sends whatever is after it to the browser. Using echo you can send any text to the browser. Rembmer that the browser will treat it as HTML, so you can also include HTML formatting tags to make the output of your CGI look however you want.

Creating a Form in HTML

Now that handling variables is covered, we'll create a simple CGI program in Bash that gets some data from an HTML form. CGI programs are often started by a user submitting HTML form data, with the CGI program then processing the result and giving some kind of output.

First, lets start by creating a simple HTML form, which will submit data to our CGI program, which is /cgi-bin/example.sh

For those unfamilar with HTML forms, here's a breakdown of the above:

• The first line creates a form. action="/cgi-bin/example.sh tells the browser that everything submitted should go to the CGI program found at http://www.example.com/cgi-bin/example.sh and method="get" tells the browser to send the data using the GET method (there are two ways a browser can send data to a CGI program. For now, we will only deal with the GET method. The main limitation of GET is that you can only send a few hundred characters worth of data this way. In general, unless you are uploading files or huge blocks of text, GET will work fine for CGI programs).
• The next line creates a text box named username.
• The next line creates a radio button named whatToDo with the value "remove" and automatically checks it.
• The next line creates a radio button named whatToDo with the value "create".
• The next line creates a submit button named subbtn with the text "Submit" on it.
• The last line ends the form

When a CGI program sees the data submitted from this form, it sees something like this: Assuming the user entered "John Doe" into the text box and selected the "create" radio button.

Getting Form Data in a Bash CGI

We've created a great HTML form that submits data to a CGI program. Now all we need to do is create a CGI program that does something with this data. Below is a simple Bash program that will tell the user what they entered:

This will give the person who clicked submit in our form a webpage that tells them what they entered into the form. For example, if the person enterd "John Doe" as their username and clicked the "Create" radio button, they would get a webpage that says: Lets look at how this works, line by line:

• We are already familar with the first 5 lines, so we'll skip ahead to the first new one:
• USERNAME=`echo "$QUERY_STRING" | sed -n 's/^.*username=\([^&]*\).*$/\1/p' | sed "s/%20/ /g" puts the form data named "username" into a variable named USERNAME.
• WHATTODO=`echo "$QUERY_STRING" | sed -n 's/^.*whatToDo=\([^&]*\).*$/\1/p' | sed "s/%20/ /g" puts the form data named "whatToDo" into a vairable named WHATTODO.
• The next two lines send some HTML code the the browser.
• The second-to-last line sends the browser the text telling the user what they entered. Since the variable names on this line are preceded with a $, the values of the variables are substituted for the vairable names.
• Finally, the last line ends the HTML code for the browser. At this point, the CGI is finished and the program on the web server ends.

The most important lines are 3, 4, 6, and 7, discussed below:

The lines that actually get the form input from the form into the CGI are copied below, and color coded:

How does this work?

When your user hits the submit button in your HTML form, the web browser sends everything they put into the form to the CGI program referenced in the form. Since the form uses the GET method to transmit data, the web server takes the data it receives from the form and puts it in an enviromental variable named QUERY_STRING. It then starts the CGI program referenced in the form, which is our Bash program.

Our Bash program begins with the normal initialization of a Bash CGI program. Eventually, it needs to read in the form data. Remember that this is stored in an enviromental variable. Lines 3 and 4 of our Bash CGI, color coded above, do the work of pulling the data out of the enviromtal variable and into variables in our Bash program.

First, a variable in Bash is created (colored red). The variable is created by parsing reading the QUERY_STRING enviromental variable set by the web server (green). The QUERY_STRING variable is sent through the sed program, which looks for a pattern matching the name of a form element (blue) and collects any data belonging to that form element. Finally, the result is sent to another sed program (orange), which replaces any occurances of %20 with a space, since when the form data is transfered from the browser to the server, spaces are turned into %20 (so "Hi there" becomes "Hi%20there").

You can use any Bash variable you like, and to get different form elements, simply change the name sed looks for, which in this example is hilighted in blue.

<-- Page 1: Introduction | Page 3 - Handling POST Data -->