waldek
/
jetforce
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update README.md

This commit is contained in:
Michael Lazar 2020-05-29 14:14:52 -04:00 committed by GitHub
parent 4202e69ff4
commit 15943b4b2a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 147 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
README.md
View File

@ -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 directory to return. Otherwise, a directory file listing will be automatically
generated. generated.
### CGI Scripts ### CGI
Jetforce supports a simplified version of CGI scripting. It doesn't Jetforce supports a simplified version of CGI scripting. It doesn't
exactly follow the [RFC 3875](https://tools.ietf.org/html/rfc3875) 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 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, 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 jetforce server will execute the script and pass along information about
the request using environment variables: 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 CGI script must then write the gemini response to the *stdout* stream. 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 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 CGI script will be forwarded *verbatim* to the gemini client, without any
additional modification by the server. 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 ## Deployment
Jetforce is intended to be run behind a process manager that handles Jetforce is intended to be run behind a process manager that handles