commit - 7f03b52bd61e64f2627fa0891582f981cc215e0d
commit + 9b15e4c62807eda8a248e6df7ac0603a6b9331cc
blob - 3d5673417467d9978f619c0576c7ce2e0a45ec1d (mode 644)
blob + /dev/null
--- gmid.1
+++ /dev/null
-.\" Copyright (c) 2021, 2022 Omar Polo <op@omarpolo.com>
-.\"
-.\" Permission to use, copy, modify, and distribute this software for any
-.\" purpose with or without fee is hereby granted, provided that the above
-.\" copyright notice and this permission notice appear in all copies.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-.Dd $Mdocdate: April 7 2022$
-.Dt GMID 1
-.Os
-.Sh NAME
-.Nm gmid
-.Nd simple and secure Gemini server
-.Sh SYNOPSIS
-.Nm
-.Bk -words
-.Op Fl fnv
-.Op Fl c Ar config
-.Op Fl D Ar macro Ns = Ns Ar value
-.Op Fl P Ar pidfile
-.Ek
-.Nm
-.Bk -words
-.Op Fl 6hVv
-.Op Fl d Ar certs-dir
-.Op Fl H Ar hostname
-.Op Fl p Ar port
-.Op Ar dir
-.Ek
-.Sh DESCRIPTION
-.Nm
-is a simple and minimal gemini server that can serve static files,
-talk to FastCGI applications and act as a gemini reverse proxy.
-It can run without a configuration file with a limited set of features
-available.
-.Pp
-.Nm
-rereads the configuration file when it receives
-.Dv SIGHUP .
-.Pp
-The options are as follows:
-.Bl -tag -width 14m
-.It Fl c Ar config
-Specify the configuration file.
-.It Fl D Ar macro Ns = Ns Ar value
-Define
-.Ar macro
-to be set to
-.Ar value
-on the command line.
-Overrides the definition of
-.Ar macro
-in the config file if present.
-.It Fl f
-Stays and logs on the foreground.
-.It Fl n
-Check that the configuration is valid, but don't start the server.
-If specified two or more time, dump the configuration in addition to
-verify it.
-.It Fl P Ar pidfile
-Write daemon's pid to the given location.
-.Ar pidfile
-will also act as lock: if another process is holding a lock on that
-file,
-.Nm
-will refuse to start.
-.El
-.Pp
-If no configuration file is given,
-.Nm
-runs in
-.Dq config-less mode
-.Pq i.e. runs in the foreground to serve a directory from the shell
-and looks for the following options
-.Bl -tag -width 14m
-.It Fl 6
-Enable IPv6.
-.It Fl d Ar certs-path
-Directory where certificates for the config-less mode are stored.
-By default it is
-.Pa $XDG_DATA_HOME/gmid ,
-i.e.
-.Pa ~/.local/share/gmid .
-.It Fl H Ar hostname
-The hostname
-.Po
-.Ar localhost
-by default
-.Pc .
-Certificates for the given
-.Ar hostname
-are searched inside the
-.Ar certs-dir
-directory given with the
-.Fl d
-option.
-They have the form
-.Pa hostname.cert.pem
-and
-.Pa hostname.key.pem .
-If a certificate or a key doesn't exist for a given hostname, they
-will be generated automatically.
-.It Fl h , Fl -help
-Print the usage and exit.
-.It Fl p Ar port
-The port to listen on, by default 1965.
-.It Fl V , Fl -version
-Print the version and exit.
-.It Fl v
-Verbose mode.
-Multiple
-.Fl v
-options increase the verbosity.
-.It Ar dir
-The root directory to serve.
-By default the current working directory is assumed.
-.El
-.Sh LOGGING
-Messages and requests are logged by
-.Xr syslog 3
-using the
-.Dv DAEMON
-facility or printed on
-.Em stderr .
-.Pp
-Requests are logged with the
-.Dv NOTICE
-severity.
-Each request log entry has the following fields, separated by
-whitespace:
-.Pp
-.Bl -bullet -compact
-.It
-Client IP address and the source port number, separated by a colon
-.It
-.Sy GET
-keyword
-.It
-Request URL
-.It
-Response status
-.It
-Response meta
-.El
-.Sh EXAMPLES
-Serve the current directory
-.Bd -literal -offset indent
-$ gmid .
-.Ed
-.Pp
-To run
-.Nm
-as a deamon a configuration file and a X.509 certificate must be provided.
-A self-signed certificate, which are commonly used in the Geminispace,
-can be generated using for e.g.\&
-.Xr openssl 1 :
-.Bd -literal -offset indent
-# openssl req \-x509 \-newkey rsa:4096 \-nodes \e
- \-keyout /etc/ssl/private/example.com.key \e
- \-out /etc/ssl/example.com.pem \e
- \-days 365 \-subj "/CN=example.com"
-# chmod 600 /etc/ssl/example.com.crt
-# chmod 600 /etc/ssl/private/example.com.key
-.Ed
-.Pp
-Then
-.Nm
-can be started with
-.Bd -literal -offset indent
-# gmid -c /etc/gmid.conf
-.Ed
-.Sh SEE ALSO
-.Xr gmid.conf 5
-.Sh ACKNOWLEDGEMENTS
-.Nm
-uses the
-.Dq Flexible and Economical
-UTF-8 decoder written by
-.An Bjoern Hoehrmann .
-.Sh AUTHORS
-.An -nosplit
-The
-.Nm
-program was written by
-.An Omar Polo Aq Mt op@omarpolo.com .
-.Sh CAVEATS
-.Bl -bullet
-.It
-All the root directories are opened during the daemon startup; if a
-root directory is deleted and then re-created,
-.Nm
-won't be able to serve files inside that directory until a restart.
-This restriction only applies to the root directories and not their
-content.
-.It
-a %2F sequence is indistinguishable from a literal slash: this is not
-RFC3986-compliant.
-.It
-a %00 sequence is treated as invalid character and thus rejected.
-.El
blob - /dev/null
blob + f1581ce87ac48875c3afa110ac2757d7e4bc2b16 (mode 644)
--- /dev/null
+++ gmid.8
+.\" Copyright (c) 2021, 2022 Omar Polo <op@omarpolo.com>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.Dd September 8, 2022
+.Dt GMID 8
+.Os
+.Sh NAME
+.Nm gmid
+.Nd simple and secure Gemini server
+.Sh SYNOPSIS
+.Nm
+.Bk -words
+.Op Fl fhnVv
+.Op Fl c Ar config
+.Op Fl D Ar macro Ns = Ns Ar value
+.Op Fl P Ar pidfile
+.Ek
+.Sh DESCRIPTION
+.Nm
+is a simple and minimal gemini server that can serve static files,
+talk to FastCGI applications and act as a gemini reverse proxy.
+It can run without a configuration file with a limited set of features
+available.
+.Pp
+.Nm
+rereads the configuration file when it receives
+.Dv SIGHUP .
+.Pp
+The options are as follows:
+.Bl -tag -width 14m
+.It Fl c Ar config
+Specifies the configuration file.
+The default is
+.Pa /etc/gmid.conf .
+.It Fl D Ar macro Ns = Ns Ar value
+Define
+.Ar macro
+to be set to
+.Ar value
+on the command line.
+Overrides the definition of
+.Ar macro
+in the config file if present.
+.It Fl f
+Stays and logs on the foreground.
+.It Fl h , Fl -help
+Print the usage and exit.
+.It Fl n
+Check that the configuration is valid, but don't start the server.
+If specified two or more time, dump the configuration in addition to
+verify it.
+.It Fl P Ar pidfile
+Write daemon's pid to the given location.
+.Ar pidfile
+will also act as lock: if another process is holding a lock on that
+file,
+.Nm
+will refuse to start.
+.It Fl V , Fl -version
+Print the version and exit.
+.It Fl v
+Verbose mode.
+Multiple
+.Fl v
+options increase the verbosity.
+.El
+.Sh LOGGING
+Messages and requests are logged by
+.Xr syslog 3
+using the
+.Dv DAEMON
+facility or printed on
+.Em stderr .
+.Pp
+Requests are logged with the
+.Dv NOTICE
+severity.
+Each request log entry has the following fields, separated by
+whitespace:
+.Pp
+.Bl -bullet -compact
+.It
+Client IP address and the source port number, separated by a colon
+.It
+.Sy GET
+keyword
+.It
+Request URL
+.It
+Response status
+.It
+Response meta
+.El
+.Sh EXAMPLES
+To run
+.Nm
+a configuration file and a X.509 certificate must be provided.
+A self-signed certificate, which are commonly used in the Geminispace,
+can be generated using for e.g.\&
+.Xr openssl 1 :
+.Bd -literal -offset indent
+# openssl req \-x509 \-newkey rsa:4096 \-nodes \e
+ \-keyout /etc/ssl/private/example.com.key \e
+ \-out /etc/ssl/example.com.pem \e
+ \-days 365 \-subj "/CN=example.com"
+# chmod 600 /etc/ssl/example.com.crt
+# chmod 600 /etc/ssl/private/example.com.key
+.Ed
+.Pp
+Then
+.Nm
+can be started with
+.Bd -literal -offset indent
+# gmid -c /etc/gmid.conf
+.Ed
+.Sh SEE ALSO
+.Xr gmid.conf 5
+.Sh ACKNOWLEDGEMENTS
+.Nm
+uses the
+.Dq Flexible and Economical
+UTF-8 decoder written by
+.An Bjoern Hoehrmann .
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+program was written by
+.An Omar Polo Aq Mt op@omarpolo.com .
+.Sh CAVEATS
+.Bl -bullet
+.It
+All the root directories are opened during the daemon startup; if a
+root directory is deleted and then re-created,
+.Nm
+won't be able to serve files inside that directory until a restart.
+This restriction only applies to the root directories and not their
+content.
+.It
+a %2F sequence is indistinguishable from a literal slash: this is not
+RFC3986-compliant.
+.It
+a %00 sequence is treated as invalid character and thus rejected.
+.El
blob - cbd16fd34ce9d1e25da04ecbdbec4bf60475e8e3
blob + 59e69537a1893a46092d9822d4160f71daa685b6
--- gmid.conf.5
+++ gmid.conf.5
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-.Dd $Mdocdate: April 7 2022$
+.Dd September 8, 2022
.Dt GMID.CONF 5
.Os
.Sh NAME
.Sh DESCRIPTION
.Nm
is the configuration file format for the
-.Xr gmid 1
+.Xr gmid 8
Gemini server.
.Pp
The configuration file is divided into three sections:
.Ar file
should contain a PEM encoded certificate.
This option is mandatory.
-.It Ic cgi Ar path
-Execute
-.Sx CGI
-scripts that matches
+.It Ic default type Ar string
+Set the default media type that is used if the media type for a
+specified extension is not found.
+If not specified, the
+.Ic default type
+is set to
+.Dq application/octet-stream .
+.It Ic fastcgi Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
+Enable
+.Sx FastCGI
+instead of serving files.
+The
+.Ar socket
+can either be a UNIX-domain socket or a TCP socket.
+If the FastCGI application is listening on a UNIX domain socket,
+.Ar socket
+is a local path name within the
+.Xr chroot 2
+root directory of
+.Nm .
+Otherwise, the
+.Ic tcp
+keyword must be provided and
+.Ar socket
+is interpreted as a hostname or an IP address.
+.Ar port
+can be either a port number or the name of a service enclosed in
+double quotes.
+If not specified defaults to 9000.
+.It Ic index Ar string
+Set the directory index file.
+If not specified, it defaults to
+.Pa index.gmi .
+.It Ic key Ar file
+Specify the private key to use for this server.
+.Ar file
+should contain a PEM encoded private key.
+This option is mandatory.
+.It Ic lang Ar string
+Specify the language tag for the text/gemini content served.
+If not specified, no
+.Dq lang
+parameter will be added in the response.
+.It Ic location Ar path Brq ...
+Specify server configuration rules for a specific location.
.Ar path
-using shell globbing rules.
-.Pp
-The CGI scripts are executed in the directory they reside and inherit
-the environment from
-.Nm gmid
-with these additional variables set:
+argument will be matched against the request path with shell globbing
+rules.
+In case of multiple location statements in the same context, the first
+matching location will be put into effect and the later ones ignored.
+Therefore is advisable to match for more specific paths first and for
+generic ones later on.
+A
+.Ic location
+section may include most of the server configuration rules
+except
+.Ic alias , Ic cert , Ic key , Ic location , Ic param No and Ic proxy .
+.It Ic log Ar bool
+Enable or disable the logging for the current server or location block.
+.It Ic param Ar name Cm = Ar value
+Set the param
+.Ar name
+to
+.Ar value
+for FastCGI.
+By default the following parameters are defined:
.Bl -tag -width 24m
.It Ev GATEWAY_INTERFACE
.Dq CGI/1.1
.It Ev GEMINI_DOCUMENT_ROOT
The root directory of the virtual host.
.It Ev GEMINI_SCRIPT_FILENAME
-Full path to the CGI script being executed.
+Full path to the FastCGI script being executed.
.It Ev GEMINI_URL
The full IRI of the request.
.It Ev GEMINI_URL_PATH
This is present only for RFC3875 (CGI) compliance.
It's always set to the empty string.
.It Ev SCRIPT_NAME
-The part of the
-.Ev GEMINI_URL_PATH
-that identifies the current CGI script.
+The virtual URI path to the script.
.It Ev SERVER_NAME
The name of the server
.It Ev SERVER_PORT
The time corresponding to the start of the validity period of the peer
certificate in the ISO 8601 format.
.El
-.It Ic default type Ar string
-Set the default media type that is used if the media type for a
-specified extension is not found.
-If not specified, the
-.Ic default type
-is set to
-.Dq application/octet-stream .
-.It Ic entrypoint Ar path
-Handle all the requests for the current virtual host using the
-.Sx CGI
-script at
-.Ar path ,
-relative to the current document root.
-.It Ic env Ar name Cm = Ar value
-Set the environment variable
-.Ar name
-to
-.Ar value
-when executing CGI scripts.
-Can be provided more than once.
-.\" don't document the "spawn <prog>" form because it probably won't
-.\" be kept.
-.It Ic fastcgi Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
-Enable
-.Sx FastCGI
-instead of serving files.
-The
-.Ar socket
-can either be a UNIX-domain socket or a TCP socket.
-If the FastCGI application is listening on a UNIX domain socket,
-.Ar socket
-is a local path name within the
-.Xr chroot 2
-root directory of
-.Nm .
-Otherwise, the
-.Ic tcp
-keyword must be provided and
-.Ar socket
-is interpreted as a hostname or an IP address.
-.Ar port
-can be either a port number or the name of a service enclosed in
-double quotes.
-If not specified defaults to 9000.
-.It Ic index Ar string
-Set the directory index file.
-If not specified, it defaults to
-.Pa index.gmi .
-.It Ic key Ar file
-Specify the private key to use for this server.
-.Ar file
-should contain a PEM encoded private key.
-This option is mandatory.
-.It Ic lang Ar string
-Specify the language tag for the text/gemini content served.
-If not specified, no
-.Dq lang
-parameter will be added in the response.
-.It Ic location Ar path Brq ...
-Specify server configuration rules for a specific location.
-.Ar path
-argument will be matched against the request path with shell globbing
-rules.
-In case of multiple location statements in the same context, the first
-matching location will be put into effect and the later ones ignored.
-Therefore is advisable to match for more specific paths first and for
-generic ones later on.
-A
-.Ic location
-section may include most of the server configuration rules
-except
-.Ic alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key ,
-.Ic location , Ic param No and Ic proxy .
-.It Ic log Ar bool
-Enable or disable the logging for the current server or location block.
-.It Ic param Ar name Cm = Ar value
-Set the param
-.Ar name
-to
-.Ar value
-for FastCGI.
-By default the following variables
-.Pq parameters
-are sent, and carry the same semantics as with CGI:
-.Pp
-.Bl -bullet -compact
-.It
-GATEWAY_INTERFACE
-.It
-GEMINI_URL_PATH
-.It
-QUERY_STRING
-.It
-REMOTE_ADDR
-.It
-REMOTE_HOST
-.It
-REQUEST_METHOD
-.It
-SERVER_NAME
-.It
-SERVER_PROTOCOL
-.It
-SERVER_SOFTWARE
-.It
-AUTH_TYPE
-.It
-REMOTE_USER
-.It
-TLS_CLIENT_ISSUER
-.It
-TLS_CLIENT_HASH
-.It
-TLS_VERSION
-.It
-TLS_CIPHER
-.It
-TLS_CIPHER_STRENGTH
-.It
-TLS_CLIENT_NOT_BEFORE
-.It
-TLS_CLIENT_NOT_AFTER
-.El
.It Ic ocsp Ar file
Specify an OCSP response to be stapled during TLS handshakes
with this server.
key "/etc/ssl/private/example.it.key"
root "/var/gemini/example.it"
- # execute cgi scripts inside "cgi-bin"
- cgi "/cgi-bin/*"
-
# set the language for text/gemini files
lang "it"
}
}
.Ed
.Sh SEE ALSO
-.Xr gmid 1 ,
+.Xr gmid 8 ,
.Xr slowcgi 8
.Sh AUTHORS
.An -nosplit
