mirror of https://github.com/omar-polo/gmid.git
new README + wording in manpage
This commit is contained in:
parent
85dff1f9c3
commit
b9220ca4de
3
Makefile
3
Makefile
|
@ -12,9 +12,6 @@ gmid: gmid.o uri.o utf8.o
|
||||||
TAGS: gmid.c uri.c utf8.c
|
TAGS: gmid.c uri.c utf8.c
|
||||||
-etags gmid.c uri.c utf8.c || true
|
-etags gmid.c uri.c utf8.c || true
|
||||||
|
|
||||||
README.md: gmid.1
|
|
||||||
mandoc -Tmarkdown gmid.1 | sed -e '1d' -e '$$d' > README.md
|
|
||||||
|
|
||||||
clean:
|
clean:
|
||||||
rm -f *.o gmid
|
rm -f *.o gmid
|
||||||
|
|
||||||
|
|
250
README.md
250
README.md
|
@ -1,235 +1,55 @@
|
||||||
|
# gmid
|
||||||
|
|
||||||
# NAME
|
> dead simple, zero configuration Gemini server
|
||||||
|
|
||||||
**gmid** - dead simple zero configuration gemini server
|
gmid is a simple and minimal Gemini server. It requires no
|
||||||
|
configuration whatsoever so it's well suited for local development
|
||||||
|
machines.
|
||||||
|
|
||||||
# SYNOPSIS
|
Care has been taken to assure that gmid doesn't serve files outside
|
||||||
|
the given directory, and it won't follow symlinks. Furthermore, on
|
||||||
|
OpenBSD, gmid is also `pledge(2)`ed and `unveil(2)`ed: the set of
|
||||||
|
pledges are `stdio rpath inet`, with the addition of `proc exec` if
|
||||||
|
CGI scripts are enabled, while the given directory is unveiled with
|
||||||
|
`rx`.
|
||||||
|
|
||||||
**gmid**
|
|
||||||
\[**-6fh**]
|
|
||||||
\[**-c** *cert.pem*]
|
|
||||||
\[**-d** *docs*]
|
|
||||||
\[**-k** *key.pem*]
|
|
||||||
\[**-p** *port*]
|
|
||||||
\[**-x** *cgi-bin*]
|
|
||||||
|
|
||||||
# DESCRIPTION
|
## Features
|
||||||
|
|
||||||
**gmid**
|
- IRI support (RFC RFC3987)
|
||||||
is a very simple and minimal gemini server that can serve static files
|
- dual stack: can serve over both IPv4 and IPv6
|
||||||
and execute CGI scripts.
|
- CGI scripts
|
||||||
|
- (very) low memory footprint
|
||||||
|
- small codebase, easily hackable
|
||||||
|
|
||||||
**gmid**
|
|
||||||
won't serve files outside the given directory and won't follow
|
|
||||||
symlinks.
|
|
||||||
Furthermore, on
|
|
||||||
OpenBSD,
|
|
||||||
pledge(2)
|
|
||||||
and
|
|
||||||
unveil(2)
|
|
||||||
are used to ensure that
|
|
||||||
**gmid**
|
|
||||||
dosen't do anything else than read files from the given directory,
|
|
||||||
accept network connections and, optionally, execute CGI scripts.
|
|
||||||
|
|
||||||
**gmid**
|
## Planned features
|
||||||
fully supports IRIs (Internationalized Resource Identifiers, see
|
|
||||||
RFC3987).
|
|
||||||
|
|
||||||
It should be noted that
|
- virtual hosts
|
||||||
**gmid**
|
|
||||||
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.
|
|
||||||
|
|
||||||
If a user request path is a directory,
|
|
||||||
**gmid**
|
|
||||||
will try to serve a
|
|
||||||
*index.gmi*
|
|
||||||
file inside that directory.
|
|
||||||
|
|
||||||
The options are as follows:
|
## Drawbacks
|
||||||
|
|
||||||
**-6**
|
- not suited for very busy hosts. If you receive an high number of
|
||||||
|
connection per-second you'd probably want to run multiple gmid
|
||||||
|
instances behind relayd/haproxy or a different server.
|
||||||
|
|
||||||
> Enable IPv6.
|
|
||||||
|
|
||||||
**-c** *cert.pem*
|
## Building
|
||||||
|
|
||||||
> The certificate to use, by default is
|
gmid depends a POSIX libc and libtls. It can probably be linked
|
||||||
> *cert.pem*.
|
against libretls, but I've never tried.
|
||||||
|
|
||||||
**-d** *docs*
|
See [INSTALL.gmi](INSTALL.gmi) for more info, but the build is as
|
||||||
|
simple as
|
||||||
|
|
||||||
> The root directory to serve.
|
make
|
||||||
> **gmid**
|
|
||||||
> won't serve any file that is outside that directory.
|
|
||||||
> By default is
|
|
||||||
> *docs*.
|
|
||||||
|
|
||||||
**-f**
|
The Makefile isn't able to produce a statically linked executable
|
||||||
|
(yet), so for that you have to execute by hand
|
||||||
|
|
||||||
> stays and log in the foreground, do not daemonize the process.
|
make
|
||||||
|
cc -static *.o /usr/lib/lib{crypto,tls,ssl}.a -o gmid
|
||||||
**-h**
|
strip gmid
|
||||||
|
|
||||||
> Print the usage and exit.
|
|
||||||
|
|
||||||
**-k** *key.pem*
|
|
||||||
|
|
||||||
> The key for the certificate, by default is
|
|
||||||
> *key.pem*.
|
|
||||||
|
|
||||||
**-p** *port*
|
|
||||||
|
|
||||||
> The port to bind to, by default 1965.
|
|
||||||
|
|
||||||
**-x** *dir*
|
|
||||||
|
|
||||||
> Enable execution of CGI scripts inside the given directory (relative
|
|
||||||
> to the document root.) Cannot be provided more than once.
|
|
||||||
|
|
||||||
# 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.
|
|
||||||
|
|
||||||
The CGI scripts will inherit the environment from
|
|
||||||
**gmid**
|
|
||||||
with these additional variables set:
|
|
||||||
|
|
||||||
`SERVER_SOFTWARE`
|
|
||||||
|
|
||||||
> "gmid"
|
|
||||||
|
|
||||||
`SERVER_PORT`
|
|
||||||
|
|
||||||
> "1965"
|
|
||||||
|
|
||||||
`SCRIPT_NAME`
|
|
||||||
|
|
||||||
> The (public) path to the script.
|
|
||||||
|
|
||||||
`SCRIPT_EXECUTABLE`
|
|
||||||
|
|
||||||
> The full path to the executable.
|
|
||||||
|
|
||||||
`REQUEST_URI`
|
|
||||||
|
|
||||||
> The user request (without the query parameters.)
|
|
||||||
|
|
||||||
`REQUEST_RELATIVE`
|
|
||||||
|
|
||||||
> The request relative to the script.
|
|
||||||
|
|
||||||
`QUERY_STRING`
|
|
||||||
|
|
||||||
> The query parameters.
|
|
||||||
|
|
||||||
`REMOTE_HOST`
|
|
||||||
|
|
||||||
> The remote IP address.
|
|
||||||
|
|
||||||
`REMOTE_ADDR`
|
|
||||||
|
|
||||||
> The remote IP address.
|
|
||||||
|
|
||||||
`DOCUMENT_ROOT`
|
|
||||||
|
|
||||||
> The root directory being served, the one provided with the
|
|
||||||
> *d*
|
|
||||||
> parameter to
|
|
||||||
> **gmid**
|
|
||||||
|
|
||||||
`AUTH_TYPE`
|
|
||||||
|
|
||||||
> The string "Certificate" if the client used a certificate, otherwise unset.
|
|
||||||
|
|
||||||
`REMOTE_USER`
|
|
||||||
|
|
||||||
> The subject of the client certificate if provided, otherwise unset.
|
|
||||||
|
|
||||||
`TLS_CLIENT_ISSUER`
|
|
||||||
|
|
||||||
> The is the issuer of the client certificate if provided, otherwise unset.
|
|
||||||
|
|
||||||
`TLS_CLIENT_HASH`
|
|
||||||
|
|
||||||
> The hash of the client certificate if provided, otherwise unset.
|
|
||||||
> The format is "ALGO:HASH".
|
|
||||||
|
|
||||||
Let's say you have a script in
|
|
||||||
*/cgi-bin/script*
|
|
||||||
and the user request is
|
|
||||||
*/cgi-bin/script/foo/bar?quux*.
|
|
||||||
Then
|
|
||||||
`SCRIPT_NAME`
|
|
||||||
will be
|
|
||||||
*/cgi-bin/script*,
|
|
||||||
`SCRIPT_EXECUTABLE`
|
|
||||||
will be
|
|
||||||
*$DOCUMENT\_ROOT/cgi-bin/script*,
|
|
||||||
`REQUEST_URI`
|
|
||||||
will be
|
|
||||||
*/cgi-bin/script/foo/bar*,
|
|
||||||
`REQUEST_RELATIVE`
|
|
||||||
will be
|
|
||||||
*foo/bar and*
|
|
||||||
`QUERY_STRING`
|
|
||||||
will be
|
|
||||||
*quux*.
|
|
||||||
|
|
||||||
# EXAMPLES
|
|
||||||
|
|
||||||
To quickly getting started
|
|
||||||
|
|
||||||
$ # 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
|
|
||||||
|
|
||||||
Now you can visit gemini://localhost/ with your preferred gemini
|
|
||||||
client.
|
|
||||||
|
|
||||||
To add some CGI scripts, assuming a setup similar to the previous
|
|
||||||
example, you can
|
|
||||||
|
|
||||||
$ 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
|
|
||||||
|
|
||||||
Note that the argument to the
|
|
||||||
**-x**
|
|
||||||
option is
|
|
||||||
*cgi-bin*
|
|
||||||
and not
|
|
||||||
*docs/cgi-bin*,
|
|
||||||
since it's relative to the document root.
|
|
||||||
|
|
||||||
# ACKNOWLEDGEMENTS
|
|
||||||
|
|
||||||
**gmid**
|
|
||||||
uses the "Flexible and Economical" UTF-8 decoder written by
|
|
||||||
Bjoern Hoehrmann.
|
|
||||||
|
|
||||||
# CAVEATS
|
|
||||||
|
|
||||||
* it doesn't support virtual hosts: the host part of the request URL is
|
|
||||||
completely ignored.
|
|
||||||
|
|
||||||
* a %2F sequence in the path part is indistinguishable from a literal
|
|
||||||
slash: this is not RFC3986-compliant.
|
|
||||||
|
|
||||||
* a %00 sequence either in the path or in the query part is treated as
|
|
||||||
invalid character and thus rejected.
|
|
||||||
|
|
||||||
|
to enjoy your ~2.3M statically-linked gmid.
|
||||||
|
|
11
gmid.1
11
gmid.1
|
@ -29,8 +29,8 @@
|
||||||
.Ek
|
.Ek
|
||||||
.Sh DESCRIPTION
|
.Sh DESCRIPTION
|
||||||
.Nm
|
.Nm
|
||||||
is a very simple and minimal gemini server that can serve static files
|
is a simple and minimal gemini server that can serve static files and
|
||||||
and execute CGI scripts.
|
execute CGI scripts.
|
||||||
.Pp
|
.Pp
|
||||||
.Nm
|
.Nm
|
||||||
won't serve files outside the given directory and won't follow
|
won't serve files outside the given directory and won't follow
|
||||||
|
@ -137,16 +137,17 @@ and the user request is
|
||||||
Then
|
Then
|
||||||
.Ev SCRIPT_NAME
|
.Ev SCRIPT_NAME
|
||||||
will be
|
will be
|
||||||
.Pa /cgi-bin/script ,
|
.Pa cgi-bin/script ,
|
||||||
.Ev SCRIPT_EXECUTABLE
|
.Ev SCRIPT_EXECUTABLE
|
||||||
will be
|
will be
|
||||||
.Pa $DOCUMENT_ROOT/cgi-bin/script ,
|
.Pa $DOCUMENT_ROOT/cgi-bin/script ,
|
||||||
.Ev REQUEST_URI
|
.Ev REQUEST_URI
|
||||||
will be
|
will be
|
||||||
.Pa /cgi-bin/script/foo/bar ,
|
.Pa cgi-bin/script/foo/bar ,
|
||||||
.Ev REQUEST_RELATIVE
|
.Ev REQUEST_RELATIVE
|
||||||
will be
|
will be
|
||||||
.Pa foo/bar and
|
.Pa foo/bar
|
||||||
|
and
|
||||||
.Ev QUERY_STRING
|
.Ev QUERY_STRING
|
||||||
will be
|
will be
|
||||||
.Ar quux .
|
.Ar quux .
|
||||||
|
|
Loading…
Reference in New Issue