.\" 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_IRTT 3" .TH Smokeping_probes_IRTT 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::IRTT \- a SmokePing Probe for IRTT .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& *** Probes *** \& \& +IRTT \& \& binary = /usr/local/bin/irtt # mandatory \& forks = 5 \& offset = 50% \& step = 300 \& timeout = 15 \& tmpdir = /tmp/smokeping\-irtt \& \& # The following variables can be overridden in each target section \& /^influx_.+/ = influx_location = In the basement \& dscp = 46 \& extraargs = \-\-ttl=32 \& fill = rand \& hmac = opensesame \& interval = 1.5 \& ipversion = 6 \& length = 172 \& localaddr = 192.168.1.10:63814 \& metric = rtt \& pings = 5 \& readfrom = irtt1 \& readfrompollinterval = 2 \& serverfill = rand \& sleep = 0.5 \& writeto = irtt1 \& \& # [...] \& \& *** Targets *** \& \& probe = IRTT # if this should be the default probe \& \& # [...] \& \& + mytarget \& # probe = IRTT # if the default probe is something else \& host = my.host \& /^influx_.+/ = influx_location = In the basement \& dscp = 46 \& extraargs = \-\-ttl=32 \& fill = rand \& hmac = opensesame \& interval = 1.5 \& ipversion = 6 \& length = 172 \& localaddr = 192.168.1.10:63814 \& metric = rtt \& pings = 5 \& readfrom = irtt1 \& readfrompollinterval = 2 \& serverfill = rand \& sleep = 0.5 \& writeto = irtt1 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This SmokePing probe uses \s-1IRTT\s0 to record network round-trip time , one-way delay or \&\s-1IPDV\s0 (jitter), based on the value of the \fBmetric\fR variable. .PP Additionally, the probe provides a results sharing feature, which allows using results from a single \s-1IRTT\s0 run to record multiple metrics for a given host at the same time. One target is defined with the \fBwriteto\fR variable set, which selects the name of a temporary file to save the \s-1IRTT\s0 output to. Additional targets are defined with the \fBreadfrom\fR variable set to the same value, which, instead of running \s-1IRTT,\s0 wait for the main target's output to become available, then parse it to record the chosen metric from the same data. See the \&\fBwriteto\fR and \fBreadfrom\fR variables for more information. .SS "\s-1WARNING\s0" .IX Subsection "WARNING" The results sharing feature (\fBwriteto\fR and \fBreadfrom\fR variables) requires the number of \fBforks\fR for the \s-1IRTT\s0 probe to be at least the total number of \s-1IRTT\s0 targets defined (regardless of whether they have \fBwriteto\fR and \fBreadfrom\fR set). Otherwise, there can be a deadlock while \fBreadfrom\fR targets wait for their corresponding \fBwriteto\fR target to complete, which may never start. .SH "VARIABLES" .IX Header "VARIABLES" Supported probe-specific variables: .IP "binary" 4 .IX Item "binary" The location of your irtt binary. .Sp Example value: /usr/local/bin/irtt .Sp Default value: /usr/bin/irtt .Sp This setting is mandatory. .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 "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 .IP "timeout" 4 .IX Item "timeout" How long a single 'ping' takes at maximum .Sp Example value: 15 .Sp Default value: 5 .IP "tmpdir" 4 .IX Item "tmpdir" A temporary directory in which to place files for writeto/readfrom. .Sp Default value: /tmp/smokeping\-irtt .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 "dscp" 4 .IX Item "dscp" The packet \s-1DSCP\s0 value to use (\f(CW\*(C`irtt client \-\-dscp\*(C'\fR). This is the same as the classic one byte \s-1IP\s0 ToS field, but on the modern Internet, typically only the lower 6 bits are used, and this is called the \s-1DSCP\s0 value. The upper two bits are reserved for \&\s-1ECN\s0 . Hex may be used if prefixed by \f(CW\*(C`0x\*(C'\fR. .Sp Example value: 46 .IP "extraargs" 4 .IX Item "extraargs" Extra arguments to \f(CW\*(C`irtt client\*(C'\fR (see \fBirtt\-client\fR\|(1)). \fBBe careful\fR with extra arguments, as some can corrupt the results. .Sp Example value: \-\-ttl=32 .IP "fill" 4 .IX Item "fill" The fill to use in the payload for the client to server packet (\f(CW\*(C`irtt client \&\-\-fill\*(C'\fR). The \fBlength\fR variable must be large enough so there's a payload to fill. Use rand for random fill, or see \fBirtt\-client\fR\|(1) for more options. .Sp Example value: rand .IP "hmac" 4 .IX Item "hmac" The \&\s-1HMAC\s0 key to use when sending packets to the server (\f(CW\*(C`irtt client \-\-hmac\*(C'\fR). .Sp Example value: opensesame .IP "interval" 4 .IX Item "interval" The interval between successive requests, in seconds (\f(CW\*(C`irtt client \-i\*(C'\fR, but the unit is always seconds (s)). .Sp \&\fB\s-1WARNING\s0\fR .Sp If \fBinterval\fR is increased to greater than 5 seconds, the \fBtimeout\fR (which defaults to \fBpings\fR * 5 seconds + 1) must be modified so that SmokePing doesn't kill the probe prematurely. Additionally, \fBinterval\fR must not be increased such that \fBpings\fR * \fBinterval\fR is greater than \fBstep\fR. For example, at \fBstep\fR=300 and \fBpings\fR=20, the \fBinterval\fR must not be greater than 15 seconds, but should preferably be less to account for handshake and packet wait times. .Sp Example value: 1.5 .Sp Default value: 1 .IP "ipversion" 4 .IX Item "ipversion" The \s-1IP\s0 version to use for packets (4 or 6, corresponding to \f(CW\*(C`irtt client \-4\*(C'\fR or \f(CW\*(C`irtt client \-6\*(C'\fR). By default the \s-1IP\s0 version is chosen based on the supplied host variable. .Sp Example value: 6 .IP "length" 4 .IX Item "length" The length (size) of the packet (\f(CW\*(C`irtt client \-l\*(C'\fR). The length includes \s-1IRTT\s0 headers, but not \s-1IP\s0 or \s-1UDP\s0 headers. The actual packet length is increased to accommodate the \s-1IRTT\s0 headers, if necessary. Header size as of \s-1IRTT 0.9.0\s0 as used in SmokePing is 48 bytes when \fBwriteto\fR is set (since both monotonic and wall clock values are requested) and 40 bytes otherwise. .Sp Example value: 172 .IP "localaddr" 4 .IX Item "localaddr" The local address to bind to when sending packets (\f(CW\*(C`irtt client \-\-local\*(C'\fR). See \fBirtt\-client\fR\|(1) Host formats for valid syntax. .Sp Example value: 192.168.1.10:63814 .IP "metric" 4 .IX Item "metric" The metric to record, one of: .RS 4 .IP "\(bu" 4 rtt: round-trip time .IP "\(bu" 4 send: one-way send delay \&\fI(requires external time synchronization)\fR .IP "\(bu" 4 receive: one-way receive delay \&\fI(requires external time synchronization)\fR .IP "\(bu" 4 ipdv: \s-1IPDV\s0 (instantaneous packet delay variation, or jitter) .IP "\(bu" 4 send_ipdv: \s-1IPDV\s0 for sent packets .IP "\(bu" 4 receive_ipdv: \s-1IPDV\s0 for received packets .RE .RS 4 .Sp Note that the \f(CW\*(C`send\*(C'\fR and \f(CW\*(C`receive\*(C'\fR metrics require accurate external system clock synchronization, otherwise the values from one will be abnormally high and the other will be abnormally low or even negative, in which case the value 0 will be given SmokePing. It is recommended to install ntp on both the SmokePing client and \s-1IRTT\s0 server. Properly configured \s-1NTP\s0 may be able to synchronize time to within a few milliseconds, which is usually enough to provide useful results. \&\s-1PTP\s0 over a \s-1LAN\s0 may achieve microsecond-level accuracy. For best results between geographically remote hosts, \s-1GPS\s0 receivers may be used. Since \f(CW\*(C`send_ipdv\*(C'\fR and \&\f(CW\*(C`receive_ipdv\*(C'\fR measure the variation in times between successive packets, and since \f(CW\*(C`rtt\*(C'\fR and \f(CW\*(C`ipdv\*(C'\fR use monotonic clock values on the client side only, external time synchronization is not required for these metrics. .Sp Default value: rtt .RE .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 "readfrom" 4 .IX Item "readfrom" The name of a file to read results from, instead of running \s-1IRTT.\s0 Use in combination with \fBwriteto\fR to use the results from one \s-1IRTT\s0 run to record multiple metrics. The value will become the name of a file in \fBtmpdir\fR, and must be the same as another target's setting for \fBwriteto\fR. Multiple targets may use the same value for \fBreadfrom\fR, but \fBwriteto\fR and \fBreadfrom\fR may not be both set for a given target. When \fBreadfrom\fR is set, any variables that affect \f(CW\*(C`irtt client\*(C'\fR are ignored because \s-1IRTT\s0 is not being invoked, including: \&\fBdscp\fR, \fBextraargs\fR, \fBfill\fR, \fBhmac\fR, \fBinterval\fR, \fBipversion\fR, \fBlength\fR, \&\fBlocaladdr\fR and \fBserverfill\fR. These values are only relevant in the corresponding \fBwriteto\fR target. .Sp Note that the \fBhost\fR variable must still be defined for targets that define \&\fBreadfrom\fR, otherwise the target won't be used. .Sp When using this feature, be sure to have at least as many \fBforks\fR for the \&\s-1IRTT\s0 probe as you have total \s-1IRTT\s0 targets defined. See the \*(L"\s-1DESCRIPTION\*(R"\s0 section for more information. .Sp Example value: irtt1 .IP "readfrompollinterval" 4 .IX Item "readfrompollinterval" The integer interval in seconds on which to poll for results when \fBreadfrom\fR is set. Lower numbers will allow \fBreadfrom\fR to see the results a bit sooner, at the cost of higher \s-1CPU\s0 usage. Polling does not begin until the soonest time at which the \s-1IRTT\s0 client could have terminated normally. .Sp Example value: 2 .Sp Default value: 5 .IP "serverfill" 4 .IX Item "serverfill" The fill to use in the payload for the server to client packet (\f(CW\*(C`irtt client \&\-\-sfill\*(C'\fR). The \fBlength\fR variable must be large enough to accommodate a payload. Use \f(CW\*(C`rand\*(C'\fR for random fill, or see \fBirtt\-client\fR\|(1) for more options. .Sp Example value: rand .IP "sleep" 4 .IX Item "sleep" The amount of time to sleep before starting requests or processing results (a float in seconds). This may be used to avoid \s-1CPU\s0 spikes caused by invoking multiple instances of \s-1IRTT\s0 at the same time. .Sp Example value: 0.5 .IP "writeto" 4 .IX Item "writeto" The name of a file to write results to after running \s-1IRTT.\s0 Use in combination with \fBreadfrom\fR to use the results from this \s-1IRTT\s0 run to record multiple metrics. The value will become the name of a file in \fBtmpdir\fR, and any targets with \fBreadfrom\fR set to the same value will use this target's results. There must be only one target with \fBwriteto\fR set for a given file, and \fBwriteto\fR and \fBreadfrom\fR may not be both set for a given target. .Sp When using this feature, be sure to have at least as many \fBforks\fR for the \s-1IRTT\s0 probe as you have total \s-1IRTT\s0 targets defined. See the \*(L"\s-1DESCRIPTION\*(R"\s0 section for more information. .Sp Example value: irtt1 .SH "AUTHORS" .IX Header "AUTHORS" Pete Heist