Update README.md
This commit is contained in:
Michael Lazar
GitHub
parent
4202e69ff4
commit
15943b4b2a
178
README.md
178
README.md
|
|
@ -121,7 +121,7 @@ a directory is requested, jetforce will look for a file named **index.gmi** in t
|
|||
directory to return. Otherwise, a directory file listing will be automatically
|
||||
generated.
|
||||
|
||||
### CGI Scripts
|
||||
### CGI
|
||||
|
||||
Jetforce supports a simplified version of CGI scripting. It doesn't
|
||||
exactly follow the [RFC 3875](https://tools.ietf.org/html/rfc3875)
|
||||
|
|
@ -130,36 +130,7 @@ specification for CGI, but it gets the job done for the purposes of Gemini.
|
|||
Any executable file placed in the server's ``cgi-bin/`` directory will be
|
||||
considered a CGI script. When a CGI script is requested by a gemini client,
|
||||
the jetforce server will execute the script and pass along information about
|
||||
the request using environment variables:
|
||||
|
||||
| Variable Name | Description | Example |
|
||||
| --- | --- | --- |
|
||||
| GATEWAY_INTERFACE | CGI version (for compatability). | ``GCI/1.1`` |
|
||||
| SERVER_PROTOCOL | The server protocol. | ``GEMINI`` |
|
||||
| SERVER_SOFTWARE | The server version string. | ``jetforce/0.0.7`` |
|
||||
| GEMINI_URL | Raw URL string from the request. | ``gemini://mozz.us/cgi-bin/example.cgi/hello?world``
|
||||
| SCRIPT_NAME | The part of the URL's path that corresponds to the CGI script location. | ``/cgi-bin/example.cgi`` |
|
||||
| PATH_INFO | The remainder of the URL's path after the CGI script location. | ``/hello`` |
|
||||
| QUERY_STRING | The query string portion of the request URL. | ``world`` |
|
||||
| HOSTNAME | Server hostname. | ``mozz.us`` |
|
||||
| SERVER_NAME | Server hostname (alias for HOSTNAME). | ``mozz.us`` |
|
||||
| REMOTE_ADDR | Client IP address. | ``10.10.0.2`` |
|
||||
| REMOTE_HOST | Client IP address (alias for REMOTE_ADDR). | ``10.10.0.2`` |
|
||||
| SERVER_PORT | Server port number. | ``1965`` |
|
||||
| TLS_CIPHER | TLS cipher that was negotiated. | ``TLS_AES_256_GCM_SHA384``|
|
||||
| TLS_VERSION | TLS version that was negotiated. | ``TLSv1.3`` |
|
||||
|
||||
Additional CGI variables will also be included when the connection uses a TLS client certificate:
|
||||
|
||||
| Variable Name | Description | Example |
|
||||
| --- | --- | --- |
|
||||
| AUTH_TYPE | Authentication type (for compatability). | ``CERTIFICATE`` |
|
||||
| REMOTE_USER | The subject CommonName attribute, if provided. | ``michael123`` |
|
||||
| TLS_CLIENT_HASH | A base64-encoded certificate fingerprint. | ``hjQftIC/4zPDQ1MNdav5nRQ39pM482xoTIgxtjyZOpY=`` |
|
||||
| TLS_CLIENT_NOT_BEFORE | Certificate activation date. | ``2020-04-05T04:18:22Z`` |
|
||||
| TLS_CLIENT_NOT_AFTER | Certificate expiration date. | ``2021-04-05T04:18:22Z`` |
|
||||
| TLS_CLIENT_SERIAL_NUMBER | Certificate serial number. | ``73629018972631`` |
|
||||
| TLS_CLIENT_VERIFIED | Was the certificate verified by OpenSSL? | ``0`` (not verified) / ``1`` (verified) |
|
||||
the request using environment variables.
|
||||
|
||||
The CGI script must then write the gemini response to the *stdout* stream.
|
||||
This includes the status code and meta string on the first line, and the
|
||||
|
|
@ -167,6 +138,151 @@ optional response body on subsequent lines. The bytes generated by the
|
|||
CGI script will be forwarded *verbatim* to the gemini client, without any
|
||||
additional modification by the server.
|
||||
|
||||
#### CGI Environment Variables
|
||||
|
||||
<dl>
|
||||
<dt>GATEWAY_INTERFACE</dt>
|
||||
<dd>
|
||||
CGI version (for compatability with RFC 3785).<br>
|
||||
<em>Example: "GCI/1.1"</em>
|
||||
</dd>
|
||||
|
||||
<dt>SERVER_PROTOCOL</dt>
|
||||
<dd>
|
||||
The server protocol.<br>
|
||||
<em>Example: "GEMINI"</em>
|
||||
</dd>
|
||||
|
||||
<dt>SERVER_SOFTWARE</dt>
|
||||
<dd>
|
||||
The server name and version.<br>
|
||||
<em>Example: "jetforce/0.0.7"</em>
|
||||
</dd>
|
||||
|
||||
<dt>GEMINI_URL</dt>
|
||||
<dd>
|
||||
The entire URL that was requested by the client.<br>
|
||||
<em>Example: "gemini://mozz.us/cgi-bin/example.cgi/hello?world"</em>
|
||||
</dd>
|
||||
|
||||
<dt>SCRIPT_NAME</dt>
|
||||
<dd>
|
||||
The part of the URL's path that corresponds to the CGI script location.<br>
|
||||
<em>Example: "/cgi-bin/example.cgi"</em>
|
||||
</dd>
|
||||
|
||||
<dt>PATH_INFO</dt>
|
||||
<dd>
|
||||
The remainder of the URL's path after the SCRIPT_NAME.<br>
|
||||
<em>Example: "/hello"</em>
|
||||
</dd>
|
||||
|
||||
<dt>QUERY_STRING</dt>
|
||||
<dd>
|
||||
The query string portion of the request URL.<br>
|
||||
<em>Example: "world"</em>
|
||||
</dd>
|
||||
|
||||
<dt>HOSTNAME</dt>
|
||||
<dd>
|
||||
The server hostname.<br>
|
||||
<em>Example: "mozz.us"</em>
|
||||
</dd>
|
||||
|
||||
<dt>SERVER_NAME</dt>
|
||||
<dd>
|
||||
The server hostname (alias for HOSTNAME).<br>
|
||||
<em>Example: "mozz.us"</em>
|
||||
</dd>
|
||||
|
||||
<dt>SERVER_PORT</dt>
|
||||
<dd>
|
||||
The server port number.<br>
|
||||
<em>Example: "1965"</em>
|
||||
</dd>
|
||||
|
||||
<dt>REMOTE_HOST</dt>
|
||||
<dd>
|
||||
The client's IP address (alias for REMOTE_ADDR).<br>
|
||||
<em>Example: "10.10.0.2"</em>
|
||||
</dd>
|
||||
|
||||
<dt>REMOTE_ADDR</dt>
|
||||
<dd>
|
||||
The client's IP address.<br>
|
||||
<em>Example: "10.10.0.2"</em>
|
||||
</dd>
|
||||
|
||||
<dt>REMOTE_HOST</dt>
|
||||
<dd>
|
||||
The client's IP address (alias for REMOTE_ADDR).<br>
|
||||
<em>Example: "10.10.0.2"</em>
|
||||
</dd>
|
||||
|
||||
<dt>TLS_CIPHER</dt>
|
||||
<dd>
|
||||
The negotiated TLS cipher<br>
|
||||
<em>Example: "TLS_AES_256_GCM_SHA384"</em>
|
||||
</dd>
|
||||
|
||||
<dt>TLS_VERSION</dt>
|
||||
<dd>
|
||||
The negotiated TLS version.<br>
|
||||
<em>Example: "TLSv1.3"</em>
|
||||
</dd>
|
||||
|
||||
</dl>
|
||||
|
||||
#### CGI Environment Variables - Authenticated
|
||||
|
||||
Additional CGI variables will be included only when the client connection uses a TLS client certificate:
|
||||
|
||||
<dl>
|
||||
|
||||
<dt>AUTH_TYPE</dt>
|
||||
<dd>
|
||||
Authentication type (for compatability with RFC 3785).<br>
|
||||
<em>Example: "CERTIFICATE"</em>
|
||||
</dd>
|
||||
|
||||
<dt>REMOTE_USER</dt>
|
||||
<dd>
|
||||
The certificate's subject CommonName attribute, if provided.<br>
|
||||
<em>Example: "mozz123"</em>
|
||||
</dd>
|
||||
|
||||
<dt>TLS_CLIENT_HASH</dt>
|
||||
<dd>
|
||||
A base64-encoded fingerprint that can be used to uniquely identify the certificate.<br>
|
||||
<em>Example: "hjQftIC/4zPDQ1MNdav5nRQ39pM482xoTIgxtjyZOpY="</em>
|
||||
</dd>
|
||||
|
||||
<dt>TLS_CLIENT_NOT_BEFORE</dt>
|
||||
<dd>
|
||||
The certificate's activation date.<br>
|
||||
<em>Example: "2020-04-05T04:18:22Z"</em>
|
||||
</dd>
|
||||
|
||||
<dt>TLS_CLIENT_NOT_AFTER</dt>
|
||||
<dd>
|
||||
The certificate's activation date.<br>
|
||||
<em>Example: "2021-04-05T04:18:22Z"</em>
|
||||
</dd>
|
||||
|
||||
<dt>TLS_CLIENT_SERIAL_NUMBER</dt>
|
||||
<dd>
|
||||
The certificate's serial number.<br>
|
||||
<em>Example: "73629018972631"</em>
|
||||
</dd>
|
||||
|
||||
<dt>TLS_CLIENT_VERIFIED</dt>
|
||||
<dd>
|
||||
Was the certificate deemed trusted by the server's certificate store.<br>
|
||||
<em>0 (not verified) / 1 (verified)</em>
|
||||
</dd>
|
||||
|
||||
</dl>
|
||||
|
||||
## Deployment
|
||||
|
||||
Jetforce is intended to be run behind a process manager that handles
|
||||
|
|
|
|||
Loading…
Reference in New Issue