mirror of
https://code.rocketnine.space/tslocum/twins.git
synced 2024-11-27 13:38:14 +01:00
163 lines
4 KiB
Markdown
163 lines
4 KiB
Markdown
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 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`.
|
|
|
|
# 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/.*\.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
|
|
```
|