2020-10-31 00:29:25 +00:00
|
|
|
`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.
|
|
|
|
|
|
|
|
```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.
|
|
|
|
|
|
|
|
## Hosts
|
|
|
|
|
|
|
|
Hosts are defined by their hostname followed by one or more paths to serve.
|
|
|
|
|
2020-10-29 21:58:12 +00:00
|
|
|
Paths may be defined as fixed strings or regular expressions (starting with `^`).
|
|
|
|
|
2020-10-31 00:29:25 +00:00
|
|
|
Paths are matched in the order they are defined.
|
|
|
|
|
2020-10-29 21:58:12 +00:00
|
|
|
Fixed string paths will match with and without a trailing slash.
|
|
|
|
|
2020-10-31 00:29:25 +00:00
|
|
|
When accessing a directory the file `index.gemini` or `index.gmi` is served.
|
|
|
|
|
2020-10-31 05:11:54 +00:00
|
|
|
### Path
|
2020-10-31 00:29:25 +00:00
|
|
|
|
2020-10-31 05:11:54 +00:00
|
|
|
#### Resources
|
2020-10-31 00:29:25 +00:00
|
|
|
|
2020-10-31 05:11:54 +00:00
|
|
|
One resource must be defined for each path.
|
2020-10-31 00:29:25 +00:00
|
|
|
|
2020-10-31 05:11:54 +00:00
|
|
|
##### Root
|
|
|
|
|
|
|
|
Serve static files from specified root directory.
|
2020-10-31 01:31:13 +00:00
|
|
|
|
2020-10-31 05:11:54 +00:00
|
|
|
##### Proxy
|
2020-10-31 00:29:25 +00:00
|
|
|
|
|
|
|
Forward request to Gemini server at specified URL.
|
|
|
|
|
|
|
|
Use the pseudo-scheme `gemini-insecure://` to disable certificate verification.
|
2020-10-30 20:30:09 +00:00
|
|
|
|
2020-10-31 05:11:54 +00:00
|
|
|
##### Command
|
2020-10-30 00:17:23 +00:00
|
|
|
|
2020-10-31 00:29:25 +00:00
|
|
|
Serve output of system command.
|
2020-10-30 00:17:23 +00:00
|
|
|
|
2020-10-31 05:11:54 +00:00
|
|
|
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.
|
|
|
|
|
2020-10-31 00:29:25 +00:00
|
|
|
# Example config.yaml
|
2020-10-29 20:35:48 +00:00
|
|
|
|
|
|
|
```yaml
|
2020-10-30 20:30:09 +00:00
|
|
|
# Address to listen on
|
2020-10-31 00:29:25 +00:00
|
|
|
listen: :1965
|
2020-10-30 18:19:16 +00:00
|
|
|
|
2020-10-30 20:30:09 +00:00
|
|
|
# TLS certificates
|
|
|
|
certificates:
|
2020-10-29 20:35:48 +00:00
|
|
|
-
|
2020-10-30 20:30:09 +00:00
|
|
|
cert: /home/gemini.rocks/data/cert.crt
|
|
|
|
key: /home/gemini.rocks/data/cert.key
|
|
|
|
|
|
|
|
# Hosts and paths to serve
|
|
|
|
hosts:
|
2020-10-30 20:36:55 +00:00
|
|
|
gemini.rocks:
|
|
|
|
-
|
|
|
|
path: /sites
|
|
|
|
root: /home/gemini.rocks/data/sites
|
2020-10-31 01:31:13 +00:00
|
|
|
listdirectory: true
|
2020-10-30 20:36:55 +00:00
|
|
|
-
|
|
|
|
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
|
2020-10-29 20:35:48 +00:00
|
|
|
```
|