twins/CONFIGURATION.md

This page is also available at [gemini://twins.rocketnine.space/configuration.gmi](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`

## 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.

### Certificates

A certificate and private key must be specified.

#### localhost certificate

Use `openssl` generate a certificate for localhost.

```bash
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](https://certbot.eff.org) to get a certificate from [Let's Encrypt](https://letsencrypt.org) for a domain.

```bash
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.

### Path

#### Resources

One resource must be defined for each path.

##### Root

Serve static files from specified root directory.

##### Proxy

Forward requests 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.

##### Type

Content type is normally detected automatically, defaulting to
`text/gemini; charset=utf-8`. This option forces a specific content type.

##### FastCGI

Forward requests to [FastCGI](https://en.wikipedia.org/wiki/FastCGI) server at
specified address or path.

A `Root` attribute must also be specified to use `FastCGI`.

## 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) because it unnecessarily tacks on ancient
baggage. This baggage has caused (and continues to cause) increased complexity in
client and server implementations, which naturally gives rise to more bugs.

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](https://lists.orbitalfox.eu/archives/gemini/2019/000131.html)
[2](https://lists.orbitalfox.eu/archives/gemini/2020/000756.html)
[3](https://lists.orbitalfox.eu/archives/gemini/2020/001339.html) 
[4](https://lists.orbitalfox.eu/archives/gemini/2020/003065.html)

# Example config.yaml

```yaml
# Address to listen on
listen: :1965

# Hosts and paths to serve
hosts:
  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
        listdirectory: true
      -
        path: ^/(help|info)$
        root: /home/geminirocks/data/help
      -
        path: ^/proxy-example$
        proxy: gemini://localhost:1966
      -
        path: ^/cmd-example$
        command: uname -a
      -
        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
```