blob: 2ad4faaf46c169a5989d80868578a89319aca91c (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
|
# gnix
a simple stupid reverse proxy
## Features
- Simple to configure (see below)
- Handles connection upgrades correctly by default (websocket, etc.)
- Composable modules
- TLS support
- _TODO: h2; match on uris; connection pooling_
## Quick Start
Run the binary with the a path to the configuration as the first argument. The
configuration file is written in YAML and could look like this:
```toml
# Both the 'http' and 'https' sections are optional
http:
# the value for 'bind' can either be a string or a list of strings
bind: "[::1]:8080"
https:
bind: "[::1]:8443"
tls_cert: "ssl/cert.pem"
tls_key: "ssl/key.pem" # only accepts pkcs8
# !hosts multiplexes requests for different hostnames.
handler: !hosts
# requests for `example.org` are forwarded to 127.0.0.1:8000
"example.org": !proxy { backend: "127.0.0.1:8000" }
# requests for `mydomain.com` will access files from /srv/http
"mydomain.com": !files
root: "/srv/http"
index: true
"panel.mydomain.com": !access_log
```
## Reference
- **section `http`**
- `bind`: string or list of strings with addresses to listen on.
- **section `https`**
- `bind`: string or list of strings with addresses to listen on.
- `tls_cert`: path to the SSL certificate. (Sometimes called `fullchain.pem`)
- `tls_key`: path to the SSL key. (Often called `key.pem` or `privkey.pem`)
- **section `limits`**
- Note: Make sure you do not exceed the maximum file descriptor limit on your
platform.
- `max_incoming_connections` number of maximum incoming (downstream)
connections. excess connections are rejected. Default: 512
- `max_outgoing_connections` number of maximum outgoing (upstream)
connections. excess connections are rejected. Default: 256
- **section `handler`**
- A module to handle all requests. Usually an instance of `hosts`.
- `watch_config`: boolean if to watch the configuration file for changes and
apply them accordingly. Default: true (Note: This will watch the entire parent
directory of the config since most editors first move the file. Currently any
change will trigger a reload. TODO)
### Modules
- **module `hosts`**
- Hands over the requests to different modules depending on the `host` header.
- Takes a map from hostname (string) to handler (module)
- **module `proxy`**
- Forwards the request as-is to some other server. the `x-real-ip` header is
injected into the request. Connection upgrades are handled by direct
forwarding of network traffic.
- `backend`: socket address (string) to the backend server
- **module `files`**
- Provides a simple built-in fileserver. The server handles `accept-ranges`.
The `content-type` header is inferred from the file extension and falls back
to `application/octet-stream`. If a directory is requested `index.html` will
be served or else when indexing is enabled, `index.banner.html` will be
prepended to the response.
- `root`: root directory to be served (string)
- `index`: enables directory indexing (boolean)
- **module `http_basic_auth`**
- Filters requests via HTTP Basic Authentification. Unauthorized clients will
be challenged on every request.
- `realm`: describes what the user is logging into (most modern browsers dont show this anymore -_-)
- `valid`: list of valid logins (string) in the format `<username>:<password>`
(password in plain text). TODO: hashing
- `next`: a module to handle this request on successfully authentificated. (module)
- **module `access_log`**
- Logs requests to a file.
- `file`: file path to log (string)
- `reject_on_fail`: rejects requests if log could not be written (boolean)
- `flush`: flushes log on every request (boolean)
- `next`: module for further handling of the request (module)
- **module `error`**
- Rejects every request with a custom error message.
- Takes an error message (string)
## License
AGPL-3.0-only; see [COPYING](./COPYING)
|
