# Local CGI support in Chawan Chawan supports the invocation of CGI scripts locally. This feature can be used in the following way: * All local CGI scripts must be placed in a directory specified in `external.cgi-dir`. Multiple directories can be specified in an array too, and directories specified first have higher precedence. * Then, a CGI script in one of these directories can be executed by visiting the URL `cgi-bin:script-name`. $PATH_INFO and $QUERY_STRING are set as normal, i.e. `cgi-bin:script-name/abcd?defgh=ijkl` will set $PATH_INFO to `/abcd`, and $QUERY_STRING to `defgh=ijkl`. Further notes on processing CGI paths: * The URL must be opaque, so you must not add a double slash after the scheme. e.g. `cgi-bin://script-name` will NOT work, only `cgi-bin:script-name`. * Paths beginning with `/cgi-bin/` or `/$LIB/` are stripped of this segment automatically. So e.g. `file:///cgi-bin/script-name` becomes `cgi-bin:script-name`. * If `extern.w3m-cgi-compat` is true, file: URLs are converted to cgi-bin: URLs if the path name starts with `/cgi-bin/`, `/$LIB/`, or the path of a local CGI script. * Absolute paths are accepted as e.g. `cgi-bin:/path/to/cgi/dir/script-name`. Note however, that this only works if `/path/to/cgi/dir` has already been specified as a CGI directory in `external.cgi-dir`. 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.cgi-dir` is true.) Also, for now Chawan has no equivalent to the W3m-control headers (but this may change in the future). ## Environment variables Chawan sets the following environment variables: * `SERVER_SOFTWARE="Chawan"` * `SERVER_PROTOCOL="HTTP/1.0"` * `SERVER_NAME="localhost"` * `SERVER_PORT="80"` * `REMOTE_HOST="localhost"` * `REMOTE_ADDR="127.0.0.1"` * `GATEWAY_INTERFACE="CGI/1.1"` * `SCRIPT_NAME="/cgi-bin/script-name"` if called with a relative path, and `"/path/to/script/script-name"` if called with an absolute path. * `SCRIPT_FILENAME="/path/to/script/script-name"` * `QUERY_STRING=` the query string (i.e. `URL.search`). Note that this variable is percent-encoded. * `PATH_INFO=` everything after the script's path name, e.g. for `cgi-bin:script-name/abcd/efgh` `"/abcd/efgh"`. Note that this variable is NOT percent-encoded. * `REQUEST_URI="$SCRIPT_NAME/$PATH_INFO?$QUERY_STRING` * `REQUEST_METHOD=` HTTP method used for making the request, e.g. GET or POST * `CONTENT_TYPE=` for POST requests, the Content-Type header. Not set for other request types (e.g. GET). * `CONTENT_LENGTH=` the content length, if $CONTENT_TYPE has been set. * `HTTP_PROXY=` and (lower case) `http_proxy=`: the proxy URL if a proxy has been set and its scheme is either `http` or `https`. * `ALL_PROXY=` if a proxy has been set, the proxy URL. * `HTTP_COOKIE=` if set, the Cookie header. * `HTTP_REFERER=` if set, the Referer header. ## Request body If the request body is not empty, it is streamed into the program through the standard input. NOTE: multipart requests are not implemented yet. This will be fixed in the future. ## 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 "no local-CGI directory configured" error message. Configure a local-CGI directory using `external.cgi-dir`. e.g. you could add this to your config.toml: ```toml [external] cgi-dir = "/usr/local/libexec/chawan/cgi-bin" ``` and then put your script in `/usr/local/libexec/chawan/cgi-bin`. ### 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`). Also, make sure `external.cgi-dir` is set to the directory your script is in. ### My script returns a page saying "Failed to execute script". 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 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?)