3.4 KiB
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.
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 to get a certificate from Let's Encrypt for a domain.
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
# 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