# checkout source code
git clone https://github.com/pjincz/nginx-cgi
cd nginx-cgi

# build deb package
./build-deb-package.sh

# install built package
dpkg -i ../libnginx-mod-http-cgi_*_amd64.deb 

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    root /var/www/html;

    index index.html index.htm index.nginx-debian.html;

    server_name _;

    location / {
        try_files $uri $uri/ =404;
    }
}

    location /cgi-bin {
        cgi on;
    }

#!/bin/bash

echo "Content-Type: text/plain"
echo

echo Hello CGI

chmod +x /var/www/html/cgi-bin/hello.sh

curl http://127.0.0.1/cgi-bin/hello.sh

location /cgi-bin {
    cgi on;
}

location /cgi {
    alias /var/www/html/cgi-bin;
    cgi on;
}

#!/bin/sh

echo "Status: 200 OK"
echo "Content-Type: text/plain"
echo

echo "Hello world"

chmod +x /var/www/html/cgi-bin/hello.sh

#!/bin/sh
echo ""

echo "query string: $QUERY_STRING"
echo "http accept: $HTTP_ACCEPT"

#!/bin/sh
echo ""

body=$(cat)

echo "request body: $body"

#!/bin/sh
echo ""

bc 2>&1

curl 127.0.0.1/cgi-bin/bc.sh --no-progress-meter -T .

#!/bin/sh

echo 'Content-Type: text/plain'
echo

printenv

# allow wwww-data run /var/www/bin/my-danger-script with root account
www-data ALL=(root) NOPASSWD: /var/www/bin/my-danger-script

