mirror of https://github.com/omar-polo/gmid.git
235 lines
5.2 KiB
Groff
235 lines
5.2 KiB
Groff
.\" Copyright (c) 2021, 2022 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 $Mdocdate: April 7 2022$
|
|
.Dt GMID 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm gmid
|
|
.Nd simple and secure Gemini server
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Bk -words
|
|
.Op Fl fnv
|
|
.Op Fl c Ar config
|
|
.Op Fl D Ar macro Ns = Ns Ar value
|
|
.Op Fl P Ar pidfile
|
|
.Ek
|
|
.Nm
|
|
.Bk -words
|
|
.Op Fl 6hVv
|
|
.Op Fl d Ar certs-dir
|
|
.Op Fl H Ar hostname
|
|
.Op Fl p Ar port
|
|
.Op Fl x Ar cgi
|
|
.Op Ar dir
|
|
.Ek
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is a simple and minimal gemini server that can serve static files,
|
|
execute CGI scripts and talk to FastCGI applications.
|
|
It can run without a configuration file with a limited set of features
|
|
available.
|
|
.Pp
|
|
.Nm
|
|
rereads the configuration file when it receives
|
|
.Dv SIGHUP .
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width 14m
|
|
.It Fl c Ar config
|
|
Specify the configuration file.
|
|
.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 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.
|
|
.El
|
|
.Pp
|
|
If no configuration file is given,
|
|
.Nm
|
|
runs in
|
|
.Dq config-less mode
|
|
.Pq i.e. runs in the foreground to serve a directory from the shell
|
|
and looks for the following options
|
|
.Bl -tag -width 14m
|
|
.It Fl 6
|
|
Enable IPv6.
|
|
.It Fl d Ar certs-path
|
|
Directory where certificates for the config-less mode are stored.
|
|
By default it is
|
|
.Pa $XDG_DATA_HOME/gmid ,
|
|
i.e.
|
|
.Pa ~/.local/share/gmid .
|
|
.It Fl H Ar hostname
|
|
The hostname
|
|
.Po
|
|
.Ar localhost
|
|
by default
|
|
.Pc .
|
|
Certificates for the given
|
|
.Ar hostname
|
|
are searched inside the
|
|
.Ar certs-dir
|
|
directory given with the
|
|
.Fl d
|
|
option.
|
|
They have the form
|
|
.Pa hostname.cert.pem
|
|
and
|
|
.Pa hostname.key.pem .
|
|
If a certificate or a key doesn't exist for a given hostname, they
|
|
will be generated automatically.
|
|
.It Fl h , Fl -help
|
|
Print the usage and exit.
|
|
.It Fl p Ar port
|
|
The port to listen on, by default 1965.
|
|
.It Fl V , Fl -version
|
|
Print the version and exit.
|
|
.It Fl v
|
|
Verbose mode.
|
|
Multiple
|
|
.Fl v
|
|
options increase the verbosity.
|
|
.It Fl x Ar path
|
|
Enable execution of
|
|
.Sx CGI
|
|
scripts.
|
|
See the description of the
|
|
.Ic cgi
|
|
option in the
|
|
.Sq Servers
|
|
section below to learn how
|
|
.Ar path
|
|
is processed.
|
|
Cannot be provided more than once.
|
|
.It Ar dir
|
|
The root directory to serve.
|
|
By default the current working directory is assumed.
|
|
.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
|
|
Serve the current directory
|
|
.Bd -literal -offset indent
|
|
$ gmid .
|
|
.Ed
|
|
.Pp
|
|
To serve the directory
|
|
.Pa docs
|
|
and enable CGI scripts inside
|
|
.Pa docs/cgi
|
|
.Bd -literal -offset indent
|
|
$ mkdir docs/cgi
|
|
$ cat <<EOF > docs/cgi/hello
|
|
#!/bin/sh
|
|
printf "20 text/plain\er\en"
|
|
echo "hello world"
|
|
EOF
|
|
$ chmod +x docs/cgi/hello
|
|
$ gmid -x '/cgi/*' docs
|
|
.Ed
|
|
.Pp
|
|
To run
|
|
.Nm
|
|
as a deamon 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 startup; if a
|
|
root directory is deleted and then re-created,
|
|
.Nm
|
|
won't be able to serve files inside that directory until a restart.
|
|
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
|