2023-06-24 15:02:44 +02:00
|
|
|
.\" Copyright (c) 2021, 2022, 2023 Omar Polo <op@omarpolo.com>
|
2020-10-02 19:39:00 +02:00
|
|
|
.\"
|
|
|
|
.\" 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.
|
2023-06-24 15:02:44 +02:00
|
|
|
.Dd June 24, 2023
|
2022-09-08 23:15:02 +02:00
|
|
|
.Dt GMID 8
|
2020-10-02 19:39:00 +02:00
|
|
|
.Os
|
|
|
|
.Sh NAME
|
|
|
|
.Nm gmid
|
2021-01-30 12:49:27 +01:00
|
|
|
.Nd simple and secure Gemini server
|
2020-10-02 19:39:00 +02:00
|
|
|
.Sh SYNOPSIS
|
|
|
|
.Nm
|
|
|
|
.Bk -words
|
2023-06-05 22:35:12 +02:00
|
|
|
.Op Fl fhnVv
|
|
|
|
.Op Fl c Ar config
|
2021-06-29 16:19:35 +02:00
|
|
|
.Op Fl D Ar macro Ns = Ns Ar value
|
2021-04-28 14:45:22 +02:00
|
|
|
.Op Fl P Ar pidfile
|
2021-02-04 15:38:37 +01:00
|
|
|
.Ek
|
2020-10-02 19:39:00 +02:00
|
|
|
.Sh DESCRIPTION
|
|
|
|
.Nm
|
2021-05-24 11:07:28 +02:00
|
|
|
is a simple and minimal gemini server that can serve static files,
|
2022-09-06 18:11:09 +02:00
|
|
|
talk to FastCGI applications and act as a gemini reverse proxy.
|
2020-10-02 19:39:00 +02:00
|
|
|
.Pp
|
2021-02-04 14:34:27 +01:00
|
|
|
.Nm
|
|
|
|
rereads the configuration file when it receives
|
2023-07-24 11:00:19 +02:00
|
|
|
.Dv SIGHUP
|
|
|
|
and reopens log files when it receives
|
|
|
|
.Dv SIGUSR1 .
|
2021-02-04 14:34:27 +01:00
|
|
|
.Pp
|
2021-01-18 22:52:01 +01:00
|
|
|
The options are as follows:
|
2021-01-25 15:31:34 +01:00
|
|
|
.Bl -tag -width 14m
|
2023-06-05 22:35:12 +02:00
|
|
|
.It Fl c Ar config
|
|
|
|
Specifies the configuration file.
|
|
|
|
The default is
|
|
|
|
.Pa /etc/gmid.conf .
|
2021-06-29 16:19:35 +02:00
|
|
|
.It Fl D Ar macro Ns = Ns Ar value
|
|
|
|
Define
|
|
|
|
.Ar macro
|
|
|
|
to be set to
|
|
|
|
.Ar value
|
|
|
|
on the command line.
|
|
|
|
Overrides the definition of
|
|
|
|
.Ar macro
|
|
|
|
in the config file if present.
|
2023-06-05 22:35:12 +02:00
|
|
|
.It Fl f
|
|
|
|
Stays and logs on the foreground.
|
2022-09-08 23:15:02 +02:00
|
|
|
.It Fl h , Fl -help
|
|
|
|
Print the usage and exit.
|
2021-01-18 22:52:01 +01:00
|
|
|
.It Fl n
|
|
|
|
Check that the configuration is valid, but don't start the server.
|
2021-10-09 23:40:55 +02:00
|
|
|
If specified two or more time, dump the configuration in addition to
|
|
|
|
verify it.
|
2022-01-05 00:22:14 +01:00
|
|
|
.It Fl P Ar pidfile
|
2021-07-29 06:13:46 +02:00
|
|
|
Write daemon's pid to the given location.
|
2021-07-09 10:01:22 +02:00
|
|
|
.Ar pidfile
|
|
|
|
will also act as lock: if another process is holding a lock on that
|
|
|
|
file,
|
2021-04-28 14:45:22 +02:00
|
|
|
.Nm
|
2021-07-09 10:01:22 +02:00
|
|
|
will refuse to start.
|
2021-06-29 13:00:28 +02:00
|
|
|
.It Fl V , Fl -version
|
|
|
|
Print the version and exit.
|
2021-01-28 00:14:16 +01:00
|
|
|
.It Fl v
|
2021-02-07 16:30:28 +01:00
|
|
|
Verbose mode.
|
2021-01-18 22:52:01 +01:00
|
|
|
.El
|
2021-07-29 06:13:43 +02:00
|
|
|
.Sh LOGGING
|
|
|
|
Messages and requests are logged by
|
|
|
|
.Xr syslog 3
|
|
|
|
using the
|
|
|
|
.Dv DAEMON
|
|
|
|
facility or printed on
|
|
|
|
.Em stderr .
|
|
|
|
.Pp
|
|
|
|
Requests are logged with the
|
|
|
|
.Dv NOTICE
|
|
|
|
severity.
|
|
|
|
Each request log entry has the following fields, separated by
|
|
|
|
whitespace:
|
|
|
|
.Pp
|
|
|
|
.Bl -bullet -compact
|
|
|
|
.It
|
|
|
|
Client IP address and the source port number, separated by a colon
|
|
|
|
.It
|
|
|
|
.Sy GET
|
|
|
|
keyword
|
|
|
|
.It
|
|
|
|
Request URL
|
|
|
|
.It
|
|
|
|
Response status
|
|
|
|
.It
|
|
|
|
Response meta
|
|
|
|
.El
|
2020-10-02 19:39:00 +02:00
|
|
|
.Sh EXAMPLES
|
2022-04-08 16:08:33 +02:00
|
|
|
To run
|
2021-07-29 06:13:45 +02:00
|
|
|
.Nm
|
2022-09-08 23:15:02 +02:00
|
|
|
a configuration file and a X.509 certificate must be provided.
|
2022-04-08 16:08:33 +02:00
|
|
|
A self-signed certificate, which are commonly used in the Geminispace,
|
|
|
|
can be generated using for e.g.\&
|
|
|
|
.Xr openssl 1 :
|
2021-07-29 06:13:45 +02:00
|
|
|
.Bd -literal -offset indent
|
2022-04-08 16:08:33 +02:00
|
|
|
# openssl req \-x509 \-newkey rsa:4096 \-nodes \e
|
|
|
|
\-keyout /etc/ssl/private/example.com.key \e
|
|
|
|
\-out /etc/ssl/example.com.pem \e
|
|
|
|
\-days 365 \-subj "/CN=example.com"
|
2021-07-29 06:13:45 +02:00
|
|
|
# chmod 600 /etc/ssl/example.com.crt
|
|
|
|
# chmod 600 /etc/ssl/private/example.com.key
|
|
|
|
.Ed
|
|
|
|
.Pp
|
2022-04-08 16:08:33 +02:00
|
|
|
Then
|
2022-04-07 19:50:37 +02:00
|
|
|
.Nm
|
2022-04-08 16:08:33 +02:00
|
|
|
can be started with
|
2021-01-25 15:31:34 +01:00
|
|
|
.Bd -literal -offset indent
|
2022-04-08 16:08:33 +02:00
|
|
|
# gmid -c /etc/gmid.conf
|
2021-01-25 15:31:34 +01:00
|
|
|
.Ed
|
2022-04-07 19:50:37 +02:00
|
|
|
.Sh SEE ALSO
|
|
|
|
.Xr gmid.conf 5
|
2021-01-09 21:32:23 +01:00
|
|
|
.Sh ACKNOWLEDGEMENTS
|
|
|
|
.Nm
|
2021-01-18 22:52:01 +01:00
|
|
|
uses the
|
|
|
|
.Dq Flexible and Economical
|
|
|
|
UTF-8 decoder written by
|
2021-01-25 15:31:34 +01:00
|
|
|
.An Bjoern Hoehrmann .
|
2021-01-30 12:49:27 +01:00
|
|
|
.Sh AUTHORS
|
|
|
|
.An -nosplit
|
|
|
|
The
|
|
|
|
.Nm
|
|
|
|
program was written by
|
|
|
|
.An Omar Polo Aq Mt op@omarpolo.com .
|
2020-10-02 19:39:00 +02:00
|
|
|
.Sh CAVEATS
|
|
|
|
.Bl -bullet
|
|
|
|
.It
|
2023-06-24 15:02:44 +02:00
|
|
|
All the root directories are opened during the daemon configuration;
|
|
|
|
if a root directory is deleted and then re-created,
|
2021-01-18 22:52:01 +01:00
|
|
|
.Nm
|
2023-06-24 15:02:44 +02:00
|
|
|
won't be able to serve files inside that directory until a reload.
|
2021-07-09 10:01:22 +02:00
|
|
|
This restriction only applies to the root directories and not their
|
|
|
|
content.
|
2020-12-25 13:15:15 +01:00
|
|
|
.It
|
2021-01-30 12:49:27 +01:00
|
|
|
a %2F sequence is indistinguishable from a literal slash: this is not
|
|
|
|
RFC3986-compliant.
|
2020-12-26 00:37:43 +01:00
|
|
|
.It
|
2021-01-30 12:49:27 +01:00
|
|
|
a %00 sequence is treated as invalid character and thus rejected.
|
2020-10-02 19:39:00 +02:00
|
|
|
.El
|