1 b3010dbb 2023-06-24 op .\" Copyright (c) 2021, 2022, 2023 Omar Polo <op@omarpolo.com>
  2 9b15e4c6 2022-09-08 op .\"
  3 9b15e4c6 2022-09-08 op .\" Permission to use, copy, modify, and distribute this software for any
  4 9b15e4c6 2022-09-08 op .\" purpose with or without fee is hereby granted, provided that the above
  5 9b15e4c6 2022-09-08 op .\" copyright notice and this permission notice appear in all copies.
  6 9b15e4c6 2022-09-08 op .\"
  7 9b15e4c6 2022-09-08 op .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  8 9b15e4c6 2022-09-08 op .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  9 9b15e4c6 2022-09-08 op .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 10 9b15e4c6 2022-09-08 op .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 11 9b15e4c6 2022-09-08 op .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 12 9b15e4c6 2022-09-08 op .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 13 9b15e4c6 2022-09-08 op .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 14 b3010dbb 2023-06-24 op .Dd June 24, 2023
 15 9b15e4c6 2022-09-08 op .Dt GMID 8
 16 9b15e4c6 2022-09-08 op .Os
 17 9b15e4c6 2022-09-08 op .Sh NAME
 18 9b15e4c6 2022-09-08 op .Nm gmid
 19 9b15e4c6 2022-09-08 op .Nd simple and secure Gemini server
 20 9b15e4c6 2022-09-08 op .Sh SYNOPSIS
 21 9b15e4c6 2022-09-08 op .Nm
 22 9b15e4c6 2022-09-08 op .Bk -words
 23 0ac785a6 2023-06-05 op .Op Fl fhnVv
 24 0ac785a6 2023-06-05 op .Op Fl c Ar config
 25 9b15e4c6 2022-09-08 op .Op Fl D Ar macro Ns = Ns Ar value
 26 9b15e4c6 2022-09-08 op .Op Fl P Ar pidfile
 27 9b15e4c6 2022-09-08 op .Ek
 28 9b15e4c6 2022-09-08 op .Sh DESCRIPTION
 29 9b15e4c6 2022-09-08 op .Nm
 30 9b15e4c6 2022-09-08 op is a simple and minimal gemini server that can serve static files,
 31 9b15e4c6 2022-09-08 op talk to FastCGI applications and act as a gemini reverse proxy.
 32 9b15e4c6 2022-09-08 op .Pp
 33 9b15e4c6 2022-09-08 op .Nm
 34 9b15e4c6 2022-09-08 op rereads the configuration file when it receives
 35 9b15e4c6 2022-09-08 op .Dv SIGHUP .
 36 9b15e4c6 2022-09-08 op .Pp
 37 9b15e4c6 2022-09-08 op The options are as follows:
 38 9b15e4c6 2022-09-08 op .Bl -tag -width 14m
 39 0ac785a6 2023-06-05 op .It Fl c Ar config
 40 0ac785a6 2023-06-05 op Specifies the configuration file.
 41 0ac785a6 2023-06-05 op The default is
 42 0ac785a6 2023-06-05 op .Pa /etc/gmid.conf .
 43 9b15e4c6 2022-09-08 op .It Fl D Ar macro Ns = Ns Ar value
 44 9b15e4c6 2022-09-08 op Define
 45 9b15e4c6 2022-09-08 op .Ar macro
 46 9b15e4c6 2022-09-08 op to be set to
 47 9b15e4c6 2022-09-08 op .Ar value
 48 9b15e4c6 2022-09-08 op on the command line.
 49 9b15e4c6 2022-09-08 op Overrides the definition of
 50 9b15e4c6 2022-09-08 op .Ar macro
 51 9b15e4c6 2022-09-08 op in the config file if present.
 52 0ac785a6 2023-06-05 op .It Fl f
 53 0ac785a6 2023-06-05 op Stays and logs on the foreground.
 54 9b15e4c6 2022-09-08 op .It Fl h , Fl -help
 55 9b15e4c6 2022-09-08 op Print the usage and exit.
 56 9b15e4c6 2022-09-08 op .It Fl n
 57 9b15e4c6 2022-09-08 op Check that the configuration is valid, but don't start the server.
 58 9b15e4c6 2022-09-08 op If specified two or more time, dump the configuration in addition to
 59 9b15e4c6 2022-09-08 op verify it.
 60 9b15e4c6 2022-09-08 op .It Fl P Ar pidfile
 61 9b15e4c6 2022-09-08 op Write daemon's pid to the given location.
 62 9b15e4c6 2022-09-08 op .Ar pidfile
 63 9b15e4c6 2022-09-08 op will also act as lock: if another process is holding a lock on that
 64 9b15e4c6 2022-09-08 op file,
 65 9b15e4c6 2022-09-08 op .Nm
 66 9b15e4c6 2022-09-08 op will refuse to start.
 67 9b15e4c6 2022-09-08 op .It Fl V , Fl -version
 68 9b15e4c6 2022-09-08 op Print the version and exit.
 69 9b15e4c6 2022-09-08 op .It Fl v
 70 9b15e4c6 2022-09-08 op Verbose mode.
 71 9b15e4c6 2022-09-08 op Multiple
 72 9b15e4c6 2022-09-08 op .Fl v
 73 9b15e4c6 2022-09-08 op options increase the verbosity.
 74 9b15e4c6 2022-09-08 op .El
 75 9b15e4c6 2022-09-08 op .Sh LOGGING
 76 9b15e4c6 2022-09-08 op Messages and requests are logged by
 77 9b15e4c6 2022-09-08 op .Xr syslog 3
 78 9b15e4c6 2022-09-08 op using the
 79 9b15e4c6 2022-09-08 op .Dv DAEMON
 80 9b15e4c6 2022-09-08 op facility or printed on
 81 9b15e4c6 2022-09-08 op .Em stderr .
 82 9b15e4c6 2022-09-08 op .Pp
 83 9b15e4c6 2022-09-08 op Requests are logged with the
 84 9b15e4c6 2022-09-08 op .Dv NOTICE
 85 9b15e4c6 2022-09-08 op severity.
 86 9b15e4c6 2022-09-08 op Each request log entry has the following fields, separated by
 87 9b15e4c6 2022-09-08 op whitespace:
 88 9b15e4c6 2022-09-08 op .Pp
 89 9b15e4c6 2022-09-08 op .Bl -bullet -compact
 90 9b15e4c6 2022-09-08 op .It
 91 9b15e4c6 2022-09-08 op Client IP address and the source port number, separated by a colon
 92 9b15e4c6 2022-09-08 op .It
 93 9b15e4c6 2022-09-08 op .Sy GET
 94 9b15e4c6 2022-09-08 op keyword
 95 9b15e4c6 2022-09-08 op .It
 96 9b15e4c6 2022-09-08 op Request URL
 97 9b15e4c6 2022-09-08 op .It
 98 9b15e4c6 2022-09-08 op Response status
 99 9b15e4c6 2022-09-08 op .It
