src/collectd-unixsock.5

   1 .\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is turned on, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{
  60 .    if \nF \{
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "COLLECTD-UNIXSOCK 5"
 136 .TH COLLECTD-UNIXSOCK 5 "2015-03-10" "5.4.1.805.g42e4d6c" "collectd"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 collectd\-unixsock \- Documentation of collectd's "unixsock plugin"
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 9
 146 \&  # See collectd.conf(5)
 147 \&  LoadPlugin unixsock
 148 \&  # ...
 149 \&  <Plugin unixsock>
 150 \&    SocketFile "/path/to/socket"
 151 \&    SocketGroup "collectd"
 152 \&    SocketPerms "0770"
 153 \&    DeleteSocket false
 154 \&  </Plugin>
 155 .Ve
 156 .SH "DESCRIPTION"
 157 .IX Header "DESCRIPTION"
 158 The \f(CW\*(C`unixsock plugin\*(C'\fR opens an UNIX-socket over which one can interact with
 159 the daemon. This can be used to use the values collected by collectd in other
 160 applications, such as monitoring solutions, or submit externally collected
 161 values to collectd.
 162 .PP
 163 For example, this plugin is used by \fIcollectd\-nagios\fR\|(1) to check if some
 164 value is in a certain range and exit with a Nagios-compatible exit code.
 165 .SH "COMMANDS"
 166 .IX Header "COMMANDS"
 167 Upon start the \f(CW\*(C`unixsock plugin\*(C'\fR opens a UNIX-socket and waits for
 168 connections. Once a connection is established the client can send commands to
 169 the daemon which it will answer, if it understand them.
 170 .PP
 171 In general the plugin answers with a status line of the following form:
 172 .PP
 173 \&\fIStatus\fR \fIMessage\fR
 174 .PP
 175 If \fIStatus\fR is greater than or equal to zero the message indicates success,
 176 if \fIStatus\fR is less than zero the message indicates failure. \fIMessage\fR is a
 177 human-readable string that further describes the return value.
 178 .PP
 179 On success, \fIStatus\fR furthermore indicates the number of subsequent lines of
 180 output (not including the status line). Each such lines usually contains a
 181 single return value. See the description of each command for details.
 182 .PP
 183 The following commands are implemented:
 184 .IP "\fB\s-1GETVAL\s0\fR \fIIdentifier\fR" 4
 185 .IX Item "GETVAL Identifier"
 186 If the value identified by \fIIdentifier\fR (see below) is found the complete
 187 value-list is returned. The response is a list of name-value-pairs, each pair
 188 on its own line (the number of lines is indicated by the status line \- see
 189 above). Each name-value-pair is of the form \fIname\fR\fB=\fR\fIvalue\fR.
 190 Counter-values are converted to a rate, e.\ g. bytes per second.
 191 Undefined values are returned as \fBNaN\fR.
 192 .Sp
 193 Example:
 194   \-> | \s-1GETVAL\s0 myhost/cpu\-0/cpu\-user
 195   <\- | 1 Value found
 196   <\- | value=1.260000e+00
 197 .IP "\fB\s-1LISTVAL\s0\fR" 4
 198 .IX Item "LISTVAL"
 199 Returns a list of the values available in the value cache together with the
 200 time of the last update, so that querying applications can issue a \fB\s-1GETVAL\s0\fR
 201 command for the values that have changed. Each return value consists of the
 202 update time as an epoch value and the identifier, separated by a space. The
 203 update time is the time of the last value, as provided by the collecting
 204 instance and may be very different from the time the server considers to be
 205 \&\*(L"now\*(R".
 206 .Sp
 207 Example:
 208   \-> | \s-1LISTVAL
 209  \s0 <\- | 69 Values found
 210   <\- | 1182204284 myhost/cpu\-0/cpu\-idle
 211   <\- | 1182204284 myhost/cpu\-0/cpu\-nice
 212   <\- | 1182204284 myhost/cpu\-0/cpu\-system
 213   <\- | 1182204284 myhost/cpu\-0/cpu\-user
 214   ...
 215 .IP "\fB\s-1PUTVAL\s0\fR \fIIdentifier\fR [\fIOptionList\fR] \fIValuelist\fR" 4
 216 .IX Item "PUTVAL Identifier [OptionList] Valuelist"
 217 Submits one or more values (identified by \fIIdentifier\fR, see below) to the
 218 daemon which will dispatch it to all it's write-plugins.
 219 .Sp
 220 An \fIIdentifier\fR is of the form
 221 \&\f(CW\*(C`\f(CIhost\f(CW\f(CB/\f(CW\f(CIplugin\f(CW\f(CB\-\f(CW\f(CIinstance\f(CW\f(CB/\f(CW\f(CItype\f(CW\f(CB\-\f(CW\f(CIinstance\f(CW\*(C'\fR with both
 222 \&\fIinstance\fR\-parts being optional. If they're omitted the hyphen must be
 223 omitted, too. \fIplugin\fR and each \fIinstance\fR\-part may be chosen freely as long
 224 as the tuple (plugin, plugin instance, type instance) uniquely identifies the
 225 plugin within collectd. \fItype\fR identifies the type and number of values
 226 (i.\ e. data-set) passed to collectd. A large list of predefined
 227 data-sets is available in the \fBtypes.db\fR file.
 228 .Sp
 229 The \fIOptionList\fR is an optional list of \fIOptions\fR, where each option is a
 230 key-value-pair. A list of currently understood options can be found below, all
 231 other options will be ignored. Values that contain spaces must be quoted with
 232 double quotes.
 233 .Sp
 234 \&\fIValuelist\fR is a colon-separated list of the time and the values, each either
 235 an integer if the data-source is a counter, or a double if the data-source is
 236 of type \*(L"gauge\*(R". You can submit an undefined gauge-value by using \fBU\fR. When
 237 submitting \fBU\fR to a counter the behavior is undefined. The time is given as
 238 epoch (i.\ e. standard \s-1UNIX\s0 time).
 239 .Sp
 240 You can mix options and values, but the order is important: Options only
 241 effect following values, so specifying an option as last field is allowed, but
 242 useless. Also, an option applies to \fBall\fR following values, so you don't need
 243 to re-set an option over and over again.
 244 .Sp
 245 The currently defined \fBOptions\fR are:
 246 .RS 4
 247 .IP "\fBinterval=\fR\fIseconds\fR" 4
 248 .IX Item "interval=seconds"
 249 Gives the interval in which the data identified by \fIIdentifier\fR is being
 250 collected.
 251 .RE
 252 .RS 4
 253 .Sp
 254 Please note that this is the same format as used in the \fBexec plugin\fR, see
 255 \&\fIcollectd\-exec\fR\|(5).
 256 .Sp
 257 Example:
 258   \-> | \s-1PUTVAL\s0 testhost/interface/if_octets\-test0 interval=10 1179574444:123:456
 259   <\- | 0 Success
 260 .RE
 261 .IP "\fB\s-1PUTNOTIF\s0\fR [\fIOptionList\fR] \fBmessage=\fR\fIMessage\fR" 4
 262 .IX Item "PUTNOTIF [OptionList] message=Message"
 263 Submits a notification to the daemon which will then dispatch it to all plugins
 264 which have registered for receiving notifications.
 265 .Sp
 266 The \fB\s-1PUTNOTIF\s0\fR command is followed by a list of options which further describe
 267 the notification. The \fBmessage\fR option is special in that it will consume the
 268 rest of the line as its value. The \fBmessage\fR, \fBseverity\fR, and \fBtime\fR options
 269 are mandatory.
 270 .Sp
 271 Valid options are:
 272 .RS 4
 273 .IP "\fBmessage=\fR\fIMessage\fR (\fB\s-1REQUIRED\s0\fR)" 4
 274 .IX Item "message=Message (REQUIRED)"
 275 Sets the message of the notification. This is the message that will be made
 276 accessible to the user, so it should contain some useful information. As with
 277 all options: If the message includes spaces, it must be quoted with double
 278 quotes. This option is mandatory.
 279 .IP "\fBseverity=failure\fR|\fBwarning\fR|\fBokay\fR (\fB\s-1REQUIRED\s0\fR)" 4
 280 .IX Item "severity=failure|warning|okay (REQUIRED)"
 281 Sets the severity of the notification. This option is mandatory.
 282 .IP "\fBtime=\fR\fITime\fR (\fB\s-1REQUIRED\s0\fR)" 4
 283 .IX Item "time=Time (REQUIRED)"
 284 Sets the time of the notification. The time is given as \*(L"epoch\*(R", i.\ e. as
 285 seconds since January 1st, 1970, 00:00:00. This option is mandatory.
 286 .IP "\fBhost=\fR\fIHostname\fR" 4
 287 .IX Item "host=Hostname"
 288 .PD 0
 289 .IP "\fBplugin=\fR\fIPlugin\fR" 4
 290 .IX Item "plugin=Plugin"
 291 .IP "\fBplugin_instance=\fR\fIPlugin-Instance\fR" 4
 292 .IX Item "plugin_instance=Plugin-Instance"
 293 .IP "\fBtype=\fR\fIType\fR" 4
 294 .IX Item "type=Type"
 295 .IP "\fBtype_instance=\fR\fIType-Instance\fR" 4
 296 .IX Item "type_instance=Type-Instance"
 297 .PD
 298 These \*(L"associative\*(R" options establish a relation between this notification and
 299 collected performance data. This connection is purely informal, i.\ e. the
 300 daemon itself doesn't do anything with this information. However, websites or
 301 GUIs may use this information to place notifications near the affected graph or
 302 table. All the options are optional, but \fBplugin_instance\fR without \fBplugin\fR
 303 or \fBtype_instance\fR without \fBtype\fR doesn't make much sense and should be
 304 avoided.
 305 .IP "\fBtype:key=\fR\fIvalue\fR" 4
 306 .IX Item "type:key=value"
 307 Sets user defined meta information. The \fBtype\fR key is a single character
 308 defining the type of the meta information.
 309 .Sp
 310 The current supported types are:
 311 .RS 4
 312 .IP "\fBs\fR A string passed as-is." 8
 313 .IX Item "s A string passed as-is."
 314 .RE
 315 .RS 4
 316 .RE
 317 .RE
 318 .RS 4
 319 .Sp
 320 Please note that this is the same format as used in the \fBexec plugin\fR, see
 321 \&\fIcollectd\-exec\fR\|(5).
 322 .Sp
 323 Example:
 324   \-> | \s-1PUTNOTIF\s0 type=temperature severity=warning time=1201094702 message=The roof is on fire!
 325   <\- | 0 Success
 326 .RE
 327 .IP "\fB\s-1FLUSH\s0\fR [\fBtimeout=\fR\fITimeout\fR] [\fBplugin=\fR\fIPlugin\fR [...]] [\fBidentifier=\fR\fIIdent\fR [...]]" 4
 328 .IX Item "FLUSH [timeout=Timeout] [plugin=Plugin [...]] [identifier=Ident [...]]"
 329 Flushes all cached data older than \fITimeout\fR seconds. If no timeout has been
 330 specified, it defaults to \-1 which causes all data to be flushed.
 331 .Sp
 332 If the \fBplugin\fR option has been specified, only the \fIPlugin\fR plugin will be
 333 flushed. You can have multiple \fBplugin\fR options to flush multiple plugins in
 334 one go. If the \fBplugin\fR option is not given all plugins providing a flush
 335 callback will be flushed.
 336 .Sp
 337 If the \fBidentifier\fR option is given only the specified values will be flushed.
 338 This is meant to be used by graphing or displaying frontends which want to have
 339 the latest values for a specific graph. Again, you can specify the
 340 \&\fBidentifier\fR option multiple times to flush several values. If this option is
 341 not specified at all, all values will be flushed.
 342 .Sp
 343 Example:
 344   \-> | \s-1FLUSH\s0 plugin=rrdtool identifier=localhost/df/df\-root identifier=localhost/df/df\-var
 345   <\- | 0 Done: 2 successful, 0 errors
 346 .SS "Identifiers"
 347 .IX Subsection "Identifiers"
 348 Value or value-lists are identified in a uniform fashion:
 349 .PP
 350 \&\fIHostname\fR/\fIPlugin\fR/\fIType\fR
 351 .PP
 352 Where \fIPlugin\fR and \fIType\fR are both either of type "\fIName\fR\*(L" or
 353 \&\*(R"\fIName\fR\-\fIInstance\fR". If the identifier includes spaces, it must be quoted
 354 using double quotes. This sounds more complicated than it is, so here are
 355 some examples:
 356 .PP
 357 .Vb 5
 358 \&  myhost/cpu\-0/cpu\-user
 359 \&  myhost/load/load
 360 \&  myhost/memory/memory\-used
 361 \&  myhost/disk\-sda/disk_octets
 362 \&  "myups/snmp/temperature\-Outlet 1"
 363 .Ve
 364 .SH "ABSTRACTION LAYER"
 365 .IX Header "ABSTRACTION LAYER"
 366 \&\fBcollectd\fR ships the Perl-Module Collectd::Unixsock which
 367 provides an abstraction layer over the actual socket connection. It can be
 368 found in the directory \fIbindings/perl/\fR in the source distribution or
 369 (usually) somewhere near \fI/usr/share/perl5/\fR if you're using a package. If
 370 you want to use Perl to communicate with the daemon, you're encouraged to use
 371 and expand this module.
 372 .SH "SEE ALSO"
 373 .IX Header "SEE ALSO"
 374 \&\fIcollectd\fR\|(1),
 375 \&\fIcollectd.conf\fR\|(5),
 376 \&\fIcollectd\-nagios\fR\|(1),
 377 \&\fIunix\fR\|(7)
 378 .SH "AUTHOR"
 379 .IX Header "AUTHOR"
 380 Florian Forster <octo@collectd.org>