Blame
Date:
Tue Mar 29 12:25:18 2022 UTC
Message:
add a "contributing" section
001
2021-01-11
op
# gmid
002
2020-10-02
op
003
2021-02-08
op
gmid is a fast Gemini server written with security in mind. I
004
2021-02-08
op
initially wrote it to serve static files, but it has grown into a
005
2021-02-08
op
featureful server.
006
2020-10-02
op
007
2020-10-02
op
008
2021-01-11
op
## Features
009
2020-10-02
op
010
2021-01-30
op
(random order)
011
2021-01-30
op
012
2021-04-29
op
- sandboxed by default on OpenBSD, Linux and FreeBSD
013
2021-02-08
op
- reconfiguration: reload the running configuration without
014
2021-02-08
op
interruption
015
2021-02-23
op
- automatic redirect/error pages (see `block return`)
016
2021-01-13
op
- IRI support (RFC3987)
017
2021-01-30
op
- automatic certificate generation for config-less mode
018
2021-12-29
op
- reverse proxying
019
2021-06-11
op
- CGI and FastCGI support
020
2021-04-29
op
- virtual hosts
021
2021-04-29
op
- location rules
022
2021-02-08
op
- event-based asynchronous I/O model
023
2021-04-29
op
- low memory footprint
024
2021-01-11
op
- small codebase, easily hackable
025
2020-10-02
op
026
2020-10-03
op
027
2021-01-27
op
## Internationalisation (IRIs, UNICODE, punycode, all that stuff)
028
2021-01-27
op
029
2021-01-27
op
Even thought the current Gemini specification doesn't mention anything
030
2021-01-30
op
in this regard, I do think these are important things and so I tried
031
2021-01-30
op
to implement them in the most user-friendly way I could think of.
032
2021-01-27
op
033
2021-01-30
op
For starters, gmid has full support for IRI (RFC3987 —
034
2021-01-29
op
Internationalized Resource Identifiers). IRIs are a superset of URIs,
035
2021-01-27
op
so there aren't incompatibilities with URI-only clients.
036
2021-01-27
op
037
2021-01-30
op
There is full support also for punycode. In theory, the user doesn't
038
2021-01-27
op
even need to know that punycode is a thing. The hostname in the
039
2021-01-30
op
configuration file can (and must be) in the decoded form (e.g. `naïve`
040
2021-01-30
op
and not `xn--nave-6pa`), gmid will do the rest.
041
2021-01-27
op
042
2021-01-30
op
The only missing piece is UNICODE normalisation of the IRI path: gmid
043
2021-01-30
op
doesn't do that (yet).
044
2021-01-27
op
045
2021-01-27
op
046
2021-02-06
op
## Configuration
047
2021-02-06
op
048
2021-02-06
op
gmid has a rich configuration file, heavily inspired by OpenBSD'
049
2021-04-29
op
httpd, with every detail carefully documented in the manpage. Here's
050
2021-04-29
op
a minimal example of a config file:
051
2021-02-06
op
052
2021-02-06
op
```conf
053
2021-04-29
op
server "example.com" {
054
2021-04-29
op
cert "/path/to/cert.pem"
055
2021-04-29
op
key "/path/to/key.pem"
056
2021-04-29
op
root "/var/gemini/example.com"
057
2021-04-29
op
}
058
2021-04-29
op
```
059
2021-04-29
op
060
2021-07-06
op
and a slightly more complex one
061
2021-04-29
op
062
2021-04-29
op
```conf
063
2021-02-06
op
ipv6 on # enable ipv6
064
2021-02-06
op
065
2021-07-06
op
# define a macro
066
2021-07-06
op
cert_root = "/path/to/keys"
067
2021-07-06
op
068
2021-02-06
op
server "example.com" {
069
2021-04-29
op
alias "foobar.com"
070
2021-02-06
op
071
2021-07-06
op
cert $cert_root "/example.com.crt"
072
2021-07-06
op
key $cert_root "/example.com.pem"
073
2021-04-29
op
root "/var/gemini/example.com"
074
2021-02-06
op
075
2021-04-29
op
# lang for text/gemini files
076
2021-07-06
op
lang "en"
077
2021-04-29
op
078
2021-04-29
op
# execute CGI scripts in /cgi/
079
2021-04-29
op
cgi "/cgi/*"
080
2021-04-29
op
081
2021-04-29
op
# only for locations that matches /files/*
082
2021-04-29
op
location "/files/*" {
083
2021-04-29
op
# generate directory listings
084
2021-04-29
op
auto index on
085
2021-04-29
op
}
086
2021-04-29
op
087
2021-04-29
op
location "/repo/*" {
088
2021-04-29
op
# change the index file name
089
2021-04-29
op
index "README.gmi"
090
2021-07-06
op
lang "it"
091
2021-04-29
op
}
092
2021-02-06
op
}
093
2021-02-06
op
```
094
2021-02-06
op
095
2021-02-06
op
096
2021-01-11
op
## Building
097
2020-10-02
op
098
2022-03-29
op
gmid depends on libevent2, OpenSSL/LibreSSL and libtls (provided
099
2022-03-29
op
either by LibreSSL or libretls). At build time, yacc (or GNU bison)
100
2022-03-29
op
is also needed.
101
2020-10-02
op
102
2021-01-17
op
The build is as simple as
103
2020-10-02
op
104
2021-01-30
op
./configure
105
2021-01-11
op
make
106
2020-10-02
op
107
2021-03-29
op
or `make static` to build a statically-linked executable.
108
2021-03-29
op
109
2021-01-21
op
If the configure scripts fails to pick up something, please open an
110
2021-01-21
op
issue or notify me via email.
111
2021-01-21
op
112
2021-01-17
op
To install execute:
113
2021-01-16
op
114
2021-01-17
op
make install
115
2021-01-17
op
116
2021-04-25
op
Please keep in mind that the master branch, from time to time, may be
117
2021-04-25
op
accidentally broken on some platforms. gmid is developed primarily on
118
2021-04-25
op
OpenBSD/amd64 and commits on the master branch don't get always tested
119
2021-04-25
op
in other OSes. Before tagging a release however, a comprehensive
120
2021-04-27
op
testing on various platform is done to ensure that everything is
121
2021-04-27
op
working as intended.
122
2021-04-25
op
123
2021-04-25
op
124
2021-01-22
op
### Testing
125
2021-01-22
op
126
2021-01-23
op
Execute
127
2021-01-22
op
128
2021-01-22
op
make regress
129
2021-01-22
op
130
2022-02-18
op
to start the suite. Keep in mind that the regression tests needs to
131
2021-01-30
op
create files inside the `regress` directory and bind the 10965 port.
132
2021-01-22
op
133
2021-01-22
op
134
2022-03-29
op
## Contributing
135
2022-03-29
op
136
2022-03-29
op
Any form of contribution is welcome, not only patches or bug reports.
137
2022-03-29
op
If you have a sample configuration for some specific use-case, a
138
2022-03-29
op
script or anything that could be useful to others, consider adding it
139
2022-03-29
op
to the `contrib` directory.
140
2022-03-29
op
141
2022-03-29
op
142
2021-01-16
op
## Architecture/Security considerations
143
2021-01-16
op
144
2021-02-23
op
gmid is composed by four processes: the parent process, the logger,
145
2021-02-23
op
the listener and the executor. The parent process is the only one
146
2021-02-23
op
that doesn't drop privileges, but all it does is to wait for a SIGHUP
147
2021-02-23
op
to reload the configuration and spawn a new generation of children
148
2021-07-29
op
process. The logger process gathers the logs and prints 'em to
149
2021-02-23
op
stderr or syslog (for the time being.) The listener process is the
150
2021-02-23
op
only one that needs internet access and is sandboxed by default. The
151
2021-07-09
op
executor process exists only to fork and execute CGI scripts, and
152
2021-07-09
op
optionally to connect to FastCGI applications.
153
2021-01-16
op
154
2021-10-24
op
On OpenBSD the processes are all `pledge(2)`d and `unveil(2)`ed.
155
2021-01-16
op
156
2021-03-20
op
On FreeBSD, the listener and logger process are sandboxed with `capsicum(4)`.
157
2021-01-17
op
158
2021-01-30
op
On Linux, a `seccomp(2)` filter is installed in the listener to allow
159
2021-01-30
op
only certain syscalls, see [sandbox.c](sandbox.c) for more information
160
2021-09-19
op
about the BPF program. If available, landlock is used to limit the
161
2021-09-19
op
portion of the file system gmid can access (requires linux 5.13+.)
162
2021-01-17
op
163
2021-06-04
op
In any case, it's advisable to run gmid inside some sort of
164
2021-01-25
op
container/jail/chroot.
Omar Polo