Blame
Date:
Fri Apr 8 14:08:33 2022 UTC
Message:
rework the 'running gmid as a daemon' example a bit
001
2021-01-02
op
.\" Copyright (c) 2021, 2022 Omar Polo <op@omarpolo.com>
002
2020-10-02
op
.\"
003
2020-10-02
op
.\" Permission to use, copy, modify, and distribute this software for any
004
2020-10-02
op
.\" purpose with or without fee is hereby granted, provided that the above
005
2020-10-02
op
.\" copyright notice and this permission notice appear in all copies.
006
2020-10-02
op
.\"
007
2020-10-02
op
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
008
2020-10-02
op
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
009
2020-10-02
op
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
010
2020-10-02
op
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
011
2020-10-02
op
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
012
2020-10-02
op
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
013
2020-10-02
op
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
014
2022-04-07
op
.Dd $Mdocdate: April 7 2022$
015
2021-04-16
op
.Dt GMID 1
016
2020-10-02
op
.Os
017
2020-10-02
op
.Sh NAME
018
2020-10-02
op
.Nm gmid
019
2021-01-30
op
.Nd simple and secure Gemini server
020
2020-10-02
op
.Sh SYNOPSIS
021
2020-10-02
op
.Nm
022
2020-10-02
op
.Bk -words
023
2021-02-04
op
.Op Fl fnv
024
2021-01-15
op
.Op Fl c Ar config
025
2021-06-29
op
.Op Fl D Ar macro Ns = Ns Ar value
026
2021-04-28
op
.Op Fl P Ar pidfile
027
2021-02-04
op
.Ek
028
2021-02-04
op
.Nm
029
2021-02-04
op
.Bk -words
030
2021-06-29
op
.Op Fl 6hVv
031
2022-01-04
op
.Op Fl d Ar certs-dir
032
2021-01-25
op
.Op Fl H Ar hostname
033
2020-11-18
op
.Op Fl p Ar port
034
2022-01-04
op
.Op Fl x Ar cgi
035
2022-01-04
op
.Op Ar dir
036
2020-10-02
op
.Ek
037
2020-10-02
op
.Sh DESCRIPTION
038
2020-10-02
op
.Nm
039
2021-05-24
op
is a simple and minimal gemini server that can serve static files,
040
2021-05-24
op
execute CGI scripts and talk to FastCGI applications.
041
2021-01-18
op
It can run without a configuration file with a limited set of features
042
2021-01-18
op
available.
043
2021-02-04
op
.Pp
044
2021-02-04
op
.Nm
045
2021-02-04
op
rereads the configuration file when it receives
046
2021-02-04
op
.Dv SIGHUP .
047
2020-10-02
op
.Pp
048
2021-01-18
op
The options are as follows:
049
2021-01-25
op
.Bl -tag -width 14m
050
2022-01-04
op
.It Fl c Ar config
051
2021-01-25
op
Specify the configuration file.
052
2021-06-29
op
.It Fl D Ar macro Ns = Ns Ar value
053
2021-06-29
op
Define
054
2021-06-29
op
.Ar macro
055
2021-06-29
op
to be set to
056
2021-06-29
op
.Ar value
057
2021-06-29
op
on the command line.
058
2021-06-29
op
Overrides the definition of
059
2021-06-29
op
.Ar macro
060
2021-06-29
op
in the config file if present.
061
2021-01-27
op
.It Fl f
062
2021-01-27
op
Stays and logs on the foreground.
063
2021-01-18
op
.It Fl n
064
2021-01-18
op
Check that the configuration is valid, but don't start the server.
065
2021-10-09
op
If specified two or more time, dump the configuration in addition to
066
2021-10-09
op
verify it.
067
2022-01-04
op
.It Fl P Ar pidfile
068
2021-07-29
op
Write daemon's pid to the given location.
069
2021-07-09
op
.Ar pidfile
070
2021-07-09
op
will also act as lock: if another process is holding a lock on that
071
2021-07-09
op
file,
072
2021-04-28
op
.Nm
073
2021-07-09
op
will refuse to start.
074
2021-01-18
op
.El
075
2020-10-02
op
.Pp
076
2021-01-18
op
If no configuration file is given,
077
2020-10-03
op
.Nm
078
2021-12-02
op
runs in
079
2021-12-02
op
.Dq config-less mode
080
2021-12-02
op
.Pq i.e. runs in the foreground to serve a directory from the shell
081
2021-12-02
op
and looks for the following options
082
2021-01-25
op
.Bl -tag -width 14m
083
2021-01-11
op
.It Fl 6
084
2021-01-11
op
Enable IPv6.
085
2022-01-04
op
.It Fl d Ar certs-path
086
2021-01-25
op
Directory where certificates for the config-less mode are stored.
087
2021-07-29
op
By default it is
088
2021-01-25
op
.Pa $XDG_DATA_HOME/gmid ,
089
2021-01-25
op
i.e.
090
2021-01-25
op
.Pa ~/.local/share/gmid .
091
2021-01-25
op
.It Fl H Ar hostname
092
2021-07-09
op
The hostname
093
2021-07-29
op
.Po
094
2021-07-09
op
.Ar localhost
095
2021-07-29
op
by default
096
2021-07-29
op
.Pc .
097
2021-01-25
op
Certificates for the given
098
2021-01-25
op
.Ar hostname
099
2021-01-25
op
are searched inside the
100
2022-01-04
op
.Ar certs-dir
101
2021-01-25
op
directory given with the
102
2021-01-25
op
.Fl d
103
2021-01-25
op
option.
104
2021-01-30
op
They have the form
105
2021-01-25
op
.Pa hostname.cert.pem
106
2021-01-25
op
and
107
2021-01-25
op
.Pa hostname.key.pem .
108
2021-07-29
op
If a certificate or a key doesn't exist for a given hostname, they
109
2021-07-29
op
will be generated automatically.
110
2021-06-29
op
.It Fl h , Fl -help
111
2020-10-03
op
Print the usage and exit.
112
2020-11-18
op
.It Fl p Ar port
113
2021-01-18
op
The port to listen on, by default 1965.
114
2021-06-29
op
.It Fl V , Fl -version
115
2021-06-29
op
Print the version and exit.
116
2021-01-27
op
.It Fl v
117
2021-02-07
op
Verbose mode.
118
2021-02-07
op
Multiple
119
2021-02-07
op
.Fl v
120
2021-02-07
op
options increase the verbosity.
121
2022-01-04
op
.It Fl x Ar path
122
2021-07-29
op
Enable execution of
123
2021-07-29
op
.Sx CGI
124
2021-07-29
op
scripts.
125
2021-01-18
op
See the description of the
126
2021-01-18
op
.Ic cgi
127
2021-07-29
op
option in the
128
2021-01-18
op
.Sq Servers
129
2021-07-29
op
section below to learn how
130
2022-01-04
op
.Ar path
131
2021-01-18
op
is processed.
132
2021-01-18
op
Cannot be provided more than once.
133
2022-01-04
op
.It Ar dir
134
2021-01-25
op
The root directory to serve.
135
2021-01-25
op
By default the current working directory is assumed.
136
2021-01-01
op
.El
137
2021-07-29
op
.Sh LOGGING
138
2021-07-29
op
Messages and requests are logged by
139
2021-07-29
op
.Xr syslog 3
140
2021-07-29
op
using the
141
2021-07-29
op
.Dv DAEMON
142
2021-07-29
op
facility or printed on
143
2021-07-29
op
.Em stderr .
144
2021-07-29
op
.Pp
145
2021-07-29
op
Requests are logged with the
146
2021-07-29
op
.Dv NOTICE
147
2021-07-29
op
severity.
148
2021-07-29
op
Each request log entry has the following fields, separated by
149
2021-07-29
op
whitespace:
150
2021-07-29
op
.Pp
151
2021-07-29
op
.Bl -bullet -compact
152
2021-07-29
op
.It
153
2021-07-29
op
Client IP address and the source port number, separated by a colon
154
2021-07-29
op
.It
155
2021-07-29
op
.Sy GET
156
2021-07-29
op
keyword
157
2021-07-29
op
.It
158
2021-07-29
op
Request URL
159
2021-07-29
op
.It
160
2021-07-29
op
Response status
161
2021-07-29
op
.It
162
2021-07-29
op
Response meta
163
2021-07-29
op
.El
164
2020-10-02
op
.Sh EXAMPLES
165
2021-01-25
op
Serve the current directory
166
2020-10-02
op
.Bd -literal -offset indent
167
2021-01-25
op
$ gmid .
168
2020-10-02
op
.Ed
169
2020-10-02
op
.Pp
170
2021-01-25
op
To serve the directory
171
2021-01-25
op
.Pa docs
172
2021-01-25
op
and enable CGI scripts inside
173
2021-07-09
op
.Pa docs/cgi
174
2020-11-06
op
.Bd -literal -offset indent
175
2021-01-25
op
$ mkdir docs/cgi
176
2021-04-15
op
$ cat <<EOF > docs/cgi/hello
177
2020-11-06
op
#!/bin/sh
178
2021-07-21
op
printf "20 text/plain\er\en"
179
2021-01-25
op
echo "hello world"
180
2020-11-06
op
EOF
181
2021-01-25
op
$ chmod +x docs/cgi/hello
182
2021-03-20
op
$ gmid -x '/cgi/*' docs
183
2020-11-06
op
.Ed
184
2021-07-29
op
.Pp
185
2022-04-08
op
To run
186
2021-07-29
op
.Nm
187
2022-04-08
op
as a deamon a configuration file and a X.509 certificate must be provided.
188
2022-04-08
op
A self-signed certificate, which are commonly used in the Geminispace,
189
2022-04-08
op
can be generated using for e.g.\&
190
2022-04-08
op
.Xr openssl 1 :
191
2021-07-29
op
.Bd -literal -offset indent
192
2022-04-08
op
# openssl req \-x509 \-newkey rsa:4096 \-nodes \e
193
2022-04-08
op
\-keyout /etc/ssl/private/example.com.key \e
194
2022-04-08
op
\-out /etc/ssl/example.com.pem \e
195
2022-04-08
op
\-days 365 \-subj "/CN=example.com"
196
2021-07-29
op
# chmod 600 /etc/ssl/example.com.crt
197
2021-07-29
op
# chmod 600 /etc/ssl/private/example.com.key
198
2021-07-29
op
.Ed
199
2021-07-29
op
.Pp
200
2022-04-08
op
Then
201
2022-04-07
op
.Nm
202
2022-04-08
op
can be started with
203
2021-01-18
op
.Bd -literal -offset indent
204
2022-04-08
op
# gmid -c /etc/gmid.conf
205
2021-01-18
op
.Ed
206
2022-04-07
op
.Sh SEE ALSO
207
2022-04-07
op
.Xr gmid.conf 5
208
2021-01-09
op
.Sh ACKNOWLEDGEMENTS
209
2021-01-09
op
.Nm
210
2021-01-18
op
uses the
211
2021-01-18
op
.Dq Flexible and Economical
212
2021-01-18
op
UTF-8 decoder written by
213
2021-01-25
op
.An Bjoern Hoehrmann .
214
2021-01-30
op
.Sh AUTHORS
215
2021-01-30
op
.An -nosplit
216
2021-01-30
op
The
217
2021-01-30
op
.Nm
218
2021-01-30
op
program was written by
219
2021-01-30
op
.An Omar Polo Aq Mt op@omarpolo.com .
220
2020-10-02
op
.Sh CAVEATS
221
2020-10-02
op
.Bl -bullet
222
2020-10-02
op
.It
223
2021-07-09
op
All the root directories are opened during the daemon startup; if a
224
2021-07-09
op
root directory is deleted and then re-created,
225
2021-01-18
op
.Nm
226
2021-01-18
op
won't be able to serve files inside that directory until a restart.
227
2021-07-09
op
This restriction only applies to the root directories and not their
228
2021-07-09
op
content.
229
2020-12-25
op
.It
230
2021-01-30
op
a %2F sequence is indistinguishable from a literal slash: this is not
231
2021-01-30
op
RFC3986-compliant.
232
2020-12-25
op
.It
233
2021-01-30
op
a %00 sequence is treated as invalid character and thus rejected.
234
2020-10-02
op
.El
Omar Polo