Update README.md

v2.0.0
2025-12-12 17:32:31 +00:00 · 2025-06-26 17:57:18 +01:00 · 2025-06-26 17:54:43 +01:00
3 changed files with 1188 additions and 566 deletions
--- a/README.md
+++ b/README.md
@ -1,47 +1,134 @@
 # zabbix-domain-expiry

-## Description
+Monitor domain expiration dates using RDAP or WHOIS protocols.

-Zabbix template to check domain registration expiry
+</br>

-Tested on:
-* Zabbix 6.4
+## Features
+- **(NEW) RDAP and WHOIS Support**: Queries domain expiration via RDAP (preferred) with fallback to WHOIS.
+- **(NEW) JSON Output**: Script outputs JSON for easy parsing by Zabbix.
+- **(NEW) Debug Mode**: Detailed debug output for troubleshooting.

-## Requirements:
-* Zabbix v6.4 or later
-* whois installed on zabbix server (GNU utils)
+## Requirements
+- **Zabbix Server/Agent**: Version 6.4 or higher
+- **OS**: GNU/Linux systems
+- **Shell Script Dependencies**:
+  - `curl`: For RDAP queries.
+  - `mktemp`: For temporary files.
+  - `date`: For date calculations.
+  - `whois`: For WHOIS queries.
+  - `grep`: For parsing output.
+  - `awk`: For parsing WHOIS and RDAP data.
+  - `jq`: For parsing RDAP JSON responses.

-## Setup:
+## Tested on
+- **OS**: RHEL/Rocky (bash) and Debian/Ubuntu (dash)
+- **Zabbix Server**: 6.4
+- **Note**: Shell script is *mostly* POSIX compliant so should be widely compatible

-1. Copy shell script check_domain.sh to your Zabbix server external scripts dir (default: /usr/lib/zabbix/externalscripts/)
-2. Make it executable (e.g. chmod +x /usr/lib/zabbix/externalscripts/check_domain.sh)
-2. Import yaml template to your zabbix server
-3. Create a host with a domain name as the Host name and attach the template to the host. Make sure required macros are filled out
+## Installation (Zabbix server)

-## Required macros:
+### Install Dependencies
+Ensure the required dependencies are installed on your system.

-|Macro|Default Value|Description|
-|-----|-------------|-----------|
-|{$EXP_CRIT}|7|Threshold value of days remaining before triggering a HIGH alert|
-|{$EXP_WARN}|30|Threshold value of days remaining before triggering a WARNING alert|
-|{$WHOIS_SERVER}|""|Specify the whois service to use (e.g whois.godaddy.com). Default value "" uses the whois util config default|
+**For RHEL/Rocky**:
+```bash
+sudo dnf install -y epel-release
+sudo dnf install -y curl coreutils whois grep gawk jq
+```

-## Items:
+**For Debian/Ubuntu**:
+```bash
+sudo apt update
+sudo apt install -y curl coreutils whois grep gawk jq
+```

-|Name|Description|Type|Key and additional info|
-|----|-----------|----|----|
-|Domain Check Expiry|Run external script to check domain registration status|External check|check_domain.sh["-d",{HOST.NAME},"-s",{$WHOIS_SERVER},"-w",{$EXP_WARN},"-c",{$EXP_CRIT}], Update interval: 1d|
-|Domain Check Expiry: Status|Get "State:" from script output|Dependant item|domain_check_expiry.status|
-|Domain Check Expiry: Expire Date|Get "Expire date:" from script output|Dependant item|domain_check_expiry.expire_date|
-|Domain Check Expiry: Days Since Expired|Get "Days since expired:" from script output|Dependant item|domain_check_expiry.days_since_expired|
-|Domain Check Expiry: Days Left|Get "Days left:" from script output|Dependant item|domain_check_expiry.days_left|
+### Setup Steps
+1. **Clone the Repository**:
+   ```bash
+   git clone https://github.com/a-stoyanov/zabbix-domain-expiry.git
+   cd zabbix-domain-expiry
+   ```
+2. Copy shell script `check_domain.sh` to your Zabbix server external scripts dir (default: `/usr/lib/zabbix/externalscripts/`)
+3. Make it executable (e.g. `chmod +x /usr/lib/zabbix/externalscripts/check_domain.sh`)
+4. Import yaml template `zbx_domain_expiry.yaml` to your zabbix server
+5. Create a host with a domain name (e.g: `example.com`) as the Host name and attach the template to the host

