diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 113 |
1 files changed, 65 insertions, 48 deletions
@@ -9,9 +9,10 @@ Lilin is service monitoring for HTTP and TCP services. Features, -- Monitoring HTTP, TCP, UDP services +- Monitoring HTTP and TCP services - Sending notification when service up or down through, - Mattermost incoming webhook + - SMTP server (email) ## Building @@ -25,7 +26,9 @@ to build the program, The above command will create executable file named `lilin` in the current directory. -## Command options +## Usage + +### Command options The lilin program has the following options, @@ -33,7 +36,7 @@ The lilin program has the following options, service configurations, and storing the service logs. If not defined, its default to "/". -## Main configuration +### Main configuration Lilin read the main configuration from `${BASEDIR}etc/lilin/lilin.cfg`. The configuration is written in @@ -48,17 +51,52 @@ For example, The `lilin.cfg` has the following format, ``` +[default] +down_template = Service {{.ID}} is down: {{.Error}} +up_template = Service {{.ID}} is alive! + [server] -address = +address = 127.0.0.1:14507 +``` + +The `[default]` section define the default value for common configuration. + +The `down_template` and `up_template` define the text template to be send +for notification when the service down or up. +If its empty, it will use the default one (as written above). +The `down_template` and `up_template` can contains the following variables, + +- .ID: the service ID +- .At: the time when service up or down +- .Error: the error message that cause the service marked as down + +For example, given the following scan report value, + +``` +.ID: http-server +.At: 2025-09-26 06:38:11 +0000 UTC +.Error: 503 Service Unavailable +``` + +The following `down_template` + +``` +{{.At}}: Service {{.ID}} is down: {{.Error}} +``` + +will be rendered as + +``` +2025-09-26 06:38:11 +0000 UTC: Service http-server is down: 503 Service Unavailable ``` -**address**:: define the HTTP server address to view the status of monitored -services from web browser, default to 127.0.0.1:14507. +The server `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 +### Monitoring services Lilin monitor the services by reading each service configuration inside the -`${BASEDIR}etc/lilin/service.d/` directory. +`${BASEDIR}/etc/lilin/service.d/` directory. Each service configuration is written in INI file format and must have `.cfg` file extension. @@ -81,7 +119,6 @@ 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. @@ -111,7 +148,7 @@ interval = 5m timeout = 60s ``` -Sample of service configuration that monitor TCP service at +Example of service configuration that monitor TCP service at 127.0.0.1:5432 every 90 seconds with 30 seconds timeout, ``` @@ -124,11 +161,16 @@ timeout = 30s ## Notification +Lilin send the down notification when the service check failed three times +consecutively. + Lilin support sending notification to, - Mattermost using incoming webhook. - SMTP server (email). +Each notification can have their own `down_template` and `up_template`. + See the next section on how to use the notification. ### Mattermost incoming webhook @@ -147,32 +189,6 @@ down_template = # Message template when service is down. up_template = # Message template when service is up. ``` -The `down_template` and `up_template` can contains the following variables, - -- .ID: the service ID -- .At: the time when service up or down -- .Error: the error message that cause the service marked as down - -For example, given the following scan report value, - -``` -.ID: http-server -.At: 2025-09-26 06:38:11 +0000 UTC -.Error: 503 Service Unavailable -``` - -The following `down_template` - -``` -{{.At}}: Service {{.ID}} is down: {{.Error}} -``` - -will be rendered as - -``` -2025-09-26 06:38:11 +0000 UTC: Service http-server is down: 503 Service Unavailable -``` - <!--}}}--> ### SMTP server @@ -183,9 +199,11 @@ will be rendered as [notif] kind = smtp remote_url = <scheme "://" (domain | ip_address [":" port])> -user = -password = -recipient = +user = # Sender email address. +password = # Sender SMTP password for authentication. +recipient = # Email address that receive notification. +down_template = # Custom text to be send when service down. +up_template = # Custom text to be send when service up. ``` The `remote_url` define the SMTP server address. @@ -194,27 +212,26 @@ The scheme in `remote_url` can be set either to, - smtps: implicit TLS, connect to port 465 by default - smtp+starttls: explicit STARTTLS, connect to port 587 by default. -The `user` field define the sender email address. +The `recipient` field can be defined multiple times. -The `password` field define the password for authentication, on behalf of -the `user`. +<!--}}}--> -The `recipient` is the email address that will receives the notification. -This field can be defined multiple times. +## License -<!--}}}--> +Lilin is licensed under GPL version 3.0. +See LICENSE file for more information. ## Links [Project page](https://sr.ht/~shulhan/lilin). -[Repository](https://git.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) -- +[Mailing list](https://lists.sr.ht/~shulhan/lilin) - Place for discussion and sending patches. -[Issues](https://todo.sr.ht/~shulhan/lilin) -- +[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 |