twins-upstream/CONFIGURATION.md

This page is also available at gemini://twins.rocketnine.space/configuration.gmi

twins requires a configuration file to operate. It is loaded from ~/.config/twins/config.yaml by default. You may specify a different location via the --config argument.

Configuration options

Listen

Address to listen for connections on in the format of interface:port.

Listen on localhost

localhost:1965

Listen on all interfaces

:1965

Types

Content types may be defined by file extension. When a type is not defined for the requested file extension, content type is detected automatically.

Hosts

Hosts are defined by their hostname followed by one or more paths to serve.

Paths may be defined as fixed strings or regular expressions (starting with ^).

Paths are matched in the order they are defined.

Fixed string paths will match with and without a trailing slash.

When accessing a directory the file index.gemini or index.gmi is served.

When a host is defined with the name default, other hosts and paths will use those values as the default configuration. It is not currently possible to enable an attribute by default and then disable it for individual paths.

Certificates

A certificate and private key must be specified.

localhost certificate

Use openssl generate a certificate for localhost.

openssl req -x509 -out localhost.crt -keyout localhost.key \
  -newkey rsa:2048 -nodes -sha256 \
  -subj '/CN=localhost' -extensions EXT -config <( \
   printf "[dn]\nCN=localhost\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:localhost\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")

Domain certificate

Use certbot to get a certificate from Let's Encrypt for a domain.

certbot certonly --config-dir /home/www/certs \
  --work-dir /home/www/certs \  
  --logs-dir /home/www/certs \
  --webroot \
  -w /home/www/gemini.rocks/public_html \
  -d gemini.rocks \
  -d www.gemini.rocks

Provide the path to the certificate file at certs/live/$DOMAIN/fullchain.pem and the private key file at certs/live/$DOMAIN/privkey.pem to twins.

DisableSize

The size of the response body is included in the media type header by default. Set this option to true to disable this feature. See PROPOSALS.md for more information.

Path

Resources

One resource must be defined for each path.

Root

Serve static files from specified root directory.

Command

Serve output of system command.

When input is requested from the user, it is available as a pseudo-variable $USERINPUT which does not require surrounding quotes. It may be used as an argument to the command, otherwise user input is passed via standard input.

Proxy

Forward requests to Gemini server at specified URL.

Use the pseudo-scheme gemini-insecure:// to disable certificate verification.

Redirect

Redirect requests to specified path or URL.

Attributes

Any number of attributes may be defined for a path.

Cache

Cache duration (in seconds). Set to 0 to disable caching entirely. This is an out-of-spec feature. See PROPOSALS.md for more information.

Hidden

When enabled, hidden files and directories may be accessed. This attribute is disabled by default.

Input

Request text input from user.

SensitiveInput

Request sensitive text input from the user. Text will not be shown as it is entered.

List

When enabled, directories without an index file will serve a list of their contents. This attribute is disabled by default.

Log

Path to log file. Requests are logged in Apache format, excluding IP address and query.

SymLinks

When enabled, symbolic links may be accessed. This attribute is disabled by default.

Type

Content type is normally detected automatically. This attribute forces a specific content type for a path.

FastCGI

Forward requests to FastCGI server at specified address or path.

A Root attribute must also be specified.

Connect via Unix socket:

unix:///var/run/php.sock

Connect via TCP:

tcp://127.0.0.1:9000

End-of-line indicator

The Gemini protocol requires \r\n (CRLF) as the end-of-line indicator. This convention is carried over from protocol specifications first written in the 1970s. This requirement is antithetic to the spirit of Gemini (to improve upon the Finger and Gopher protocols), increasing the complexity of client and server implementations unnecessarily.

In anticipation of an improvement to the Gemini specification, administrators may configure twins to send standard \n (LF) line endings by setting SaneEOL to true.

References: 1 2 3 4

Example config.yaml

# Address to listen on
listen: :1965

# Custom content types
types:
  .json: application/json; charset=UTF-8

# Hosts and paths to serve
hosts:
  default: # Default host configuration
    paths: # Default path attributes
      -
        log: /srv/log/gemini.log
        symlinks: true # Follow symbolic links
  gemini.rocks:
    cert: /srv/gemini.rocks/data/cert.crt
    key: /srv/gemini.rocks/data/cert.key
    paths:
      -
        path: ^/sites/.*\.php$
        root: /home/geminirocks/data
        fastcgi: unix:///var/run/php.sock
      -
        path: /sites
        root: /home/geminirocks/data
        cache: 604800 # Cache for 1 week
        list: true # Enable directory listing
      -
        path: ^/(help|info)$
        root: /home/geminirocks/data/help
      -
        path: ^/proxy-example$
        proxy: gemini://localhost:1966
      -
        path: ^/cmd-example$
        command: uname -a
        cache: 0 # Do not cache
      -
        path: /redir-path-example
        redirect: /other-resource
      -
        path: /redir-url-example
        redirect: gemini://gemini.circumlunar.space/
      -
        path: /
        root: /home/geminirocks/data/home
  twins.rocketnine.space:
    cert: /srv/twins.rocketnine.space/data/cert.crt
    key: /srv/twins.rocketnine.space/data/cert.key
    paths:
      -
        path: /sites
        root: /home/twins/data/sites
      -
        path: /
        root: /home/twins/data/home