render-docs now builds with spaces instead of tabs. The output is more
closely aligned to the original docs/stargazer.1.txt
---
doc/stargazer.1.txt | 38 +--
doc/stargazer.ini.5.txt | 514 ++++++++++++++++++++--------------------
scripts/render-docs | 19 +-
3 files changed, 294 insertions(+), 277 deletions(-)
diff --git a/doc/stargazer.1.txt b/doc/stargazer.1.txt
index d0003ba..83ae449 100644
--- a/doc/stargazer.1.txt
+++ b/doc/stargazer.1.txt
@@ -1,4 +1,6 @@
-stargazer(1) General Commands Manual stargazer(1)
+stargazer(1) General Commands Manual stargazer(1)
+
+
NAME
stargazer - a gemini server
@@ -8,28 +10,28 @@ SYNOPSIS
ARGS
path
- Specifies an alternate path to read the config file from.
+ Specifies an alternate path to read the config file from.
OPTIONS
-D --debug
- Turn on debug logging. This logs a lot more information
- about the servers operation which is useful for debugging
- problems. This is more verbose then is likely desired for
- normal operation.
+ Turn on debug logging. This logs a lot more information
+ about the servers operation which is useful for debugging
+ problems. This is more verbose then is likely desired for
+ normal operation.
-d --dev
- Start the server in dev mode. Server will server files from
- the current directory over ‘localhost:1965‘. This overrides
- the config file and the -C option.
+ Start the server in dev mode. Server will server files from
+ the current directory over `localhost:1965`. This overrides
+ the config file and the -C option.
--check-config
- Check for config errors and exit.
+ Check for config errors and exit.
-V --version
- Print program version and exit.
+ Print program version and exit.
-h --help
- Print command line argument help.
+ Print command line argument help.
LOGGING
Server errors and other debugging info is printed to stderr in
- an unspecified format. Client request logging is printed to
+ an unspecified format. Client request logging is printed to
stdout, with each of the following fields in order, separated
by a tab character:
@@ -46,8 +48,10 @@ SEE ALSO
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/stargazer@lists.sr.ht.
+ can be found at https://sr.ht/~zethra/stargazer/ and
+ bugs/patches can be submitted by email to
+ ~zethra/stargazer@lists.sr.ht.
+
+
- 1980-01-01 stargazer(1)
+ 2024-07-31 stargazer(1)
diff --git a/doc/stargazer.ini.5.txt b/doc/stargazer.ini.5.txt
index f3bb559..cc23b42 100644
--- a/doc/stargazer.ini.5.txt
+++ b/doc/stargazer.ini.5.txt
@@ -1,115 +1,117 @@
-stargazer.ini(5) File Formats Manual stargazer.ini(5)
+stargazer.ini(5) File Formats Manual stargazer.ini(5)
+
+
NAME
stargazer.ini - configuration file for stargazer(1)
EXAMPLE CONFIG
- listen = 0.0.0.0
+ listen = 0.0.0.0
- [:tls]
- store = /var/lib/gemini/certs
- organiztion = example org
+ [:tls]
+ store = /var/lib/gemini/certs
+ organiztion = example org
- [example.com]
- root = /srv/gemini/example.com
+ [example.com]
+ root = /srv/gemini/example.com
- [example.com˜(.*).cgi(.*)]
- root = /srv/gemini/example.com/cgi-bin
- cgi = on
+ [example.com~(.*).cgi(.*)]
+ root = /srv/gemini/example.com/cgi-bin
+ cgi = on
- An default config file should also be installed at
+ 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,
+ 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
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ Set to false to turn off automatic certificate generation.
regen-certs
- Set to false to turn off automatic regeneration of expired
- certificates.
+ 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.
+ 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
@@ -117,187 +119,188 @@ CONFIGURATION KEYS
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
+ 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/".
+ : 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
+ ~ 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
+ [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
+ 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
+ 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.
+ 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.
+ 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.
+ 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:
+ Example:
- [localhost˜ˆ/([a-zA-Z]+)\.(?P<extension>png|jpg)$]
- root=./root
- rewrite=/images/\1.\{extension}
+ [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.
+ 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".
+ 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.
+ "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.
+ 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.
+ 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.
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.
+ 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 con‐
- tent. The URI exactly as written will be sent to the
- client. Mutually exclusive with most other settings.
+ 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.
+ 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.
+ "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.
+ 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.
+ "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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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
+ 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
+ 3875, but is sufficient for most of the needs of Gemini
servers.
- Set cgi=on for a route configuration to enable CGI for that
+ 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
+ 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
+ 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
+ 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‐
@@ -305,71 +308,65 @@ CGI Support
The following environment variables will be set:
- ┌────────────────────┬──────────────────────┬─────────────────┐
- │ Variable │ Example │ Description │
- ├────────────────────┼──────────────────────┼─────────────────┤
- │ GATEWAY_INTERFACE │ CGI/1.1 │ CGI version │
- ├────────────────────┼──────────────────────┼─────────────────┤
- │ SERVER_PROTOCOL │ GEMINI │ The server pro‐ │
- │ │ │ tocol │
- ├────────────────────┼──────────────────────┼─────────────────┤
- │ SERVER_SOFTWARE │ stargazer/0.1.0 │ The stargazer │
- │ │ │ server name and │
- │ │ │ version │
- ├────────────────────┼──────────────────────┼─────────────────┤
- │ GEMINI_URL │ See [1] │ The URL re‐ │
- │ │ │ quested by the │
- │ │ │ client │
- ├────────────────────┼──────────────────────┼─────────────────┤
- │ SCRIPT_NAME │ /cgi-bin/foo.sh │ The portion of │
- │ │ │ the URL refer‐ │
- │ │ │ ring to the │
- │ │ │ script name. │
- ├────────────────────┼──────────────────────┼─────────────────┤
- │ PATH_INFO │ /bar │ The remainder │
- │ │ │ of the path │
- │ │ │ following │
- │ │ │ 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. │
- └────────────────────┴──────────────────────┴─────────────────┘
-
+ ┌───────────────────┬──────────────────────┬───────────────────┐
+ │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‐
+ [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.
@@ -385,23 +382,22 @@ SCGI Support
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
+ 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
+ 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 │
- └────────────────┴─────────┴──────────────────────────────────┘
-
+ ┌───────────────┬─────────┬────────────────────────────────────┐
+ │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.
@@ -411,8 +407,10 @@ SCGI Support
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/stargazer@lists.sr.ht.
+ can be found at https://sr.ht/~zethra/stargazer/ and
+ bugs/patches can be submitted by email to
+ ~zethra/stargazer@lists.sr.ht.
+
+
- 1980-01-01 stargazer.ini(5)
+ 2024-07-31 stargazer.ini(5)
diff --git a/scripts/render-docs b/scripts/render-docs
index dd337fb..0080119 100755
--- a/scripts/render-docs
+++ b/scripts/render-docs
@@ -1,4 +1,19 @@
#!/bin/sh
-scdoc < doc/stargazer.scd | MANWIDTH=72 man -l - | sed -r "s/\x1B\[([0-9]{1,2}(;[0-9]{1,2})?)?[mGK]//g" | col -b > doc/stargazer.1.txt
-scdoc < doc/stargazer-ini.scd | MANWIDTH=72 man -l - | sed -r "s/\x1B\[([0-9]{1,2}(;[0-9]{1,2})?)?[mGK]//g" | col -b > doc/stargazer.ini.5.txt
+# Explanation:
+# sed changes alignment from left to justified and sets the line width to 70
+# groff renders the output from scdoc into a terminal display format
+# col removes any control sequences and replaces tabs with spaces
+
+scdoc < doc/stargazer.scd \
+ | sed 's/^\.ad l/.ad n\n.ll 70/' \
+ | groff -Tutf8 -t -m mandoc \
+ | col -bx \
+ > doc/stargazer.1.txt
+
+scdoc < doc/stargazer-ini.scd \
+ | sed 's/^\.ad l/.ad n\n.ll 70/' \
+ | groff -Tutf8 -t -m mandoc \
+ | col -bx \
+ > doc/stargazer.ini.5.txt
+
--
2.39.3 (Apple Git-146)