stargazer.ini(5)

📦
version 1.3.4 · 3 versions
, in alpine 3.24

💅 stargazer.ini(5) — File Formats Manual 🎀

okay bestie so this is stargazer.ini(5), the manual for the config file of stargazer(1). yes it's called a "File Formats Manual" and yes that's very serious of it ✨

🌸 NAME 🌸

stargazer.ini — the configuration file for stargazer(1). that's it. that's the whole name section 💖

🦋 EXAMPLE CONFIG 🦋

okay so here's what a real one looks like, and honestly? it's giving main character energy. copy it, adapt it, live your truth:

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

(and yes, organiztion is spelled like that in the original. do not come for me, I am simply the messenger 🙈)

🫶 also! a default config file should also be installed at /etc/stargazer.ini — so if you're ever lost, that's your safe space.

✨ SYNTAX ✨

okay so stargazer.ini is an INI file. periodt. that means every single line is either:

  • a key/value pair, or
  • a section heading

and that's the whole vibe check 💅

key/value pairs are written as key=value. sections are written as [section]. that's the ✨entire✨ format, she's simple, she's iconic.

- extra white space is generally ignored, so you can space things out however feels right — no need to be weird about it 🌈

booleans, bestie, listen: you can write them as true/false, on/off, or yes/no 🔥 and they're case insensitive, so ON, On, and oN are all literally the same thing. go off. slay. 💀

(more to come, bestie — this was only part one 💜)

💖 CONFIGURATION KEYS 💖

Okay so the meaning of a key lowkey depends on which section it's chillin' in, bestie. Anonymous keys — meaning the ones that show up prior to the first [section] directive — are used to specify parameters for the daemon itself. Sections whose name is prefixed 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 sections is a route that stargazer will serve requests to, and at least one route must be specified, periodt.

🎀 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 presumed. To specify an IPv6 address, enclose it in [], e.g. [::]. Note that IPv6 listeners 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.
  • log-ip — Log client IP addresses in the connection log. Mutually exclusive with log-ip-partial. Off by default.
  • log-ip-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 segments are logged, the rest are zeroed. May be preferable to log-ip to help maintain user privacy. Mutually exclusive with log-ip-partial (yes, the page says that here too — direct quote, no cap). Off by default.
  • request-timeout — Number of seconds to wait for the client to send a complete request. If the timeout is exceeded, 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, stargazer will send and close the connection. Disabled by default (the page literally says “by default default” — keeping the lore).
⚠️ Warning: if this is set, large files and cgi scripts may be cut off before their response finishes.
  • proxy-protocol — Whether or not to expect a proxy protocol header before the tls connection. It is generally used with a reverse proxy in situations where you need to know the real IP address of the client. Off by default.

See the formal specification of proxy protocol:

http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt

🦋 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 required, 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 specified along with the hostname. Stargazer does not support serving 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)]

(That line wrap is exactly how it appears in the page — not me, bestie.)

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 directive 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/example.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 available 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 provide 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 provide a valid charset value. Currently, this parameter is only used when serving static files.
  • mime-override — Override the MIME type of all files served under this route with the specified value. This parameter can only be used when serving static files. This can be used with an exact match route to override the MIME type for a single file.
  • redirect — Send a redirect to this URI instead of serving other content. 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 processes 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. scgi-address must also be set. See “SCGI 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. Otherwise the address value will be treated as a socket address 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 default 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 specified per route. Client certificate must be in the PEM format.

💖 CGI Support 💖

okay so stargazer supports a limited version of CGI, and it's compatible with the Jetforce server. It is not a faithful implementation of RFC 3875, but it's enough for most of the needs of Gemini servers. slay.

Set cgi=on in 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 it must print a Gemini response (including status code and meta) to stdout. no cap.

If a CGI process exceeded the timeout set by cgi-timeout, or if the connection to the client is lost and the CGI process is still running, it will be killed. On *nix systems, the CGI process will receive SIGTERM. If it is still running after 3 seconds it will receive 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.

The following environment variables will be set:

  • GATEWAY_INTERFACE — example: CGI/1.1 — CGI version
  • SERVER_PROTOCOL — example: GEMINI — The server protocol
  • SERVER_SOFTWARE — example: stargazer/0.1.0 — The stargazer server name and version
  • GEMINI_URL — example: See [1] — The URL requested by the client
  • SCRIPT_NAME — example: /cgi-bin/foo.sh — The portion of the URL referring to the script name.
  • PATH_INFO — example: /bar — The remainder of the path following SCRIPT_NAME.
  • QUERY_STRING — example: hello=world — The query string portion of the URL. [3]
  • SERVER_NAME, HOSTNAME — example: example.org — The server host name.
  • SERVER_PORT — example: 1965 — The server port number.
  • REMOTE_HOST, REMOTE_ADDR — example: 10.10.0.2 — The client's IP address.
  • TLS_CLIENT_HASH — example: See [2] — A fingerprint that can be used to uniquely identify the cert.
  • TLS_CLIENT_NOT_BEFORE — example: 2020-10-22T04:31:40Z — The date the client's cert is not valid before. See [4].
  • TLS_CLIENT_NOT_AFTER — example: 2021-10-22T04:31:59Z — The date the client's cert is not valid after. See [4].
  • REMOTE_USER — example: "My cert" — The client cert's issuer field.

Footnotes, bestie:

  • [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, undecoded.
  • [4]: Timestamps are rfc3339 complaint, exact format is unspecified.

The exit status of the script is ignored. periodt.

🌈 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 address can either be a path to a 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 connection 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:

  • CONTENT_LENGTH — example: 0 — Length in bytes of the request body. See [1].
  • SCGI — example: 1 — SCGI Version
  • [1]: Always 0 since gemini doesn't have request bodies but included as it's required by the SCGI protocol.

CGI header that are omitted from SCGI:

  • GATEWAY_INTERFACE

👑 AUTHORS 👑

Maintained by Sashanoraa <sasha@noraa.gay>. Up-to-date sources can be found at https://sr.ht/~zethra/stargazer/ and bugs/patches can be submitted by email to ~zethra/public-inbox@lists.sr.ht with the prefix stargazer.

That's the whole vibe, bestie. This lil page is stargazer.ini(5), dated 2025-11-02. Go off and configure your server 💅✨🦋

📦 where this page comes from