mirror of
https://github.com/omar-polo/gmid.git
synced 2024-09-30 06:21:19 +02:00
205 lines
5.2 KiB
Groff
205 lines
5.2 KiB
Groff
.\" Copyright (c) 2020 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: October 2 2020$
|
|
.Dt GMIND 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm gmid
|
|
.Nd dead simple zero configuration gemini server
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Bk -words
|
|
.Op Fl 6fh
|
|
.Op Fl c Ar cert.pem
|
|
.Op Fl d Ar docs
|
|
.Op Fl k Ar key.pem
|
|
.Op Fl p Ar port
|
|
.Op Fl x Ar cgi-bin
|
|
.Ek
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is a very simple and minimal gemini server that can serve static files
|
|
and execute CGI scripts.
|
|
.Pp
|
|
.Nm
|
|
won't serve files outside the given directory and won't follow
|
|
symlinks.
|
|
Furthermore, on
|
|
.Ox ,
|
|
.Xr pledge 2
|
|
and
|
|
.Xr unveil 2
|
|
are used to ensure that
|
|
.Nm
|
|
dosen't do anything else than read files from the given directory,
|
|
accept network connections and, optionally, execute CGI scripts.
|
|
.Pp
|
|
.Nm
|
|
fully supports IRIs (Internationalized Resource Identifiers, see
|
|
RFC3987).
|
|
.Pp
|
|
It should be noted that
|
|
.Nm
|
|
is very simple in its implementation, and so it may not be appropriate
|
|
for serving sites with lots of users.
|
|
After all, the code is single threaded and use a single process,
|
|
although it can handle multiple clients at the same time.
|
|
.Pp
|
|
If a user request path is a directory,
|
|
.Nm
|
|
will try to serve a
|
|
.Pa index.gmi
|
|
file inside that directory.
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width 12m
|
|
.It Fl 6
|
|
Enable IPv6.
|
|
.It Fl c Ar cert.pem
|
|
The certificate to use, by default is
|
|
.Pa cert.pem .
|
|
.It Fl d Ar docs
|
|
The root directory to serve.
|
|
.Nm
|
|
won't serve any file that is outside that directory.
|
|
By default is
|
|
.Pa docs .
|
|
.It Fl f
|
|
stays and log in the foreground, do not daemonize the process.
|
|
.It Fl h
|
|
Print the usage and exit.
|
|
.It Fl k Ar key.pem
|
|
The key for the certificate, by default is
|
|
.Pa key.pem .
|
|
.It Fl p Ar port
|
|
The port to bind to, by default 1965.
|
|
.It Fl x Ar dir
|
|
Enable execution of CGI scripts inside the given directory (relative
|
|
to the document root.) Cannot be provided more than once.
|
|
.El
|
|
.Sh CGI
|
|
When CGI scripts are enabled for a directory, a request for an
|
|
executable file will execute it and fed its output to the client.
|
|
.Pp
|
|
The CGI scripts will inherit the environment from
|
|
.Nm
|
|
with these additional variables set:
|
|
.Bl -tag -width 18m
|
|
.It Ev SERVER_SOFTWARE
|
|
"gmid"
|
|
.It Ev SERVER_PORT
|
|
"1965"
|
|
.It Ev SCRIPT_NAME
|
|
The (public) path to the script.
|
|
.It Ev SCRIPT_EXECUTABLE
|
|
The full path to the executable.
|
|
.It Ev REQUEST_URI
|
|
The user request (without the query parameters.)
|
|
.It Ev REQUEST_RELATIVE
|
|
The request relative to the script.
|
|
.It Ev QUERY_STRING
|
|
The query parameters.
|
|
.It Ev REMOTE_HOST
|
|
The remote IP address.
|
|
.It Ev REMOTE_ADDR
|
|
The remote IP address.
|
|
.It Ev DOCUMENT_ROOT
|
|
The root directory being served, the one provided with the
|
|
.Ar d
|
|
parameter to
|
|
.Nm
|
|
.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 "ALGO:HASH".
|
|
.El
|
|
.Pp
|
|
Let's say you have a script in
|
|
.Pa /cgi-bin/script
|
|
and the user request is
|
|
.Pa /cgi-bin/script/foo/bar?quux .
|
|
Then
|
|
.Ev SCRIPT_NAME
|
|
will be
|
|
.Pa /cgi-bin/script ,
|
|
.Ev SCRIPT_EXECUTABLE
|
|
will be
|
|
.Pa $DOCUMENT_ROOT/cgi-bin/script ,
|
|
.Ev REQUEST_URI
|
|
will be
|
|
.Pa /cgi-bin/script/foo/bar ,
|
|
.Ev REQUEST_RELATIVE
|
|
will be
|
|
.Pa foo/bar and
|
|
.Ev QUERY_STRING
|
|
will be
|
|
.Ar quux .
|
|
.Sh EXAMPLES
|
|
To quickly getting started
|
|
.Bd -literal -offset indent
|
|
$ # generate a cert and a key
|
|
$ openssl req -x509 -newkey rsa:4096 -keyout key.pem \\
|
|
-out cert.pem -days 365 -nodes
|
|
$ mkdir docs
|
|
$ cat <<EOF > docs/index.gmi
|
|
# Hello world
|
|
test paragraph...
|
|
EOF
|
|
$ gmid -c cert.pem -k key.pem -d docs
|
|
.Ed
|
|
.Pp
|
|
Now you can visit gemini://localhost/ with your preferred gemini
|
|
client.
|
|
.Pp
|
|
To add some CGI scripts, assuming a setup similar to the previous
|
|
example, you can
|
|
.Bd -literal -offset indent
|
|
$ mkdir docs/cgi-bin
|
|
$ cat <<EOF > docs/cgi-bin/hello-world
|
|
#!/bin/sh
|
|
printf "20 text/plain\\r\\n"
|
|
echo "hello world!"
|
|
EOF
|
|
$ gmid -x cgi-bin
|
|
.Ed
|
|
.Pp
|
|
Note that the argument to the
|
|
.Fl x
|
|
option is
|
|
.Pa cgi-bin
|
|
and not
|
|
.Pa docs/cgi-bin ,
|
|
since it's relative to the document root.
|
|
.Sh ACKNOWLEDGEMENTS
|
|
.Nm
|
|
uses the "Flexible and Economical" UTF-8 decoder written by
|
|
.An Bjoern Hoehrmann .
|
|
.Sh CAVEATS
|
|
.Bl -bullet
|
|
.It
|
|
it doesn't support virtual hosts: the host part of the request URL is
|
|
completely ignored.
|
|
.It
|
|
a %2F sequence in the path part is indistinguishable from a literal
|
|
slash: this is not RFC3986-compliant.
|
|
.It
|
|
a %00 sequence either in the path or in the query part is treated as
|
|
invalid character and thus rejected.
|
|
.El
|