3.3 KiB

Raw Blame History

twins requires a configuration file to operate. By default, it is loaded from ~/.config/twins/config.yaml. 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

Certificates

At least one certificate and private key must be specified, as Gemini requires TLS.

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.

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.

Path

Resources

One resource must be defined for each path.

Root

Serve static files from specified root directory.

Proxy

Forward request to Gemini server at specified URL.

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

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.

Attributes

Any number of attributes may be defined for a path.

ListDirectory

Directory listing may be enabled by adding listdirectory: true.

Input

Request text input from user.

SensitiveInput

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

Example config.yaml

# Address to listen on
listen: :1965

# TLS certificates
certificates:
  -
    cert: /home/gemini.rocks/data/cert.crt
    key: /home/gemini.rocks/data/cert.key

# Hosts and paths to serve
hosts:
  gemini.rocks:
    -
      path: /sites
      root: /home/gemini.rocks/data/sites
      listdirectory: true
    -
      path: ^/(help|info)$
      root: /home/gemini.rocks/data/help
    -
      path: ^/proxy-example$
      proxy: gemini://localhost:1966
    -
      path: ^/cmd-example$
      command: uname -a
    -
      path: /
      root: /home/gemini.rocks/data/home
  twins.rocketnine.space:
    -
      path: /sites
      root: /home/twins/data/sites
    -
      path: /
      root: /home/twins/data/home

3.3 KiB Raw Blame History