Common Gateway Interface (CGI): How It Works, Server Requirements, and Basic Setup

Common Gateway Interface (CGI) is a standard way for a web server to run a program and return that program’s output as an HTTP response. This is most useful for engineers maintaining legacy systems, troubleshooting old form handlers, or learning how server-side execution works at a low level.

This article is a technical revision of the original post: Introduction of CGI | What is Common Gateway Interface (CGI)?.

Originally published on 2013-05-17; fully revised and updated.

What CGI is

CGI stands for Common Gateway Interface. It defines how a web server passes request data to an external program and how that program returns response data back to the server.

• CGI programs run on the server, not in the browser.
• They can be written in multiple languages (for example Perl, PHP, shell, C/C++), as long as the runtime is available on the server.
• A CGI program receives request context through environment variables and may receive request body data through standard input (STDIN).
• The CGI program must output valid HTTP headers (such as Content-Type) before the response body.

Prerequisites before you deploy CGI scripts

• A web server that allows CGI execution.
• Access to server logs for debugging.
• Basic experience in at least one scripting/programming language.
• Knowledge of HTTP headers and request methods.
• For local practice: a local stack such as WAMP or XAMPP can be used if CGI execution is enabled.

Server requirements and environment differences

CGI behavior depends on server configuration. The core idea is the same everywhere, but handler mapping, file extensions, and permissions vary by platform.

How CGI request and response flow works

The web server sits between the browser and the CGI program. It passes request details to the script and forwards script output back to the client.

flowchart TD
    A[Browser sends HTTP request] --> B[Web server receives request]
    B --> C{Target is CGI script?}
    C -- no --> D[Serve normal content]
    C -- yes --> E[Start CGI process]
    E --> F[Pass environment and body data]
    F --> G[CGI writes headers and body]
    G --> H[Server returns HTTP response]

Minimal CGI example and basic setup checks

1) Example CGI script (Bash)

#!/usr/bin/env bash
echo "Content-Type: text/plain"
echo
echo "Hello from CGI"
echo "REQUEST_METHOD=$REQUEST_METHOD"
echo "QUERY_STRING=$QUERY_STRING"Code language: PHP (php)

2) Make it executable and test it

chmod 755 hello.cgi
curl -i "http://localhost/cgi-bin/hello.cgi?name=devops"Code language: JavaScript (javascript)

3) Example Apache directives often used for CGI

Exact directives depend on host policy and Apache layout, but these are common patterns seen in CGI setups:

Options +ExecCGI
AddHandler cgi-script .cgi .plCode language: CSS (css)

Troubleshooting checklist

• Check server error logs first; CGI failures are usually visible there.
• Confirm the script has executable permission where required.
• Confirm the script extension matches configured handler rules.
• Verify the interpreter path (shebang) is valid on the server.
• Ensure the script prints headers correctly (at minimum Content-Type and a blank line after headers).
• Test with a very small script before adding application logic.

Common pitfalls and best practices

• Pitfall: assuming CGI is enabled by default. Best practice: verify module/handler configuration explicitly.
• Pitfall: weak visibility into failures. Best practice: require access to web server and CGI logs before deployment.
• Pitfall: environment-specific assumptions. Best practice: document per-server requirements (extensions, permissions, runtime paths).
• Pitfall: jumping into full app debugging first. Best practice: start from a minimal known-good CGI script and iterate.

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.