diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 140 |
1 files changed, 139 insertions, 1 deletions
@@ -1,5 +1,127 @@ +<!-- +SPDX-License-Identifier: GPL-3.0-only +SPDX-FileCopyrightText: 2025 M. Shulhan <ms@kilabit.info> +--> + # lilin +Lilin is service monitoring for HTTP and TCP services. + +Features, + +- Monitoring HTTP, TCP, UDP services +- Sending notification when service up or down through, + - Mattermost incoming webhook + +## Building + +To build lilin program, you need +[Go compiler](https://go.dev/dl). +Once you have installed and setup the Go compiler, run the following command +to build the program, + + $ go build ./cmd/lilin + +The above command will create executable file named `lilin` in the current +directory. + +## Command options + +The lilin program has the following options, + +**-basedir**:: set the base directory for reading main configuration, +service configurations, and storing the service logs. +If not defined, its default to "/". + +## Main configuration + +Lilin read the main configuration from `${BASEDIR}etc/lilin/lilin.cfg`. +The configuration is written in +[INI file format](https://pkg.go.dev/git.sr.ht/~shulhan/pakakeh.go/lib/ini). + +The `$BASEDIR` variable can be changes during running lilin program with +`-basedir` option. +For example, + + $ lilin -basedir ./monitoring + +The `lilin.cfg` has the following format, + +``` +[server] +address = +``` + +**address**:: define the HTTP server address to view the status of monitored +services from web browser, default to 127.0.0.1:14507. + +## Monitoring services + +Lilin monitor the services by reading each service configuration inside the +`${BASEDIR}etc/lilin/service.d/` directory. +Each service configuration is written in INI file format and must have +`.cfg` file extension. + +The service configuration has the following format, + +``` +[service] +name = +address = +method = +timeout = +interval = +``` + +**name**:: The human readable service name. + +**address**:: The address of service to be monitored, using scheme based. +For example + +- `http://example.com/health` for monitoring HTTP service, +- `https://example.com:8443/health` for monitoring HTTPS service, +- `tcp://127.0.0.1:22` for monitoring TCP service, +- `udp://127.0.0.1:53` for monitoring UDP service. + +**method**:: The HTTP method to be used to inquiry the HTTP or HTTPS +service, default to GET. +Supported method are DELETE, GET, HEAD, PATCH, POST, or PUT. + +**timeout**:: Timeout for connecting and reading the response, default to 5 +seconds. +Timeout format is using suffix `s` for second, `m` for minute, and `h` for +hour. + +**interval**:: Interval between each scan, default and minimum value is 10 +seconds. +Interval format is using suffix `s` for second, `m` for minute, and `h` for +hour. + +For example to monitor HTTP service at http://127.0.0.1:8080 every 5 minutes +using HTTP method `HEAD` with timeout 60 seconds, create file named +`myhttp.cfg` inside the `$BASEDIR/etc/lilin/service.d/` directory with the +following content, + +``` +[service] +name = myhttp +address = http://127.0.0.1:8080 +method = HEAD +interval = 5m +timeout = 60s +``` + +Sample of service configuration that monitor TCP service at +127.0.0.1:5432 every 90 seconds with timeout 30 seconds, + +``` +[service] +name = my-tcp-service +address = tcp://127.0.0.1:5432 +interval = 90s +timeout = 30s +``` + ## Notification Lilin support sending notification to, @@ -10,7 +132,7 @@ See the next section on how to use the notification. ### Mattermost incoming webhook -In the server configuration, add the section "notif" with the following +In the main configuration, add the section "notif" with the following format, ``` @@ -47,3 +169,19 @@ will be rendered as ``` 2025-09-26 06:38:11 +0000 UTC: Service http-server is down: 503 Service Unavailable ``` + +## Links + +[Project page](https://sr.ht/~shulhan/lilin). + +[Repository](https://git.sr.ht/~shulhan/lilin) -- +The repository of this software project. + +[Mailing list](https://lists.sr.ht/~shulhan/lilin) -- +Place for discussion and sending patches. + +[Issues](https://todo.sr.ht/~shulhan/lilin) -- +Place to open new issue or request for new feature. + +[Changelog](https://kilabit.info/project/lilin/CHANGELOG.html) - Log for +each release. |