Merge branch 'ff/dns'
[collectd.git] / 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   Mode    Client
8   DataDir /path/to/data/
9   PIDFile /path/to/pidfile/collectd.pid
10   LogFile /path/to/logfile/collectd.log
11   Server  123.123.123.123 12345
12
13   LoadPlugin cpu
14   LoadPlugin load
15   LoadPlugin ping
16
17   <Plugin ping>
18     Host example.org
19     Host provider.net
20   </Plugin>
21
22 =head1 DESCRIPTION
23
24 This config file controls how the system statistics collection daemon
25 B<collectd> behaves. The most significant options are B<Mode>, which controlls
26 if the daemon will act as client, server or will be independent in local mode,
27 and B<LoadPlugin> which controls which plugins to load.
28
29 The syntax of this config file is similar to the config file of the famos
30 B<Apache Webserver>. Each line containes either a key-value-pair or a
31 section-start or -end. Empty lines and everything after the hash-symbol `#' is
32 ignored.
33
34 =head1 GLOBAL OPTIONS
35
36 =over 4
37
38 =item B<Mode> (B<Local>|B<Client>|B<Server>|B<Log>)
39
40 Sets the operating mode. See the section B<MODES> in L<collectd(1)> for a
41 description. This option determines which other options are allowed. Defaults
42 to B<Local>.
43
44 =item B<LoadPlugin> I<Plugin>
45
46 Loads the plugin I<Plugin>. There must be at least one such line or B<collectd>
47 will be mostly useless. The names of the plugins are listed in L<collectd(1)>.
48
49 =item B<PIDFile> I<File>
50
51 Sets where to write the PID file to. This file is overwritten when it exists
52 and deleted when the program ist stopped. Some init-scripts might override this
53 setting using the B<-P> commandline option. Available in B<all modes>.
54
55 =item B<DataDir> I<Directory>
56
57 Sets the data directory. This is the directory beneath all RRD-files are
58 created. Possibly more subdirectories are created. This is also the working
59 directory for the daemon. Available in B<all modes>, though the B<Client> mode
60 won't write to this directory.
61
62 =item B<LogFile> I<File>
63
64 Sets the file to write debugging output to. This is only used if compiled with
65 debugging enabled. It's ignored otherwise. Available in B<all modes>.
66
67 =item B<Listen> I<Host> [I<Port>]
68
69 =item B<Server> I<Host> [I<Port>]
70
71 In B<client mode> the B<Server> statement sets the server to send datagrams to.
72 The statement may occur multiple times to send each datagram to multiple
73 destinations.
74
75 In B<server mode> the B<Listen> statement sets the interfaces to bind to. When
76 multiple statements are found the daemon will bind to multiple interfaces.
77
78 The argument I<Host> may be a hostname, an IPv4 address or an IPv6 address. If
79 the argument is a multicast address the daemon will join that multicast group.
80
81 If no B<Listen> statement is found the server tries join both, the IPv6
82 multicast group and the IPv4 multicast group. If no B<Server> statement is
83 found the client will try to send data to the IPv6 multicast group first. If
84 that failes the client will try the IPv4 multicast group.
85
86 The default IPv6 multicast group is C<ff18::efc0:4a42>. The default IPv4
87 multicast group is C<239.192.74.66>.
88
89 The optional I<Port> argument sets the port to use. It can either be given
90 using a numeric port number or a service name. If the argument is omited the
91 default port B<25826> is assumed.
92
93 =item B<TimeToLive> I<1-255>
94
95 Set the time-to-live of sent packets. This applies to all, unicast and
96 multicast, and IPv4 and IPv6 packets. The default is to not change this value.
97 That means that multicast packets will be sent with a TTL of C<1> (one) on most
98 operating systems.
99
100 =back
101
102 =head1 PLUGIN OPTIONS
103
104 Some Plugins may register own options. These options must be inclosed in a
105 C<Plugin>-Section. Which options exist depends on the plugin used:
106
107 =head2 Plugin C<apache>
108
109 To configure the C<apache>-plugin you first need to configure the Apache
110 webserver correctly. The Apache-plugin C<mod_status> needs to be loaded and
111 working and the C<ExtendedStatus> directive needs to be B<enabled>. You can use
112 the following snipped to base your Apache config upon:
113
114   ExtendedStatus on
115   <IfModule mod_status.c>
116     <Location /mod_status>
117       SetHandler server-status
118     </Location>
119   </IfModule>
120
121 The following options are accepted by the C<apache>-plugin:
122
123 =over 4
124
125 =item B<URL> I<http://host/mod_status?auto>
126
127 Sets the URL of the C<mod_status> output. This needs to be the output generated
128 by C<ExtendedStatus on> and it needs to be the machine readable output
129 generated by appending the C<?auto> argument.
130
131 =item B<User> I<Username>
132
133 Optional user name needed for authentication.
134
135 =item B<Password> I<Password>
136
137 Optional password needed for authentication.
138
139 =item B<CACert> I<File>
140
141 File that holds one or more SSL certificates. If you want to use HTTPS you will
142 possibly need this option. What CA certificates come bundeled with C<libcurl>
143 and are checked by default depends on the distribution you use.
144
145 =back
146
147 =head2 Plugin C<apcups>
148
149 =over 4
150
151 =item B<Host> I<Hostname>
152
153 Hostname of the host running B<apcupsd>. Defaults to B<localhost>. Please note
154 that IPv6 support has been disabled unless someone can confirm or decline that
155 B<apcupsd> can handle it.
156
157 =item B<Port> I<Port>
158
159 TCP-Port to connect to. Defaults to B<3551>.
160
161 =back
162
163 =head2 Plugin C<df>
164
165 =over 4
166
167 =item B<Device> I<Device>
168
169 Select partitions based on the devicename.
170
171 =item B<MountPoint> I<Directory>
172
173 Select partitions based on the mountpoint.
174
175 =item B<FSType> I<FSType>
176
177 Select partitions based on the filesystem type.
178
179 =item B<IgnoreSelected> I<true>|I<false>
180
181 Invert the selection: If set to true, all partitions B<except> the ones that
182 match any one of the criteria are collected. By default only selected
183 partitions are collected if a selection is made. If no selection is conifured
184 at all, B<all> partitions are selected.
185
186 =back
187
188 =head2 Plugin C<hddtemp>
189
190 =over 4
191
192 =item B<Host> I<Hostname>
193
194 Hostname to connect to. Defaults to B<127.0.0.1>.
195
196 =item B<Port> I<Port>
197
198 TCP-Port to connect to. Defaults to B<7634>.
199
200 =back
201
202 =head2 Plugin C<ntpd>
203
204 =over 4
205
206 =item B<Host> I<Hostname>
207
208 Hostname of the host running B<ntpd>. Defaults to B<localhost>.
209
210 =item B<Port> I<Port>
211
212 UDP-Port to connect to. Defaults to B<123>.
213
214 =back
215
216 =head2 Plugin C<mysql>
217
218 =over 4
219
220 =item B<Host> I<Hostname>
221
222 Hostname of the database server. Defaults to B<localhost>.
223
224 =item B<User> I<Username>
225
226 Username to use when connecting to the database.
227
228 =item B<Password> I<Password>
229
230 Password needed to log into the database.
231
232 =item B<Database> I<Database>
233
234 Select this database. Defaults to I<no database> which is a perfecly reasonable
235 option for what this plugin does.
236
237 =back
238
239 =head2 Plugin C<ping>
240
241 =over 4
242
243 =item B<Host> I<IP-address>
244
245 Host to ping periodically. This option may be repeated several times to ping
246 multiple hosts.
247
248 =item B<TTL> I<0-255>
249
250 Sets the Time-To-Live of generated ICMP packets.
251
252 =back
253
254 =head2 Plugin C<sensors>
255
256 =over 4
257
258 =item B<ExtendedSensorNaming> I<true>|I<false>
259
260 If set to I<true> this option switches on the extended sensors and RRD-files
261 naming. This option exists to preserve backwards compatibility. It is
262 recommended that you set this option to I<true>. The default is I<false> to
263 maintain compatibility only.
264
265 Sensors get names like I<chip-bus-address/type-feature> (e.g.
266 I<it8712-isa-0290/voltage-in1>) and RRD files are therefore stored in a
267 standalone directory inside the B<DataDir> directory and get names like
268 I<lm_sensors-chip-bus-address/type-feature.rrd> (e.g.
269 I<lm_sensors-it8712-isa-0290/voltage-in1.rrd>).
270
271 The B<ExtendedSensorNaming> option breaks the compatibility with previous
272 sensors and RRD files naming and the place where RRDs are stored. If you turn
273 it on, the plugin will create new RRD files in a standalone directory inside
274 the B<DataDir> directory and without previous history. You can rename ``old''
275 RRD-files to preserve already collected statistics, because the file layout
276 hasn't changed. If you have two chips of the same type, you need to use
277 B<ExtendedSensorNaming> in order to collect information from both chips.
278
279 If not set or set to I<false>, the extended naming is not active. Sensors get
280 names like I<chip-feature> (e.g. I<it8712-in1>) and RRD files are stored in the
281 main B<DataDir> directory and get names like I<sensors-chip-feature.rrd> (e.g.
282 I<sensors-it8712-in1.rrd>).  You simply continue using the plugin the old way
283 and additionally also getting data for newly added sensors in this mode.
284
285 =item B<Sensor> I<chip-feature> or B<Sensor> I<chip-bus-address/type-feature>
286
287 Both option modes select the name of the sensor which you want to collect.
288 The naming scheme is dependent on the state of the B<ExtendedSensorNaming>
289 option (see previous option). Both option modes can also deselect the
290 sensor according to the B<IgnoreSelected> option (see below).
291
292 For example the option "B<Sensor> I<it8712-in1>" will cause the collectd
293 to gather data for the voltage sensor I<in1> of the I<it8712> chip in case
294 of the B<ExtendedSensorNaming> option is set to I<false>.
295
296 And likewise the option "B<Sensor> I<it8712-isa-0290/voltage-in1>" will
297 cause the collectd to gather data for the voltage sensor I<in1> of the I<it8712>
298 on the isa bus at the address 0290 in case of the B<ExtendedSensorNaming>
299 option set to I<true>.
300
301 =item B<IgnoreSelected> I<true>|I<false>
302
303 If no configuration if given, the B<sensors>-plugin will collect data from
304 all sensors. This may not be practical, especially for uninteresting sensors.
305 Thus, you can use the B<Sensor>-option to pick the sensors you're
306 interested in. Sometimes, however, it's easier/prefered to collect all
307 sensors I<except> a few ones. This option enables you to
308 do that: By setting B<IgnoreSelected> to I<true> the effect of
309 B<Sensor> is inversed: All selected sensors are ignored and all
310 other sensors are collected.
311
312 back
313
314 =back
315
316 =head2 Plugin C<traffic>
317
318 =over 4
319
320 =item B<Interface> I<Interface>
321
322 Select this interface. By default these interfaces will then be collected. For a more detailed description see B<IgnoreSelected> below.
323
324 =item B<IgnoreSelected> I<true>|I<false>
325
326 If no configuration if given, the B<traffic>-plugin will collect data from
327 all interfaces. This may not be practical, especially for loopback- and
328 similar interfaces. Thus, you can use the B<Interface>-option to pick the
329 interfaces you're interested in. Sometimes, however, it's easier/prefered
330 to collect all interfaces I<except> a few ones. This option enables you to
331 do that: By setting B<IgnoreSelected> to I<true> the effect of
332 B<Interface> is inversed: All selected interfaces are ignored and all
333 other interfaces are collected.
334
335 =back
336
337 =head1 SEE ALSO
338
339 L<collectd(1)>
340
341 =head1 AUTHOR
342
343 Florian Forster E<lt>octo@verplant.orgE<gt>
344
345 =cut