src/collectd.conf.pod

   1 =head1 NAME
   2
   3 collectd.conf - Configuration for the system statistics collection daemon B<collectd>
   4
   5 =head1 SYNOPSIS
   6
   7   BaseDir "/path/to/data/"
   8   PIDFile "/path/to/pidfile/collectd.pid"
   9   Server  "123.123.123.123" 12345
  10
  11   LoadPlugin cpu
  12   LoadPlugin load
  13   LoadPlugin ping
  14
  15   <Plugin ping>
  16     Host "example.org"
  17     Host "provider.net"
  18   </Plugin>
  19
  20 =head1 DESCRIPTION
  21
  22 This config file controls how the system statistics collection daemon
  23 B<collectd> behaves. The most significant option is B<LoadPlugin>, which
  24 controls which plugins to load. These plugins ultimately define collectd's
  25 behavior.
  26
  27 The syntax of this config file is similar to the config file of the famous
  28 B<Apache Webserver>. Each line contains either a key-value-pair or a
  29 section-start or -end. Empty lines and everything after the hash-symbol `#' is
  30 ignored. Values are either string, enclosed in double-quotes,
  31 (floating-point-)numbers or a boolean expression, i.E<nbsp>e. either B<true> or
  32 B<false>. String containing of only alphanumeric characters and underscores do
  33 not need to be quoted.
  34
  35 The configuration is read and processed in order, i.E<nbsp>e. from top to
  36 bottom. So the plugins are loaded in the order listed in this config file. It
  37 is a good idea to load any logging plugins first in order to catch messages
  38 from plugins during configuration. Also, the C<LoadPlugin> option B<must> occur
  39 B<before> the C<E<lt>Plugin ...E<gt>> block.
  40
  41 =head1 GLOBAL OPTIONS
  42
  43 =over 4
  44
  45 =item B<BaseDir> I<Directory>
  46
  47 Sets the base directory. This is the directory beneath all RRD-files are
  48 created. Possibly more subdirectories are created. This is also the working
  49 directory for the daemon.
  50
  51 =item B<LoadPlugin> I<Plugin>
  52
  53 Loads the plugin I<Plugin>. There must be at least one such line or B<collectd>
  54 will be mostly useless.
  55
  56 =item B<Include> I<File>
  57
  58 Includes the file I<File> as if it was copy and pasted here. To prevent loops
  59 and shooting yourself in the foot in interesting ways the nesting is limited to
  60 a depth of 8E<nbsp>levels, which should be sufficient for most uses.
  61
  62 It is no problem to have a block like C<E<lt>Plugin fooE<gt>> in more than one
  63 file, but you cannot include files from within blocks.
  64
  65 =item B<PIDFile> I<File>
  66
  67 Sets where to write the PID file to. This file is overwritten when it exists
  68 and deleted when the program is stopped. Some init-scripts might override this
  69 setting using the B<-P> command-line option.
  70
  71 =item B<PluginDir> I<Directory>
  72
  73 Path to the plugins (shared objects) of collectd.
  74
  75 =item B<TypesDB> I<File> [I<File> ...]
  76
  77 Set one or more files that contain the data-set descriptions. See
  78 L<types.db(5)> for a description of the format of this file.
  79
  80 =item B<Interval> I<Seconds>
  81
  82 Configures the interval in which to query the read plugins. Obviously smaller
  83 values lead to a higher system load produced by collectd, while higher values
  84 lead to more coarse statistics.
  85
  86 =item B<ReadThreads> I<Num>
  87
  88 Number of threads to start for reading plugins. The default value is B<5>, but
  89 you may want to increase this if you have more than five plugins that take a
  90 long time to read. Mostly those are plugin that do network-IO. Setting this to
  91 a value higher than the number of plugins you've loaded is totally useless.
  92
  93 =item B<Hostname> I<Name>
  94
  95 Sets the hostname that identifies a host. If you omit this setting, the
  96 hostname will be determinded using the L<gethostname(2)> system call.
  97
  98 =item B<FQDNLookup> B<true|false>
  99
 100 If B<Hostname> is determined automatically this setting controls whether or not
 101 the daemon should try to figure out the "fully qualified domain name", FQDN.
 102 This is done using a lookup of the name returned by C<gethostname>.
 103
 104 Using this feature (i.E<nbsp>e. setting this option to B<true>) is recommended.
 105 However, to preserve backwards compatibility the default is set to B<false>.
 106 The sample config file that is installed with C<makeE<nbsp>install> includes a
 107 line which sets this option, though, so that default installations will have
 108 this setting enabled.
 109
 110 =back
 111
 112 =head1 PLUGIN OPTIONS
 113
 114 Some plugins may register own options. These options must be enclosed in a
 115 C<Plugin>-Section. Which options exist depends on the plugin used. Some plugins
 116 require external configuration, too. The C<apache plugin>, for example,
 117 required C<mod_status> to be configured in the webserver you're going to
 118 collect data from. These plugins are listed below as well, even if they don't
 119 require any configuration within collectd's configfile.
 120
 121 A list of all plugins and a short summary for each plugin can be found in the
 122 F<README> file shipped with the sourcecode and hopefully binary packets as
 123 well.
 124
 125 =head2 Plugin C<apache>
 126
 127 To configure the C<apache>-plugin you first need to configure the Apache
 128 webserver correctly. The Apache-plugin C<mod_status> needs to be loaded and
 129 working and the C<ExtendedStatus> directive needs to be B<enabled>. You can use
 130 the following snipped to base your Apache config upon:
 131
 132   ExtendedStatus on
 133   <IfModule mod_status.c>
 134     <Location /mod_status>
 135       SetHandler server-status
 136     </Location>
 137   </IfModule>
 138
 139 Since its C<mod_status> module is very similar to Apache's, B<lighttpd> is
 140 also supported. It introduces a new field, called C<BusyServers>, to count the
 141 number of currently connected clients. This field is also supported.
 142
 143 The following options are accepted by the C<apache>-plugin:
 144
 145 =over 4
 146
 147 =item B<URL> I<http://host/mod_status?auto>
 148
 149 Sets the URL of the C<mod_status> output. This needs to be the output generated
 150 by C<ExtendedStatus on> and it needs to be the machine readable output
 151 generated by appending the C<?auto> argument.
 152
 153 =item B<User> I<Username>
 154
 155 Optional user name needed for authentication.
 156
 157 =item B<Password> I<Password>
 158
 159 Optional password needed for authentication.
 160
 161 =item B<CACert> I<File>
 162
 163 File that holds one or more SSL certificates. If you want to use HTTPS you will
 164 possibly need this option. What CA certificates come bundled with C<libcurl>
 165 and are checked by default depends on the distribution you use.
 166
 167 =back
 168
 169 =head2 Plugin C<apcups>
 170
 171 =over 4
 172
 173 =item B<Host> I<Hostname>
 174
 175 Hostname of the host running B<apcupsd>. Defaults to B<localhost>. Please note
 176 that IPv6 support has been disabled unless someone can confirm or decline that
 177 B<apcupsd> can handle it.
 178
 179 =item B<Port> I<Port>
 180
 181 TCP-Port to connect to. Defaults to B<3551>.
 182
 183 =back
 184
 185 =head2 Plugin C<cpufreq>
 186
 187 This plugin doesn't have any options. It reads
 188 F</sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq> (for the first CPU
 189 installed) to get the current CPU frequency. If this file does not exist make
 190 sure B<cpufreqd> (L<http://cpufreqd.sourceforge.net/>) or a similar tool is
 191 installed and an "cpu governor" (that's a kernel module) is loaded.
 192
 193 =head2 Plugin C<csv>
 194
 195 =over 4
 196
 197 =item B<DataDir> I<Directory>
 198
 199 Set the directory to store CSV-files under. Per default CSV-files are generated
 200 beneath the daemon's working directory, i.E<nbsp>e. the B<BaseDir>.
 201
 202 =item B<StoreRates> B<true|false>
 203
 204 If set to B<true>, convert counter values to rates. If set to B<false> (the
 205 default) counter values are stored as is, i.E<nbsp>e. as an increasing integer
 206 number.
 207
 208 =back
 209
 210 =head2 Plugin C<df>
 211
 212 =over 4
 213
 214 =item B<Device> I<Device>
 215
 216 Select partitions based on the devicename.
 217
 218 =item B<MountPoint> I<Directory>
 219
 220 Select partitions based on the mountpoint.
 221
 222 =item B<FSType> I<FSType>
 223
 224 Select partitions based on the filesystem type.
 225
 226 =item B<IgnoreSelected> I<true>|I<false>
 227
 228 Invert the selection: If set to true, all partitions B<except> the ones that
 229 match any one of the criteria are collected. By default only selected
 230 partitions are collected if a selection is made. If no selection is configured
 231 at all, B<all> partitions are selected.
 232
 233 =back
 234
 235 =head2 Plugin C<dns>
 236
 237 =over 4
 238
 239 =item B<Interface> I<Interface>
 240
 241 The dns plugin uses B<libpcap> to capture dns traffic and analyses it. This
 242 option sets the interface that should be used. If this option is not set, or
 243 set to "any", the plugin will try to get packets from B<all> interfaces. This
 244 may not work on certain platforms, such as MacE<nbsp>OSE<nbsp>X.
 245
 246 =item B<IgnoreSource> I<IP-address>
 247
 248 Ignore packets that originate from this address.
 249
 250 =back
 251
 252 =head2 Plugin C<email>
 253
 254 =over 4
 255
 256 =item B<SocketFile> I<Path>
 257
 258 Sets the socket-file which is to be created.
 259
 260 =item B<SocketGroup> I<Group>
 261
 262 If running as root change the group of the UNIX-socket after it has been
 263 created. Defaults to B<collectd>.
 264
 265 =item B<SocketPerms> I<Permissions>
 266
 267 Change the file permissions of the UNIX-socket after it has been created. The
 268 permissions must be given as a numeric, octal value as you would pass to
 269 L<chmod(1)>. Defaults to B<0770>.
 270
 271 =item B<MaxConns> I<Number>
 272
 273 Sets the maximum number of connections that can be handled in parallel. Since
 274 this many threads will be started immediately setting this to a very high
 275 value will waste valuable resources. Defaults to B<5> and will be forced to be
 276 at most B<16384> to prevent typos and dumb mistakes.
 277
 278 =back
 279
 280 =head2 Plugin C<exec>
 281
 282 Please make sure to read L<collectd-exec(5)> before using this plugin. It
 283 contains valuable information on when the executable is executed and the
 284 output that is expected from it.
 285
 286 =over 4
 287
 288 =item B<Exec> I<User>[:[I<Group>]] I<Executable> [I<E<lt>argE<gt>> [I<E<lt>argE<gt>> ...]]
 289
 290 =item B<NotificationExec> I<User>[:[I<Group>]] I<Executable> [I<E<lt>argE<gt>> [I<E<lt>argE<gt>> ...]]
 291
 292 =item B<NagiosExec> I<User>[:[I<Group>]] I<Executable> [I<E<lt>argE<gt>> [I<E<lt>argE<gt>> ...]]
 293
 294 Execute the executable I<Executable> as user I<User>. If the user name is
 295 followed by a colon and a group name, the effective group is set to that group.
 296 The real group and saved-set group will be set to the default group of that
 297 user. If no group is given the effective group ID will be the same as the real
 298 group ID.
 299
 300 Please note that in order to change the user and/or group the daemon needs
 301 superuser privileges. If the daemon is run as an unprivileged user you must
 302 specify the same user/group here. If the daemon is run with superuser
 303 privileges, you must supply a non-root user here.
 304
 305 The executable may be followed by optional arguments that are passed to the
 306 program. Please note that due to the configuration parsing numbers and boolean
 307 values may be changed. If you want to be absolutely sure that something is
 308 passed as-is please enclose it in quotes.
 309
 310 The B<Exec>, B<NotificationExec>, and B<NagiosExec> statements change the
 311 semantics of the programs executed, i.E<nbsp>e. the data passed to them and the
 312 response expected from them. This is documented in great detail in
 313 L<collectd-exec(5)>.
 314
 315 =back
 316
 317 =head2 Plugin C<hddtemp>
 318
 319 To get values from B<hddtemp> collectd connects to B<localhost> (127.0.0.1),
 320 port B<7634/tcp>. The B<Host> and B<Port> options can be used to change these
 321 default values, see below. C<hddtemp> has to be running to work correctly. If
 322 C<hddtemp> is not running timeouts may appear which may interfere with other
 323 statistics..
 324
 325 The B<hddtemp> homepage can be found at
 326 L<http://www.guzu.net/linux/hddtemp.php>.
 327
 328 =over 4
 329
 330 =item B<Host> I<Hostname>
 331
 332 Hostname to connect to. Defaults to B<127.0.0.1>.
 333
 334 =item B<Port> I<Port>
 335
 336 TCP-Port to connect to. Defaults to B<7634>.
 337
 338 =back
 339
 340 =head2 Plugin C<interface>
 341
 342 =over 4
 343
 344 =item B<Interface> I<Interface>
 345
 346 Select this interface. By default these interfaces will then be collected. For
 347 a more detailed description see B<IgnoreSelected> below.
 348
 349 =item B<IgnoreSelected> I<true>|I<false>
 350
 351 If no configuration if given, the B<traffic>-plugin will collect data from
 352 all interfaces. This may not be practical, especially for loopback- and
 353 similar interfaces. Thus, you can use the B<Interface>-option to pick the
 354 interfaces you're interested in. Sometimes, however, it's easier/preferred
 355 to collect all interfaces I<except> a few ones. This option enables you to
 356 do that: By setting B<IgnoreSelected> to I<true> the effect of
 357 B<Interface> is inversed: All selected interfaces are ignored and all
 358 other interfaces are collected.
 359
 360 =back
 361
 362 =head2 Plugin C<iptables>
 363
 364 =over 4
 365
 366 =item B<Chain> I<Table> I<Chain> [I<Comment|Number> [I<Name>]]
 367
 368 Select the rules to count. If only I<Table> and I<Chain> are given, this plugin
 369 will collect the counters of all rules which have a comment-match. The comment
 370 is then used as type-instance.
 371
 372 If I<Comment> or I<Number> is given, only the rule with the matching comment or
 373 the I<n>th rule will be collected. Again, the comment (or the number) will be
 374 used as the type-instance.
 375
 376 If I<Name> is supplied, it will be used as the type-instance instead of the
 377 comment or the number.
 378
 379 =back
 380
 381 =head2 Plugin C<irq>
 382
 383 =over 4
 384
 385 =item B<Irq> I<Irq>
 386
 387 Select this irq. By default these irqs will then be collected. For a more
 388 detailed description see B<IgnoreSelected> below.
 389
 390 =item B<IgnoreSelected> I<true>|I<false>
 391
 392 If no configuration if given, the B<irq>-plugin will collect data from all
 393 irqs. This may not be practical, especially if no interrupts happen. Thus, you
 394 can use the B<Irq>-option to pick the interrupt you're interested in.
 395 Sometimes, however, it's easier/preferred to collect all interrupts I<except> a
 396 few ones. This option enables you to do that: By setting B<IgnoreSelected> to
 397 I<true> the effect of B<Irq> is inversed: All selected interrupts are ignored
 398 and all other interrupts are collected.
 399
 400 =back
 401
 402 =head2 Plugin C<libvirt>
 403
 404 This plugin allows CPU, disk and network load to be collected for virtualized
 405 guests on the machine. This means that these characteristics can be collected
 406 for guest systems without installing any software on them - collectd only runs
 407 on the hosting system. The statistics are collected through libvirt
 408 (L<http://libvirt.org/>).
 409
 410 Only I<Connection> is required.
 411
 412 =over 4
 413
 414 =item B<Connection> I<uri>
 415
 416 Connect to the hypervisor given by I<uri>. For example if using Xen use:
 417
 418  Connection "xen:///"
 419
 420 Details which URIs allowed are given at L<http://libvirt.org/uri.html>.
 421
 422 =item B<RefreshInterval> I<seconds>
 423
 424 Refresh the list of domains and devices every I<seconds>. The default is 60
 425 seconds. Setting this to be the same or smaller than the I<Interval> will cause
 426 the list of domains and devices to be refreshed on every iteration.
 427
 428 Refreshing the devices in particular is quite a costly operation, so if your
 429 virtualization setup is static you might consider increasing this.
 430
 431 =item B<Domain> I<name>
 432
 433 =item B<BlockDevice> I<name:dev>
 434
 435 =item B<InterfaceDevice> I<name:dev>
 436
 437 =item B<IgnoreSelected> I<true>|I<false>
 438
 439 Select which domains and devices are collected.
 440
 441 If I<IgnoreSelected> is not given or I<false> then only the listed domains and
 442 disk/network devices are collected.
 443
 444 If I<IgnoreSelected> is I<true> then the test is reversed and the listed
 445 domains and disk/network devices are ignored, while the rest are collected.
 446
 447 The domain name and device names may use a regular expression, if the name is
 448 surrounded by I</.../> and collectd was compiled with support for regexps.
 449
 450 The default is to collect statistics for all domains and all their devices.
 451
 452 Example:
 453
 454  BlockDevice "/:hdb/"
 455  IgnoreSelected "true"
 456
 457 Ignore all I<hdb> devices on any domain, but other block devices (eg. I<hda>)
 458 will be collected.
 459
 460 =item B<HostnameFormat> B<name|uuid|hostname|...>
 461
 462 When the libvirt plugin logs data, it sets the hostname of the collected data
 463 according to this setting. The default is to use the guest name as provided by
 464 the hypervisor, which is equal to setting B<name>.
 465
 466 B<uuid> means use the guest's UUID. This is useful if you want to track the
 467 same guest across migrations.
 468
 469 B<hostname> means to use the global B<Hostname> setting, which is probably not
 470 useful on its own because all guests will appear to have the same name.
 471
 472 You can also specify combinations of these fields. For example B<name uuid>
 473 means to concatenate the guest name and UUID (with a literal colon character
 474 between, thus I<"foo:1234-1234-1234-1234">).
 475
 476 =back
 477
 478 =head2 Plugin C<logfile>
 479
 480 =over 4
 481
 482 =item B<LogLevel> B<debug|info|notice|warning|err>
 483
 484 Sets the log-level. If, for example, set to B<notice>, then all events with
 485 severity B<notice>, B<warning>, or B<err> will be written to the logfile.
 486
 487 Please note that B<debug> is only available if collectd has been compiled with
 488 debugging support.
 489
 490 =item B<File> I<File>
 491
 492 Sets the file to write log messages to. The special strings B<stdout> and
 493 B<stderr> can be used to write to the standard output and standard error
 494 channels, respectively. This, of course, only makes much sense when collectd is
 495 running in foreground- or non-daemon-mode.
 496
 497 =item B<Timestamp> B<true>|B<false>
 498
 499 Prefix all lines printed by the current time. Defaults to B<true>.
 500
 501 =back
 502
 503 =head2 Plugin C<mbmon>
 504
 505 The C<mbmon plugin> uses mbmon to retrieve temperature, voltage, etc.
 506
 507 Be default collectd connects to B<localhost> (127.0.0.1), port B<411/tcp>. The
 508 B<Host> and B<Port> options can be used to change these values, see below.
 509 C<mbmon> has to be running to work correctly. If C<mbmon> is not running
 510 timeouts may appear which may interfere with other statistics..
 511
 512 C<mbmon> must be run with the -r option ("print TAG and Value format");
 513 Debian's F</etc/init.d/mbmon> script already does this, other people
 514 will need to ensure that this is the case.
 515
 516 =over 4
 517
 518 =item B<Host> I<Hostname>
 519
 520 Hostname to connect to. Defaults to B<127.0.0.1>.
 521
 522 =item B<Port> I<Port>
 523
 524 TCP-Port to connect to. Defaults to B<411>.
 525
 526 =back
 527
 528 =head2 Plugin C<memcached>
 529
 530 The C<memcached plugin> connects to a memcached server and queries statistics
 531 about cache utilization, memory and bandwidth used.
 532 L<http://www.danga.com/memcached/>
 533
 534 =over 4
 535
 536 =item B<Host> I<Hostname>
 537
 538 Hostname to connect to. Defaults to B<127.0.0.1>.
 539
 540 =item B<Port> I<Port>
 541
 542 TCP-Port to connect to. Defaults to B<11211>.
 543
 544 =back
 545
 546 =head2 Plugin C<mysql>
 547
 548 The C<mysql plugin> requires B<mysqlclient> to be installed. It connects to the
 549 database when started and keeps the connection up as long as possible. When the
 550 connection is interrupted for whatever reason it will try to re-connect. The
 551 plugin will complaint loudly in case anything goes wrong.
 552
 553 This plugin issues C<SHOW STATUS> and evaluates C<Bytes_{received,sent}>,
 554 C<Com_*> and C<Handler_*> which correspond to F<mysql_octets.rrd>,
 555 F<mysql_commands-*.rrd> and F<mysql_handler-*.rrd>. Also, the values of
 556 C<Qcache_*> are put in F<mysql_qcache.rrd> and values of C<Threads_*> are put
 557 in F<mysql_threads.rrd>. Please refer to the B<MySQL reference manual>,
 558 I<5.2.4. Server Status Variables> for an explanation of these values.
 559
 560 Use the following options to configure the plugin:
 561
 562 =over 4
 563
 564 =item B<Host> I<Hostname>
 565
 566 Hostname of the database server. Defaults to B<localhost>.
 567
 568 =item B<User> I<Username>
 569
 570 Username to use when connecting to the database.
 571
 572 =item B<Password> I<Password>
 573
 574 Password needed to log into the database.
 575
 576 =item B<Database> I<Database>
 577
 578 Select this database. Defaults to I<no database> which is a perfectly reasonable
 579 option for what this plugin does.
 580
 581 =back
 582
 583 =head2 Plugin C<netlink>
 584
 585 The C<netlink> plugin uses a netlink socket to query the Linux kernel about
 586 statistics of various interface and routing aspects.
 587
 588 =over 4
 589
 590 =item B<Interface> I<Interface>
 591
 592 =item B<VerboseInterface> I<Interface>
 593
 594 Instruct the plugin to collect interface statistics. This is basically the same
 595 as the statistics provided by the C<interface> plugin (see above) but
 596 potentially much more detailed.
 597
 598 When configuring with B<Interface> only the basic statistics will be collected,
 599 namely octets, packets, and errors. These statistics are collected by
 600 the C<interface> plugin, too, so using both at the same time is no benefit.
 601
 602 When configured with B<VerboseInterface> all counters B<except> the basic ones,
 603 so that no data needs to be collected twice if you use the C<interface> plugin.
 604 This includes dropped packets, received multicast packets, collisions and a
 605 whole zoo of differentiated RX and TX errors. You can try the following command
 606 to get an idea of what awaits you:
 607
 608   ip -s -s link list
 609
 610 If I<Interface> is B<All>, all interfaces will be selected.
 611
 612 =item B<QDisc> I<Interface> [I<QDisc>]
 613
 614 =item B<Class> I<Interface> [I<Class>]
 615
 616 =item B<Filter> I<Interface> [I<Filter>]
 617
 618 Collect the octets and packets that pass a certain qdisc, class or filter.
 619
 620 QDiscs and classes are identified by their type and handle (or classid).
 621 Filters don't necessarily have a handle, therefore the parent's handle is used.
 622 The notation used in collectd differs from that used in tc(1) in that it
 623 doesn't skip the major or minor number if it's zero and doesn't print special
 624 ids by their name. So, for example, a qdisc may be identified by
 625 C<pfifo_fast-1:0> even though the minor number of B<all> qdiscs is zero and
 626 thus not displayed by tc(1).
 627
 628 If B<QDisc>, B<Class>, or B<Filter> is given without the second argument,
 629 i.E<nbsp>.e. without an identifier, all qdiscs, classes, or filters that are
 630 associated with that interface will be collected.
 631
 632 Since a filter itself doesn't necessarily have a handle, the parent's handle is
 633 used. This may lead to problems when more than one filter is attached to a
 634 qdisc or class. This isn't nice, but we don't know how this could be done any
 635 better. If you have a idea, please don't hesitate to tell us.
 636
 637 As with the B<Interface> option you can specify B<All> as the interface,
 638 meaning all interfaces.
 639
 640 Here are some examples to help you understand the above text more easily:
 641
 642   <Plugin netlink>
 643     VerboseInterface "All"
 644     QDisc "eth0" "pfifo_fast-1:0"
 645     QDisc "ppp0"
 646     Class "ppp0" "htb-1:10"
 647     Filter "ppp0" "u32-1:0"
 648   </Plugin>
 649
 650 =item B<IgnoreSelected>
 651
 652 The behaviour is the same as with all other similar plugins: If nothing is
 653 selected at all, everything is collected. If some things are selected using the
 654 options described above, only these statistics are collected. If you set
 655 B<IgnoreSelected> to B<true>, this behavior is inversed, i.E<nbsp>e. the
 656 specified statistics will not be collected.
 657
 658 =back
 659
 660 =head2 Plugin C<network>
 661
 662 =over 4
 663
 664 =item B<Listen> I<Host> [I<Port>]
 665
 666 =item B<Server> I<Host> [I<Port>]
 667
 668 The B<Server> statement sets the server to send datagrams B<to>.  The statement
 669 may occur multiple times to send each datagram to multiple destinations.
 670
 671 The B<Listen> statement sets the interfaces to bind to. When multiple
 672 statements are found the daemon will bind to multiple interfaces.
 673
 674 The argument I<Host> may be a hostname, an IPv4 address or an IPv6 address. If
 675 the argument is a multicast address the daemon will join that multicast group.
 676
 677 If no B<Listen> statement is found the server tries join both, the default IPv6
 678 multicast group and the default IPv4 multicast group. If no B<Server> statement
 679 is found the client will try to send data to the IPv6 multicast group first. If
 680 that fails the client will try the IPv4 multicast group.
 681
 682 The default IPv6 multicast group is C<ff18::efc0:4a42>. The default IPv4
 683 multicast group is C<239.192.74.66>.
 684
 685 The optional I<Port> argument sets the port to use. It can either be given
 686 using a numeric port number or a service name. If the argument is omitted the
 687 default port B<25826> is assumed.
 688
 689 =item B<TimeToLive> I<1-255>
 690
 691 Set the time-to-live of sent packets. This applies to all, unicast and
 692 multicast, and IPv4 and IPv6 packets. The default is to not change this value.
 693 That means that multicast packets will be sent with a TTL of C<1> (one) on most
 694 operating systems.
 695
 696 =item B<Forward> I<true|false>
 697
 698 If set to I<true>, write packets that were received via the network plugin to
 699 the sending sockets. This should only be activated when the B<Listen>- and
 700 B<Server>-statements differ. Otherwise packets may be send multiple times to
 701 the same multicast group. While this results in more network traffic than
 702 necessary it's not a huge problem since the plugin has a duplicate detection,
 703 so the values will not loop.
 704
 705 =item B<CacheFlush> I<Seconds>
 706
 707 For each host/plugin/type combination the C<network plugin> caches the time of
 708 the last value being sent or received. Every I<Seconds> seconds the plugin
 709 searches and removes all entries that are older than I<Seconds> seconds, thus
 710 freeing the unused memory again. Since this process is somewhat expensive and
 711 normally doesn't do much, this value should not be too small. The default is
 712 1800 seconds, but setting this to 86400 seconds (one day) will not do much harm
 713 either.
 714
 715 =back
 716
 717 =head2 Plugin C<nginx>
 718
 719 This plugin collects the number of connections and requests handled by the
 720 C<nginx daemon> (speak: engineE<nbsp>X), a HTTP and mail server/proxy. It
 721 queries the page provided by the C<ngx_http_stub_status_module> module, which
 722 isn't compiled by default. Please refer to
 723 L<http://wiki.codemongers.com/NginxStubStatusModule> for more information on
 724 how to compile and configure nginx and this module.
 725
 726 The following options are accepted by the C<nginx plugin>:
 727
 728 =over 4
 729
 730 =item B<URL> I<http://host/nginx_status>
 731
 732 Sets the URL of the C<ngx_http_stub_status_module> output.
 733
 734 =item B<User> I<Username>
 735
 736 Optional user name needed for authentication.
 737
 738 =item B<Password> I<Password>
 739
 740 Optional password needed for authentication.
 741
 742 =item B<CACert> I<File>
 743
 744 File that holds one or more SSL certificates. If you want to use HTTPS you will
 745 possibly need this option. What CA certificates come bundled with C<libcurl>
 746 and are checked by default depends on the distribution you use.
 747
 748 =back
 749
 750 =head2 Plugin C<ntpd>
 751
 752 =over 4
 753
 754 =item B<Host> I<Hostname>
 755
 756 Hostname of the host running B<ntpd>. Defaults to B<localhost>.
 757
 758 =item B<Port> I<Port>
 759
 760 UDP-Port to connect to. Defaults to B<123>.
 761
 762 =item B<ReverseLookups> B<true>|B<false>
 763
 764 Sets wether or not to perform reverse lookups on peers. Since the name or
 765 IP-address may be used in a filename it is recommended to disable reverse
 766 lookups. The default is to do reverse lookups to preserve backwards
 767 compatibility, though.
 768
 769 =back
 770
 771 =head2 Plugin C<nut>
 772
 773 =over 4
 774
 775 =item B<UPS> I<upsname>B<@>I<hostname>[B<:>I<port>]
 776
 777 Add a UPS to collect data from. The format is identical to the one accepted by
 778 L<upsc(8)>.
 779
 780 =back
 781
 782 =head2 Plugin C<perl>
 783
 784 This plugin embeds a Perl-interpreter into collectd and provides an interface
 785 to collectd's plugin system. See L<collectd-perl(5)> for its documentation.
 786
 787 =head2 Plugin C<ping>
 788
 789 =over 4
 790
 791 =item B<Host> I<IP-address>
 792
 793 Host to ping periodically. This option may be repeated several times to ping
 794 multiple hosts.
 795
 796 =item B<TTL> I<0-255>
 797
 798 Sets the Time-To-Live of generated ICMP packets.
 799
 800 =back
 801
 802 =head2 Plugin C<processes>
 803
 804 =over 4
 805
 806 =item B<Process> I<Name>
 807
 808 Select more detailed statistics of processes matching this name. The statistics
 809 collected for these selected processes are size of the resident segment size
 810 (RSS), user- and system-time used, number of processes and number of threads,
 811 and minor and major pagefaults.
 812
 813 =back
 814
 815 =head2 Plugin C<rrdtool>
 816
 817 You can use the settings B<StepSize>, B<HeartBeat>, B<RRARows>, and B<XFF> to
 818 fine-tune your RRD-files. Please read L<rrdcreate(1)> if you encounter problems
 819 using these settings. If you don't want to dive into the depths of RRDTool, you
 820 can safely ignore these settings.
 821
 822 =over 4
 823
 824 =item B<DataDir> I<Directory>
 825
 826 Set the directory to store RRD-files under. Per default RRD-files are generated
 827 beneath the daemon's working directory, i.E<nbsp>e. the B<BaseDir>.
 828
 829 =item B<StepSize> I<Seconds>
 830
 831 B<Force> the stepsize of newly created RRD-files. Ideally (and per default)
 832 this setting is unset and the stepsize is set to the interval in which the data
 833 is collected. Do not use this option unless you absolutely have to for some
 834 reason. Setting this option may cause problems with the C<snmp plugin>, the
 835 C<exec plugin> or when the daemon is set up to receive data from other hosts.
 836
 837 =item B<HeartBeat> I<Seconds>
 838
 839 B<Force> the heartbeat of newly created RRD-files. This setting should be unset
 840 in which case the heartbeat is set to twice the B<StepSize> which should equal
 841 the interval in which data is collected. Do not set this option unless you have
 842 a very good reason to do so.
 843
 844 =item B<RRARows> I<NumRows>
 845
 846 The C<rrdtool plugin> calculates the number of PDPs per CDP based on the
 847 B<StepSize>, this setting and a timespan. This plugin creates RRD-files with
 848 three times five RRAs, i. e. five RRAs with the CFs B<MIN>, B<AVERAGE>, and
 849 B<MAX>. The five RRAs are optimized for graphs covering one hour, one day, one
 850 week, one month, and one year.
 851
 852 So for each timespan, it calculates how many PDPs need to be consolidated into
 853 one CDP by calculating:
 854   number of PDPs = timespan / (stepsize * rrarows)
 855
 856 Bottom line is, set this no smaller than the width of you graphs in pixels. The
 857 default is 1200.
 858
 859 =item B<RRATimespan> I<Seconds>
 860
 861 Adds an RRA-timespan, given in seconds. Use this option multiple times to have
 862 more then one RRA. If this option is never used, the built-in default of (3600,
 863 86400, 604800, 2678400, 31622400) is used.
 864
 865 For more information on how RRA-sizes are calculated see B<RRARows> above.
 866
 867 =item B<XFF> I<Factor>
 868
 869 Set the "XFiles Factor". The default is 0.1. If unsure, don't set this option.
 870
 871 =item B<CacheFlush> I<Seconds>
 872
 873 When the C<rrdtool plugin> uses a cache (by setting B<CacheTimeout>, see below)
 874 it writes all values for a certain RRD-file if the oldest value is older than
 875 (or equal to) the number of seconds specified. If some RRD-file is not updated
 876 anymore for some reason (the computer was shut down, the network is broken,
 877 etc.) some values may still be in the cache. If B<CacheFlush> is set, then the
 878 entire cache is searched for entries older than B<CacheTimeout> seconds and
 879 written to disk every I<Seconds> seconds. Since this is kind of expensive and
 880 does nothing under normal circumstances, this value should not be too small.
 881 900 seconds might be a good value, though setting this to 7200 seconds doesn't
 882 normally do much harm either.
 883
 884 =item B<CacheTimeout> I<Seconds>
 885
 886 If this option is set to a value greater than zero, the C<rrdtool plugin> will
 887 save values in a cache, as described above. Writing multiple values at once
 888 reduces IO-operations and thus lessens the load produced by updating the files.
 889 The trade off is that the graphs kind of "drag behind" and that more memory is
 890 used.
 891
 892 =back
 893
 894 =head2 Plugin C<sensors>
 895
 896 The C<sensors plugin> uses B<lm_sensors> to retrieve sensor-values. This means
 897 that all the needed modules have to be loaded and lm_sensors has to be
 898 configured (most likely by editing F</etc/sensors.conf>. Read
 899 L<sensors.conf(5)> for details.
 900
 901 The B<lm_sensors> homepage can be found at
 902 L<http://secure.netroedge.com/~lm78/>.
 903
 904 =over 4
 905
 906 =item B<Sensor> I<chip-bus-address/type-feature>
 907
 908 Selects the name of the sensor which you want to collect or ignore, depending
 909 on the B<IgnoreSelected> below. For example, the option "B<Sensor>
 910 I<it8712-isa-0290/voltage-in1>" will cause collectd to gather data for the
 911 voltage sensor I<in1> of the I<it8712> on the isa bus at the address 0290.
 912
 913 =item B<IgnoreSelected> I<true>|I<false>
 914
 915 If no configuration if given, the B<sensors>-plugin will collect data from all
 916 sensors. This may not be practical, especially for uninteresting sensors.
 917 Thus, you can use the B<Sensor>-option to pick the sensors you're interested
 918 in. Sometimes, however, it's easier/preferred to collect all sensors I<except> a
 919 few ones. This option enables you to do that: By setting B<IgnoreSelected> to
 920 I<true> the effect of B<Sensor> is inversed: All selected sensors are ignored
 921 and all other sensors are collected.
 922
 923 =back
 924
 925 =head2 Plugin C<snmp>
 926
 927 Since the configuration of the C<snmp plugin> is a little more complicated than
 928 other plugins, its documentation has been moved to an own manpage,
 929 L<collectd-snmp(5)>. Please see there for details.
 930
 931 =head2 Plugin C<syslog>
 932
 933 =over 4
 934
 935 =item B<LogLevel> B<debug|info|notice|warning|err>
 936
 937 Sets the log-level. If, for example, set to B<notice>, then all events with
 938 severity B<notice>, B<warning>, or B<err> will be submitted to the
 939 syslog-daemon.
 940
 941 Please note that B<debug> is only available if collectd has been compiled with
 942 debugging support.
 943
 944 =back
 945
 946 =head2 Plugin C<tcpconns>
 947
 948 The C<tcpconns plugin> counts the number of currently established TCP
 949 connections based on the local port and/or the remote port. Since there may be
 950 a lot of connections the default if to count all connections with a local port,
 951 for which a listening socket is opened. You can use the following options to
 952 fine-tune the ports you are interested in:
 953
 954 =over 4
 955
 956 =item B<ListeningPorts> I<true>|I<false>
 957
 958 If this option is set to I<true>, statistics for all local ports for which a
 959 listening socket exists are collected. The default depends on B<LocalPort> and
 960 B<RemotePort> (see below): If no port at all is specifically selected, the
 961 default is to collect listening ports. If specific ports (no matter if local or
 962 remote ports) are selected, this option defaults to I<false>, i.E<nbsp>e. only
 963 the selected ports will be collected unless this option is set to I<true>
 964 specifically.
 965
 966 =item B<LocalPort> I<Port>
 967
 968 Count the connections to a specific local port. This can be used to see how
 969 many connections are handled by a specific daemon, e.E<nbsp>g. the mailserver.
 970 You have to specify the port in numeric form, so for the mailserver example
 971 you'd need to set B<25>.
 972
 973 =item B<RemotePort> I<Port>
 974
 975 Count the connections to a specific remote port. This is useful to see how
 976 much a remote service is used. This is most useful if you want to know how many
 977 connections a local service has opened to remote services, e.E<nbsp>g. how many
 978 connections a mail server or news server has to other mail or news servers, or
 979 how many connections a web proxy holds to web servers. You have to give the
 980 port in numeric form.
 981
 982 =back
 983
 984 =head2 Plugin C<unixsock>
 985
 986 =over 4
 987
 988 =item B<SocketFile> I<Path>
 989
 990 Sets the socket-file which is to be created.
 991
 992 =item B<SocketGroup> I<Group>
 993
 994 If running as root change the group of the UNIX-socket after it has been
 995 created. Defaults to B<collectd>.
 996
 997 =item B<SocketPerms> I<Permissions>
 998
 999 Change the file permissions of the UNIX-socket after it has been created. The
1000 permissions must be given as a numeric, octal value as you would pass to
1001 L<chmod(1)>. Defaults to B<0770>.
1002
1003 =back
1004
1005 =head2 Plugin C<uuid>
1006
1007 This plugin, if loaded, causes the Hostname to be taken from the machine's
1008 UUID. The UUID is a universally unique designation for the machine, usually
1009 taken from the machine's BIOS. This is most useful if the machine is running in
1010 a virtual environment such as Xen, in which case the UUID is preserved across
1011 shutdowns and migration.
1012
1013 The following methods are used to find the machine's UUID, in order:
1014
1015 =over 4
1016
1017 =item
1018
1019 Check I</etc/uuid> (or I<UUIDFile>).
1020
1021 =item
1022
1023 Check for UUID from HAL (L<http://www.freedesktop.org/wiki/Software/hal>) if
1024 present.
1025
1026 =item
1027
1028 Check for UUID from C<dmidecode> / SMBIOS.
1029
1030 =item
1031
1032 Check for UUID from Xen hypervisor.
1033
1034 =back
1035
1036 If no UUID can be found then the hostname is not modified.
1037
1038 =over 4
1039
1040 =item B<UUIDFile> I<Path>
1041
1042 Take the UUID from the given file (default I</etc/uuid>).
1043
1044 =back
1045
1046 =head2 Plugin C<vserver>
1047
1048 This plugin doesn't have any options. B<VServer> support is only available for
1049 Linux. It cannot yet be found in a vanilla kernel, though. To make use of this
1050 plugin you need a kernel that has B<VServer> support built in, i.E<nbsp>e. you
1051 need to apply the patches and compile your own kernel, which will then provide
1052 the F</proc/virtual> filesystem that is required by this plugin.
1053
1054 The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
1055
1056 =head1 THRESHOLD CONFIGURATION
1057
1058 Starting with version C<4.3.0> collectd has support for B<monitoring>. By that
1059 we mean that the values are not only stored or sent somewhere, but that they
1060 are judged and, if a problem is recognized, acted upon. The only action
1061 collectd takes itself is to generate and dispatch a "notification". Plugins can
1062 register to receive notifications and perform appropriate further actions.
1063
1064 Since systems and what you expect them to do differ a lot, you can configure
1065 B<thresholds> for your values freely. This gives you a lot of flexibility but
1066 also a lot of responsibility.
1067
1068 Every time a value is out of range a notification is dispatched. This means
1069 that the idle percentage of your CPU needs to be less then the configured
1070 threshold only once for a notification to be generated. There's no such thing
1071 as a moving average or similar - at least not now.
1072
1073 Also, all values that match a threshold are considered to be relevant or
1074 "interesting". As a consequence collectd will issue a notification if they are
1075 not received for twice the last timeout of the values. If, for example, some
1076 hosts sends it's CPU statistics to the server every 60 seconds, a notification
1077 will be dispatched after about 120 seconds. It may take a little longer because
1078 the timeout is checked only once each B<Interval> on the server.
1079
1080 Here is a configuration example to get you started. Read below for more
1081 information.
1082
1083  <Threshold>
1084    <Type "foo">
1085      WarningMin    0.00
1086      WarningMax 1000.00
1087      FailureMin    0.00
1088      FailureMax 1200.00
1089      Invert false
1090      Instance "bar"
1091    </Type>
1092
1093    <Plugin "interface">
1094      Instance "eth0"
1095      <Type "if_octets">
1096        FailureMax 10000000
1097      </Type>
1098    </Plugin>
1099
1100    <Host "hostname">
1101      <Type "cpu">
1102        Instance "idle"
1103        FailureMin 10
1104      </Type>
1105
1106      <Plugin "memory">
1107        <Type "memory">
1108          Instance "cached"
1109          WarningMin 100000000
1110        </Type>
1111      </Plugin>
1112    </Host>
1113  </Threshold>
1114
1115 There are basically two types of configuration statements: The C<Host>,
1116 C<Plugin>, and C<Type> blocks select the value for which a threshold should be
1117 configured. The C<Plugin> and C<Type> blocks may be specified further using the
1118 C<Instance> option. You can combine the block by nesting the blocks, though
1119 they must be nested in the above order, i.E<nbsp>e. C<Host> may contain either
1120 C<Plugin> and C<Type> blocks, C<Plugin> may only contain C<Type> blocks and
1121 C<Type> may not contain other blocks. If multiple blocks apply to the same
1122 value the most specific block is used.
1123
1124 The other statements specify the threshold to configure. They B<must> be
1125 included in a C<Type> block. Currently the following statements are recognized:
1126
1127 =over 4
1128
1129 =item B<FailureMax> I<Value>
1130
1131 =item B<WarningMax> I<Value>
1132
1133 Sets the upper bound of acceptable values. If unset defaults to positive
1134 infinity. If a value is greater than B<FailureMax> a B<FAILURE> notification
1135 will be created. If the value is greater than B<WarningMax> but less than (or
1136 equal to) B<FailureMax> a B<WARNING> notification will be created.
1137
1138 =item B<FailureMin> I<Value>
1139
1140 =item B<WarningMin> I<Value>
1141
1142 Sets the lower bound of acceptable values. If unset defaults to negative
1143 infinity. If a value is less than B<FailureMin> a B<FAILURE> notification will
1144 be created. If the value is less than B<WarningMin> but greater than (or equal
1145 to) B<FailureMin> a B<WARNING> notification will be created.
1146
1147 =item B<Invert> B<true>|B<false>
1148
1149 If set to B<true> the range of acceptable values is inverted, i.E<nbsp>e.
1150 values between B<FailureMin> and B<FailureMax> (B<WarningMin> and
1151 B<WarningMax>) are not okay. Defaults to B<false>.
1152
1153 =item B<Persist> B<true>|B<false>
1154
1155 Sets how often notifications are generated. If set to B<true> one notification
1156 will be generated for each value that is out of the acceptable range. If set to
1157 B<false> (the default) then a notification is only generated if a value is out
1158 of range but the previous value was okay.
1159
1160 This applies to missing values, too: If set to B<true> a notification about a
1161 missing value is generated once every B<Interval> seconds. If set to B<false>
1162 only one such notification is generated until the value appears again.
1163
1164 =back
1165
1166 =head1 SEE ALSO
1167
1168 L<collectd(1)>,
1169 L<collectd-exec(5)>,
1170 L<collectd-perl(5)>,
1171 L<collectd-unixsock(5)>,
1172 L<types.db(5)>,
1173 L<hddtemp(8)>,
1174 L<kstat(3KSTAT)>,
1175 L<mbmon(1)>,
1176 L<rrdtool(1)>,
1177 L<sensors(1)>
1178
1179 =head1 AUTHOR
1180
1181 Florian Forster E<lt>octo@verplant.orgE<gt>
1182
1183 =cut