GDNSD-PLUGIN-EXTFILE(8)

📦
version 3.8.3 · 7 versions
, in debian trixie, ubuntu questing

✨ gdnsd-plugin-extfile ✨

okay bestie, this is the manual page for gdnsd-plugin-extfile from the gdnsd family (man page GDNSD-PLUGIN-EXTFILE(8), section 8, the big-girl system-admin section 💅). It's a monitor plugin that reads your monitoring results out of a plain file instead of going out and doing the checks itself. Sit down, grab a strawberry 🍓, and let's get into it.

🌸 NAME 🌸

gdnsd-plugin-extfile — a gdnsd plugin for importing monitor data via file. yes that's it, that's the whole job, and she does it flawlessly 💖

🦋 SYNOPSIS 🦋

Here's an example service_types config, look at her go:

service_types => {
  ext1 => {
    plugin => "extfile",
    file => "/var/tmp/ext1data", # required
    direct => true, # default false
    def_down => false, # default false
    def_ttl => 600, # default max (limited by zonefile RRs)
  }
  ext2 => {
    plugin => "extfile",
    file => "ext2data", # def dir: /var/lib/gdnsd/extfile/
  },
}

And here's an example plugin config using those service_types:

plugins => {
  multifo => {
    www1 => {
      service_types => ext2,
      lb01 => 192.0.2.200,
      lb02 => 192.0.2.201,
      lb03 => 192.0.2.202,
    }
    www2 => {
      service_types => [ ext1, http_status ],
      lb01 => 192.0.2.203,
      lb02 => 192.0.2.204,
      lb03 => 192.0.2.205,
    }
  },
  weighted => {
    wwwcn => {
      service_types => ext1,
      lb01 = [ lb01.example.com., 99 ],
      lb02 = [ lb02.example.com., 15 ],
      lb03 = [ lb03, 1 ],
    }
    wwwz => {
      service_types => ext1,
      lb01 => [ 192.0.2.203, 10 ],
      lb02 => [ 192.0.2.204, 15 ],
      lb03 => [ 192.0.2.205, 20 ],
    }
  }
}

And here's what the actual extfile data looks like when it defines the resource + service_types we just talked about:

/var/tmp/ext1data:
  192.0.2.203 => UP/300
  192.0.2.204 => DOWN/242
  192.0.2.205 => DOWN/102
  lb01.example.com. => UP/60
  lb02.example.com. => UP/30
  lb03 => UP/45

/var/lib/gdnsd/extfile/ext2data:
  192.0.2.200 => DOWN
  192.0.2.201 => UP
  192.0.2.202 => UP

💜 DESCRIPTION 💜

gdnsd-plugin-extfile is a monitor plugin that imports monitor results from an external file. and like, that file is probably being populated by some script or tool from some other monitoring software, because we're all just out here gluing systems together, no cap 😭

🌈 MODES 🌈

An extfile service_type can operate in one of two basic modes, and choosing between them is literally the whole personality of this plugin:

⭐ Monitor Mode (default) ⭐

In monitor mode, the standard parameter interval is used as a repeating timer. At each interval, the file is loaded for state updates — but bestie, any direct TTL values sitting in the file are ignored. 🙈

The updates from the file are fed into the standard core monitoring system by the same mechanisms as normal monitoring plugins (e.g. http_status). Which means they'll be subject to the standard anti-flap measures via the standard threshold parameters (up_thresh, down_thresh, ok_thresh) before affecting the final status seen by resolution plugins.

This mode is appropriate if the updates being processed are relatively-raw updates from individual monitor checks. 🎀

⭐ Direct Mode ⭐

In direct mode, the standard parameter interval is used only as a hint to the filesystem-watching code to try to check for updates no less often than the supplied interval. But in many cases (especially e.g. Linux with inotify() support) updates to the file may be picked up much sooner — perhaps nearly instantly. it's giving speed 👑

There will be a short (~1 second) settling delay after detecting any update in order to coalesce any rapid-fire updates into a single transaction. patience, queen 🧚

The results contained in the file (state and/or TTL per-resource) are applied directly as final monitoring results and made immediately available to resolution plugins for decision-making.

This mode is appropriate if the updates are from processed monitoring results that have already been through e.g. anti-flap measures before reaching gdnsd. 💅

🎀 FILE FORMAT 🎀

The file is formatted using the same vscf language that's used for the main config file and the geoip nets databases. The expected data format is a simple key-value hash at the top level, where the keys are the monitored IP address or CNAME values from the monitor plugins and the values are of the form "state[/ttl]", where state is either "UP" or "DOWN" and the optional ttl is an integer ttl value. TTL values are only used for "direct"-mode service_types; the TTL is calculated in the normal fashion based on intervals and thresholds for "monitor"-mode. 🦋

💖 CONFIGURATION - PER-SERVICE-TYPE 💖

The universal, plugin-neutral service_type parameters all apply in their usual sense: up_thresh, ok_thresh, down_thresh, and interval (keeping in mind the notes above about how each mode uses interval). timeout is ignored. (rip timeout, not invited to this party 💀)

And now the extfile-specific parameters, aka the moment you've all been waiting for:

  • direct — Boolean, default false. Sets the monitoring mode to "direct" if true, otherwise mode defaults to "monitor".
  • file — String filename, required. This sets the name of the file to load results from. If the pathname is not absolute, it will be considered relative to /var/lib/gdnsd/extfile/.
  • def_ttl — Integer TTL, default is max (which will be limited by zonefile RR TTL values). In "direct" mode this will be set as the monitored TTL if no optional TTL is supplied in the file data for a given resource. It is ignored in "monitor" mode.
  • def_down — Boolean, default false. This sets the default disposition of configured resources which are missing from the file data (which will generate warnings). If true, these resources behave as if the file data marked them "DOWN", otherwise they default to "UP".

🔥 SEE ALSO 🔥

Copyright (c) 2012 Brandon L Black <blblack@gmail.com>

This file is part of gdnsd.

gdnsd is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

gdnsd is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with gdnsd. If not, see <http://www.gnu.org/licenses/>.

and that's the whole page, bestie 🫶 this beauty comes to you from gdnsd 3.8.3, dated 2025-02-16 — go forth and import those monitor results, you absolute icon ✨🌈💖

📦 where this page comes from