twins-upstream/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.

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

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

# TLS certificates
certificates:
  -

# 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
        root: /home/geminirocks/data/sites
        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
```