# allow all CGI script be launched with sudo by nginx-cgi directly
www-data ALL=(root) NOPASSWD: SETENV: /var/www/html/cgi-bin/*

mkdir -p /var/www/html/cgi-bin
cat > /var/www/html/cgi-bin/ls.sh <<EOF
#!/bin/sh
echo "Status: 200"
echo "Content-Type: text-plain"
echo
echo "files under /:"
ls /
EOF
chmod +x /var/www/html/cgi-bin/ls.sh

# try it
/var/www/html/cgi-bin/ls.sh

# In this example, I put everything to /var/www/chroot
# Be careful, I download x86_64 busybox version here, you may need to change it
# You need root permission to run all following commands, I'm too lazy to
# prepend sudo to every commands here.

root_dir=/var/www/chroot

mkdir -p "$root_dir/bin" && cd "$root_dir/bin"
wget https://www.busybox.net/downloads/binaries/1.35.0-x86_64-linux-musl/busybox
chmod +x busybox

cd "$root_dir"
mkdir -p $(dirname $(./bin/busybox --list-full) | sort -u)
./bin/busybox --list-full | while read line; do ln -sf /bin/busybox $line; done

# try it
chroot "$root_dir" ls

mkdir -p /var/www/chroot/var/www/html
mount --bind /var/www/html /var/www/chroot/var/www/html

# try it
ls /var/www/chroot/var/www/html

cat >/etc/sudoers.d/www-run-with-chroot <<EOF
# allow and only allow www-data run chroot with /var/www/chroot
www-data ALL=(root) NOPASSWD: /usr/sbin/chroot /var/www/chroot *
EOF

location /cgi-bin {
    cgi on;
    cgi_interpreter /usr/bin/sudo /usr/sbin/chroot /var/www/chroot;
}

curl 127.0.0.1/cgi-bin/ls.sh

mkdir -p /var/www/html/cgi-bin
cat > /var/www/html/cgi-bin/ls.sh <<EOF
#!/bin/sh
echo "Status: 200"
echo "Content-Type: text-plain"
echo
echo "files under /:"
ls /
EOF
chmod +x /var/www/html/cgi-bin/ls.sh

# try it
/var/www/html/cgi-bin/ls.sh

# Change -v if necessary
# -d: runs background
# -i -t: keep a terminal
# --restart always: keep container alive
docker run -dit --restart always --name my_cgi_docker -v /var/www:/var/www busybox sh

# try it
docker exec my_cgi_docker /var/www/html/cgi-bin/ls.sh

sudo usermod -aG docker www-data

# try it
sudo -u www-data docker exec my_cgi_docker /var/www/html/cgi-bin/ls.sh

location /cgi-bin {
    cgi on;
    cgi_interpreter /usr/bin/docker exec my_cgi_docker;
}

mkdir -p /var/www/html/cgi-bin
cat > /var/www/html/cgi-bin/ls.sh <<EOF
#!/bin/sh
echo "Status: 200"
echo "Content-Type: text-plain"
echo
echo "files under /:"
ls /
EOF
chmod +x /var/www/html/cgi-bin/ls.sh

# try it
/var/www/html/cgi-bin/ls.sh

mkdir -p /var/www/jail && cd /var/www/jail
fetch https://download.freebsd.org/ftp/releases/$(uname -m)/$(uname -m)/$(uname -r)/base.txz
tar -xvf base.txz -C .

# create mount points
mkdir -p /var/www/jail/var/www/html
touch /var/www/jail/etc/resolv.conf

# uncomment following lines, if you want to allow network access in jail
# ip4 = inherit;
# ip6 = inherit;
# exec.prestart += “mount_nullfs /etc/resolv.conf /var/www/jail/etc/resolv.conf || true”;

# uncomment fowlling lines, if you also want `ping` available in jail
# allow.raw_sockets = 1;

persist; # keep jail if no process runs
}”>

www-jail {
    path = "/var/www/jail";
    host.hostname = "www-jail.local";

    exec.clean;
    exec.start = "/bin/sh /etc/rc";
    exec.stop = "/bin/sh /etc/rc.shutdown";

    # mount /var/www/html => /var/www/jail/var/www/html
    exec.prestart += "mount_nullfs /var/www/html /var/www/jail/var/www/html || true";
    mount.devfs;

    # uncomment following lines, if you want to allow network access in jail
    # ip4 = inherit;
    # ip6 = inherit;
    # exec.prestart += "mount_nullfs /etc/resolv.conf /var/www/jail/etc/resolv.conf || true";

    # uncomment fowlling lines, if you also want `ping` available in jail
    # allow.raw_sockets = 1;

    persist; # keep jail if no process runs
}

service jail start www-jail

# try it
jexec www-jail ls /
jexec www-jail /var/www/html/cgi-bin/ls.sh

cat >/usr/local/etc/sudoers.d/www-jexec <<EOF
# allow and only allow `www` run `jexec` with `www-jail`
www ALL=(root) NOPASSWD: /usr/sbin/jexec www-jail *
EOF

# try it
sudo -u www sudo jexec www-jail /var/www/html/cgi-bin/ls.sh

location /cgi-bin {
    cgi on;
    cgi_interpreter /usr/local/bin/sudo /usr/sbin/jexec www-jail;
}

curl 127.0.0.1/cgi-bin/ls.sh

taskid=1234
logfile="/var/lib/my-project/$taskid"
./long-run-task.sh "$taskid" </dev/null >"$logfile" 2>&1 &

My http request hangs

As you see abvoing. In CGI world, http request’s lifecycle depends on pipe’s
(stdout’s) lifecycle.

Each child process might inherit the CGI process’s pipe. If any process that
inherited stdout remains alive, the HTTP request will never finish.

This may causes confiusing, when you want a long run background or killing
CGI process.

For creating long-run process, see aboving topic.

For killing CGI process, kill the whole process group rather than CGI process
itself.

cgi_pid=...

# don't do this
# kill "$cgi_pid"

# do this
kill -- "-$cgi_pid"

I want to kill my cgi script

See aboving topic.

I want to generate content dynamicaly

Traditionally, people use rewriting to archive this. But it’s much easier here.
You can do it with cgi pass. Here’s an example to render markdone dynamically:

{
    location ~ ^.*.md$ {
        cgi_pass /var/www/bin/cgi/render-markdown.sh;
    }
}

#!/bin/sh

set -e

if [ ! -f "${DOCUMENT_ROOT}${PATH_INFO}" ]; then
    echo "Status: 404"
    echo
    exit
fi

echo "Status: 200"
echo "Content-Type: text/html"
echo

echo ""
markdown "${DOCUMENT_ROOT}${PATH_INFO}"
echo ""

I don’t like suffixes in url

Way 1: Removing CGI script’s suffix

Way 2: do rewriting

Way 3: cgi pass

How can I response status other than 200

#!/bin/sh

echo "Status: 404"
echo "Content-Type: text/plain"
echo

echo "Welcome to the void"

How can I response a redirection

#!/bin/sh

echo "Status: 302"
echo "Location: https://theuselessweb.com"
echo

How can I get http request body

You can read the request body from stdin. If you’re using shell, cat can
quickly save request body to a file.

How can send file to the client

For small files, you can write file to stdout directly.

For large files, it’s much better to send a 302 response. Because CGI response
is streaming, protocol cannot easily handle caching, chunked downloads, or
resume support.

I want to write CGI with python, ruby, perl, C, C++…

Go for it. Nginx-cgi don’t care what language you use. Just grabs information
from environment var, and read request body from stdin, and write output to
stdout.

Manual

Options

cgi or cgi pass [script_args...]

Enable or disable cgi module on giving location block.

Alias of cgi pass .

Set interpreter and interpreter args for cgi script.

When this option is not empty, cgi script will be run with giving interpreter.
Otherwise, script will be executed directly.

This option can contains nginx variables, see
https://nginx.org/en/docs/varindex.html for more details.

This option is extremely useful in a lot of senarios, for example:

• run CGI scripts missing x-perm
• do sudo before executing CGI script
• wrap general binary as CGI script
• filter CGI script output
• …

Default: empty

cgi_working_dir

Set the working directory of CGI script.

A standard CGI script should output two parts: header and body. And an empty
line to split those two parts.

Change cgi script PATH environment variable.

Enable or disable strict mode.

Add and pass extra environment variables to CGI script. The first argument of
this command is the name of environment variable. It should contains only
alphabets, numbers and underscore, and doesn’t start with number. The second
argument of this command is the value express of the var. It can contains nginx
variables, see https://nginx.org/en/docs/varindex.html for more details.

This option can appears more than 1 time to set multiple variables. If more than
one option set the same var, then the last one works. These directives are
inherited from the previous configuration level if and only if there’s no
cgi_set_var directives defined on the current level.

This option can also be used to override standard CGI vars. This may be useful
in some case, for example hacking old CGI script or simulate standard vars that
are not supported by this plugin now (Such as PATH_TRANSLATED,
REMOTE_IDENT). But it’s not recommanded, it may introduce confusing issues to
your system.

cgi_stderr

Redirect cgi stderr to giving file.

Enable or disable reverse dns.

Send TERM/KILL signals to the CGI process if it runs too long.

Nginx-cgi implemented almost all rfc3875 standard variables. If they cannot
cover all of your usage, you can add your own variable by cgi_set_var. Also
those variables can be overrided by cgi_set_var if you really want to.

• AUTH_TYPE, REMOTE_USER (rfc3875 standard)

If cgi script is behind an authorization module (such as
ngx_http_auth_basic_module), and the authorization is succeed, the value is
set to auth type (such as Basic) and authorized user.

If no authorization module enabled, no matter client passes autoriazation header
or not. Those 2 fields are not present.

Authorization header is not visible in cgi script for security reason. If you
really want to do authorization in CGI script, try cgi_set_var.

• CONTENT_LENGTH, CONTENT_TYPE (rfc3875 standard)

Same to request header’s Content-Length and Content-Type.

• GATEWAY_INTERFACE (rfc3875 standard)

Always be CGI/1.1 in this plugin.

• PATH_INFO (rfc3875 standard)

Let’s say if you have a script under /cgi-bin/hello.sh, and you access
http://127.0.0.1/cgi-bin/hello.sh/somewhat.

Then PATH_INFO contains the string /somewhat.

Combination with url rewrite or cgi pass, this variable can be used for
dynamic content generating.

• PATH_TRANSLATED (rfc3875 standard)

Note: this option is not implemented strictly compliant with rfc3875.
Please avoid this, if you are writing new CGI script.

This is related to PATH_INFO.

Let’s say if you have a script under /cgi-bin/hello.sh, and you access
http://127.0.0.1/cgi-bin/hello.sh/somewhat.

The standard says, the server should try again with http://127.0.0.1/somewhat,
and found out where the uri should mapped to.

For technical reason, I just construct this variable by document root and
PATH_INFO.

The behaviour may be changed in future version.

• QUERY_STRING (rfc3875 standard)

Contains the query string of the request. For example, if you are accessing
http://127.0.0.1/cgi-bin/hello.sh?a=1&b=2, QUERY_STRING will contains
a=1&b=2.

• REMOTE_ADDR, (rfc3875 standard)

Client ip address.

• REMOTE_HOST (rfc3875 standard)

Client host name. Only available if cgi_rdns is turns on.

If cgi_rdns is on, nginx-cgi will do a reverse DNS, and find a domain matches
REMOTE_ADDR. If any found, it will be set to REMOTE_HOST.

If cgi_rdns is double, after the RDNS, nginx-cgi will do a forward DNS again.
REMOTE_HOST will only be set if the forward DNS result matches the original
address.

See cgi_rdns for more information.

• REMOTE_IDENT (rfc3875 standard)

Nginx-cgi plugin doesn’t support this for security reason.

• REQUEST_METHOD (rfc3875 standard)

Request method of the request, for example: GET, POST…

• SCRIPT_NAME (rfc3875 standard)

Path to current script. Normally, you don’t need this. It doesn’t contains the
full path. See SCRIPT_FILENAME.

The only reason to use this is construct the URI after rewriting. You can use
SCRIPT_NAME + PATH_INFO to get the URI after rewriting.

• SERVER_NAME (rfc3875 standard)

Server name, normally it equals to Host header without port part. If Host
header doesn’t appear in the request (HTTP/1.0) or contains invalid value, then
this value is set to the reflect server ip address. If the ip address is an ipv6
address, it will be quoted with bracket like [::1].

• SERVER_PORT (rfc3875 standard)

Server listening port, such as 80, 443…

• SERVER_PROTOCOL (rfc3875 standard)

The protocol used between client and server. Such as HTTP/1.0, HTTP/1.1…

• SERVER_SOFTWARE (rfc3875 standard)

Contains a string of nginx and version, such as nginx/1.27.4.

• X_ (rfc3875 standard)

All X- prefixed http request header will be convert to X_ variables. For
example:

If X-a: 123 appears in header, X_A will be set to 123.

• HTTP_ (rfc3875 standard)

All other http request header will be convert to HTTP_ variables, for example:

If Accept: */* appears in header, HTTP_ACCEPT will be set to */*.

• DOCUMENT_ROOT (non-standard, impled by apache2)

Document root of current location block, see root stmt in nginx.

• REMOTE_PORT (non-standard, impled by apache2)

Client port number.

• REQUEST_SCHEME (non-standard, impled by apache2)

http or https.

• REQUEST_URI (non-standard, impled by apache2)

The raw uri before rewriting. If you want the URL after rewriting, try
SCRIPT_NAME + PATH_INFO.

Note: this variable doesn’t same to nginx varible $request_uri. You can find
the document at https://httpd.apache.org/docs/2.4/mod/mod_rewrite.html.

• SCRIPT_FILENAME (non-standard, impled by apache2)

The full path to the CGI script.

• SERVER_ADDR (non-standard, impled by apache2)

Server ip address. If the server has multiple ip addresses. The value of this
variable can be different if requests came from different interfaces.

Known Issues

PATH_TRANSLATED impl not accurate

By rfc3875, PATH_TRANSLATED should point to the file that as if $PATH_INFO
accessed as uri. But that’s really hard to impl on nginx, it need re-trigger
nginx’s location process. And those functions are private, cannot access by
plugin directly. The another way to impl it is starting a sub-request, but it’s
too expensive, and this var is really rearly used. It’s really not worth to do
it. So I simply construct this var by document root and path_info vars.

RDNS impl doesn’t access /etc/hosts

Nginx’s resolver impl doesn’t access /etc/hosts. I don’t want to impl an extra
resolver in plugin. So I just ignore this problem.

Reference

rfc3875

https://datatracker.ietf.org/doc/html/rfc3875

nginx

https://nginx.org/en/docs/dev/development_guide.html
https://hg.nginx.org/nginx-tests

Hop-by-hop headers

https://datatracker.ietf.org/doc/html/rfc2616#section-13.5.1

CGI environments

https://datatracker.ietf.org/doc/html/rfc3875#section-4.1

Apache CGI

https://httpd.apache.org/docs/2.4/howto/cgi.html

Lighttpd CGI

https://redmine.lighttpd.net/projects/lighttpd/wiki/Mod_cgi

License

2-clause BSD license