twins/CONFIGURATION.md

298 lines
8.5 KiB
Markdown
Raw Permalink Normal View History

2020-10-31 23:49:37 +00:00
This page is also available at [gemini://twins.rocketnine.space/configuration.gmi](gemini://twins.rocketnine.space/configuration.gmi)
2020-10-31 16:59:12 +00:00
`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.
2020-10-31 00:29:25 +00:00
# Configuration options
## Listen
Address to listen for connections on in the format of `interface:port`.
2023-05-06 17:49:39 +00:00
### Listen on all addresses (IPv4 and IPv6)
2020-10-31 00:29:25 +00:00
2023-05-06 17:49:39 +00:00
`:1965`
2020-10-31 00:29:25 +00:00
2023-05-06 17:49:39 +00:00
### Listen on a specific address (IPv4 or IPv6)
`192.0.2.1:1965` or `"[2001:db8::1]:1965"` (please note the quotes and brackets
for IPv6 addresses).
2023-05-06 17:49:39 +00:00
### Listen on localhost (IPv4 only)
2020-10-31 00:29:25 +00:00
2023-05-06 17:49:39 +00:00
`localhost:1965`
2020-10-31 00:29:25 +00:00
2020-11-17 19:31:22 +00:00
## Types
Content types may be defined by file extension. When a type is not defined for
the requested file extension, content type is detected automatically.
## ShowImages
When enabled, clients accessing gemini pages via HTTPS will see links to images
as inline images.
## 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 `^`).
Any path not matching a specific page, file name or file extension should end
in a trailing slash, signifying that it is a directory. Visitors are
automatically redirected when accessing a directory path without including a
trailing slash.
Paths are matched in the order they are defined.
When accessing a directory the file `index.gemini` or `index.gmi` is served.
When a host is defined with the name `default`, other hosts and paths will use
those values as the default configuration. It is not currently possible to
enable an attribute by default and then disable it for individual paths.
### Certificates
2020-10-31 00:29:25 +00:00
A certificate and private key must be specified.
2020-10-31 00:29:25 +00:00
2021-06-04 01:05:51 +00:00
#### Self-signed domain certificate (recommended)
Use `openssl` generate a certificate for a domain.
Replace `rocketnine.space` and `twins.rocketnine.space` with your domain and subdomain.
```bash
openssl req -x509 -out localhost.crt -keyout localhost.key \
-newkey rsa:2048 -nodes -sha256 \
-days 36500 \
-subj '/CN=localhost' -extensions EXT -config <( \
printf "[dn]\nCN=rocketnine.space\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:rocketnine.space,DNS:twins.rocketnine.space\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")
```
#### Self-signed localhost certificate
2020-10-31 00:29:25 +00:00
Use `openssl` generate a certificate for localhost.
2021-06-04 01:05:51 +00:00
Some Gemini clients will not accept such a certificate when accessing a server via domain or subdomain.
2020-10-31 00:29:25 +00:00
```bash
openssl req -x509 -out localhost.crt -keyout localhost.key \
-newkey rsa:2048 -nodes -sha256 \
2021-06-04 01:05:51 +00:00
-days 36500 \
2020-10-31 00:29:25 +00:00
-subj '/CN=localhost' -extensions EXT -config <( \
printf "[dn]\nCN=localhost\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:localhost\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")
```
2021-06-04 01:05:51 +00:00
#### Signed certificate from Let's Encrypt
2020-10-31 00:29:25 +00:00
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.
2021-07-10 16:13:39 +00:00
### StyleSheet
Provide the path to a style sheet to serve instead of the default style sheet.
This option only applies when serving HTTPS connections.
### DisableHTTPS
2020-12-03 19:12:13 +00:00
Pages are also available via HTTPS on the same port by default.
Set this option to `true` to disable this feature.
2021-04-08 03:53:11 +00:00
Pages are converted automatically by [gmitohtml](https://code.rocketnine.space/tslocum/gmitohtml).
2020-12-03 19:12:13 +00:00
### DisableSize
The size of the response body is included in the media type header by default.
2020-12-03 19:12:13 +00:00
Set this option to `true` to disable this feature.
2021-04-08 03:53:11 +00:00
See [PROPOSALS.md](https://code.rocketnine.space/tslocum/twins/src/branch/master/PROPOSALS.md) for more information.
### Path
2020-10-31 00:29:25 +00:00
#### Resources
2020-10-31 00:29:25 +00:00
One resource must be defined for each path.
2020-10-31 00:29:25 +00:00
##### Root
Serve static files from specified root directory.
2020-10-31 01:31:13 +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
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.
2020-11-19 17:24:12 +00:00
##### Proxy
Forward requests to Gemini server at specified URL.
Use the pseudo-scheme `gemini-insecure://` to disable certificate verification.
##### Redirect
Redirect requests to specified path or URL.
#### Attributes
Any number of attributes may be defined for a path.
2020-11-10 04:10:53 +00:00
##### Cache
Cache duration (in seconds). Set to `0` to disable caching entirely. This is an
2021-04-08 03:53:11 +00:00
out-of-spec feature. See [PROPOSALS.md](https://code.rocketnine.space/tslocum/twins/src/branch/master/PROPOSALS.md)
2020-11-10 04:10:53 +00:00
for more information.
2020-12-03 19:12:13 +00:00
##### FastCGI
Forward requests to [FastCGI](https://en.wikipedia.org/wiki/FastCGI) server at
specified address or path. A `Root` attribute must also be specified.
2020-12-03 19:12:13 +00:00
When a client certificate is provided with a request, the SHA-1 hash of the
first certificate is available as `$_SERVER['CLIENT_CERT_A']`. If a second
certificate is provided, it is available as `$_SERVER['CLIENT_CERT_B']`, and so
on.
2020-12-03 19:12:13 +00:00
Connect via Unix socket:
```
unix:///var/run/php.sock
```
Connect via TCP:
```
tcp://127.0.0.1:9000
```
2020-11-19 16:57:28 +00:00
##### Hidden
2020-11-12 17:56:59 +00:00
2020-11-19 16:57:28 +00:00
When enabled, hidden files and directories may be accessed. This attribute is
disabled by default.
2020-11-12 17:56:59 +00:00
2020-11-19 16:57:28 +00:00
##### Input
2020-11-19 16:57:28 +00:00
Request text input from user.
2020-12-03 19:12:13 +00:00
##### Lang
2020-12-03 19:12:13 +00:00
Specifies content language. This is sent to clients via the MIME type `lang` parameter.
2020-11-16 17:17:42 +00:00
##### List
2020-11-16 17:17:42 +00:00
When enabled, directories without an index file will serve a list of their
contents. This attribute is disabled by default.
2020-11-19 16:57:28 +00:00
##### Log
2020-11-19 16:57:28 +00:00
Path to log file. Requests are logged in [Apache format](https://httpd.apache.org/docs/2.2/logs.html#combined),
excluding IP address and query.
2020-12-03 19:12:13 +00:00
##### SensitiveInput
Request sensitive text input from the user. Text will not be shown as it is entered.
2020-11-19 16:57:28 +00:00
##### SymLinks
2020-11-19 16:57:28 +00:00
When enabled, symbolic links may be accessed. This attribute is disabled by default.
2020-11-04 20:48:55 +00:00
##### Type
Content type is normally detected automatically. This attribute forces a
specific content type for a path.
2020-11-04 20:48:55 +00:00
2020-11-05 20:57:28 +00:00
## 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
2020-11-10 04:10:53 +00:00
upon the Finger and Gopher protocols), increasing the complexity of client and
server implementations unnecessarily.
2020-11-05 20:57:28 +00:00
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)
2020-11-09 21:59:30 +00:00
[3](https://lists.orbitalfox.eu/archives/gemini/2020/001339.html)
2020-11-05 20:57:28 +00:00
[4](https://lists.orbitalfox.eu/archives/gemini/2020/003065.html)
2020-10-31 00:29:25 +00:00
# Example config.yaml
2020-10-29 20:35:48 +00:00
```yaml
# Address to listen on
2020-10-31 00:29:25 +00:00
listen: :1965
2020-11-17 19:31:22 +00:00
# Custom content types
types:
.json: application/json; charset=UTF-8
.js: application/javascript; charset=UTF-8
2020-11-17 19:31:22 +00:00
# Hosts and paths to serve
hosts:
default: # Default host configuration
paths: # Default path attributes
-
2020-12-02 18:29:23 +00:00
lang: en
2020-11-12 17:56:59 +00:00
log: /srv/log/gemini.log
symlinks: true # Follow symbolic links
2020-10-30 20:36:55 +00:00
gemini.rocks:
cert: /srv/gemini.rocks/data/cert.crt
key: /srv/gemini.rocks/data/cert.key
2021-07-10 16:13:39 +00:00
stylesheet: /srv/gemini.rocks/style.css
paths:
2020-11-04 20:48:55 +00:00
-
2020-12-04 00:45:20 +00:00
path: ^/.*\.php$
root: /home/geminirocks/public_html
2020-11-04 20:48:55 +00:00
fastcgi: unix:///var/run/php.sock
-
path: /files/
2020-12-04 00:45:20 +00:00
root: /home/geminirocks/files
2020-11-10 04:10:53 +00:00
cache: 604800 # Cache for 1 week
2020-11-16 17:17:42 +00:00
list: true # Enable directory listing
-
path: ^/(help|info)/$
2020-12-04 00:45:20 +00:00
root: /home/geminirocks/docs/help
-
path: /proxy-example/
proxy: gemini://localhost:1966
-
path: /cmd-example
command: uname -a
2020-11-10 04:10:53 +00:00
cache: 0 # Do not cache
-
path: /
2020-12-04 00:45:20 +00:00
root: /home/geminirocks/public_html
2020-10-30 20:36:55 +00:00
twins.rocketnine.space:
cert: /srv/twins.rocketnine.space/data/cert.crt
key: /srv/twins.rocketnine.space/data/cert.key
paths:
-
2020-12-04 00:45:20 +00:00
path: /redir-path-example
redirect: /other-resource
-
path: /redir-url-example
redirect: gemini://gemini.circumlunar.space/
-
path: /
2020-12-04 00:45:20 +00:00
root: /home/twins/public_html
2020-10-31 16:59:12 +00:00
```