An experimental TCP server for the new, under development Gemini Protocol. Learn more about Gemini here.
- A built-in static file server with support for gemini directories and CGI scripts.
- A complete framework for writing robust gemini applications like astrobotany.
- A lean, modern codebase with type hints and black formatting.
- A solid foundation built on top of the twisted asynchronous networking engine.
Requires Python 3.7 or newer.
The latest stable release can be installed from PyPI:
$ pip install jetforceOr, install from source:
$ git clone https://github.com/michael-lazar/jetforce
$ cd jetforce
$ pip install .Or, install into a python virtual environment:
# Create a project directory somewhere
$ mkdir /opt/jetforce
# Activate a virtual environment and install jetforce
$ python3 -m virtualenv /opt/jetforce/venv
$ source /opt/jetforce/venv/bin/activate
$ pip install jetforce
# The launch script will be installed here
$ /opt/jetforce/venv/bin/jetforceUse the --help flag to view command-line options:
usage: jetforce [-h] [-V] [--host HOST] [--port PORT] [--hostname HOSTNAME]
[--tls-certfile FILE] [--tls-keyfile FILE] [--tls-cafile FILE]
[--tls-capath DIR] [--dir DIR] [--cgi-dir DIR] [--index-file FILE]
[--default-lang DEFAULT_LANG] [--rate-limit RATE_LIMIT]
An Experimental Gemini Protocol Server
optional arguments:
-h, --help show this help message and exit
-V, --version show program's version number and exit
server configuration:
--host HOST Server address to bind to (default: 127.0.0.1)
--port PORT Server port to bind to (default: 1965)
--hostname HOSTNAME Server hostname (default: localhost)
--tls-certfile FILE Server TLS certificate file (default: None)
--tls-keyfile FILE Server TLS private key file (default: None)
--tls-cafile FILE A CA file to use for validating clients (default: None)
--tls-capath DIR A directory containing CA files for validating clients (default:
None)
fileserver configuration:
--dir DIR Root directory on the filesystem to serve (default: /var/gemini)
--cgi-dir DIR CGI script directory, relative to the server's root directory
(default: cgi-bin)
--index-file FILE If a directory contains a file with this name, that file will be
served instead of auto-generating an index page (default: index.gmi)
--default-lang DEFAULT_LANG
A lang parameter that will be used for all text/gemini responses
(default: None)
--rate-limit RATE_LIMIT
Enable IP rate limiting, e.g. '60/5m' (60 requests per 5 minutes)
(default: None)The server's hostname should be set to the DNS name that you expect to receive traffic from. For example, if your jetforce server is running on "gemini://cats.com", you should set the hostname to "cats.com". Any URLs that do not match this hostname will be refused by the server, including URLs that use a direct IP address such as "gemini://174.138.124.169".
IDNs (domain names that contain unicode characters) should be defined using
their ASCII punycode representation. For example, the domain name
café.mozz.us should be represented as --hostname xn--caf-dma.mozz.us.
The server's host should be set to the local socket that you want to bind to:
--host "127.0.0.1"- Accept local connections only--host "0.0.0.0"- Accept remote connections over IPv4--host "::"- Accept remote connections over IPv6--host ""- Accept remote connections over any interface (IPv4 + IPv6)
The gemini specification requires that all connections be sent over TLS.
If you do not provide a TLS certificate file using the --tls-certfile flag,
jetforce will automatically generate a temporary cert for you to use. This is
great for making development easier, but before you expose your server to the
public internet you should setup something more permanent. You can generate
your own self-signed server certificate, or obtain one from a Certificate
Authority like Let's Encrypt.
Here's an example openssl command that you can use to generate a self-signed certificate:
$ openssl req -newkey rsa:2048 -nodes -keyout {hostname}.key \
-nodes -x509 -out {hostname}.crt -subj "/CN={hostname}"
Jetforce also supports TLS client certificates (both self-signed and CA authorised). Requests that are made with client certificates will include additional CGI/environment variables with information about the TLS connection.
You can specify a CA for client validation with the --tls-cafile or --tls-capath
flags. Connections validated by the CA will have the TLS_CLIENT_AUTHORISED environment
variable set to True. Instructions on how to generate CA's are outside of the scope of
this readme, but you can find many helpful tutorials
online.
Jetforce will serve static files in the /var/gemini/ directory by default.
Files ending with *.gmi will be interpreted as the text/gemini type. If
a directory is requested, jetforce will look for a file named index.gmi in that
directory to return. Otherwise, a directory file listing will be automatically
generated.
For the sake of keeping the command line arguments straightforward and easy to understand, configuring virtual hosting is not supported via the command line. However, it is readily available using only a few lines of python and a custom launch script. Check out examples/vhost.py for more information.
Jetforce does not (yet) support virtual hosting at the TLS-layer using SNI.
This means that you cannot return different server TLS certificates for
different domains. The suggested workaround is to use a single certificate with
multiple subjectAltName attributes. There is also an
sni_callback()
hook in the server codebase that can be subclassed to implement custom TLS
behavior.
Jetforce supports a simplified version of CGI scripting. It doesn't exactly follow the RFC 3875 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.
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 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.
| Name | Example Value |
|---|---|
| GATEWAY_INTERFACE | CGI/1.1 (for compatibility with RFC 3875) |
| SERVER_PROTOCOL | GEMINI |
| SERVER_SOFTWARE | jetforce/0.0.7 |
| GEMINI_URL | gemini://mozz.us/cgi-bin/example.cgi/extra?hello%20world |
| SCRIPT_NAME | /cgi-bin/example.cgi |
| PATH_INFO | /extra |
| QUERY_STRING | hello%20world |
| SERVER_NAME | mozz.us |
| SERVER_PORT | 1965 |
| REMOTE_HOST | 10.10.0.2 |
| REMOTE_ADDR | 10.10.0.2 |
| TLS_CIPHER | TLS_AES_256_GCM_SHA384 |
| TLS_VERSION | TLSv1.3 |
Additional CGI variables will be included only when the client connection uses a TLS client certificate:
| Name | Example Value |
|---|---|
| AUTH_TYPE | CERTIFICATE |
| REMOTE_USER | mozz123 (the certificate subject CN attribute) |
| TLS_CLIENT_HASH | SHA256:86341FB480BFE333C343530D75ABF99D1437F69338F36C684C8831B63C993A96 |
| TLS_CLIENT_NOT_BEFORE | 2020-04-05T04:18:22Z |
| TLS_CLIENT_NOT_AFTER | 2021-04-05T04:18:22Z |
| TLS_CLIENT_SERIAL_NUMBER | 73629018972631 |
| TLS_CLIENT_AUTHORISED | 0 (not authorised) / 1 (authorised) † |
† Requires the server to be configured with a CA for validating client certificates.
Jetforce is intended to be run behind a process manager that handles daemonizing the script, redirecting output to system logs, etc. I prefer to use systemd for this because it's installed on my operating system and easy to set up.
Here's how I configure my server over at gemini://mozz.us:
# /etc/systemd/system/jetforce.service
[Unit]
Description=Jetforce Server
[Service]
Type=simple
Restart=always
RestartSec=5
Environment="PYTHONUNBUFFERED=1"
ExecStart=/usr/local/bin/jetforce \
--host 0.0.0.0 \
--port 1965 \
--hostname mozz.us \
--dir /var/gemini \
--tls-certfile /etc/letsencrypt/live/mozz.us/fullchain.pem \
--tls-keyfile /etc/letsencrypt/live/mozz.us/privkey.pem \
--tls-cafile /etc/pki/tls/jetforce_client/ca.cer
[Install]
WantedBy=default.target
--host 0.0.0.0allows the server to accept external connections from any IP address over IPv4.PYTHONUNBUFFERED=1disables bufferingstderrand is sometimes necessary for logging to work.--tls-certfileand--tls-keyfilepoint to my WWW server's Let's Encrypt certificate chain.--tls-cafilepoints to a self-signed CA that I created in order to test accepting client TLS connections.
With this service installed, I can start and stop the server using
systemctl start jetforce
systemctl stop jetforce
And I can view the server logs using
journalctl -u jetforce -f
WARNING
You are exposing a server to the internet. You (yes you!) are responsible for securing your server and setting up appropriate access permissions. This likely means not running jetforce as the root user. Security best practices are outside of the scope of this document and largely depend on your individual threat model.
To view the project's release history, see the CHANGELOG file.
This project is licensed under the Floodgap Free Software License.
The Floodgap Free Software License (FFSL) has one overriding mandate: that software using it, or derivative works based on software that uses it, must be free. By free we mean simply "free as in beer" -- you may put your work into open or closed source packages as you see fit, whether or not you choose to release your changes or updates publicly, but you must not ask any fee for it.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent