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 famos
  28 B<Apache Webserver>. Each line containes 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 extression, 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 =head1 GLOBAL OPTIONS
  36
  37 =over 4
  38
  39 =item B<BaseDir> I<Directory>
  40
  41 Sets the base directory. This is the directory beneath all RRD-files are
  42 created. Possibly more subdirectories are created. This is also the working
  43 directory for the daemon.
  44
  45 =item B<LoadPlugin> I<Plugin>
  46
  47 Loads the plugin I<Plugin>. There must be at least one such line or B<collectd>
  48 will be mostly useless. The names of the plugins are listed in L<collectd(1)>.
  49
  50 =item B<PIDFile> I<File>
  51
  52 Sets where to write the PID file to. This file is overwritten when it exists
  53 and deleted when the program ist stopped. Some init-scripts might override this
  54 setting using the B<-P> commandline option.
  55
  56 =item B<Interval> I<Seconds>
  57
  58 Configures the interval in which to query the read plugins. Obviously smaller
  59 values lead to a higher system load produces by collectd, while higher values
  60 lead to more coarse statistics.
  61
  62 =item B<ReadThreads> I<Num>
  63
  64 Number of threads to start for reading plugins. The default value if B<5>, but
  65 you may want to increase this if you have more than five plugins that take a
  66 long time to read. Mostly those are plugin that do network-IO. Setting this to
  67 a value higher than the number of plugins you've loaded is totally useless.
  68
  69 =back
  70
  71 =head1 PLUGIN OPTIONS
  72
  73 Some Plugins may register own options. These options must be inclosed in a
  74 C<Plugin>-Section. Which options exist depends on the plugin used:
  75
  76 =head2 Plugin C<apache>
  77
  78 To configure the C<apache>-plugin you first need to configure the Apache
  79 webserver correctly. The Apache-plugin C<mod_status> needs to be loaded and
  80 working and the C<ExtendedStatus> directive needs to be B<enabled>. You can use
  81 the following snipped to base your Apache config upon:
  82
  83   ExtendedStatus on
  84   <IfModule mod_status.c>
  85     <Location /mod_status>
  86       SetHandler server-status
  87     </Location>
  88   </IfModule>
  89
  90 Since it's C<mod_status> module is very similar to Apache's, B<lighttpd> is
  91 also supported. It introduces a new field, called C<BusyServers>, to count the
  92 number of currently connected clients. This field is also supported.
  93
  94 The following options are accepted by the C<apache>-plugin:
  95
  96 =over 4
  97
  98 =item B<URL> I<http://host/mod_status?auto>
  99
 100 Sets the URL of the C<mod_status> output. This needs to be the output generated
 101 by C<ExtendedStatus on> and it needs to be the machine readable output
 102 generated by appending the C<?auto> argument.
 103
 104 =item B<User> I<Username>
 105
 106 Optional user name needed for authentication.
 107
 108 =item B<Password> I<Password>
 109
 110 Optional password needed for authentication.
 111
 112 =item B<CACert> I<File>
 113
 114 File that holds one or more SSL certificates. If you want to use HTTPS you will
 115 possibly need this option. What CA certificates come bundeled with C<libcurl>
 116 and are checked by default depends on the distribution you use.
 117
 118 =back
 119
 120 =head2 Plugin C<apcups>
 121
 122 =over 4
 123
 124 =item B<Host> I<Hostname>
 125
 126 Hostname of the host running B<apcupsd>. Defaults to B<localhost>. Please note
 127 that IPv6 support has been disabled unless someone can confirm or decline that
 128 B<apcupsd> can handle it.
 129
 130 =item B<Port> I<Port>
 131
 132 TCP-Port to connect to. Defaults to B<3551>.
 133
 134 =back
 135
 136 =head2 Plugin C<csv>
 137
 138 =over 4
 139
 140 =item B<DataDir> I<Directory>
 141
 142 Set the directory to store RRD-files under. Per default RRD-files are generated
 143 beneath the daemon's working directory, i.E<nbsp>e. the B<BaseDir>.
 144
 145 =back
 146
 147 =head2 Plugin C<df>
 148
 149 =over 4
 150
 151 =item B<Device> I<Device>
 152
 153 Select partitions based on the devicename.
 154
 155 =item B<MountPoint> I<Directory>
 156
 157 Select partitions based on the mountpoint.
 158
 159 =item B<FSType> I<FSType>
 160
 161 Select partitions based on the filesystem type.
 162
 163 =item B<IgnoreSelected> I<true>|I<false>
 164
 165 Invert the selection: If set to true, all partitions B<except> the ones that
 166 match any one of the criteria are collected. By default only selected
 167 partitions are collected if a selection is made. If no selection is conifured
 168 at all, B<all> partitions are selected.
 169
 170 =back
 171
 172 =head2 Plugin C<dns>
 173
 174 =over 4
 175
 176 =item B<Interface> I<Interface>
 177
 178 The dns plugin uses B<libpcap> to capture dns traffic and analyses it. This
 179 option sets the interface that should be used. If this option is not set, or
 180 set to "any", the plugin will try to get packets from B<all> interfaces. This
 181 may not work on certain platforms, such as MacE<nbsp>OSE<nbsp>X.
 182
 183 =item B<IgnoreSource> I<IP-address>
 184
 185 Ignore packets that originate from this address.
 186
 187 =back
 188
 189 =head2 Plugin C<email>
 190
 191 =over 4
 192
 193 =item B<SocketGroup> I<Group>
 194
 195 If running as root change the group of the UNIX-socket after it has been
 196 created. Defaults to B<collectd>.
 197
 198 =item B<SocketPerms> I<Permissions>
 199
 200 Change the file permissions of the UNIX-socket after it has been created. The
 201 permissions must be given as a numeric, octal value as you would pass to
 202 L<chmod(1)>. Defaults to B<0770>.
 203
 204 =item B<MaxConns> I<Number>
 205
 206 Sets the maximum number of connections that can be handled in parallel. Since
 207 this many threads will be started immediately setting this to a very high
 208 value will waste valuable resources. Defaults to B<5> and will be forced to be
 209 at most B<16384> to prevent typos and dumb mistakes.
 210
 211 =back
 212
 213 =head2 Plugin C<exec>
 214
 215 Please make sure to read L<collectd/"SPECIAL PLUGINS"> before using this
 216 plugin. It containes valueable information on when the executable is executed
 217 and the output that is expected from it.
 218
 219 =over 4
 220
 221 =item B<Exec> I<User> I<Executable>
 222
 223 Execute the executable I<Executable> as user I<User>.
 224
 225 =back
 226
 227 =head2 Plugin C<hddtemp>
 228
 229 =over 4
 230
 231 =item B<Host> I<Hostname>
 232
 233 Hostname to connect to. Defaults to B<127.0.0.1>.
 234
 235 =item B<Port> I<Port>
 236
 237 TCP-Port to connect to. Defaults to B<7634>.
 238
 239 =back
 240
 241 =head2 Plugin C<interface>
 242
 243 =over 4
 244
 245 =item B<Interface> I<Interface>
 246
 247 Select this interface. By default these interfaces will then be collected. For
 248 a more detailed description see B<IgnoreSelected> below.
 249
 250 =item B<IgnoreSelected> I<true>|I<false>
 251
 252 If no configuration if given, the B<traffic>-plugin will collect data from
 253 all interfaces. This may not be practical, especially for loopback- and
 254 similar interfaces. Thus, you can use the B<Interface>-option to pick the
 255 interfaces you're interested in. Sometimes, however, it's easier/prefered
 256 to collect all interfaces I<except> a few ones. This option enables you to
 257 do that: By setting B<IgnoreSelected> to I<true> the effect of
 258 B<Interface> is inversed: All selected interfaces are ignored and all
 259 other interfaces are collected.
 260
 261 =back
 262
 263 =head2 Plugin C<iptables>
 264
 265 =over 4
 266
 267 =item B<Chain> I<Table> I<Chain> [I<Comment|Number> [I<Name>]]
 268
 269 Select the rules to count. If only I<Table> and I<Chain> are given, this plugin
 270 will collect the counters of all rules which have a comment-match. The comment
 271 is then used as type-instance.
 272
 273 If I<Comment> or I<Number> is given, only the rule with the matching comment or
 274 the I<n>th rule will be collected. Again, the comment (or the number) will be
 275 used as the type-instance.
 276
 277 If I<Name> is supplied, it will be used as the type-instance instead of the
 278 comment or the number.
 279
 280 =back
 281
 282 =head2 Plugin C<irq>
 283
 284 =over 4
 285
 286 =item B<Irq> I<Irq>
 287
 288 Select this irq. By default these irqs will then be collected. For a more
 289 detailed description see B<IgnoreSelected> below.
 290
 291 =item B<IgnoreSelected> I<true>|I<false>
 292
 293 If no configuration if given, the B<irq>-plugin will collect data from all
 294 irqs. This may not be practical, especially if no interrupts happen. Thus, you
 295 can use the B<Irq>-option to pick the interupt you're interested in.
 296 Sometimes, however, it's easier/prefered to collect all interupts I<except> a
 297 few ones. This option enables you to do that: By setting B<IgnoreSelected> to
 298 I<true> the effect of B<Irq> is inversed: All selected interupts are ignored
 299 and all other interupts are collected.
 300
 301 =back
 302
 303 =head2 Plugin C<logfile>
 304
 305 =over 4
 306
 307 =item B<LogLevel> B<debug|info|notice|warning|err>
 308
 309 Sets the log-level. If, for example, set to B<notice>, then all events with
 310 severity B<notice>, B<warning>, or B<err> will be written to the logfile.
 311
 312 =item B<File> I<File>
 313
 314 Sets the file to write log messages to. The special strings B<stdout> and
 315 B<stderr> can be used to write to the standard output and standard error
 316 channels, respectively. This, of course, only makes much sense when collectd is
 317 running in foreground- or non-daemon-mode.
 318
 319 =back
 320
 321 =head2 Plugin C<mbmon>
 322
 323 =over 4
 324
 325 =item B<Host> I<Hostname>
 326
 327 Hostname to connect to. Defaults to B<127.0.0.1>.
 328
 329 =item B<Port> I<Port>
 330
 331 TCP-Port to connect to. Defaults to B<411>.
 332
 333 =back
 334
 335 =head2 Plugin C<mysql>
 336
 337 =over 4
 338
 339 =item B<Host> I<Hostname>
 340
 341 Hostname of the database server. Defaults to B<localhost>.
 342
 343 =item B<User> I<Username>
 344
 345 Username to use when connecting to the database.
 346
 347 =item B<Password> I<Password>
 348
 349 Password needed to log into the database.
 350
 351 =item B<Database> I<Database>
 352
 353 Select this database. Defaults to I<no database> which is a perfecly reasonable
 354 option for what this plugin does.
 355
 356 =back
 357
 358 =head2 Plugin C<network>
 359
 360 =over 4
 361
 362 =item B<Listen> I<Host> [I<Port>]
 363
 364 =item B<Server> I<Host> [I<Port>]
 365
 366 The B<Server> statement sets the server to send datagrams B<to>.  The statement
 367 may occur multiple times to send each datagram to multiple destinations.
 368
 369 The B<Listen> statement sets the interfaces to bind to. When multiple
 370 statements are found the daemon will bind to multiple interfaces.
 371
 372 The argument I<Host> may be a hostname, an IPv4 address or an IPv6 address. If
 373 the argument is a multicast address the daemon will join that multicast group.
 374
 375 If no B<Listen> statement is found the server tries join both, the default IPv6
 376 multicast group and the default IPv4 multicast group. If no B<Server> statement
 377 is found the client will try to send data to the IPv6 multicast group first. If
 378 that failes the client will try the IPv4 multicast group.
 379
 380 The default IPv6 multicast group is C<ff18::efc0:4a42>. The default IPv4
 381 multicast group is C<239.192.74.66>.
 382
 383 The optional I<Port> argument sets the port to use. It can either be given
 384 using a numeric port number or a service name. If the argument is omited the
 385 default port B<25826> is assumed.
 386
 387 =item B<TimeToLive> I<1-255>
 388
 389 Set the time-to-live of sent packets. This applies to all, unicast and
 390 multicast, and IPv4 and IPv6 packets. The default is to not change this value.
 391 That means that multicast packets will be sent with a TTL of C<1> (one) on most
 392 operating systems.
 393
 394 =item B<Forward> I<true|false>
 395
 396 If set to I<true>, write packets that were received via the network plugin to
 397 the sending sockets. This should only be activated when the B<Listen>- and
 398 B<Server>-statements differ. Otherwise packets may be send multiple times to
 399 the same multicast group. While this results in more network traffic than
 400 neccessary it's not a huge problem since the plugin has a duplicate detection,
 401 so the values will not loop.
 402
 403 =item B<CacheFlush> I<Seconds>
 404
 405 For each host/plugin/type combination the C<network plugin> caches the time of
 406 the last value being sent or received. Every I<Seconds> seconds the plugin
 407 searches and removes all entries that are older than I<Seconds> seconds, thus
 408 freeing the unused memory again. Since this process is somewhat expensive and
 409 normally doesn't do much, this value should not be too small. The default is
 410 1800 seconds, but setting this to 86400 seconds (one day) will not do much harm
 411 either.
 412
 413 =back
 414
 415 =head2 Plugin C<ntpd>
 416
 417 =over 4
 418
 419 =item B<Host> I<Hostname>
 420
 421 Hostname of the host running B<ntpd>. Defaults to B<localhost>.
 422
 423 =item B<Port> I<Port>
 424
 425 UDP-Port to connect to. Defaults to B<123>.
 426
 427 =back
 428
 429 =head2 Plugin C<nut>
 430
 431 =over 4
 432
 433 =item B<UPS> I<upsname>B<@>I<hostname>[B<:>I<port>]
 434
 435 Add a UPS to collect data from. The format is identical to the one accepted by
 436 L<upsc(8)>.
 437
 438 =back
 439
 440 =head2 Plugin C<ping>
 441
 442 =over 4
 443
 444 =item B<Host> I<IP-address>
 445
 446 Host to ping periodically. This option may be repeated several times to ping
 447 multiple hosts.
 448
 449 =item B<TTL> I<0-255>
 450
 451 Sets the Time-To-Live of generated ICMP packets.
 452
 453 =back
 454
 455 =head2 Plugin C<processes>
 456
 457 =over 4
 458
 459 =item B<Process> I<Name>
 460
 461 Select more detailed statistics of processes matching this name. The statistics
 462 collected for these selected processes are size of the resident segment size
 463 (RSS), user- and system-time used, number of processes and number of threads,
 464 and minor and major pagefaults.
 465
 466 =back
 467
 468 =head2 Plugin C<rrdtool>
 469
 470 You can use the settings B<StepSize>, B<HeartBeat>, B<RRARows>, and B<XFF> to
 471 finetune your RRD-files. Please read L<rrdcreate(1)> if you encounter problems
 472 using these settings. If you don't want to dive into the depths of RRDTool, you
 473 can savely ignore these settings.
 474
 475 =over 4
 476
 477 =item B<DataDir> I<Directory>
 478
 479 Set the directory to store CSV-files under. Per default CSV-files are generated
 480 beneath the daemon's working directory, i.E<nbsp>e. the B<BaseDir>.
 481
 482 =item B<StepSize> I<Seconds>
 483
 484 Sets the stepsize of newly created RRD-files. Ideally (and per default) this
 485 setting is identical to the global B<Interval>-option and should not be
 486 smaller. If unsure, don't set this option.
 487
 488 =item B<HeartBeat> I<Seconds>
 489
 490 Sets the heartbeat of newly created RRD-files. Ideally this setting is bigger
 491 than the B<Interval>-setting, by default it's twice the B<Interval>-setting. If
 492 unsure, don't set this option.
 493
 494 =item B<RRARows> I<NumRows>
 495
 496 The C<rrdtool plugin> calculates the number of PDPs per CDP based on the
 497 B<StepSize>, this setting and a timespan. This plugin creates RRD-files with
 498 three times five RRAs, i. e. five RRAs with the CFs B<MIN>, B<AVERAGE>, and
 499 B<MAX>. The five RRAs are optimized for graphs covering one hour, one day, one
 500 week, one month, and one year.
 501
 502 So for each timespan, it calculates how many PDPs need to be consolidated into
 503 one CDP by calculating:
 504   number of PDPs = timespan / (stepsize * rrarows)
 505
 506 Bottom line is, set this no smaller than the width of you graphs in pixels. The
 507 default is 1200.
 508
 509 =item B<RRATimespan> I<Seconds>
 510
 511 Adds an RRA-timespan, given in seconds. Use this option mulitple times to have
 512 more then one RRA. If this option is never used, the built-in default of (3600,
 513 86400, 604800, 2678400, 31622400) is used.
 514
 515 For more information on how RRA-sizes are calculated see B<RRARows> above.
 516
 517 =item B<XFF> I<Factor>
 518
 519 Set the "XFiles Factor". The default is 0.1. If unsure, don't set this option.
 520
 521 =item B<CacheFlush> I<Seconds>
 522
 523 When the C<rrdtool plugin> uses a cache (by setting B<CacheTimeout>, see below)
 524 it writes all values for a certain RRD-file if the oldest value is older than
 525 (or equal to) the number of seconds specified. If some RRD-file is not updated
 526 anymore for some reason (the computer was shut down, the network is broken,
 527 etc.) some values may still be in the cache. If B<CacheFlush> is set, then the
 528 entire cache is searched for entries older than B<CacheTimeout> seconds and
 529 written to disk every I<Seconds> seconds. Since this is kind of expensive and
 530 does nothing under normal circumstances, this value should not be too small.
 531 900 seconds might be a good value, though setting this to 7200 seconds doesn't
 532 normally do much harm either.
 533
 534 =item B<CacheTimeout> I<Seconds>
 535
 536 If this option is set to a value greater than zero, the C<rrdtool plugin> will
 537 save values in a cache, as described above. Writing multiple values at once
 538 reduces IO-operations and thus lessens the load produced by updating the files.
 539 The tradeoff is that the graphs kind of "drag behind" and that more memory is
 540 used.
 541
 542 =back
 543
 544 =head2 Plugin C<sensors>
 545
 546 =over 4
 547
 548 =item B<Sensor> I<chip-bus-address/type-feature>
 549
 550 Selects the name of the sensor which you want to collect or ignore, depending
 551 on the B<IgnoreSelected> below. For example, the option "B<Sensor>
 552 I<it8712-isa-0290/voltage-in1>" will cause collectd to gather data for the
 553 voltage sensor I<in1> of the I<it8712> on the isa bus at the address 0290.
 554
 555 =item B<IgnoreSelected> I<true>|I<false>
 556
 557 If no configuration if given, the B<sensors>-plugin will collect data from all
 558 sensors. This may not be practical, especially for uninteresting sensors.
 559 Thus, you can use the B<Sensor>-option to pick the sensors you're interested
 560 in. Sometimes, however, it's easier/prefered to collect all sensors I<except> a
 561 few ones. This option enables you to do that: By setting B<IgnoreSelected> to
 562 I<true> the effect of B<Sensor> is inversed: All selected sensors are ignored
 563 and all other sensors are collected.
 564
 565 =back
 566
 567 =head2 Plugin C<syslog>
 568
 569 =over 4
 570
 571 =item B<LogLevel> B<debug|info|notice|warning|err>
 572
 573 Sets the log-level. If, for example, set to B<notice>, then all events with
 574 severity B<notice>, B<warning>, or B<err> will be submitted to the
 575 syslog-daemon.
 576
 577 =back
 578
 579 =head2 Plugin C<unixsock>
 580
 581 =over 4
 582
 583 =item B<SocketFile> I<Path>
 584
 585 Sets the socket-file which is to be created.
 586
 587 =item B<SocketGroup> I<Group>
 588
 589 If running as root change the group of the UNIX-socket after it has been
 590 created. Defaults to B<collectd>.
 591
 592 =item B<SocketPerms> I<Permissions>
 593
 594 Change the file permissions of the UNIX-socket after it has been created. The
 595 permissions must be given as a numeric, octal value as you would pass to
 596 L<chmod(1)>. Defaults to B<0770>.
 597
 598 =back
 599
 600 =head1 SEE ALSO
 601
 602 L<collectd(1)>
 603
 604 =head1 AUTHOR
 605
 606 Florian Forster E<lt>octo@verplant.orgE<gt>
 607
 608 =cut