mirror of https://github.com/omar-polo/gmid.git
move gmid to the eight section of the manual
This commit is contained in:
parent
7f03b52bd6
commit
9b15e4c628
|
@ -11,8 +11,8 @@
|
||||||
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
||||||
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
||||||
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||||
.Dd $Mdocdate: April 7 2022$
|
.Dd September 8, 2022
|
||||||
.Dt GMID 1
|
.Dt GMID 8
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
.Nm gmid
|
.Nm gmid
|
||||||
|
@ -20,19 +20,11 @@
|
||||||
.Sh SYNOPSIS
|
.Sh SYNOPSIS
|
||||||
.Nm
|
.Nm
|
||||||
.Bk -words
|
.Bk -words
|
||||||
.Op Fl fnv
|
.Op Fl fhnVv
|
||||||
.Op Fl c Ar config
|
.Op Fl c Ar config
|
||||||
.Op Fl D Ar macro Ns = Ns Ar value
|
.Op Fl D Ar macro Ns = Ns Ar value
|
||||||
.Op Fl P Ar pidfile
|
.Op Fl P Ar pidfile
|
||||||
.Ek
|
.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
|
.Sh DESCRIPTION
|
||||||
.Nm
|
.Nm
|
||||||
is a simple and minimal gemini server that can serve static files,
|
is a simple and minimal gemini server that can serve static files,
|
||||||
|
@ -47,7 +39,9 @@ rereads the configuration file when it receives
|
||||||
The options are as follows:
|
The options are as follows:
|
||||||
.Bl -tag -width 14m
|
.Bl -tag -width 14m
|
||||||
.It Fl c Ar config
|
.It Fl c Ar config
|
||||||
Specify the configuration file.
|
Specifies the configuration file.
|
||||||
|
The default is
|
||||||
|
.Pa /etc/gmid.conf .
|
||||||
.It Fl D Ar macro Ns = Ns Ar value
|
.It Fl D Ar macro Ns = Ns Ar value
|
||||||
Define
|
Define
|
||||||
.Ar macro
|
.Ar macro
|
||||||
|
@ -59,6 +53,8 @@ Overrides the definition of
|
||||||
in the config file if present.
|
in the config file if present.
|
||||||
.It Fl f
|
.It Fl f
|
||||||
Stays and logs on the foreground.
|
Stays and logs on the foreground.
|
||||||
|
.It Fl h , Fl -help
|
||||||
|
Print the usage and exit.
|
||||||
.It Fl n
|
.It Fl n
|
||||||
Check that the configuration is valid, but don't start the server.
|
Check that the configuration is valid, but don't start the server.
|
||||||
If specified two or more time, dump the configuration in addition to
|
If specified two or more time, dump the configuration in addition to
|
||||||
|
@ -70,46 +66,6 @@ will also act as lock: if another process is holding a lock on that
|
||||||
file,
|
file,
|
||||||
.Nm
|
.Nm
|
||||||
will refuse to start.
|
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
|
.It Fl V , Fl -version
|
||||||
Print the version and exit.
|
Print the version and exit.
|
||||||
.It Fl v
|
.It Fl v
|
||||||
|
@ -117,9 +73,6 @@ Verbose mode.
|
||||||
Multiple
|
Multiple
|
||||||
.Fl v
|
.Fl v
|
||||||
options increase the verbosity.
|
options increase the verbosity.
|
||||||
.It Ar dir
|
|
||||||
The root directory to serve.
|
|
||||||
By default the current working directory is assumed.
|
|
||||||
.El
|
.El
|
||||||
.Sh LOGGING
|
.Sh LOGGING
|
||||||
Messages and requests are logged by
|
Messages and requests are logged by
|
||||||
|
@ -149,14 +102,9 @@ Response status
|
||||||
Response meta
|
Response meta
|
||||||
.El
|
.El
|
||||||
.Sh EXAMPLES
|
.Sh EXAMPLES
|
||||||
Serve the current directory
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
$ gmid .
|
|
||||||
.Ed
|
|
||||||
.Pp
|
|
||||||
To run
|
To run
|
||||||
.Nm
|
.Nm
|
||||||
as a deamon a configuration file and a X.509 certificate must be provided.
|
a configuration file and a X.509 certificate must be provided.
|
||||||
A self-signed certificate, which are commonly used in the Geminispace,
|
A self-signed certificate, which are commonly used in the Geminispace,
|
||||||
can be generated using for e.g.\&
|
can be generated using for e.g.\&
|
||||||
.Xr openssl 1 :
|
.Xr openssl 1 :
|
221
gmid.conf.5
221
gmid.conf.5
|
@ -11,7 +11,7 @@
|
||||||
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
||||||
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
||||||
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||||
.Dd $Mdocdate: April 7 2022$
|
.Dd September 8, 2022
|
||||||
.Dt GMID.CONF 5
|
.Dt GMID.CONF 5
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
|
@ -20,7 +20,7 @@
|
||||||
.Sh DESCRIPTION
|
.Sh DESCRIPTION
|
||||||
.Nm
|
.Nm
|
||||||
is the configuration file format for the
|
is the configuration file format for the
|
||||||
.Xr gmid 1
|
.Xr gmid 8
|
||||||
Gemini server.
|
Gemini server.
|
||||||
.Pp
|
.Pp
|
||||||
The configuration file is divided into three sections:
|
The configuration file is divided into three sections:
|
||||||
|
@ -209,89 +209,6 @@ Path to the certificate to use for this server.
|
||||||
.Ar file
|
.Ar file
|
||||||
should contain a PEM encoded certificate.
|
should contain a PEM encoded certificate.
|
||||||
This option is mandatory.
|
This option is mandatory.
|
||||||
.It Ic cgi Ar path
|
|
||||||
Execute
|
|
||||||
.Sx CGI
|
|
||||||
scripts that matches
|
|
||||||
.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:
|
|
||||||
.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.
|
|
||||||
.It Ev GEMINI_URL
|
|
||||||
The full IRI of the request.
|
|
||||||
.It Ev GEMINI_URL_PATH
|
|
||||||
The path of the request.
|
|
||||||
.It Ev PATH_INFO
|
|
||||||
The portion of the requested path that is derived from the the IRI
|
|
||||||
path hierarchy following the part that identifies the script itself.
|
|
||||||
Can be unset.
|
|
||||||
.It Ev PATH_TRANSLATED
|
|
||||||
Present if and only if
|
|
||||||
.Ev PATH_INFO
|
|
||||||
is set.
|
|
||||||
It represent the translation of the
|
|
||||||
.Ev PATH_INFO .
|
|
||||||
.Nm gmid
|
|
||||||
builds this by appending the
|
|
||||||
.Ev PATH_INFO
|
|
||||||
to the virtual host directory root.
|
|
||||||
.It Ev QUERY_STRING
|
|
||||||
The decoded query string.
|
|
||||||
.It Ev REMOTE_ADDR , Ev REMOTE_HOST
|
|
||||||
Textual representation of the client IP.
|
|
||||||
.It Ev REQUEST_METHOD
|
|
||||||
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.
|
|
||||||
.It Ev SERVER_NAME
|
|
||||||
The name of the server
|
|
||||||
.It Ev SERVER_PORT
|
|
||||||
The port the server is listening on.
|
|
||||||
.It Ev SERVER_PROTOCOL
|
|
||||||
.Dq GEMINI
|
|
||||||
.It Ev SERVER_SOFTWARE
|
|
||||||
The name and version of the server, i.e.
|
|
||||||
.Dq gmid/1.8.4
|
|
||||||
.It Ev AUTH_TYPE
|
|
||||||
The string "Certificate" if the client used a certificate, otherwise
|
|
||||||
unset.
|
|
||||||
.It Ev REMOTE_USER
|
|
||||||
The subject of the client certificate if provided, otherwise unset.
|
|
||||||
.It Ev TLS_CLIENT_ISSUER
|
|
||||||
The is the issuer of the client certificate if provided, otherwise
|
|
||||||
unset.
|
|
||||||
.It Ev TLS_CLIENT_HASH
|
|
||||||
The hash of the client certificate if provided, otherwise unset.
|
|
||||||
The format is
|
|
||||||
.Dq ALGO:HASH .
|
|
||||||
.It Ev TLS_VERSION
|
|
||||||
The TLS version negotiated with the peer.
|
|
||||||
.It Ev TLS_CIPHER
|
|
||||||
The cipher suite negotiated with the peer.
|
|
||||||
.It Ev TLS_CIPHER_STRENGTH
|
|
||||||
The strength in bits for the symmetric cipher that is being used with
|
|
||||||
the peer.
|
|
||||||
.It Ev TLS_CLIENT_NOT_AFTER
|
|
||||||
The time corresponding to the end of the validity period of the peer
|
|
||||||
certificate in the ISO 8601 format
|
|
||||||
.Pq e.g. Dq 2021-02-07T20:17:41Z .
|
|
||||||
.It Ev TLS_CLIENT_NOT_BEFORE
|
|
||||||
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
|
.It Ic default type Ar string
|
||||||
Set the default media type that is used if the media type for a
|
Set the default media type that is used if the media type for a
|
||||||
specified extension is not found.
|
specified extension is not found.
|
||||||
|
@ -299,21 +216,6 @@ If not specified, the
|
||||||
.Ic default type
|
.Ic default type
|
||||||
is set to
|
is set to
|
||||||
.Dq application/octet-stream .
|
.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
|
.It Ic fastcgi Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
|
||||||
Enable
|
Enable
|
||||||
.Sx FastCGI
|
.Sx FastCGI
|
||||||
|
@ -363,8 +265,7 @@ A
|
||||||
.Ic location
|
.Ic location
|
||||||
section may include most of the server configuration rules
|
section may include most of the server configuration rules
|
||||||
except
|
except
|
||||||
.Ic alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key ,
|
.Ic alias , Ic cert , Ic key , Ic location , Ic param No and Ic proxy .
|
||||||
.Ic location , Ic param No and Ic proxy .
|
|
||||||
.It Ic log Ar bool
|
.It Ic log Ar bool
|
||||||
Enable or disable the logging for the current server or location block.
|
Enable or disable the logging for the current server or location block.
|
||||||
.It Ic param Ar name Cm = Ar value
|
.It Ic param Ar name Cm = Ar value
|
||||||
|
@ -373,47 +274,76 @@ Set the param
|
||||||
to
|
to
|
||||||
.Ar value
|
.Ar value
|
||||||
for FastCGI.
|
for FastCGI.
|
||||||
By default the following variables
|
By default the following parameters are defined:
|
||||||
.Pq parameters
|
.Bl -tag -width 24m
|
||||||
are sent, and carry the same semantics as with CGI:
|
.It Ev GATEWAY_INTERFACE
|
||||||
.Pp
|
.Dq CGI/1.1
|
||||||
.Bl -bullet -compact
|
.It Ev GEMINI_DOCUMENT_ROOT
|
||||||
.It
|
The root directory of the virtual host.
|
||||||
GATEWAY_INTERFACE
|
.It Ev GEMINI_SCRIPT_FILENAME
|
||||||
.It
|
Full path to the FastCGI script being executed.
|
||||||
GEMINI_URL_PATH
|
.It Ev GEMINI_URL
|
||||||
.It
|
The full IRI of the request.
|
||||||
QUERY_STRING
|
.It Ev GEMINI_URL_PATH
|
||||||
.It
|
The path of the request.
|
||||||
REMOTE_ADDR
|
.It Ev PATH_INFO
|
||||||
.It
|
The portion of the requested path that is derived from the the IRI
|
||||||
REMOTE_HOST
|
path hierarchy following the part that identifies the script itself.
|
||||||
.It
|
Can be unset.
|
||||||
REQUEST_METHOD
|
.It Ev PATH_TRANSLATED
|
||||||
.It
|
Present if and only if
|
||||||
SERVER_NAME
|
.Ev PATH_INFO
|
||||||
.It
|
is set.
|
||||||
SERVER_PROTOCOL
|
It represent the translation of the
|
||||||
.It
|
.Ev PATH_INFO .
|
||||||
SERVER_SOFTWARE
|
.Nm gmid
|
||||||
.It
|
builds this by appending the
|
||||||
AUTH_TYPE
|
.Ev PATH_INFO
|
||||||
.It
|
to the virtual host directory root.
|
||||||
REMOTE_USER
|
.It Ev QUERY_STRING
|
||||||
.It
|
The decoded query string.
|
||||||
TLS_CLIENT_ISSUER
|
.It Ev REMOTE_ADDR , Ev REMOTE_HOST
|
||||||
.It
|
Textual representation of the client IP.
|
||||||
TLS_CLIENT_HASH
|
.It Ev REQUEST_METHOD
|
||||||
.It
|
This is present only for RFC3875 (CGI) compliance.
|
||||||
TLS_VERSION
|
It's always set to the empty string.
|
||||||
.It
|
.It Ev SCRIPT_NAME
|
||||||
TLS_CIPHER
|
The virtual URI path to the script.
|
||||||
.It
|
.It Ev SERVER_NAME
|
||||||
TLS_CIPHER_STRENGTH
|
The name of the server
|
||||||
.It
|
.It Ev SERVER_PORT
|
||||||
TLS_CLIENT_NOT_BEFORE
|
The port the server is listening on.
|
||||||
.It
|
.It Ev SERVER_PROTOCOL
|
||||||
TLS_CLIENT_NOT_AFTER
|
.Dq GEMINI
|
||||||
|
.It Ev SERVER_SOFTWARE
|
||||||
|
The name and version of the server, i.e.
|
||||||
|
.Dq gmid/1.8.4
|
||||||
|
.It Ev AUTH_TYPE
|
||||||
|
The string "Certificate" if the client used a certificate, otherwise
|
||||||
|
unset.
|
||||||
|
.It Ev REMOTE_USER
|
||||||
|
The subject of the client certificate if provided, otherwise unset.
|
||||||
|
.It Ev TLS_CLIENT_ISSUER
|
||||||
|
The is the issuer of the client certificate if provided, otherwise
|
||||||
|
unset.
|
||||||
|
.It Ev TLS_CLIENT_HASH
|
||||||
|
The hash of the client certificate if provided, otherwise unset.
|
||||||
|
The format is
|
||||||
|
.Dq ALGO:HASH .
|
||||||
|
.It Ev TLS_VERSION
|
||||||
|
The TLS version negotiated with the peer.
|
||||||
|
.It Ev TLS_CIPHER
|
||||||
|
The cipher suite negotiated with the peer.
|
||||||
|
.It Ev TLS_CIPHER_STRENGTH
|
||||||
|
The strength in bits for the symmetric cipher that is being used with
|
||||||
|
the peer.
|
||||||
|
.It Ev TLS_CLIENT_NOT_AFTER
|
||||||
|
The time corresponding to the end of the validity period of the peer
|
||||||
|
certificate in the ISO 8601 format
|
||||||
|
.Pq e.g. Dq 2021-02-07T20:17:41Z .
|
||||||
|
.It Ev TLS_CLIENT_NOT_BEFORE
|
||||||
|
The time corresponding to the start of the validity period of the peer
|
||||||
|
certificate in the ISO 8601 format.
|
||||||
.El
|
.El
|
||||||
.It Ic ocsp Ar file
|
.It Ic ocsp Ar file
|
||||||
Specify an OCSP response to be stapled during TLS handshakes
|
Specify an OCSP response to be stapled during TLS handshakes
|
||||||
|
@ -588,9 +518,6 @@ server "example.it" {
|
||||||
key "/etc/ssl/private/example.it.key"
|
key "/etc/ssl/private/example.it.key"
|
||||||
root "/var/gemini/example.it"
|
root "/var/gemini/example.it"
|
||||||
|
|
||||||
# execute cgi scripts inside "cgi-bin"
|
|
||||||
cgi "/cgi-bin/*"
|
|
||||||
|
|
||||||
# set the language for text/gemini files
|
# set the language for text/gemini files
|
||||||
lang "it"
|
lang "it"
|
||||||
}
|
}
|
||||||
|
@ -623,7 +550,7 @@ server "example.com" {
|
||||||
}
|
}
|
||||||
.Ed
|
.Ed
|
||||||
.Sh SEE ALSO
|
.Sh SEE ALSO
|
||||||
.Xr gmid 1 ,
|
.Xr gmid 8 ,
|
||||||
.Xr slowcgi 8
|
.Xr slowcgi 8
|
||||||
.Sh AUTHORS
|
.Sh AUTHORS
|
||||||
.An -nosplit
|
.An -nosplit
|
||||||
|
|
Loading…
Reference in New Issue