mirror of
https://github.com/omar-polo/gmid.git
synced 2024-10-02 07:21:14 +02:00
152 lines
3.7 KiB
Groff
152 lines
3.7 KiB
Groff
.\" Copyright (c) 2021, 2022, 2023 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 June 24, 2023
|
|
.Dt GMID 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm gmid
|
|
.Nd simple and secure Gemini server
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Bk -words
|
|
.Op Fl fhnVv
|
|
.Op Fl c Ar config
|
|
.Op Fl D Ar macro Ns = Ns Ar value
|
|
.Op Fl P Ar pidfile
|
|
.Ek
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is a simple and minimal gemini server that can serve static files,
|
|
talk to FastCGI applications and act as a gemini reverse proxy.
|
|
.Pp
|
|
.Nm
|
|
rereads the configuration file when it receives
|
|
.Dv SIGHUP
|
|
and reopens log files when it receives
|
|
.Dv SIGUSR1 .
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width 14m
|
|
.It Fl c Ar config
|
|
Specifies the configuration file.
|
|
The default is
|
|
.Pa /etc/gmid.conf .
|
|
.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.
|
|
.It Fl f
|
|
Stays and logs on the foreground.
|
|
.It Fl h , Fl -help
|
|
Print the usage and exit.
|
|
.It Fl n
|
|
Check that the configuration is valid, but don't start the server.
|
|
If specified two or more time, dump the configuration in addition to
|
|
verify it.
|
|
.It Fl P Ar pidfile
|
|
Write daemon's pid to the given location.
|
|
.Ar pidfile
|
|
will also act as lock: if another process is holding a lock on that
|
|
file,
|
|
.Nm
|
|
will refuse to start.
|
|
.It Fl V , Fl -version
|
|
Print the version and exit.
|
|
.It Fl v
|
|
Verbose mode.
|
|
.El
|
|
.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
|
|
.Sh EXAMPLES
|
|
To run
|
|
.Nm
|
|
a configuration file and a X.509 certificate must be provided.
|
|
A self-signed certificate, which are commonly used in the Geminispace,
|
|
can be generated using for e.g.\&
|
|
.Xr openssl 1 :
|
|
.Bd -literal -offset indent
|
|
# 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"
|
|
# chmod 600 /etc/ssl/example.com.crt
|
|
# chmod 600 /etc/ssl/private/example.com.key
|
|
.Ed
|
|
.Pp
|
|
Then
|
|
.Nm
|
|
can be started with
|
|
.Bd -literal -offset indent
|
|
# gmid -c /etc/gmid.conf
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr gmid.conf 5
|
|
.Sh ACKNOWLEDGEMENTS
|
|
.Nm
|
|
uses the
|
|
.Dq Flexible and Economical
|
|
UTF-8 decoder written by
|
|
.An Bjoern Hoehrmann .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The
|
|
.Nm
|
|
program was written by
|
|
.An Omar Polo Aq Mt op@omarpolo.com .
|
|
.Sh CAVEATS
|
|
.Bl -bullet
|
|
.It
|
|
All the root directories are opened during the daemon configuration;
|
|
if a root directory is deleted and then re-created,
|
|
.Nm
|
|
won't be able to serve files inside that directory until a reload.
|
|
This restriction only applies to the root directories and not their
|
|
content.
|
|
.It
|
|
a %2F sequence is indistinguishable from a literal slash: this is not
|
|
RFC3986-compliant.
|
|
.It
|
|
a %00 sequence is treated as invalid character and thus rejected.
|
|
.El
|