Awesome
Apogee, a Gemini server
Apogee is a server for the Gemini protocol, written in Kotlin.
Features
Apogee currently has support for the following features:
- Static file serving.
- Redirections.
- Client authentication.
- CGI and SCGI.
Dependencies
Apogee runs on a JVM, so some implementation is required (it was developed and tested on OpenJDK). Java 8 is the minimum supported version.
Other than that, Apogee depends on the following external libraries:
- Netty to handle socket connections.
- TOML4J to handle configuration file parsing.
- kotlinx-cli to handle command line options.
Apogee has been developed and tested for Linux; Windows is not officially supported, though if you try to run it on Windows and encounter a specific problem please feel free to file an issue.
Installation
Currently, the easiest way to run Apogee is to clone the Git repository:
git clone https://github.com/bunburya/apogee.git
Then, from the cloned directory, run:
./gradlew run --args="--config /path/to/config.toml"
Alternatively, you can build a shell script:
./gradlew build -x test
This builds Apogee without running the tests (some of which are integration tests that depend on an already running
instance). The shell script can be found in the build/distributions directory (in the bin subdirectory of the
directory you get when you extract the zip or tar archive). You can then initialise Apogee using the following command
(make sure the apogee shell script is in your shell path):
apogee --config /path/to/config.toml
Configuration
Apogee is configured through a single TOML file. This section will discuss the main configuration
options. In the src/main/resources directory you will find an example config file, populated with default values
where appropriate.
NOTE: Configuration of certain features, such as redirection, is done via key-value pairs stored in tables, where the keys are regex patterns against which the path is compared. The first pattern which matches the path will be used to determine the appropriate value. Tables in TOML files are not guaranteed to be in any particular order. Therefore, you should be careful to ensure that patterns are mutually exclusive, as there is no guarantee as to what order they will be checked.
Basic settings
These are settings to control the basic behaviour of Apogee.
| Option name | Description | Default value |
|---|---|---|
| PORT | The port on which Apogee will listen for requests. | 1965 |
| HOSTNAME | The name of the host at which Apogee will listen for requests. | localhost |
| CERT_FILE | The location of the file containing the server's SSL certificate, in PEM format. | cert.pem |
| KEY_FILE | The location of the file containing the server's SSL key, in PEM format. | key.pem |
| DOCUMENT_ROOT | The location of the directory containing the files to be served by Apogee. | /var/gemini/ |
| ACCESS_FILE | Where to log access attempts. | null (logs to standard error) |
| LOG_FILE | Where to store general logs. | null (logs to standard error) |
| LOG_LEVEL | How severe a log message must be in order to be logged to LOG_FILE. This should correspond to the levels used by the java.util.logging library, ie, it should be one of "SEVERE", "WARNING", "INFO", "CONFIG", "FINE", "FINER" or "FINEST". | WARNING |
Static files
These settings control certain aspects of how Apogee serves static files.
| Option name | Description | Default value |
|---|---|---|
| GEMINI_EXT | The file extension that Apogee will interpret as indicating the "text/gemini" MIME type. | gmi |
| INDEX_FILE | The name of the file that Apogee will attempt to serve if a request corresponds to a directory. If no index file is present, Apogee will display a basic index which lists files in the directory. | index.gmi |
| DIR_SORT_METHOD | (Not yet implemented) Where Apogee auto-generates an index for a directory, how to sort the files in the directory. | NAME |
The MIME_OVERRIDES section allows you to customise the MIME type that is sent where a filename corresponds to a given
regular expression.
Dynamic content
Apogee currently supports dynamic content through the CGI and SCGI protocols. It is intended to also support FastCGI in the future.
The CGI_TIMEOUT option governs how many seconds Apogee should wait for a response from a process before returning an
error response. It defaults to 10.
The CGI_PATHS option should be an array of filesystem paths to directories. Where a request corresponds to a file in
one of these directories, Apogee will attempt to run that file as a script and return the standard output of that script
to the client.
The SCGI_PATHS section is a table mapping (relative) URL prefixes to filesystem paths to Unix domain sockets. Where a
request contains one of the specified prefixes, it will be encoded according to the SCGI protocol and written to the
relevant socket. It will then listen on the socket and return any output to the client. In the future it is intended to
support network sockets in addition to Unix domain sockets.
Both CGI and SCGI scripts are responsible for sending their own headers (eg, 20 text/gemini\r\n).
The following are the main variables passed to applications over CGI/SCGI:
| Variable name | Description | Protocol |
|---|---|---|
| GATEWAY_INTERFACE | The name of the gateway interface used, followed, if applicable, by a "/" and the version number, eg, CGI/1.1 or SCGI. | CGI/SCGI |
| SERVER_NAME | The hostname of the server on which Apogee is running. | CGI/SCGI |
| SERVER_PORT | The port on which Apogee is listening. | CGI/SCGI |
| SERVER_PROTOCOL | The protocol the server is using - always "GEMINI". | CGI/SCGI |
| SERVER_SOFTWARE | The software running the server - always "APOGEE". | CGI/SCGI |
| REMOTE_ADDR | The IP address from which the request originated. | CGI/SCGI |
| SCRIPT_PATH | The part of the request path corresponding to the relevant script. For CGI, this is the part of the path that corresponds to the CGI script to be run; for SCGI, it corresponds to the prefix specified in the config file. | CGI/SCGI |
| PATH_INFO | The part of the request path after SCRIPT_PATH (excluding any query string). | CGI/SCGI |
| QUERY_STRING | You guessed it - the query string, if any, specified in the request. | CGI/SCGI |
| REQUEST_METHOD | Always an empty string, as Gemini does not support different request methods. | CGI/SCGI |
| TLS_CLIENT_HASH | If a client certificate is provided, the SHA256 hash of that certificate. Not present otherwise. | CGI/SCGI |
| TLS_CLIENT_ISSUER_DN | If a client certificate is provided, the distinguished name of the certificate issuer. Not present otherwise. | CGI/SCGI |
| TLS_CLIENT_SUBJECT_DN | If a client certificate is provided, the distinguished name of the certificate subject. Not present otherwise. | CGI/SCGI |
| AUTH_TYPE | If a client certificate is provided, "Certificate". Not present otherwise. | CGI/SCGI |
| SCGI | Always "1", as required by the SCGI protocol. | SCGI |
| CONTENT_LENGTH | The length of the request body - this will always be 0, as Gemini does not permit request bodies. | SCGI |
Redirects
You can tell Apogee to redirect certain paths using the TEMP_REDIRECTS and PERM_REDIRECTS sections of the config
file. Each entry in these sections should map a regular expression, against which a path will be checked, to the path to
redirect to. Requests matched against entries in the TEMP_REDIRECTS section will receive a temporary redirect
response (status code 30). Requests matched against entries in the PERM_REDIRECTS section will receive a permanent
redirect response (status code 31).
Client authorisation
Apogee has support for client authentication using client-side SSL certificates. The CLIENT_CERT_ZONES section should
be a table mapping regular expressions to lists of supported client certificate SHA256 fingerprints. Client
authentication is done immediately after the request is received by the server, so redirections, dynamic content, etc,
will not be handled unless a request is authenticated (if necessary).
Obligatory security warning
Remember that Apogee is still a work in progress and should not be considered to be completely secure. Use at your own risk. It is your responsibility to ensure that your server, and any scripts called by it, are secure. If you do discover any vulnerabilities or other issues with Apogee, please file an issue.