gmid/gmid.1

158 lines
4.1 KiB
Groff
Raw Normal View History

2020-10-02 19:39:00 +02:00
.\" 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
2020-10-03 17:49:09 +02:00
.Nd dead simple zero configuration gemini server
2020-10-02 19:39:00 +02:00
.Sh SYNOPSIS
.Nm
.Bk -words
2020-11-06 18:11:45 +01:00
.Op Fl h
2020-10-02 19:39:00 +02:00
.Op Fl c Ar cert.pem
.Op Fl d Ar docs
.Op Fl k Ar key.pem
2020-11-06 18:11:45 +01:00
.Op Fl l Ar logfile
.Op Fl x Ar cgi-bin
2020-10-02 19:39:00 +02:00
.Ek
.Sh DESCRIPTION
.Nm
2020-11-06 18:11:45 +01:00
is a very simple and minimal gemini server that can serve static files
and execute CGI scripts.
2020-10-02 19:39:00 +02:00
.Pp
.Nm
will strip any sequence of
.Pa ../
or trailing
.Pa ..
in the requests made by clients, so it's impossible to serve content
outside the
.Pa docs
2020-11-06 18:11:45 +01:00
directory by mistake, and will also refuse to follow symlinks.
Furthermore, on
.Ox ,
.Xr pledge 2
2020-10-02 19:39:00 +02:00
and
.Xr unveil 2
2020-10-02 19:39:00 +02:00
are used to ensure that
.Nm
2020-11-06 18:11:45 +01:00
dosen't do anything else than read files from the given directory,
accept network connections and, optionally, execute CGI scripts.
2020-10-02 19:39:00 +02:00
.Pp
It should be noted that
.Nm
is very simple in its implementation, and so it may not be appropriate
2020-11-06 18:11:45 +01:00
for serving sites with lots of users.
After all, the code is single threaded and use a single process,
although it can handle multiple requests concurrently.
2020-10-02 19:39:00 +02:00
.Pp
2020-10-03 17:49:09 +02:00
If a user request path is a directory,
.Nm
will try to serve a
.Pa index.gmi
file inside that directory.
If not found, it will return an error 51 (not found) to the user.
.Pp
2020-10-02 19:39:00 +02:00
The options are as follows:
.Bl -tag -width 12m
.It Fl c Ar cert.pem
The certificate to use, by default is
2020-10-03 17:49:09 +02:00
.Pa cert.pem .
2020-10-02 19:39:00 +02:00
.It Fl d Ar docs
The root directory to serve.
.Nm
2020-11-06 18:11:45 +01:00
won't serve any file that is outside that directory, by default
.Pa docs .
2020-10-02 19:39:00 +02:00
.It Fl h
2020-10-03 17:49:09 +02:00
Print the usage and exit.
2020-10-02 19:39:00 +02:00
.It Fl k Ar key.pem
The key for the certificate, by default is
2020-10-03 17:49:09 +02:00
.Pa key.pem .
2020-11-06 18:11:45 +01:00
.It Fl l Ar logfile
2020-11-06 10:58:30 +01:00
log to the given file instead of the standard error.
2020-11-06 18:11:45 +01:00
.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.
2020-10-02 19:39:00 +02:00
.El
.Sh CGI
2020-11-06 18:11:45 +01:00
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
2020-11-06 18:11:45 +01:00
The CGI scripts will inherit the environment from
.Nm
with these additional variables set:
.Bl -tag -width 15m
.It Ev SERVER_SOFTWARE
"gmid"
.It Ev SERVER_PROTOCOL
"gemini"
.It Ev SERVER_PORT
"1965"
.It Ev PATH_INFO
the request path
.It Ev PATH_TRANSLATED
the full path: the concatenation of the document root and the request
path
.It Ev QUERY_STRING
the query string if present in the request URL, otherwise it
won't be set.
.It Ev REMOTE_ADDR
the IP address of the client in dot notation
.El
2020-10-02 19:39:00 +02:00
.Sh EXAMPLES
To quickly getting started
.Bd -literal -offset indent
2020-10-02 19:39:00 +02:00
$ # 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
2020-10-02 19:39:00 +02:00
.Pp
2020-11-06 18:11:45 +01:00
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 its relative to the document root.
2020-10-02 19:39:00 +02:00
.Sh CAVEATS
.Bl -bullet
.It
2020-10-03 17:49:09 +02:00
it doesn't support virtual hosts: the host part of the request URL is
2020-10-02 19:39:00 +02:00
completely ignored.
.It
it doesn't fork in the background or anything like that.
.El