-## Triggers:
-<b>Note: There is operational data included in the triggers to display live data from checks. You can include this in your "Problems" dashboard widget > Show operational data > With problem name</b>
+## Upgrading

-|Name|Description|Expression|Severity|
-|----|-----------|----------|--------|
-|Domain Expiry: {HOST.NAME} - {ITEM.LASTVALUE1}|Raise alert in case of script output error|find(/Domain Expiry/domain_check_expiry.status,#1,"like","UNKNOWN")=1|Not classified|
-|Domain Expiry: {HOST.NAME} will expire soon|Raise alert when number days remaining is below threshold|last(/Domain Expiry/domain_check_expiry.days_left)<={$EXP_WARN} and last(/Domain Expiry/domain_check_expiry.expire_date)<>0|Warning|
-|Domain Expiry: {HOST.NAME} will expire soon|Raise alert when number days remaining is below threshold|last(/Domain Expiry/domain_check_expiry.days_left)<={$EXP_CRIT} and last(/Domain Expiry/domain_check_expiry.expire_date)<>0|High|
-|Domain Expiry: {HOST.NAME} has expired|Raise alert domain registarion has expired|find(/Domain Expiry/domain_check_expiry.status,#1,"like","EXPIRED")=1 and last(/Domain Expiry/domain_check_expiry.days_since_expired)>=0 and last(/Domain Expiry/domain_check_expiry.expire_date)<>0|Disaster|
+If you are upgrading from the old version just import/overwrite the existing template and copy/overwite the old shell script with new version
+
+## Configuration
+
+### Template Macros
+The template uses the following macros, configurable at the host or template level:
+
+| Macro            | Default Value | Description                                                                 |
+|------------------|---------------|-----------------------------------------------------------------------------|
+| `{$EXP_CRIT}`    | 7             | Days remaining before triggering a HIGH (critical) alert.                   |
+| `{$EXP_WARN}`    | 30            | Days remaining before triggering a WARNING alert.                           |
+| `{$RDAP_SERVER}` | (empty)       | Specify which RDAP server to use. Default empty value will use IANA lookup.  |
+| `{$WHOIS_SERVER}`| (empty)       | Specify which WHOIS server to use. Default empty value will use rfc-3912 lookup. |
+
+### Template Items
+The template includes the following items to monitor domain expiration:
+
+| Name                | Key                                    | Type       | Value Type | Description                                                                 |
+|---------------------|----------------------------------------|------------|------------|-----------------------------------------------------------------------------|
+| Days Left           | `check_domain.days_left`               | Dependent  | Float      | Number of days until the domain expires.                                    |
+| Days Since Expired  | `check_domain.days_since_expired`      | Dependent  | Float      | Number of days since the domain expired (0 if not expired).                 |
+| Expire Date         | `check_domain.expire_date`             | Dependent  | Text       | Domain expiration date in YYYY-MM-DD format.                                |
+| Message             | `check_domain.message`                 | Dependent  | Text       | Status message returned by the script.                                      |
+| State               | `check_domain.state`                   | Dependent  | Text       | Domain status: OK, WARNING, CRITICAL, or UNKNOWN.                           |
+| Check Domain        | `check_domain.sh[...]`                 | External   | Text       | Executes the external script to check domain status.                        |
+
+### Template Triggers
+The template defines the following triggers for alerting:
+
+| Name                                    | Expression                                                                 | Priority  | Description                                                                 |
+|-----------------------------------------|---------------------------------------------------------------------------|-----------|-----------------------------------------------------------------------------|
+| Domain Expiry: {HOST.HOST} - {ITEM.LASTVALUE2} | `last(/Domain Expiry/check_domain.state)="UNKNOWN" and last(/Domain Expiry/check_domain.message)<>0` | Not Classified   | Alerts if the script cannot determine the domain's expiration status.        |
+| Domain Expiry: {HOST.HOST} has expired  | `last(/Domain Expiry/check_domain.state)="CRITICAL" and last(/Domain Expiry/check_domain.days_since_expired)>0 and last(/Domain Expiry/check_domain.expire_date)<>0` | Disaster  | Alerts if the domain has expired.                                           |
+| Domain Expiry: {HOST.HOST} will expire soon (Critical) | `last(/Domain Expiry/check_domain.state)="CRITICAL" and last(/Domain Expiry/check_domain.days_left)<={$EXP_CRIT} and last(/Domain Expiry/check_domain.expire_date)<>0` | High      | Alerts if days remaining are below the critical threshold (`{$EXP_CRIT}`).  |
+| Domain Expiry: {HOST.HOST} will expire soon (Warning)  | `last(/Domain Expiry/check_domain.state)="WARNING" and last(/Domain Expiry/check_domain.days_left)<={$EXP_WARN} and last(/Domain Expiry/check_domain.expire_date)<>0` | Warning   | Alerts if days remaining are below the warning threshold (`{$EXP_WARN}`).   |
+
+### Script Usage
+The `check_domain.sh` script can be run manually for testing:
+
+```bash
+./check_domain.sh -d example.com
+./check_domain.sh -d example.com -w 30 -c 7 -r '' -s ''
+```
+
+**Options**:
+- `-d, --domain`: Domain name to check (required).
+- `-w, --warning`: Warning threshold in days (default: 30).
+- `-c, --critical`: Critical threshold in days (default: 7).
+- `-r, --rdap-server`: RDAP server URL (use `""` for IANA lookup).
+- `-s, --whois-server`: WHOIS server hostname (use `""` for default lookup).
+- `-P, --path`: Path to `whois` executable.
+- `-z, --debug`: Enable debug output to stderr.
+- `-h, --help`: Display help.
+- `-V, --version`: Display version in JSON format.
+
+**Example Output**:
+```json
+{"state":"OK","days_left":365,"days_since_expired":0,"expire_date":"2026-06-24","message":"State: OK ; Days left: 365 ; Expire date: 2026-06-24"}
+```
+
+## Debugging
+- Enable debug mode in the script with `-z`:
+  ```bash
+  ./check_domain.sh -d example.com -z
+  ```
+- Check Zabbix logs for issues with script execution.
+- Verify RDAP/WHOIS server availability and response format outside of script
+
+## Notes
+- The script prioritizes RDAP for faster, structured queries but falls back to WHOIS if RDAP fails.
+- WHOIS awk parsing supports various date formats but may fail if whois query returns non-standard responses (no awk pattern match).
+- Rate limits on WHOIS servers may trigger UNKNOWN states; increase or use custom check interval to mitigate (the default 1d is very reasonable).
+- For some specific TLDs (e.g: `.uk`, `.br`) RDAP URL paths may have to be adjusted due to non-standard URL format. See `adjust_rdap_url()` function, which already handles /uk/ path adjustment.
+
+## License
+This project is licensed under the Apache License 2.0
--- a/check_domain.sh
+++ b/check_domain.sh
--- a/zbx_domain_expiry.yaml
+++ b/zbx_domain_expiry.yaml
@ -1,89 +1,98 @@
 zabbix_export:
  version: '6.4'
+  template_groups:
+    - uuid: 7df96b18c230490a9a0a9e2307226338
+      name: Templates
  templates:
-    - uuid: d2df9ca51f754af8aff5d50f96c656e3
+    - uuid: 644e89db964346f3b1ecd249d2d57876
      template: 'Domain Expiry'
      name: 'Domain Expiry'
-      description: 'Template downloaded from: https://github.com/a-stoyanov/zabbix-domain-expiry'
+      description: |
+        Template version: 2.0.0
+        Downloaded from: https://github.com/a-stoyanov/zabbix-domain-expiry
      vendor:
        name: github.com/a-stoyanov
        version: 6.4-0
      groups:
-        - name: Custom/Domain
+        - name: Templates
      items:
-        - uuid: 24dcc49a7c384aaeb3dd8846b3401986
-          name: 'Domain Check Expiry'
-          type: EXTERNAL
-          key: 'check_domain.sh["-d",{HOST.NAME},"-s",{$WHOIS_SERVER},"-w",{$EXP_WARN},"-c",{$EXP_CRIT}]'
-          delay: 1d
-          history: '0'
-          trends: '0'
-          value_type: TEXT
-        - uuid: 78a9ed45942a482f88d60acd4a24538d
+        - uuid: 7446af7e8dce480690f2ebd72a843953
          name: 'Days Left'
          type: DEPENDENT
-          key: domain_check_expiry.days_left
+          key: check_domain.days_left
          delay: '0'
+          value_type: FLOAT
          preprocessing:
-            - type: REGEX
+            - type: JSONPATH
              parameters:
-                - 'Days left: (\d+)'
-                - \1
+                - $.days_left
              error_handler: CUSTOM_VALUE
              error_handler_params: '0'
          master_item:
-            key: 'check_domain.sh["-d",{HOST.NAME},"-s",{$WHOIS_SERVER},"-w",{$EXP_WARN},"-c",{$EXP_CRIT}]'
-        - uuid: bccdb32210514ba1801f3c9a50c2b737
+            key: 'check_domain.sh["-d",{HOST.HOST},"-r",{$RDAP_SERVER},"-s",{$WHOIS_SERVER},"-w",{$EXP_WARN},"-c",{$EXP_CRIT}]'
+        - uuid: 5a55bf6bf9b8490bb058982428572485
          name: 'Days Since Expired'
          type: DEPENDENT
-          key: domain_check_expiry.days_since_expired
+          key: check_domain.days_since_expired
          delay: '0'
+          value_type: FLOAT
          preprocessing:
-            - type: REGEX
+            - type: JSONPATH
              parameters:
-                - 'Days since expired: (\d+)'
-                - \1
+                - $.days_since_expired
              error_handler: CUSTOM_VALUE
              error_handler_params: '0'
          master_item:
-            key: 'check_domain.sh["-d",{HOST.NAME},"-s",{$WHOIS_SERVER},"-w",{$EXP_WARN},"-c",{$EXP_CRIT}]'
-        - uuid: c6c00c3717d84bf291420b7913b1133d
+            key: 'check_domain.sh["-d",{HOST.HOST},"-r",{$RDAP_SERVER},"-s",{$WHOIS_SERVER},"-w",{$EXP_WARN},"-c",{$EXP_CRIT}]'
+        - uuid: 0e104f2540204ac686072bd6cec91a86
          name: 'Expire Date'
          type: DEPENDENT
-          key: domain_check_expiry.expire_date
+          key: check_domain.expire_date
          delay: '0'
-          trends: '0'
          value_type: TEXT
+          trends: '0'
          preprocessing:
-            - type: REGEX
+            - type: JSONPATH
              parameters:
-                - 'Expire date: (.+)'
-                - \1
+                - $.expire_date
              error_handler: CUSTOM_VALUE
              error_handler_params: '0'
          master_item:
-            key: 'check_domain.sh["-d",{HOST.NAME},"-s",{$WHOIS_SERVER},"-w",{$EXP_WARN},"-c",{$EXP_CRIT}]'
-        - uuid: 67828b062ef74c0f8e866a9fbfb78d27
-          name: Status
+            key: 'check_domain.sh["-d",{HOST.HOST},"-r",{$RDAP_SERVER},"-s",{$WHOIS_SERVER},"-w",{$EXP_WARN},"-c",{$EXP_CRIT}]'
+        - uuid: 99f25b8648814596a72f66f3e3db01cf
+          name: Message
          type: DEPENDENT
-          key: domain_check_expiry.status
+          key: check_domain.message
          delay: '0'
-          trends: '0'
          value_type: TEXT
+          trends: '0'
          preprocessing:
-            - type: REGEX
+            - type: JSONPATH
              parameters:
-                - 'State: (.+)'
-                - \1
+                - $.message
          master_item:
-            key: 'check_domain.sh["-d",{HOST.NAME},"-s",{$WHOIS_SERVER},"-w",{$EXP_WARN},"-c",{$EXP_CRIT}]'
-          triggers:
-            - uuid: 2a7fb4f347ce4c5aa0617f08a0b339f0
-              expression: 'find(/Domain Expiry/domain_check_expiry.status,#1,"like","UNKNOWN")=1'
-              name: 'Domain Expiry: {HOST.NAME} - {ITEM.LASTVALUE1}'
-              tags:
-                - tag: domain
-                  value: status
+            key: 'check_domain.sh["-d",{HOST.HOST},"-r",{$RDAP_SERVER},"-s",{$WHOIS_SERVER},"-w",{$EXP_WARN},"-c",{$EXP_CRIT}]'
+        - uuid: 48baf9c076d1453d8c7272dffa014fd9
+          name: 'Check Domain'
+          type: EXTERNAL
+          key: 'check_domain.sh["-d",{HOST.HOST},"-r",{$RDAP_SERVER},"-s",{$WHOIS_SERVER},"-w",{$EXP_WARN},"-c",{$EXP_CRIT}]'
+          delay: 1d
+          history: '0'
+          value_type: TEXT
+          trends: '0'
+        - uuid: ceb24ded619c4d34b8394a50d700bf52
+          name: State
+          type: DEPENDENT
+          key: check_domain.state
+          delay: '0'
+          value_type: TEXT
+          trends: '0'
+          preprocessing:
+            - type: JSONPATH
+              parameters:
+                - $.state
+          master_item:
+            key: 'check_domain.sh["-d",{HOST.HOST},"-r",{$RDAP_SERVER},"-s",{$WHOIS_SERVER},"-w",{$EXP_WARN},"-c",{$EXP_CRIT}]'
      tags:
        - tag: domain
          value: registration
@ -94,59 +103,82 @@ zabbix_export:
        - macro: '{$EXP_WARN}'
          value: '30'
          description: 'Threshold value of days remaining before triggering a WARNING alert'
+        - macro: '{$RDAP_SERVER}'
+          description: 'Specify which RDAP server to use. Default empty value will use IANA lookup'
        - macro: '{$WHOIS_SERVER}'
-          value: '""'
-          description: 'Used to specify which whois service to use. Default value "" uses the whois util config default'
+          description: 'Specify which WHOIS server to use. Default empty value will use the whois utility config (rfc-3912 lookup)'
  triggers:
-    - uuid: acf67a4bfd9649c9a96c63cafa812e9b
+    - uuid: 126653ca5057472c9499f5bcf74b17ba
      expression: |
-        find(/Domain Expiry/domain_check_expiry.status,#1,"like","EXPIRED")=1
+        last(/Domain Expiry/check_domain.state)="UNKNOWN"
        and
-        last(/Domain Expiry/domain_check_expiry.days_since_expired)>=0
+        last(/Domain Expiry/check_domain.message)<>0
+      name: 'Domain Expiry: {HOST.HOST} - {ITEM.LASTVALUE2}'
+      description: 'Raise alert in case script is unable to determine the expiration status for the domain (state = unknown)'
+      tags:
+        - tag: domain
+          value: status
+    - uuid: 71b376de644848379c14ef181e12245a
+      expression: |
+        last(/Domain Expiry/check_domain.state)="CRITICAL"
        and
-        last(/Domain Expiry/domain_check_expiry.expire_date)<>0
-      name: 'Domain Expiry: {HOST.NAME} has expired'
+        last(/Domain Expiry/check_domain.days_since_expired)>0
+        and
+        last(/Domain Expiry/check_domain.expire_date)<>0
+      name: 'Domain Expiry: {HOST.HOST} has expired'
      opdata: '{ITEM.LASTVALUE2} days ago on {ITEM.LASTVALUE3}'
      priority: DISASTER
+      description: 'Raise alert if domain registration has expired.'
      dependencies:
-        - name: 'Domain Expiry: {HOST.NAME} - {ITEM.LASTVALUE1}'
-          expression: 'find(/Domain Expiry/domain_check_expiry.status,#1,"like","UNKNOWN")=1'
+        - name: 'Domain Expiry: {HOST.HOST} - {ITEM.LASTVALUE2}'
+          expression: |
+            last(/Domain Expiry/check_domain.state)="UNKNOWN"
+            and
+            last(/Domain Expiry/check_domain.message)<>0
      tags:
        - tag: domain
          value: expired
-    - uuid: 7664fe7d988e4bcca9dd1518e42abf79
+    - uuid: 5f767265e8714f1db4e969d4f7f95448
      expression: |
-        last(/Domain Expiry/domain_check_expiry.days_left)<={$EXP_CRIT}
+        last(/Domain Expiry/check_domain.state)="CRITICAL"
        and
-        last(/Domain Expiry/domain_check_expiry.expire_date)<>0
-      name: 'Domain Expiry: {HOST.NAME} will expire soon'
-      opdata: 'in {ITEM.LASTVALUE1} days on {ITEM.LASTVALUE2}'
+        last(/Domain Expiry/check_domain.days_left)<={$EXP_CRIT}
+        and
+        last(/Domain Expiry/check_domain.expire_date)<>0
+      name: 'Domain Expiry: {HOST.HOST} will expire soon'
+      opdata: 'in {ITEM.LASTVALUE2} days on {ITEM.LASTVALUE3}'
      priority: HIGH
+      description: 'Raise alert if number of days remaining before expiry is below critical threshold ({$EXP_CRIT}).'
      dependencies:
-        - name: 'Domain Expiry: {HOST.NAME} has expired'
+        - name: 'Domain Expiry: {HOST.HOST} has expired'
          expression: |
-            find(/Domain Expiry/domain_check_expiry.status,#1,"like","EXPIRED")=1
+            last(/Domain Expiry/check_domain.state)="CRITICAL"
            and
-            last(/Domain Expiry/domain_check_expiry.days_since_expired)>=0
+            last(/Domain Expiry/check_domain.days_since_expired)>0
            and
-            last(/Domain Expiry/domain_check_expiry.expire_date)<>0
+            last(/Domain Expiry/check_domain.expire_date)<>0
      tags:
        - tag: domain
          value: expiry
-    - uuid: ff152c25e3114727ad0a34ccd2a1640e
+    - uuid: 68e36957e56b4d95860b6a8c131a9e1b
      expression: |
-        last(/Domain Expiry/domain_check_expiry.days_left)<={$EXP_WARN}
+        last(/Domain Expiry/check_domain.state)="WARNING"
        and
-        last(/Domain Expiry/domain_check_expiry.expire_date)<>0
-      name: 'Domain Expiry: {HOST.NAME} will expire soon'
-      opdata: 'in {ITEM.LASTVALUE1} days on {ITEM.LASTVALUE2}'
+        last(/Domain Expiry/check_domain.days_left)<={$EXP_WARN}
+        and
+        last(/Domain Expiry/check_domain.expire_date)<>0
+      name: 'Domain Expiry: {HOST.HOST} will expire soon'
+      opdata: 'in {ITEM.LASTVALUE2} days on {ITEM.LASTVALUE3}'
      priority: WARNING
+      description: 'Raise alert if number of days remaining before expiry is below warning threshold ({$EXP_WARN}).'
      dependencies:
-        - name: 'Domain Expiry: {HOST.NAME} will expire soon'
+        - name: 'Domain Expiry: {HOST.HOST} will expire soon'
          expression: |
-            last(/Domain Expiry/domain_check_expiry.days_left)<={$EXP_CRIT}
+            last(/Domain Expiry/check_domain.state)="CRITICAL"
            and
-            last(/Domain Expiry/domain_check_expiry.expire_date)<>0
+            last(/Domain Expiry/check_domain.days_left)<={$EXP_CRIT}
+            and
+            last(/Domain Expiry/check_domain.expire_date)<>0
      tags:
        - tag: domain
          value: expiry
Author	SHA1	Message	Date
Angel Stoyanov	0daffec79c	Update README.md	2025-06-26 17:57:18 +01:00
Angel Stoyanov	f1d2906d4e	v2.0.0	2025-06-26 17:54:43 +01:00