💾 Archived View for sashanoraa.gay › stargazer.ini.5.txt captured on 2023-06-14 at 13:56:30.
⬅️ Previous capture (2022-06-03)
-=-=-=-=-=-=-
stargazer.ini(5) File Formats Manual stargazer.ini(5)
NAME
stargazer.ini - configuration file for stargazer(1)
EXAMPLE CONFIG
listen = 0.0.0.0
[:tls]
store = /var/lib/gemini/certs
organiztion = example org
[example.com]
root = /srv/gemini/example.com
[example.com~(.*).cgi(.*)]
root = /srv/gemini/example.com/cgi-bin
cgi = on
An default config file should also be installed at
/etc/stargazer.ini
SYNTAX
stargazer.ini is an INI file. Each line is either a key/value
pair, or a section heading. Key/value pairs are specified as
key=value, and sections as [section]. Extra white space in gen‐
erally ignored. Boolean values can be written as true/false,
on/off, yes/no, and are case insensitive.
CONFIGURATION KEYS
The meaning of the key depends on the section. Anonymous keys
(prior to the first [section] directive) are used to specify
parameters for the daemon itself. Sections whose name is pre‐
fixed with ":", e.g. [:tls], are sub-categories of the daemon
configuration. Otherwise, section names refer to the hostnames
of domains serviced by the stargazer daemon. Each of these sec‐
tions is a route that stargazer will server requests to. At
least one route must be specified.
ANONYMOUS KEYS
listen
A space-separated list of addresses that the daemon shall
bind to. Each address shall take the format address:port.
If :port is omitted, 1965 (the default Gemini port) is pre‐
sumed. To specify an IPv6 address, enclose it in [], e.g.
[::]. Note that IPv6 listener always have IPV6_V6ONLY set,
so they will only listen on the IPv6 interface and not also
IPv4. If you wish to listen on both, specify both.
Stargazer supports listening on multiple interfaces/ports
but does not support serving different content on different
interfaces/ports. It does support serving different content
on different domains and paths.
connection-logging
Whether or not to log connections to stdout. Disabling this
may increase performance. On by default. Always on if the
debug cli flag is on.
ip-log
Log client IP addresses in the connection log. Mutually ex‐
clusive with ip-log-partial. Off by default.
ip-log-partial
Log partial client IP addresses in the connection log. For
IPv4 addresses only the first 2 octets are logged, the rest
are zeroed. For IPv6 addresses only the first 3 16bit seg‐
ments are logged, the rest are zeroed. May be preferable to
ip-log to help maintain user privacy. Mutually exclusive
with ip-log-partial. Off by default.
request-timeout
Number of seconds to wait for the client to send a complete
request. If the timeout is exceeded the timeout, stargazer
will send `59 Request timeout` and close the connection. 5
seconds by default. Set to 0 to disable.
response-timeout
Number of seconds to wait for the client to send a complete
request and for stargazer to finish sending the response.
If the timeout is exceeded the timeout, stargazer will send
and close the connection. Disabled by default default.
Warning, if this is set, large files and cgi scripts may be
cut off before their response finishes.
TLS KEYS
The following keys are accepted under the [:tls] section:
store
Path to the certificate store on disk. This should be a
persistent directory writable by the daemon. The daemon
manages its own certificates - no user intervention is re‐
quired, except in the case of moving the daemon to another
host, in which case the certificate store must be copied to
the new host.
organization
An optional key used during certificate generation. Fill
this in with the name of the organization responsible for
the host and it will be filled in as the X.509 /O name.
gen-certs
Set to false to turn off automatic certificate generation.
regen-certs
Set to false to turn off automatic regeneration of expired
certificates.
cert-lifetime
Set how long auto-generated certs last before expiring.
Specified as a number followed by y for a number of years,
m for a number of months (a month being 30 days), or d for
a number days. Ex. 5y for 5 years or 30d for 30 days.
ROUTING KEYS
To configure stargazer to service requests, routing keys must
be defined. The name of the configuration section is used to
determine what kinds of requests it configures.
The format of the section name is the hostname to be serviced,
followed by a token which defines the routing strategy, and a
string whose format is specific to each routing strategy. The
token and match string may be omitted (i.e. [hostname] alone),
which implies path routing against "/". A port may not be spec‐
ified along with the hostname. Stargazer does not support serv‐
ing different content on different ports.
: Route by path prefix. The URL path is compared to
"string/".
= Exact match. The URL path must exactly match the string.
~ Regular expression routing. The string is a Rust-compatible
regular expression which is tested against the URL path.
See the docs for the syntax section of the docs for the regex
rust crate for a definition of the regular expression syntax
and features:
https://docs.rs/regex/1.4.2/regex/#syntax
Some example section names and examples of matching paths:
[example.org:/foo] /foo, /foo/bar, /foo/bar/baz
[example.org=/foo.txt] /foo.txt
[example.org~/[a- /foo.png, /bar.webp
z]+\.(png|jpg|webp)]
Routes should be ordered from least to most specific. The
matching algorithm attempts to match the URL against each route
in reverse order, and chooses the first route which matches.
Within each routing section, the following keys are used to
configure how stargazer will respond to matching requests:
root
Configures the path on disk from which files shall be
served for this host. The path component of the URL will be
appended to this value to form the path to files on disk to
serve.
If example.org/foo/bar.txt is requested, and a route is
configured for [example.org:/foo] with the root set to
/srv/gemini, /srv/gemini/foo/bar.txt will be served.
rewrite
If regular expression routing is used, the rewrite direc‐
tive may be used to rewrite the URL path component before
proceeding. The URL will be set to the value of the rewrite
expression. If \N appears in the rewrite value, where N is
a number, that capture group will be substituted for \N. If
\{name} appears, where name is a named capture group, it
will be substituted. Capture group 0 refers to the entire
matched path.
Example:
[localhost~^/([a-zA-Z]+)\.(?P<extension>png|jpg)$]
root=./root
rewrite=/images/\1.\{extension}
This will rewrite a request for /example.png to /images/ex‐
ample.png. This directive will also modify the path of a
redirect URL if used in a redirect route.
index
Configures the name of the index file which shall be served
in the event that a request for this host does not include
the filename part. Defaults to "index.gmi".
auto-index
"on" to enable the auto-index feature, which presents
clients with a list of files in the requested directory
when an index file cannot be found. Off by default. Only
availible for static file routes.
lang
Set this value as the lang parameter for gemini files
served under this route. The lang param will only be set
for text/gemini responses. The Gemini Specification says
that the lang parameter should contain a comma separated
list of language identifier from RFC 4646. Stargazer will
use the lang parameter as given in this config. It is up to
the user to provid a valid list of languages. Currently,
this parameter is only used when serving static files.
charset
Set this value as the charset parameter for text files
served under this route. The lang param will only be set
for text/* responses. If the lang parameter is also set,
then lang will be set instead of charset for text/gemini
responses. The Gemini Specification says that the charset
parameter should be a character set specified in RFC 2046.
Stargazer will use the charset parameter as given in this
config. It is up to the user to provid a valid charset
value. Currently, this parameter is only used when serving
static files.
redirect
Send a redirect to this URI instead of serving other con‐
tent. The URI exactly as written will be sent to the
client. Mutually exclusive with most other settings.
permanent
Send a permanent redirect instead of a temporary redirect.
Requires redirect to be set.
cgi
"on" to enable CGI support. root must also be configured.
See "CGI Support" for details. Mutually exclusive with
auto-index.
cgi-user
Run CGI process as this user and their primary group. Set
to the name of the user. Otherwise process is run as same
user as stargazer, which can be a security issue if the CGI
process is untrusted (not that running untrusted CGI pro‐
cesses is a good idea to begin with). The user stargazer is
run as must be able to setuid the child process to the user
specified.
scgi
"on" to enable SCGI support. scg-address must also be
set.See "SCI Support" for details. root, index, and auto-
index not allowed when scgi is on.
scgi-address
The address of the SCGI server to connect to. If this is a
valid file system path that exists, stargazer will connect
to a Unix domain socket at that path to send requests. Oth‐
erwise the address value will be treated as a socket ad‐
dress and requests will be made over TCP.
cgi-timeout
Maximum amount of time a CGI/SCGI process on this route is
allowed to run. If the timeout is exceeded, stargazer will
send a CGI error to the client and either kill the CGI
process or close the SCGI connection. Values is a whole
number of seconds. By default CGI processes have no timeout
and stargazer will wait indefinitely for them to finish.
cert-path
Path to this certificate for this route, overrides the de‐
fault store path. This is intended to be used for certs not
managed by stargazer. As such stargazer will not attempt to
generate or regenerate these certs. If this is set, key-
path must also be set.
key-path
Path to the key that goes with the cert set by the cert-
path. If this is set, cert-path must also be set.
client-cert
Path to a client certificate that the client must use to
access this route. Only one client certificate may be spec‐
ified per route. Client certificate must be in the PEM for‐
mat.
CGI Support
stargazer supports a limited version of CGI, compatible with
the Jetforce server. It is not a faithful implementation of RFC
3875, but is sufficient for most of the needs of Gemini
servers.
Set cgi=on for a route configuration to enable CGI for that
route and set root to the path where the CGI scripts are found.
If a client requests a script, it will be executed, and must
print a Gemini response (including status code and meta) to
stdout.
If a CGI process exceeded the timeout set by cgi-timeout or if
connection to client is lost and the CGI process is still run‐
ning it will be killed. On *nix systems, the CGI process will
receive a SIGTERM. If it is still running after 3 seconds it
will receive a SIGKILL. On other systems (i.e. Windows) the CGI
process will just be killed. If cgi-timeout is exceeded,
stargazer will send a CGI error message to the gemini client
before closing the connection.
When stargazer exits, any CGI processes that are currently run‐
ning will receive a SIGHUP.
The following environment variables will be set:
┌───────────────────┬──────────────────────┬───────────────────┐
│Variable │ Example │ Description │
├───────────────────┼──────────────────────┼───────────────────┤
│GATEWAY_INTERFACE │ CGI/1.1 │ CGI version │
├───────────────────┼──────────────────────┼───────────────────┤
│SERVER_PROTOCOL │ GEMINI │ The server proto‐ │
│ │ │ col │
├───────────────────┼──────────────────────┼───────────────────┤
│SERVER_SOFTWARE │ stargazer/0.1.0 │ The stargazer │
│ │ │ server name and │
│ │ │ version │
├───────────────────┼──────────────────────┼───────────────────┤
│GEMINI_URL │ See [1] │ The URL requested │
│ │ │ by the client │
├───────────────────┼──────────────────────┼───────────────────┤
│SCRIPT_NAME │ /cgi-bin/foo.sh │ The portion of │
│ │ │ the URL referring │
│ │ │ to the script │
│ │ │ name. │
├───────────────────┼──────────────────────┼───────────────────┤
│PATH_INFO │ /bar │ The remainder of │
│ │ │ the path follow‐ │
│ │ │ ing SCRIPT_NAME. │
├───────────────────┼──────────────────────┼───────────────────┤
│QUERY_STRING │ hello=world │ The query string │
│ │ │ portion of the │
│ │ │ URL. [3] │
├───────────────────┼──────────────────────┼───────────────────┤
│SERVER_NAME, │ example.org │ The server host │
│HOSTNAME │ │ name. │
├───────────────────┼──────────────────────┼───────────────────┤
│SERVER_PORT │ 1965 │ The server port │
│ │ │ number. │
├───────────────────┼──────────────────────┼───────────────────┤
│REMOTE_HOST, RE‐ │ 10.10.0.2 │ The clients IP │
│MOTE_ADDR │ │ address. │
├───────────────────┼──────────────────────┼───────────────────┤
│TLS_CLIENT_HASH │ See [2] │ A fingerprint │
│ │ │ that can be used │
│ │ │ to uniquely iden‐ │
│ │ │ tify the cert. │
├───────────────────┼──────────────────────┼───────────────────┤
│TLS_CLIENT_NOT_BE‐ │ 2020-10-22T04:31:40Z │ The date the │
│FORE │ │ client's cert is │
│ │ │ not valid before. │
│ │ │ See [4]. │
├───────────────────┼──────────────────────┼───────────────────┤
│TLS_CLIENT_NOT_AF‐ │ 2021-10-22T04:31:59Z │ The date the │
│TER │ │ client's cert is │
│ │ │ not valid after. │
│ │ │ See [4]. │
├───────────────────┼──────────────────────┼───────────────────┤
│REMOTE_USER │ "My cert" │ The client cert's │
│ │ │ issuer field. │
└───────────────────┴──────────────────────┴───────────────────┘
[1]: gemini://example.org/cgi-bin/foo.sh/bar?hello=world
[2]: 1flC87yanv8KQ027TrvOOP/kA5yTWn3xLPJ+GxgaNB4=
[3]: stargazer will attempt to percent decode the query string
as UTF-8. If this fails the string will be provided as is, un‐
decoded. [4]: Timestamps are rfc3339 complaint, exact format is
unspecified.
The exit status of the script is ignored.
SCGI Support
stargazer has SCGI support similar to its CGI support. Set
scgi=on for a route configuration to enable SCGI for that route
and set scgi-address to the address of the SCGI server. The ad‐
dress can either be a path to an Unix Domain Socket or the TCP
Socket address. The headers included in the SCGI request match
the CGI parameters list above with a few exceptions.
If the SCGI server doesn't finish responding before cgi-timeout
is exceeded (assuming one is set) stargazer will close the con‐
nection to the SCGI server and send a CGI error to the gemini
client.
If the connection to the gemini client is lost stargazer will
close the connection to the SCGI server.
New headers:
┌───────────────┬─────────┬────────────────────────────────────┐
│Variable │ Example │ Description │
├───────────────┼─────────┼────────────────────────────────────┤
│CONTENT_LENGTH │ 0 │ Length in bytes of the request │
│ │ │ body. See [1]. │
├───────────────┼─────────┼────────────────────────────────────┤
│SCGI │ 1 │ SCGI Version │
└───────────────┴─────────┴────────────────────────────────────┘
[1]: Aways 0 since gemini doesn't have request bodies but in‐
cluded as it's required by the SCGI protocol.
CGI header that are omitted from SCGI:
• GATEWAY_INTERFACE
AUTHORS
Maintained by Ben Aaron Goldberg <ben@benaaron.dev>. Up-to-date
sources can be found at https://sr.ht/~zethra/stargazer/ and
bugs/patches can be submitted by email to
~zethra/stargazer@lists.sr.ht.
2022-05-05 stargazer.ini(5)