1 3e4749f7 2020-10-02 op .\" Copyright (c) 2020 Omar Polo <op@omarpolo.com>
  2 3e4749f7 2020-10-02 op .\"
  3 3e4749f7 2020-10-02 op .\" Permission to use, copy, modify, and distribute this software for any
  4 3e4749f7 2020-10-02 op .\" purpose with or without fee is hereby granted, provided that the above
  5 3e4749f7 2020-10-02 op .\" copyright notice and this permission notice appear in all copies.
  6 3e4749f7 2020-10-02 op .\"
  7 3e4749f7 2020-10-02 op .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  8 3e4749f7 2020-10-02 op .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  9 3e4749f7 2020-10-02 op .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 10 3e4749f7 2020-10-02 op .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 11 3e4749f7 2020-10-02 op .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 12 3e4749f7 2020-10-02 op .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 13 3e4749f7 2020-10-02 op .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 14 3e4749f7 2020-10-02 op .Dd $Mdocdate: October 2 2020$
 15 3e4749f7 2020-10-02 op .Dt GMIND 1
 16 3e4749f7 2020-10-02 op .Os
 17 3e4749f7 2020-10-02 op .Sh NAME
 18 3e4749f7 2020-10-02 op .Nm gmid
 19 fab952e1 2020-10-03 op .Nd dead simple zero configuration gemini server
 20 3e4749f7 2020-10-02 op .Sh SYNOPSIS
 21 3e4749f7 2020-10-02 op .Nm
 22 3e4749f7 2020-10-02 op .Bk -words
 23 3e4749f7 2020-10-02 op .Op Fl h
 24 3e4749f7 2020-10-02 op .Op Fl c Ar cert.pem
 25 3e4749f7 2020-10-02 op .Op Fl d Ar docs
 26 3e4749f7 2020-10-02 op .Op Fl k Ar key.pem
 27 3e4749f7 2020-10-02 op .Ek
 28 3e4749f7 2020-10-02 op .Sh DESCRIPTION
 29 3e4749f7 2020-10-02 op .Nm
 30 3e4749f7 2020-10-02 op is a very simple and minimal gemini server.
 31 3e4749f7 2020-10-02 op It only supports serving static content, and strive to be as simple as
 32 3e4749f7 2020-10-02 op possible.
 33 3e4749f7 2020-10-02 op .Pp
 34 3e4749f7 2020-10-02 op .Nm
 35 3e4749f7 2020-10-02 op will strip any sequence of
 36 3e4749f7 2020-10-02 op .Pa ../
 37 3e4749f7 2020-10-02 op or trailing
 38 3e4749f7 2020-10-02 op .Pa ..
 39 3e4749f7 2020-10-02 op in the requests made by clients, so it's impossible to serve content
 40 3e4749f7 2020-10-02 op outside the
 41 3e4749f7 2020-10-02 op .Pa docs
 42 fab952e1 2020-10-03 op directory by mistake, and will also refuse to follow symlink.
 43 6980aad6 2020-10-02 op Furthermore, on
 44 6980aad6 2020-10-02 op .Ox ,
 45 6980aad6 2020-10-02 op .Xr pledge 2
 46 3e4749f7 2020-10-02 op and
 47 6980aad6 2020-10-02 op .Xr unveil 2
 48 3e4749f7 2020-10-02 op are used to ensure that
 49 3e4749f7 2020-10-02 op .Nm
 50 3e4749f7 2020-10-02 op dosen't do anything else than read files from the given directory and
 51 3e4749f7 2020-10-02 op accept network connections.
 52 3e4749f7 2020-10-02 op .Pp
 53 3e4749f7 2020-10-02 op It should be noted that
 54 3e4749f7 2020-10-02 op .Nm
 55 3e4749f7 2020-10-02 op is very simple in its implementation, and so it may not be appropriate
 56 3e4749f7 2020-10-02 op for serving site with lots of users.
 57 3e4749f7 2020-10-02 op After all, the code is single threaded and use a single process.
 58 3e4749f7 2020-10-02 op .Pp
 59 fab952e1 2020-10-03 op If a user request path is a directory,
 60 fab952e1 2020-10-03 op .Nm
 61 fab952e1 2020-10-03 op will try to serve a
 62 fab952e1 2020-10-03 op .Pa index.gmi
 63 fab952e1 2020-10-03 op file inside that directory.
 64 fab952e1 2020-10-03 op If not found, it will return an error 51 (not found) to the user.
 65 fab952e1 2020-10-03 op .Pp
 66 3e4749f7 2020-10-02 op The options are as follows:
 67 3e4749f7 2020-10-02 op .Bl -tag -width 12m
 68 3e4749f7 2020-10-02 op .It Fl c Ar cert.pem
 69 3e4749f7 2020-10-02 op The certificate to use, by default is
 70 fab952e1 2020-10-03 op .Pa cert.pem .
 71 3e4749f7 2020-10-02 op .It Fl d Ar docs
 72 3e4749f7 2020-10-02 op The root directory to serve.
 73 3e4749f7 2020-10-02 op .Nm
 74 3e4749f7 2020-10-02 op won't serve any file that is outside that directory.
 75 3e4749f7 2020-10-02 op .It Fl h
 76 fab952e1 2020-10-03 op Print the usage and exit.
 77 3e4749f7 2020-10-02 op .It Fl k Ar key.pem
 78 3e4749f7 2020-10-02 op The key for the certificate, by default is
 79 fab952e1 2020-10-03 op .Pa key.pem .
 80 3e4749f7 2020-10-02 op .El
 81 3e4749f7 2020-10-02 op .Sh EXAMPLES
 82 3e4749f7 2020-10-02 op To quickly getting started
 83 6980aad6 2020-10-02 op .Bd -literal -offset indent
 84 3e4749f7 2020-10-02 op $ # generate a cert and a key
 85 3e4749f7 2020-10-02 op $ openssl req -x509 -newkey rsa:4096 -keyout key.pem \\
 86 3e4749f7 2020-10-02 op         -out cert.pem -days 365 -nodes
 87 3e4749f7 2020-10-02 op $ mkdir docs
 88 3e4749f7 2020-10-02 op $ cat <<EOF > docs/index.gmi
 89 3e4749f7 2020-10-02 op # Hello world
 90 3e4749f7 2020-10-02 op test paragraph...
 91 3e4749f7 2020-10-02 op EOF
 92 3e4749f7 2020-10-02 op $ gmid -c cert.pem -k key.pem -d docs
 93 6980aad6 2020-10-02 op .Ed
 94 3e4749f7 2020-10-02 op .Pp
 95 3e4749f7 2020-10-02 op now you can visit gemini://localhost/ with your preferred gemini client.
 96 3e4749f7 2020-10-02 op .Sh CAVEATS
 97 3e4749f7 2020-10-02 op .Bl -bullet
 98 3e4749f7 2020-10-02 op .It
 99 fab952e1 2020-10-03 op it doesn't support virtual hosts: the host part of the request URL is
100 3e4749f7 2020-10-02 op completely ignored.
101 3e4749f7 2020-10-02 op .It
102 3e4749f7 2020-10-02 op it doesn't fork in the background or anything like that.
103 3e4749f7 2020-10-02 op .El