1gmond.conf(5) Ganglia Monitoring System gmond.conf(5)
2
6 gmond.conf - configuration file for ganglia monitoring daemon (gmond)
7
9 The gmond.conf file is used to configure the ganglia monitoring daemon
10 (gmond) which is part of the Ganglia Distributed Monitoring System.
11
13 All sections and attributes are case-insensitive. For example, name or
14 NAME or Name or NaMe are all equivalent.
15 Some sections can be included in the configuration file multiple times
17 and some sections are singular. For example, you can have only one
18 cluster section to define the attributes of the cluster being
19 monitored; however, you can have multiple udp_recv_channel sections to
20 allow gmond to receive message on multiple UDP channels.
21 cluster
23 There should only be one cluster section defined. This section
24 controls how gmond reports the attributes of the cluster that it is
25 part of.
26 The cluster section has four attributes: name, owner, latlong and url.
28 For example,
30 cluster {
32 name = "Millennium Cluster"
33 owner = "UC Berkeley CS Dept."
34 latlong = "N37.37 W122.23"
35 url = "http://www.millennium.berkeley.edu/"
36 }
37 The name attributes specifies the name of the cluster of machines. The
39 owner tag specifies the administrators of the cluster. The pair
40 name/owner should be unique to all clusters in the world.
41 The latlong attribute is the latitude and longitude GPS coordinates of
43 this cluster on earth. Specified to 1 mile accuracy with two decimal
44 places per axis in decimal.
45 The url for more information on the cluster. Intended to give purpose,
47 owner, administration, and account details for this cluster.
48 There directives directly control the XML output of gmond. For
50 example, the cluster configuration example above would translate into
51 the following XML.
52 <CLUSTER NAME="Millennium Cluster" OWNER="UC Berkeley CS Dept."
54 LATLONG="N37.37 W122.23" URL="http://www.millennium.berkeley.edu/">
55 ...
56 </CLUSTER>
57 host
59 The host section provides information about the host running this
60 instance of gmond. Currently only the location string attribute is
61 supported. Example:
62 host {
64 location = "1,2,3"
65 }
66 The numbers represent Rack, Rank and Plane respectively.
68 globals
70 The globals section controls general characteristics of gmond such as
71 whether is should daemonize, what user it should run as, whether is
72 should send/receive date and such. The globals section has the
73 following attributes: daemonize, setuid, user, debug_level, mute, deaf,
74 allow_extra_data, host_dmax, cleanup_threshold, gexec,
75 send_metadata_interval and module_dir.
76 For example,
78 globals {
80 daemonize = true
81 setuid = true
82 user = nobody
83 host_dmax = 3600
84 }
85 The daemonize attribute is a boolean. When true, gmond will daemonize.
87 When false, gmond will run in the foreground.
88 The setuid attribute is a boolean. When true, gmond will set its
90 effective UID to the uid of the user specified by the user attribute.
91 When false, gmond will not change its effective user.
92 The debug_level is an integer value. When set to zero (0), gmond will
94 run normally. A debug_level greater than zero will result in gmond
95 running in the foreground and outputting debugging information. The
96 higher the debug_level the more verbose the output.
97 The mute attribute is a boolean. When true, gmond will not send data
99 regardless of any other configuration directives.
100 The deaf attribute is a boolean. When true, gmond will not receive
102 data regardless of any other configuration directives.
103 The allow_extra_data attribute is a boolean. When false, gmond will
105 not send out the EXTRA_ELEMENT and EXTRA_DATA parts of the XML. This
106 might be useful if you are using your own frontend to the metric data
107 and will like to save some bandwith.
108 The host_dmax value is an integer with units in seconds. When set to
110 zero (0), gmond will never delete a host from its list even when a
111 remote host has stopped reporting. If host_dmax is set to a positive
112 number then gmond will flush a host after it has not heard from it for
113 host_dmax seconds. By the way, dmax means "delete max".
114 The cleanup_threshold is the minimum amount of time before gmond will
116 cleanup any hosts or metrics where tn > dmax a.k.a. expired data.
117 The gexec boolean allows you to specify whether gmond will announce the
119 hosts availability to run gexec jobs. Note: this requires that gexecd
120 is running on the host and the proper keys have been installed.
121 The send_metadata_interval establishes an interval in which gmond will
123 send or resend the metadata packets that describe each enabled metric.
124 This directive by default is set to 0 which means that gmond will only
125 send the metadata packets at startup and upon request from other gmond
126 nodes running remotely. If a new machine running gmond is added to a
127 cluster, it needs to announce itself and inform all other nodes of the
128 metrics that it currently supports. In multicast mode, this isn't a
129 problem because any node can request the metadata of all other nodes in
130 the cluster. However in unicast mode, a resend interval must be
131 established. The interval value is the minimum number of seconds
132 between resends.
133 The module_dir is an optional parameter indicating the directory where
135 the DSO modules are to be located. If absent, the value to use is set
136 at configure time with the --with-moduledir option which will default
137 if omitted to the a subdirectory named "ganglia" in the directory where
138 libganglia will be installed.
139 For example, in a 32-bit Intel compatible Linux host that is usually:
141 /usr/lib/ganglia
143 udp_send_channel
145 You can define as many udp_send_channel sections as you like within the
146 limitations of memory and file descriptors. If gmond is configured as
147 mute this section will be ignored.
148 The udp_send_channel has a total of seven attributes: mcast_join,
150 mcast_if, host, port, ttl, bind and bind_hostname. bind and
151 bind_hostname are mutually exclusive.
152 For example, the 2.5.x version gmond would send on the following single
154 channel by default...
155 udp_send_channel {
157 mcast_join = 239.2.11.71
158 port = 8649
159 }
160 The mcast_join and mcast_if attributes are optional. When specified
162 gmond will create the UDP socket and join the mcast_join multicast
163 group and send data out the interface specified by mcast_if.
164 You can use the bind attribute to bind to a particular local address to
166 be used as the source for the multicast packets sent or let gmond
167 resolve the default hostname if bind_hostname = yes.
168 If only a host and port are specified then gmond will send unicast UDP
170 messages to the hosts specified.
171 You could specify multiple unicast hosts for redundancy as gmond will
173 send UDP messages to all UDP channels.
174 Be carefull though not to mix multicast and unicast attributes in the
176 same udp_send_channel definition.
177 For example...
179 udp_send_channel {
181 host = host.foo.com
182 port = 2389
183 }
184 udp_send_channel {
185 host = 192.168.3.4
186 port = 2344
187 }
188 would configure gmond to send messages to two hosts. The host
190 specification can be an IPv4/IPv6 address or a resolvable hostname.
191 udp_recv_channel
193 You can specify as many udp_recv_channel sections as you like within
194 the limits of memory and file descriptors. If gmond is configured deaf
195 this attribute will be ignored.
196 The udp_recv_channel section has following attributes: mcast_join,
198 bind, port, mcast_if, family. The udp_recv_channel can also have an
199 acl definition (see ACCESS CONTROL LISTS below).
200 For example, the 2.5.x gmond ran with a single udp receive channel...
202 udp_recv_channel {
204 mcast_join = 239.2.11.71
205 bind = 239.2.11.71
206 port = 8649
207 }
208 The mcast_join and mcast_if should only be used if you want to have
210 this UDP channel receive multicast packets the multicast group
211 mcast_join on interface mcast_if. If you do not specify multicast
212 attributes then gmond will simply create a UDP server on the specified
213 port.
214 You can use the bind attribute to bind to a particular local address.
216 The family address is set to inet4 by default. If you want to bind the
218 port to an inet6 port, you need to specify that in the family
219 attribute. Ganglia will not allow IPV6=>IPV4 mapping (for portability
220 and security reasons). If you want to listen on both inet4 and inet6
221 for a particular port, explicitly state it with the following:
222 udp_recv_channel {
224 port = 8666
225 family = inet4
226 }
227 udp_recv_channel {
228 port = 8666
229 family = inet6
230 }
231 If you specify a bind address, the family of that address takes
233 precedence. f your IPv6 stack doesn't support IPV6_V6ONLY, a warning
234 will be issued but gmond will continue working (this should rarely
235 happen).
236 Multicast Note: for multicast, specifying a bind address with the same
238 value used for mcast_join will prevent unicast UDP messages to the same
239 port from being processed.
240 tcp_accept_channel
242 You can specify as many tcp_accept_channel sections as you like within
243 the limitations of memory and file descriptors. If gmond is configured
244 to be mute, then these sections are ignored.
245 The tcp_accept_channel has the following attributes: bind, port,
247 interface, family and timeout. A tcp_accept_channel may also have an
248 acl section specified (see ACCESS CONTROL LISTS below).
249 For example, 2.5.x gmond would accept connections on a single TCP
251 channel.
252 tcp_accept_channel {
254 port = 8649
255 }
256 The bind address is optional and allows you to specify which local
258 address gmond will bind to for this channel.
259 The port is an integer than specifies which port to answer requests for
261 data.
262 The family address is set to inet4 by default. If you want to bind the
264 port to an inet6 port, you need to specify that in the family
265 attribute. Ganglia will not allow IPV6=>IPV4 mapping (for portability
266 and security reasons). If you want to listen on both inet4 and inet6
267 for a particular port, explicitly state it with the following:
268 tcp_accept_channel {
270 port = 8666
271 family = inet4
272 }
273 tcp_accept_channel {
274 port = 8666
275 family = inet6
276 }
277 If you specify a bind address, the family of that address takes
279 precedence. If your IPv6 stack doesn't support IPV6_V6ONLY, a warning
280 will be issued but gmond will continue working (this should rarely
281 happen).
282 The timeout attribute allows you to specify how many microseconds to
284 block before closing a connection to a client. The default is set to 1
285 second (1000000 usecs). If you have a very slow connection you may
286 need to increase this value.
287 The interface is not implemented at this time (use bind).
289 collection_group
291 You can specify as many collection_group section as you like within the
292 limitations of memory. A collection_group has the following
293 attributes: collect_once, collect_every and time_threshold. A
294 collection_group must also contain one or more metric sections.
295 The metric section has the following attributes: (one of name or
297 name_match; name_match is only permitted if pcre support is compiled
298 in), value_threshold and title. For a list of available metric names,
299 run the following command:
300 % gmond -m
302 Here is an example of a collection group for a static metric...
304 collection_group {
306 collect_once = yes
307 time_threshold = 1800
308 metric {
309 name = "cpu_num"
310 title = "Number of CPUs"
311 }
312 }
313 This collection_group entry would cause gmond to collect the cpu_num
315 metric once at startup (since the number of CPUs will not change
316 between reboots). The metric cpu_num would be send every 1/2 hour
317 (1800 seconds). The default value for the time_threshold is 3600
318 seconds if no time_threshold is specified.
319 The time_threshold is the maximum amount of time that can pass before
321 gmond sends all metrics specified in the collection_group to all
322 configured udp_send_channels. A metric may be sent before this
323 time_threshold is met if during collection the value surpasses the
324 value_threshold (explained below).
325 Here is an example of a collection group for a volatile metric...
327 collection_group {
329 collect_every = 60
330 time_threshold = 300
331 metric {
332 name = "cpu_user"
333 value_threshold = 5.0
334 title = "CPU User"
335 }
336 metric {
337 name = "cpu_idle"
338 value_threshold = 10.0
339 title = "CPU Idle"
340 }
341 }
342 This collection group would collect the cpu_user and cpu_idle metrics
344 every 60 seconds (specified in collect_every). If cpu_user varies by
345 5.0% or cpu_idle varies by 10.0%, then the entire collection_group is
346 sent. If no value_threshold is triggered within time_threshold seconds
347 (in this case 300), the entire collection_group is sent.
348 Each time the metric value is collected the new value is compared with
350 the old value collected. If the difference between the last value and
351 the current value is greater than the value_threshold, the entire
352 collection group is send to the udp_send_channels defined.
353 It's important to note that all metrics in a collection group are sent
355 even when only a single value_threshold is surpassed.
356 In addition a user friendly title can be substituted for the metric
358 name by including a title within the metric section.
359 By using the name_match parameter instead of name, it is possible to
361 use a single definition to configure multiple metrics that match a
362 regular expression. The perl compatible regular expression (pcre)
363 syntax is used. This approach is particularly useful for a series of
364 metrics that may vary in number between reboots (e.g. metric names that
365 are generated for each individual NIC or CPU core).
366 Here is an example of using the name_match directive to enable the
368 multicpu metrics:
369 metric {
371 name_match = "multicpu_([a-z]+)([0-9]+)"
372 value_threshold = 1.0
373 title = "CPU-\\2 \\1"
374 }
375 Note that in the example above, there are two matches: the alphabetical
377 match matches the variations of the metric name (e.g. idle, system)
378 while the numeric match matches the CPU core number. The second thing
379 to note is the use of substitutions within the argument to title.
380 If both name and name_match are specified, then name is ignored.
382 Modules
384 A modules section contains the parameters that are necessary to load a
385 metric module. A metric module is a dynamically loadable module that
386 extends the available metrics that gmond is able to collect. Each
387 modules section contains at least one module section. Within a module
388 section are the directives name, language, enabled, path and params.
389 The module name is the name of the module as determined by the module
390 structure if the module was developed in C/C++. Alternatively, the
391 name can be the name of the source file if the module has been
392 implemented in a interpreted language such as python. A language
393 designation must be specified as a string value for each module. The
394 language directive must correspond to the source code language in which
395 the module was implemented (ex. language = "python"). If a language
396 directive does not exist for the module, the assumed language will be
397 "C/C++". The enabled directive allows a metric module to be easily
398 enabled or disabled through the configuration file. If the enabled
399 directive is not included in the module configuration, the enabled
400 state will default to "yes". One thing to note is that if a module has
401 been disabled yet the metric which that module implements is still
402 listed as part of a collection group, gmond will produce a warning
403 message. However gmond will continue to function normally by simply
404 ignoring the metric. The path is the path from which gmond is expected
405 to load the module (C/C++ compiled dynamically loadable module only).
406 The params directive can be used to pass a single string parameter
407 directly to the module initialization function (C/C++ module only).
408 Multiple parameters can be passed to the module's initialization
409 function by including one or more param sections. Each param section
410 must be named and contain a value directive. Once a module has been
411 loaded, the additional metrics can be discovered by invoking gmond -m.
412 modules {
414 module {
415 name = "example_module"
416 enabled = yes
417 path = "modexample.so"
418 params = "An extra raw parameter"
419 param RandomMax {
420 value = 75
421 }
422 param ConstantValue {
423 value = 25
424 }
425 }
426 }
427 Include
429 This directive allows the user to include additional configuration
430 files rather than having to add all gmond configuration directives to
431 the gmond.conf file. The following example includes any file with the
432 extension of .conf contained in the directory conf.d as if the contents
433 of the included configuration files were part of the original
434 gmond.conf file. This allows the user to modularize their configuration
435 file. One usage example might be to load individual metric modules by
436 including module specific .conf files.
437 include ('/etc/ganglia/conf.d/*.conf')
439
441 The udp_recv_channel and tcp_accept_channel directives can contain an
442 Access Control List (ACL). This ACL allows you to specify exactly
443 which hosts gmond process data from.
444 An example of an acl entry looks like
446 acl {
448 default = "deny"
449 access {
450 ip = 192.168.0.4
451 mask = 32
452 action = "allow"
453 }
454 }
455 This ACL will by default reject all traffic that is not specifically
457 from host 192.168.0.4 (the mask size for an IPv4 address is 32, the
458 mask size for an IPv6 address is 128 to represent a single host).
459 Here is another example
461 acl {
463 default = "allow"
464 access {
465 ip = 192.168.0.0
466 mask = 24
467 action = "deny"
468 }
469 access {
470 ip = ::ff:1.2.3.0
471 mask = 120
472 action = "deny"
473 }
474 }
475 This ACL will by default allow all traffic unless it comes from the two
477 subnets specified with action = "deny".
478
480 The default behavior for a 2.5.x gmond would be specified as...
481 udp_recv_channel {
483 mcast_join = 239.2.11.71
484 bind = 239.2.11.71
485 port = 8649
486 }
487 udp_send_channel {
488 mcast_join = 239.2.11.71
489 port = 8649
490 }
491 tcp_accept_channel {
492 port = 8649
493 }
494 To see the complete default configuration for gmond simply run:
496 % gmond -t
498 gmond will print out its default behavior in a configuration file and
500 then exit. Capturing this output to a file can serve as a useful
501 starting point for creating your own custom configuration.
502 % gmond -t > custom.conf
504 edit custom.conf to taste and then
506 % gmond -c ./custom.conf
508
510 The ganglia web site is at http://ganglia.info/.
511
513 Copyright (c) 2005 The University of California, Berkeley
514ganglia/3.1.7 2010-02-17 gmond.conf(5)