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]+)\.(?Ppng|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 . 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)