.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 "Smokeping_probes_LDAP 3"
.TH Smokeping_probes_LDAP 3 "2022-05-08" "2.8.2" "SmokePing"
.\" 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"
Smokeping::probes::LDAP \- a LDAP probe for SmokePing
.SH "OVERVIEW"
.IX Header "OVERVIEW"
Measures \s-1LDAP\s0 search latency for SmokePing
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& *** Probes ***
\&
\& +LDAP
\&
\& forks = 5
\& offset = 50%
\& passwordfile = /some/place/secret
\& step = 300
\&
\& # The following variables can be overridden in each target section
\& /^influx_.+/ = influx_location = In the basement
\& attrs = uid,someotherattr
\& base = dc=foo,dc=bar
\& binddn = uid=testuser,dc=foo,dc=bar
\& filter = uid=testuser # mandatory
\& mininterval = 1
\& password = mypass
\& pings = 5
\& port = 389
\& scheme = ldap
\& scope = one
\& start_tls = 1
\& timeout = 10
\& verify = optional
\& version = 3
\&
\& # [...]
\&
\& *** Targets ***
\&
\& probe = LDAP # if this should be the default probe
\&
\& # [...]
\&
\& + mytarget
\& # probe = LDAP # if the default probe is something else
\& host = my.host
\& /^influx_.+/ = influx_location = In the basement
\& attrs = uid,someotherattr
\& base = dc=foo,dc=bar
\& binddn = uid=testuser,dc=foo,dc=bar
\& filter = uid=testuser # mandatory
\& mininterval = 1
\& password = mypass
\& pings = 5
\& port = 389
\& scheme = ldap
\& scope = one
\& start_tls = 1
\& timeout = 10
\& verify = optional
\& version = 3
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This probe measures \s-1LDAP\s0 query latency for SmokePing.
The query is specified by the target-specific variable `filter' and,
optionally, by the target-specific variable `base'. The attributes 
queried can be specified in the comma-separated list `attrs'.
.PP
The \s-1TCP\s0 port of the \s-1LDAP\s0 server and the \s-1LDAP\s0 version to be used can
be specified by the variables `port' and `version'.
.PP
The probe can issue the starttls command to convert the connection
into encrypted mode, if so instructed by the `start_tls' variable.
This requires the 'IO::Socket::SSL' perl module to be installed.
.PP
The probe can also optionally do an authenticated \s-1LDAP\s0 bind, if the `binddn'
variable is present. The password to be used can be specified by the
target-specific variable `password' or in an external file.
The location of this file is given in the probe-specific variable
`passwordfile'. See \fBSmokeping::probes::passwordchecker\fR\|(3pm) for the format
of this file (summary: colon-separated triplets of the form
`<host>:<bind\-dn>:<password>')
.PP
The probe tries to be nice to the server and does not send authentication
requests more frequently than once every X seconds, where X is the value
of the target-specific \*(L"min_interval\*(R" variable (1 by default).
.SH "VARIABLES"
.IX Header "VARIABLES"
Supported probe-specific variables:
.IP "forks" 4
.IX Item "forks"
Run this many concurrent processes at maximum
.Sp
Example value: 5
.Sp
Default value: 5
.IP "offset" 4
.IX Item "offset"
If you run many probes concurrently you may want to prevent them from
hitting your network all at the same time. Using the probe-specific
offset parameter you can change the point in time when each probe will
be run. Offset is specified in % of total interval, or alternatively as
\&'random', and the offset from the 'General' section is used if nothing
is specified here. Note that this does \s-1NOT\s0 influence the rrds itself,
it is just a matter of when data acquisition is initiated.
(This variable is only applicable if the variable 'concurrentprobes' is set
in the 'General' section.)
.Sp
Example value: 50%
.IP "passwordfile" 4
.IX Item "passwordfile"
Location of the file containing usernames and passwords.
.Sp
Example value: /some/place/secret
.IP "step" 4
.IX Item "step"
Duration of the base interval that this probe should use, if different
from the one specified in the 'Database' section. Note that the step in
the \s-1RRD\s0 files is fixed when they are originally generated, and if you
change the step parameter afterwards, you'll have to delete the old \s-1RRD\s0
files or somehow convert them. (This variable is only applicable if
the variable 'concurrentprobes' is set in the 'General' section.)
.Sp
Example value: 300
.PP
Supported target-specific variables:
.IP "/^influx_.+/" 4
.IX Item "/^influx_.+/"
This is a tag that will be sent to influxdb and has no impact on the probe measurement. The tag name will be sent without the \*(L"influx_\*(R" prefix, which will be replaced with \*(L"tag_\*(R" instead. Tags can be used for filtering.
.Sp
Example value: influx_location = In the basement
.IP "attrs" 4
.IX Item "attrs"
The attributes queried.
.Sp
Example value: uid,someotherattr
.IP "base" 4
.IX Item "base"
The base to be used in the \s-1LDAP\s0 query
.Sp
Example value: dc=foo,dc=bar
.IP "binddn" 4
.IX Item "binddn"
If present, authenticate the \s-1LDAP\s0 bind with this \s-1DN.\s0
.Sp
Example value: uid=testuser,dc=foo,dc=bar
.IP "filter" 4
.IX Item "filter"
The actual search to be made
.Sp
Example value: uid=testuser
.Sp
This setting is mandatory.
.IP "mininterval" 4
.IX Item "mininterval"
The minimum interval between each query sent, in (possibly fractional) second
s.
.Sp
Default value: 1
.IP "password" 4
.IX Item "password"
The password to be used, if not present in <passwordfile>.
.Sp
Example value: mypass
.IP "pings" 4
.IX Item "pings"
How many pings should be sent to each target, if different from the global
value specified in the Database section. Note that the number of pings in
the \s-1RRD\s0 files is fixed when they are originally generated, and if you
change this parameter afterwards, you'll have to delete the old \s-1RRD\s0
files or somehow convert them.
.Sp
Example value: 5
.IP "port" 4
.IX Item "port"
\&\s-1TCP\s0 port of the \s-1LDAP\s0 server
.Sp
Example value: 389
.IP "scheme" 4
.IX Item "scheme"
\&\s-1LDAP\s0 scheme to use: ldap, ldaps or ldapi
.Sp
Example value: ldap
.Sp
Default value: ldap
.IP "scope" 4
.IX Item "scope"
The scope of the query. Can be either 'base', 'one' or 'sub'. See the Net::LDAP documentation for details.
.Sp
Example value: one
.Sp
Default value: sub
.IP "start_tls" 4
.IX Item "start_tls"
If true, encrypt the connection with the starttls command. Disabled by default.
.Sp
Example value: 1
.IP "timeout" 4
.IX Item "timeout"
\&\s-1LDAP\s0 query timeout in seconds.
.Sp
Example value: 10
.Sp
Default value: 5
.IP "verify" 4
.IX Item "verify"
The \s-1TLS\s0 verification level. Can be either 'none', 'optional', 'require'. See the Net::LDAPS documentation for details.
.Sp
Example value: optional
.Sp
Default value: require
.IP "version" 4
.IX Item "version"
The \s-1LDAP\s0 version to be used.
.Sp
Example value: 3
.SH "AUTHORS"
.IX Header "AUTHORS"
Niko Tyni <ntyni@iki.fi>
.SH "BUGS"
.IX Header "BUGS"
There should be a way of specifying \s-1TLS\s0 options, such as the certificates
involved etc.
.PP
The probe has an ugly way of working around the fact that the 
IO::Socket::SSL class complains if \fBstart_tls()\fR is done more than once
in the same program. But It Works For Me (tm).