lilin

Lilin is service monitoring for HTTP and TCP services.

Features,

Building

To build lilin program, you need Go compiler. 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.

Usage

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.

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,

[default]
down_template = Service {{.ID}} is down: {{.Error}}
up_template = Service {{.ID}} is alive!

[server]
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,

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

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

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

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

Example of service configuration that monitor TCP service at 127.0.0.1:5432 every 90 seconds with 30 seconds timeout,

[service]
name = my-tcp-service
address = tcp://127.0.0.1:5432
interval = 90s
timeout = 30s

Notification

Lilin send the down notification when the service check failed three times consecutively.

Lilin support sending notification to,

Each notification can have their own down_template and up_template.

See the next section on how to use the notification.

Mattermost incoming webhook

In the main configuration, add the section "notif" with the following format,

[notif]
kind = mattermost
remote_url = # The incoming webhook URL.
channel = # The channel where the notification will be placed.
down_template = # Message template when service is down.
up_template = # Message template when service is up.

SMTP server

[notif]
kind = smtp
remote_url = <scheme "://" (domain | ip_address [":" port])>
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. The scheme in remote_url can be set either to,

The recipient field can be defined multiple times.

License

Lilin is licensed under GPL version 3.0. See LICENSE file for more information.

Links

Project page.

Repository - The repository of this software project.

Mailing list - Place for discussion and sending patches.

Issues - Place to open new issue or request for new feature.

Changelog - Log for each release.