Mercurial > prosody-modules

annotate mod_http_health/README.md @ 5689:09233b625cb9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_health: Copypaste IP access control code
author Kim Alvefur <zash@zash.se>
date Sun, 05 Nov 2023 19:22:46 +0100
parents 9bcd257dea4e
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5667
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 Simple module adding an endpoint meant to be used for health checks.
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
2
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
3 # Configuration
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
5 After installing, enable by adding to [`modules_enabled`][doc:modules_enabled] like many other modules:
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
7 ``` lua
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
8 -- in the global section
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9 modules_enabled = {
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
10 -- Other globally enabled modules here...
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11 "http_health"; -- add
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12 }
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13 ```
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14
5689
09233b625cb9 mod_http_health: Copypaste IP access control code
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
15 ## Access control
09233b625cb9 mod_http_health: Copypaste IP access control code
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
16
09233b625cb9 mod_http_health: Copypaste IP access control code
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
17 By default only access via localhost is allowed. This can be adjusted with `http_health_allow_ips`. The following example shows the default:
09233b625cb9 mod_http_health: Copypaste IP access control code
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
18
09233b625cb9 mod_http_health: Copypaste IP access control code
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
19 ```
09233b625cb9 mod_http_health: Copypaste IP access control code
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
20 http_health_allow_ips = { "::1"; "127.0.0.1" }
09233b625cb9 mod_http_health: Copypaste IP access control code
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
21 ```
09233b625cb9 mod_http_health: Copypaste IP access control code
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
22
09233b625cb9 mod_http_health: Copypaste IP access control code
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
23 Access can also be granted to one IP range via CIDR notation:
09233b625cb9 mod_http_health: Copypaste IP access control code
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
24
09233b625cb9 mod_http_health: Copypaste IP access control code
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
25 ```
09233b625cb9 mod_http_health: Copypaste IP access control code
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
26 http_health_allow_cidr = "172.17.2.0/24"
09233b625cb9 mod_http_health: Copypaste IP access control code
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
27 ```
09233b625cb9 mod_http_health: Copypaste IP access control code
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
28
09233b625cb9 mod_http_health: Copypaste IP access control code
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
29 The default for `http_health_allow_cidr` is empty.
09233b625cb9 mod_http_health: Copypaste IP access control code
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
30
5667
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
31 # Details
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
32
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
33 Adds a `http://your.prosody.example:5280/health` endpoint that returns either HTTP status code 200 when all appears to be good or 500 when any module
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
34 [status][doc:developers:moduleapi#logging-and-status] has been set to `error`.
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
35
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36 # See also
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
37
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
38 - [mod_measure_modules] provides module statues via OpenMetrics
9bcd257dea4e mod_http_health: Provide a health check HTTP endpoint
Kim Alvefur <zash@zash.se>
parents:
diff changeset
39 - [mod_http_status] provides all module status details as JSON via HTTP