Index News Docs Issues Source

Local CGI support in Chawan

Chawan supports the invocation of CGI scripts locally. This feature can be used in the following way:

Further notes on processing CGI paths:

Note that this is different from w3m’s cgi-bin functionality, in that we use a custom scheme for local CGI instead of interpreting all requests to a designated path as a CGI request. (This incompatibility is bridged over when external.w3m-cgi-compat is true.)

Headers

Local CGI scripts may send some headers that Chawan will interpret specially (and thus will not pass forward to e.g. the fetch API, etc):

Note that these headers MUST be sent before any regular headers. Headers received after a regular header or a Cha-Control: ControlDone header will be treated as regular headers.

The Cha-Control header’s value is parsed as follows:

Cha-Control-Value = Command *Parameter
Command = ALPHA *ALPHA
Parameter = SPACE *CHAR

In other words, it is Command [Param1] [Param2] ....

Currently available commands are:

Following is a list of error codes and their string counterparts. CGI scripts may use either (but not both) in a ConnectionError header.

Environment variables

Chawan sets the following environment variables:

For requests originating from a urimethodmap rewrite, Chawan will also set the parsed URL’s parts as environment variables. Use of these is highly encouraged, to avoid exploits originating from double-parsing of URLs.

e.g. if example://username:password@example.org:1234/path/name.html?example is the original URL, then:

Note: the fragment part is omitted intentionally.

Request body

If the request body is not empty, it is streamed into the program through the standard input.

Note that this may be both an application/x-www-form-urlencoded or a multipart/form-data request; CONTENT_TYPE stores information about the request type, and in case of a multipart request, the boundary as well.

Tools

Chawan provides certain helper binaries that may be useful for CGI scripts. These can be portably accessed by executing "$CHA_LIBEXEC_DIR"/[program name].

Currently, the following tools are available:

Troubleshooting

Note that standard error is redirected to the browser console (by default, M-cM-c). This makes it easy to debug a misbehaving CGI script, but may also slow down the browser in case of excessive logging. If this is not the desired behavior, we recommend wrapping your script into a shell script that redirects stderr to /dev/null.

My script is returning a “Failed to execute script” error message.

This means the execl call to the script failed. Make sure that your CGI script’s executable bit is set, i.e. run chmod +x /path/to/cgi/script.

My script is returning an “invalid CGI path” error message.

Make sure that you did not include leading slashes. Reminder: cgi-bin://script-name does not work, use cgi-bin:script-name.

My script is returning a “CGI file not found” error message.

Double check that your CGI script is in the correct location. Also, make sure that you are not accidentally calling the script with an absolute path via cgi-bin:/script-name (instead of the correct cgi-bin:script-name).

It is also possible that external.cgi-dir is not really set to the directory your script is in. Note that by default, this depends on the binary’s path, so e.g. if your binary is in ~/src/chawan/target/release/bin/cha, but you put your CGI script to /usr/local/libexec/chawan/cgi-bin, then it will not work.

My script is returning a “failed to set up CGI script” error message.

This means that either pipe or fork failed. Something strange is going on with your system; we recommend exorcism. (Maybe you are running out of memory?)