.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "GDNSD-PLUGIN-EXTFILE 8" .TH GDNSD-PLUGIN-EXTFILE 8 "2024-01-05" "gdnsd 3.8.2" "gdnsd" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" gdnsd\-plugin\-extfile \- gdnsd plugin for importing monitor data via file .SH "SYNOPSIS" .IX Header "SYNOPSIS" Example service_types config: .PP .Vb 10 \& 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/ \& }, \& } .Ve .PP Example plugin config using these service_types: .PP .Vb 10 \& 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 ], \& } \& } \& } .Ve .PP Example extfile data defining the resource + service_types specified above: .PP .Vb 7 \& /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 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBgdnsd-plugin-extfile\fR is a monitor plugin that imports monitor results from an external file (which is probably populated by some script/tool from some other monitoring software). .SH "MODES" .IX Header "MODES" An extfile service_type can operate in one of two basic modes: .IP "Monitor Mode (default)" 4 .IX Item "Monitor Mode (default)" In monitor mode, the standard parameter \f(CW\*(C`interval\*(C'\fR is used as a repeating timer. At each interval, the file is loaded for state updates (but any direct \s-1TTL\s0 values in the file are ignored). .Sp 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). This means they will be subject to the standard anti-flap measures via the standard threshold parameters (\f(CW\*(C`up_thresh\*(C'\fR, \f(CW\*(C`down_thresh\*(C'\fR, \f(CW\*(C`ok_thresh\*(C'\fR) before affecting the final status seen by resolution plugins. .Sp This mode is appropriate if the updates being processed are relatively-raw updates from individual monitor checks. .IP "Direct Mode" 4 .IX Item "Direct Mode" In direct mode, the standard parameter \f(CW\*(C`interval\*(C'\fR is used only as a \fBhint\fR to the filesystem-watching code to try to check for updates no less often than the supplied interval. However in many cases (especially e.g. Linux with \f(CW\*(C`inotify()\*(C'\fR support) updates to the file may be picked up much sooner, perhaps nearly instantly. .Sp 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. .Sp The results contained in the file (state and/or \s-1TTL\s0 per-resource) are applied directly as final monitoring results and made immediately available to resolution plugins for decision-making. .Sp 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. .SH "FILE FORMAT" .IX Header "FILE FORMAT" The file is formatted using the same \f(CW\*(C`vscf\*(C'\fR 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 \s-1IP\s0 address or \s-1CNAME\s0 values from the monitor plugins and the values are of the form form \f(CW\*(C`state[/ttl]\*(C'\fR, where state is either \f(CW\*(C`UP\*(C'\fR or \f(CW\*(C`DOWN\*(C'\fR and the optional ttl is an integer ttl value. \s-1TTL\s0 values are only used for \f(CW\*(C`direct\*(C'\fR\-mode service_types; the \s-1TTL\s0 is calculated in the normal fashion based on intervals and thresholds for \f(CW\*(C`monitor\*(C'\fR\-mode. .SH "CONFIGURATION \- PER-SERVICE-TYPE" .IX Header "CONFIGURATION - PER-SERVICE-TYPE" The universal, plugin-neutral service_type parameters all apply in their usual sense: \f(CW\*(C`up_thresh\*(C'\fR, \f(CW\*(C`ok_thresh\*(C'\fR, \f(CW\*(C`down_thresh\*(C'\fR, and \f(CW\*(C`interval\*(C'\fR (keeping in mind the notes above about how each mode uses \f(CW\*(C`interval\*(C'\fR). \f(CW\*(C`timeout\*(C'\fR is ignored. extfile-specific parameters: .IP "\fBdirect\fR" 4 .IX Item "direct" Boolean, default false. Sets the monitoring mode to \&\f(CW\*(C`direct\*(C'\fR if true, otherwise mode defaults to \f(CW\*(C`monitor\*(C'\fR. .IP "\fBfile\fR" 4 .IX Item "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 \fI/var/lib/gdnsd/extfile/\fR. .IP "\fBdef_ttl\fR" 4 .IX Item "def_ttl" Integer \s-1TTL,\s0 default is max (which will be limited by zonefile \&\s-1RR TTL\s0 values). In \f(CW\*(C`direct\*(C'\fR mode this will be set as the monitored \&\s-1TTL\s0 if no optional \s-1TTL\s0 is supplied in the file data for a given resource. It is ignored in \f(CW\*(C`monitor\*(C'\fR mode. .IP "\fBdef_down\fR" 4 .IX Item "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 \f(CW\*(C`DOWN\*(C'\fR, otherwise they default to \f(CW\*(C`UP\*(C'\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBgdnsd.config\fR\|(5), \fBgdnsd\fR\|(8) .PP The gdnsd manual. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (c) 2012 Brandon L Black .PP This file is part of gdnsd. .PP gdnsd is free software: you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. .PP gdnsd is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the \&\s-1GNU\s0 General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with gdnsd. If not, see .