Checking Your Website

With the basics operational, you can now add various endpoints to monitor. Gatus requires the name and URL for each endpoint, but many other attributes are optional or have default values. For instance, the default interval for an endpoint check is one minute, so this line could be omitted in Listing 1 (line 8) and Listing 3 (line 4). Beyond the ICMP type of check I initially added, there are various other types of endpoint checks. I'll review some common ones.

The most common type of endpoint check will likely be for a web page. You might want Gatus to visit a web page and mark it as healthy if the web server returns HTTP 200 OK as the response code. However, this only verifies that the web server returns something without errors. To ensure it returns the correct page, you can add another check that finds a text pattern in the response body. For instance, I configured Gatus to verify that my name appears in my website's response body as shown in Listing 4 (and the result depicted in Figure 4). If the web server returns an empty page due to some misconfiguration, Gatus will mark this endpoint as unhealthy.

01 endpoints:
02   - name: Website
03     url: "https://koen.vervloesem.eu"
04     conditions:
05       - "[STATUS] == 200"
06       - "[BODY] == pat(*Koen Vervloesem*)"

Figure 4: Gatus checks for my name in the body of my web page.

Another useful check is whether your web server's domain still resolves to the correct IP address. Gatus can check this with a dns endpoint: You specify an endpoint with the URL of the DNS server to use, the domain you want to verify as the query name, and "A" as the query type ("A" signifies an IPv4 address query). In the conditions, you check for the correct IP address in the body and the response code NOERROR, as specified in Listing 5. Perform a similar check for the server's IPv6 address using the "AAAA" query type. Using these checks, Gatus immediately marks the endpoint as unhealthy if a DNS issue arises.

01   - name: Web server DNS IPv4
02     url: "1.1.1.1"
03     dns:
04       query-name: "koen.vervloesem.eu"
05       query-type: "A"
06     conditions:
07       - "[BODY] == 37.252.126.12"
08       - "[DNS_RCODE] == NOERROR"

Additionally, you can verify if a server accepts an SSH connection, as shown in Listing 6. By not providing a username, password, or private key, this simply confirms whether a connection is possible. To verify successful login, specify the username along with a password or private key.

01   - name: Web server SSH
02     url: "ssh://koen.vervloesem.eu"
03     ssh:
04       username: ""
05       password: ""
06       private-key: ""
07     conditions:
08       - "[CONNECTED] == true"
09       - "[STATUS] == 0"

You can also monitor a domain's expiration, as well as a TLS certificate. Because domain expiration checks use an external service that throttles your IP address if you send too many requests, Gatus prevents you from using an interval of less than five minutes. An interval of one hour, as shown in line 3 of Listing 7, is probably fine. This checks whether the domain expires within 30 days or the certificate expires within 10 days, which should give you enough time to address the issue. Unfortunately, at the time of writing, Gatus doesn't support domain expiration checks for all top-level domains. For instance, checks for a .eu domain always fail.

01   - name: Web server domain and certificate
02     url: "https://koen.vervloesem.eu"
03     interval: 1h
04     conditions:
05       - "[DOMAIN_EXPIRATION] > 720h"
06       - "[CERTIFICATE_EXPIRATION] > 240h"

Grouping Checks

Most likely, you'll add various checks of different types for the same server or the same checks for related servers. Consequently, you may want to show these checks together. For this purpose, Gatus allows you to group multiple endpoints together on the dashboard. You just need to add a group key to the endpoint in Gatus' configuration file, with the group name as its value.

By assigning a group to all your endpoints and then sorting the endpoints by group in the user interface (in the top right), all endpoints within a group are collected under a heading with the group's name. If all endpoints in the group are healthy, the header shows a green checkmark; otherwise, it displays a red number representing the number of failed endpoints. All endpoints without a group appear in a default group named No Group.

Groups are interesting if you're dealing with a lot of endpoints. You can collapse and expand groups by clicking on their headers, and the green checkmark still shows you the group's health when it's collapsed (Figure 5). If you see a red number, simply expand the group to identify which endpoint is causing the failure. If you prefer sorting endpoints by group as a default, add the following lines to the configuration file:

ui:
  default-sort-by: group

Figure 5: Group your endpoints for a better overview.

Sending Email Alerts

Gatus supports dozens of alerting providers to notify you when an endpoint becomes unhealthy. You can find a comprehensive list on the project's GitHub page. In this article, I'll demonstrate configuring alerts for email and ntfy.

For email alerts, include the section from Listing 8 in Gatus' configuration file. Adjust the settings to match your chosen SMTP provider. For each endpoint that will receive these email alerts, add the following:

alerts:
      - type: email

01 alerting:
02   email:
03     from: "from@example.com"
04     username: "from@example.com"
05     password: "hunter2"
06     host: "mail.example.com"
07     port: 587
08     to: "recipient1@example.com,recipient2@example.com"

By default, Gatus sends an alert after an endpoint fails three times in a row (Figure 6). You can customize this setting for individual endpoints and modify other alert characteristics (see Listing 9 for an example). Notably, you can also receive an alert when a failure is resolved (Figure 7). The full details are documented on Gatus' GitHub page [2].

01 endpoints:
02   - name: example
03     url: "https://example.org"
04     conditions:
05       - "[STATUS] == 200"
06     alerts:
07       - type: email
08         description: "healthcheck failed"
09         failure-threshold: 3
10         success-threshold: 2
11         send-on-resolved: true

Figure 7: Gatus can also alert you if a failure is resolved.

Figure 6: Gatus sends an email alert for a failing endpoint.

If you want to use a specific alert configuration for all endpoints using the same alert type, define the default values within the alert type's configuration, as shown in Listing 10.

01 alerting:
02   email:
03     from: "from@example.com"
04     username: "from@example.com"
05     password: "hunter2"
06     host: "mail.example.com"
07     port: 587
08     to: "recipient1@example.com,recipient2@example.com"
09     default-alert:
10       send-on-resolved: true