100 9b15e4c6 2022-09-08 op Response meta
101 9b15e4c6 2022-09-08 op .El
102 9b15e4c6 2022-09-08 op .Sh EXAMPLES
103 9b15e4c6 2022-09-08 op To run
104 9b15e4c6 2022-09-08 op .Nm
105 9b15e4c6 2022-09-08 op a configuration file and a X.509 certificate must be provided.
106 9b15e4c6 2022-09-08 op A self-signed certificate, which are commonly used in the Geminispace,
107 9b15e4c6 2022-09-08 op can be generated using for e.g.\&
108 9b15e4c6 2022-09-08 op .Xr openssl 1 :
109 9b15e4c6 2022-09-08 op .Bd -literal -offset indent
110 9b15e4c6 2022-09-08 op # openssl req \-x509 \-newkey rsa:4096 \-nodes \e
111 9b15e4c6 2022-09-08 op 	\-keyout /etc/ssl/private/example.com.key \e
112 9b15e4c6 2022-09-08 op 	\-out /etc/ssl/example.com.pem \e
113 9b15e4c6 2022-09-08 op 	\-days 365 \-subj "/CN=example.com"
114 9b15e4c6 2022-09-08 op # chmod 600 /etc/ssl/example.com.crt
115 9b15e4c6 2022-09-08 op # chmod 600 /etc/ssl/private/example.com.key
116 9b15e4c6 2022-09-08 op .Ed
117 9b15e4c6 2022-09-08 op .Pp
118 9b15e4c6 2022-09-08 op Then
119 9b15e4c6 2022-09-08 op .Nm
120 9b15e4c6 2022-09-08 op can be started with
121 9b15e4c6 2022-09-08 op .Bd -literal -offset indent
122 9b15e4c6 2022-09-08 op # gmid -c /etc/gmid.conf
123 9b15e4c6 2022-09-08 op .Ed
124 9b15e4c6 2022-09-08 op .Sh SEE ALSO
125 9b15e4c6 2022-09-08 op .Xr gmid.conf 5
126 9b15e4c6 2022-09-08 op .Sh ACKNOWLEDGEMENTS
127 9b15e4c6 2022-09-08 op .Nm
128 9b15e4c6 2022-09-08 op uses the
129 9b15e4c6 2022-09-08 op .Dq Flexible and Economical
130 9b15e4c6 2022-09-08 op UTF-8 decoder written by
131 9b15e4c6 2022-09-08 op .An Bjoern Hoehrmann .
132 9b15e4c6 2022-09-08 op .Sh AUTHORS
133 9b15e4c6 2022-09-08 op .An -nosplit
134 9b15e4c6 2022-09-08 op The
135 9b15e4c6 2022-09-08 op .Nm
136 9b15e4c6 2022-09-08 op program was written by
137 9b15e4c6 2022-09-08 op .An Omar Polo Aq Mt op@omarpolo.com .
138 9b15e4c6 2022-09-08 op .Sh CAVEATS
139 9b15e4c6 2022-09-08 op .Bl -bullet
140 9b15e4c6 2022-09-08 op .It
141 b3010dbb 2023-06-24 op All the root directories are opened during the daemon configuration;
142 b3010dbb 2023-06-24 op if a root directory is deleted and then re-created,
143 9b15e4c6 2022-09-08 op .Nm
144 b3010dbb 2023-06-24 op won't be able to serve files inside that directory until a reload.
145 9b15e4c6 2022-09-08 op This restriction only applies to the root directories and not their
146 9b15e4c6 2022-09-08 op content.
147 9b15e4c6 2022-09-08 op .It
148 9b15e4c6 2022-09-08 op a %2F sequence is indistinguishable from a literal slash: this is not
149 9b15e4c6 2022-09-08 op RFC3986-compliant.
150 9b15e4c6 2022-09-08 op .It
151 9b15e4c6 2022-09-08 op a %00 sequence is treated as invalid character and thus rejected.
152 9b15e4c6 2022-09-08 op .El