6.1 KiB
This page is also available at 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.
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
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.
DisableSize
The size of the response body is included in the media type header by default.
Set this option to true
to disable this feature. See PROPOSALS.md
for more information.
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.
Cache
Cache duration (in seconds). Set to 0
to disable caching entirely. This is an
out-of-spec feature. See PROPOSALS.md
for more information.
Log
Path to log file. Requests are logged in Apache format, excluding IP address and query.
SymLinks
When enabled, symbolic links may be accessed. This attribute is disabled by default.
HiddenFiles
When enabled, hidden files and directories may be accessed. This attribute is disabled by default.
ListDirectory
When enabled, directories without an index file will serve a list their contents. This attribute is disabled by default.
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. This attribute forces a specific content type for a path.
FastCGI
Forward requests to FastCGI server at specified address or path.
A Root
attribute must also be specified to use FastCGI
.
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
upon the Finger and Gopher protocols), increasing the complexity of client and
server implementations unnecessarily.
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
.
Example config.yaml
# Address to listen on
listen: :1965
# Hosts and paths to serve
hosts:
default: # Default host configuration
paths: # Default path attributes
-
log: /srv/log/gemini.log
symlinks: true # Follow symbolic links
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
cache: 604800 # Cache for 1 week
listdirectory: true
-
path: ^/(help|info)$
root: /home/geminirocks/data/help
-
path: ^/proxy-example$
proxy: gemini://localhost:1966
-
path: ^/cmd-example$
command: uname -a
cache: 0 # Do not cache
-
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