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)
|
2023-05-03 12:22:19 +00:00
|
|
|
|
2023-05-04 07:23:31 +00:00
|
|
|
`192.0.2.1:1965` or `"[2001:db8::1]:1965"` (please note the quotes and brackets
|
|
|
|
for IPv6 addresses).
|
2023-05-03 12:22:19 +00:00
|
|
|
|
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.
|
|
|
|
|
2021-07-23 03:00:50 +00:00
|
|
|
## ShowImages
|
|
|
|
|
|
|
|
When enabled, clients accessing gemini pages via HTTPS will see links to images
|
|
|
|
as inline images.
|
|
|
|
|
2020-10-31 21:59:44 +00:00
|
|
|
## 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 `^`).
|
|
|
|
|
2020-12-06 06:49:53 +00:00
|
|
|
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.
|
2020-10-31 21:59:44 +00:00
|
|
|
|
2020-12-06 06:49:53 +00:00
|
|
|
Paths are matched in the order they are defined.
|
2020-10-31 21:59:44 +00:00
|
|
|
|
|
|
|
When accessing a directory the file `index.gemini` or `index.gmi` is served.
|
|
|
|
|
2020-11-10 20:05:42 +00:00
|
|
|
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.
|
|
|
|
|
2020-10-31 21:59:44 +00:00
|
|
|
### Certificates
|
2020-10-31 00:29:25 +00:00
|
|
|
|
2020-10-31 21:59:44 +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
|
|
|
|
2020-11-05 04:41:11 +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.
|
2020-11-05 04:41:11 +00:00
|
|
|
|
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
|
|
|
##### 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.
|
|
|
|
|
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.
|
|
|
|
|
2020-10-31 05:11:54 +00:00
|
|
|
#### 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
|
2020-12-15 22:02:25 +00:00
|
|
|
specified address or path. A `Root` attribute must also be specified.
|
2020-12-03 19:12:13 +00:00
|
|
|
|
2020-12-15 22:02:25 +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-10 17:59:35 +00:00
|
|
|
|
2020-11-19 16:57:28 +00:00
|
|
|
Request text input from user.
|
2020-11-10 17:59:35 +00:00
|
|
|
|
2020-12-03 19:12:13 +00:00
|
|
|
##### Lang
|
2020-11-10 17:42:32 +00:00
|
|
|
|
2020-12-03 19:12:13 +00:00
|
|
|
Specifies content language. This is sent to clients via the MIME type `lang` parameter.
|
2020-11-10 17:42:32 +00:00
|
|
|
|
2020-11-16 17:17:42 +00:00
|
|
|
##### List
|
2020-10-31 05:11:54 +00:00
|
|
|
|
2020-11-16 17:17:42 +00:00
|
|
|
When enabled, directories without an index file will serve a list of their
|
2020-11-10 17:42:32 +00:00
|
|
|
contents. This attribute is disabled by default.
|
2020-10-31 05:11:54 +00:00
|
|
|
|
2020-11-19 16:57:28 +00:00
|
|
|
##### Log
|
2020-10-31 05:11:54 +00:00
|
|
|
|
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-10-31 05:11:54 +00:00
|
|
|
|
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-10-31 05:11:54 +00:00
|
|
|
|
2020-11-19 16:57:28 +00:00
|
|
|
When enabled, symbolic links may be accessed. This attribute is disabled by default.
|
2020-10-31 05:11:54 +00:00
|
|
|
|
2020-11-04 20:48:55 +00:00
|
|
|
##### Type
|
|
|
|
|
2020-11-10 17:42:32 +00:00
|
|
|
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
|
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-11-17 19:31:22 +00:00
|
|
|
# Custom content types
|
|
|
|
types:
|
|
|
|
.json: application/json; charset=UTF-8
|
2021-07-23 02:49:24 +00:00
|
|
|
.js: application/javascript; charset=UTF-8
|
2020-11-17 19:31:22 +00:00
|
|
|
|
2020-10-30 20:30:09 +00:00
|
|
|
# Hosts and paths to serve
|
|
|
|
hosts:
|
2020-11-10 20:05:42 +00:00
|
|
|
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
|
2020-11-10 20:05:42 +00:00
|
|
|
symlinks: true # Follow symbolic links
|
2020-10-30 20:36:55 +00:00
|
|
|
gemini.rocks:
|
2020-10-31 21:59:44 +00:00
|
|
|
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
|
2020-10-31 21:59:44 +00:00
|
|
|
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
|
2020-10-31 21:59:44 +00:00
|
|
|
-
|
2020-12-06 06:49:53 +00:00
|
|
|
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
|
2020-10-31 21:59:44 +00:00
|
|
|
-
|
2020-12-06 06:49:53 +00:00
|
|
|
path: ^/(help|info)/$
|
2020-12-04 00:45:20 +00:00
|
|
|
root: /home/geminirocks/docs/help
|
2020-10-31 21:59:44 +00:00
|
|
|
-
|
2020-12-06 06:49:53 +00:00
|
|
|
path: /proxy-example/
|
2020-10-31 21:59:44 +00:00
|
|
|
proxy: gemini://localhost:1966
|
|
|
|
-
|
2020-12-06 06:49:53 +00:00
|
|
|
path: /cmd-example
|
2020-10-31 21:59:44 +00:00
|
|
|
command: uname -a
|
2020-11-10 04:10:53 +00:00
|
|
|
cache: 0 # Do not cache
|
2020-10-31 21:59:44 +00:00
|
|
|
-
|
|
|
|
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:
|
2020-10-31 21:59:44 +00:00
|
|
|
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/
|
2020-10-31 21:59:44 +00:00
|
|
|
-
|
|
|
|
path: /
|
2020-12-04 00:45:20 +00:00
|
|
|
root: /home/twins/public_html
|
2020-10-31 16:59:12 +00:00
|
|
|
```
|