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 moni‐
19 tored; 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 con‐
25 trols how gmond reports the attributes of the cluster that it is part
26 of.
27 The cluster section has four attributes: name, owner, latlong and url.
29 For example,
31 cluster {
33 name = "Millennium Cluster"
34 owner = "UC Berkeley CS Dept."
35 latlong = "N37.37 W122.23"
36 url = "http://www.millennium.berkeley.edu/"
37 }
38 The name attributes specifies the name of the cluster of machines. The
40 owner tag specifies the administrators of the cluster. The pair
41 name/owner should be unique to all clusters in the world.
42 The latlong attribute is the latitude and longitude GPS coordinates of
44 this cluster on earth. Specified to 1 mile accuracy with two decimal
45 places per axis in decimal.
46 The url for more information on the cluster. Intended to give purpose,
48 owner, administration, and account details for this cluster.
49 There directives directly control the XML output of gmond. For exam‐
51 ple, the cluster configuration example above would translate into the
52 following XML.
53 <CLUSTER NAME="Millennium Cluster" OWNER="UC Berkeley CS Dept."
55 LATLONG="N37.37 W122.23" URL="http://www.millennium.berkeley.edu/">
56 ...
57 </CLUSTER>
58 NOTE: Currently gmetad cannot process data sources that do not have a
60 cluster tag. This will be remedied in the future.
61 host
63 The host section provides information about the host running this
65 instance of gmond. Currently only the location string attribute is sup‐
66 ported. Example:
67 host {
69 location = "(1,2,3)"
70 }
71 globals
73 The globals section controls general characteristics of gmond such as
75 whether is should daemonize, what user it should run as, whether is
76 should send/receive date and such. The globals section has the follow‐
77 ing attributes: daemonize, setuid, user, debug_level, mute, deaf,
78 host_dmax, cleanup_threshold, and gexec.
79 For example,
81 globals {
83 daemonize = true
84 setuid = true
85 user = nobody
86 host_dmax = 3600
87 }
88 The daemonize attribute is a boolean. When true, gmond will daemonize.
90 When false, gmond will run in the foreground.
91 The setuid attribute is a boolean. When true, gmond will set its
93 effective UID to the uid of the user specified by the user attribute.
94 When false, gmond will not change its effective user.
95 The debug_level is an integer value. When set to zero (0), gmond will
97 run normally. A debug_level greater than zero will result in gmond
98 running in the foreground and outputting debugging information. The
99 higher the debug_level the more verbose the output.
100 The mute attribute is a boolean. When true, gmond will not send data
102 regardless of any other configuration directives.
103 The deaf attribute is a boolean. When true, gmond will not receive
105 data regardless of any other configuration directives.
106 The host_dmax value is an integer with units in seconds. When set to
108 zero (0), gmond will never delete a host from its list even when a
109 remote host has stopped responding. If host_dmax is set to a positive
110 number then gmond will flush a host after it has not heard from it for
111 host_dmax seconds. By the way, dmax means "delete max".
112 The cleanup_threshold is the minimum about of time before gmond will
114 cleanup and hosts or metrics where tn > dmax a.k.a. expired data.
115 The gexec boolean allows you to specify whether gmond will announce the
117 hosts availability to run gexec jobs. Note: this requires the gexecd
118 is running on the host and the proper keys have been installed.
119 udp_send_channel
121 You can define as many udp_send_channel sections as you like within the
123 limitations of memory and file descriptors. If gmond is configured as
124 mute this section will be ignored.
125 The udp_send_channel has a total of five attributes: mcast_join,
127 mcast_if, host, port and ttl.
128 For example, the 2.5.x version gmond would send on the following single
130 channel by default...
131 udp_send_channel {
133 mcast_join = 239.2.11.71
134 port = 8649
135 }
136 The mcast_join and mcast_if attributes are optional. When specified
138 gmond will create the UDP socket and join the mcast_join multicast
139 group and send data out the interface specified by mcast_if.
140 If only a host and port are specified then gmond will send unicast UDP
142 messages to the hosts specified. You could specify multiple unicast
143 hosts for redundancy as gmond will send UDP messages to all UDP chan‐
144 nels.
145 For example...
147 udp_send_channel {
149 host = host.foo.com
150 port = 2389
151 }
152 udp_send_channel {
153 host = 192.168.3.4
154 port = 2344
155 }
156 would configure gmond to send messages to two hosts. The host specifi‐
158 cation can be an IPv4/IPv6 address or a resolvable hostname.
159 udp_recv_channel
161 You can specify as many udp_recv_channel sections as you like within
163 the limits of memory and file descriptors. If gmond is configured deaf
164 this attribute will be ignored.
165 The udp_recv_channel section has following attributes: mcast_join,
167 bind, port, mcast_if, family. The udp_recv_channel can also have an
168 acl definition (see ACCESS CONTROL LISTS below).
169 For example, the 2.5.x gmond ran with a single udp receive channel...
171 udp_recv_channel {
173 mcast_join = 239.2.11.71
174 bind = 239.2.11.71
175 port = 8649
176 }
177 The mcast_join and mcast_if should only be used if you want to have
179 this UDP channel receive multicast packets the multicast group
180 mcast_join on interface mcast_if. If you do not specify multicast
181 attributes then gmond will simply create a UDP server on the specified
182 port.
183 You can use the bind attribute to bind to a particular local address.
185 The family address is set to inet4 by default. If you want to bind the
187 port to an inet6 port, you need to specify that in the family
188 attribute. Ganglia will not allow IPV6=>IPV4 mapping (for portability
189 and security reasons). If you want to listen on both inet4 and inet6
190 for a particular port, explicitly state it with the following:
191 udp_recv_channel {
193 port = 8666
194 family = inet4
195 }
196 udp_recv_channel {
197 port = 8666
198 family = inet6
199 }
200 If you specify a bind address, the family of that address takes prece‐
202 dence. f your IPv6 stack doesn't support IPV6_V6ONLY, a warning will
203 be issued but gmond will continue working (this should rarely happen).
204 Multicast Note: for multicast, specifying a bind address that equals
206 the mcast_join address will prevent unicast UDP messages to the same
207 port from being processed.
208 tcp_accept_channel
210 You can specify as many tcp_accept_channel sections as you like within
212 the limitations of memory and file descriptors. If gmond is configured
213 to be mute, then these sections are ignored.
214 The tcp_accept_channel has the following attributes: bind, port, inter‐
216 face, family and timeout. A tcp_accept_channel may also have an acl
217 section specified (see ACCESS CONTROL LISTS below).
218 For example, 2.5.x gmond would accept connections on a single TCP chan‐
220 nel.
221 tcp_accept_channel {
223 port = 8649
224 }
225 The bind address is optional and allows you to specify which local
227 address gmond will bind to for this channel.
228 The port is an integer than specifies which port to answer requests for
230 data.
231 The family address is set to inet4 by default. If you want to bind the
233 port to an inet6 port, you need to specify that in the family
234 attribute. Ganglia will not allow IPV6=>IPV4 mapping (for portability
235 and security reasons). If you want to listen on both inet4 and inet6
236 for a particular port, explicitly state it with the following:
237 tcp_accept_channel {
239 port = 8666
240 family = inet4
241 }
242 tcp_accept_channel {
243 port = 8666
244 family = inet6
245 }
246 If you specify a bind address, the family of that address takes prece‐
248 dence. If your IPv6 stack doesn't support IPV6_V6ONLY, a warning will
249 be issued but gmond will continue working (this should rarely happen).
250 The timeout attribute allows you to specify how many microseconds to
252 block before closing a connection to a client. The default is set to 1
253 second (1000000 usecs). If you have a very slow connection you may
254 need to increase this value.
255 The interface is not implemented at this time (use bind).
257 collection_group
259 You can specify as many collection_group section as you like within the
261 limitations of memory. A collection_group has the following
262 attributes: collect_once, collect_every and time_threshold. A collec‐
263 tion_group must also contain one or more metric sections.
264 The metric section has the following attributes: name and value_thresh‐
266 old. For a list of available metric names, run the following command:
267 % gmond -m
269 Here is an example of a collection group for a static metric...
271 collection_group {
273 collect_once = yes
274 time_threshold = 1800
275 metric {
276 name = "cpu_num"
277 }
278 }
279 This collection_group entry would cause gmond to collect the cpu_num
281 metric once at startup (since the number of CPUs will not change
282 between reboots). The metric cpu_num would be send every 1/2 hour
283 (1800 seconds). The default value for the time_threshold is 3600 sec‐
284 onds if no time_threshold is specified.
285 The time_threshold is the maximum amount of time that can pass before
287 gmond sends all metrics specified in the collection_group to all listed
288 udp_send_channels. A metric may be sent before this time_threshold is
289 met if during collection the value surpasses the value_threshold
290 (explained below).
291 Here is an example of a collection group for a volatile metric...
293 collection_group {
295 collect_every = 60
296 time_threshold = 300
297 metric {
298 name = "cpu_user"
299 value_threshold = 5.0
300 }
301 metric {
302 name = "cpu_idle"
303 value_threshold = 10.0
304 }
305 }
306 This collection group would collect the cpu_user and cpu_idle metrics
308 every 60 seconds (specified in collect_every). If cpu_user varies by
309 5.0% or cpu_idle varies by 10.0%, then the entire collection_group is
310 sent. If no value_threshold is triggered within time_threshold seconds
311 (in this case 300), the entire collection_group is sent.
312 Each time the metric value is collected the new value is compared with
314 the old value collected. If the difference between the last value and
315 current value is greater than the value_threshold, the entire collec‐
316 tion group is send to the udp_send_channels defined.
317 It's important to note that all metrics in a collection group are sent
319 even when only a single value_threshold is surpassed.
320 include
322 Useful if you want to include another configuration file; for example:
324 include("globals.conf")
326 udp_send_channel {
328 mcast_join = 239.2.11.71
329 port = 8649
330 }
331
333 The udp_recv_channel and tcp_accept_channel directives can contain an
334 Access Control List (ACL). This ACL allows you to specify exactly
335 which hosts gmond process data from.
336 An example of an acl entry looks like
338 acl {
340 default = "deny"
341 access {
342 ip = 192.168.0.4
343 mask = 32
344 action = "allow"
345 }
346 }
347 This ACL will by default reject all traffic that is not specifically
349 from host 192.168.0.4 (the mask size for an IPv4 address is 32, the
350 mask size for an IPv6 address is 128 to represent a single host).
351 Here is another example
353 acl {
355 default = "allow"
356 access {
357 ip = 192.168.0.0
358 mask = 24
359 action = "deny"
360 }
361 access {
362 ip = ::ff:1.2.3.0
363 mask = 120
364 action = "deny"
365 }
366 }
367 This ACL will by default allow all traffic unless it comes from the two
369 subnets specified with action = "deny".
370
372 The default behavior for a 2.5.x gmond would be specified as...
373 udp_recv_channel {
375 mcast_join = 239.2.11.71
376 bind = 239.2.11.71
377 port = 8649
378 }
379 udp_send_channel {
380 mcast_join = 239.2.11.71
381 port = 8649
382 }
383 tcp_accept_channel {
384 port = 8649
385 }
386 To see the complete default configuration for gmond simply run:
388 % gmond -t
390 gmond will print out it default behavior in a configuration file and
392 then exit. Capturing this output to a file can serve as a useful
393 starting point for creating your own custom configuration.
394 % gmond -t > custom.conf
396 edit custom.conf to taste and then
398 % gmond -c ./custom.conf
400
402 The ganglia web site is at http://ganglia.info/.
403
405 Copyright (c) 2005 The University of California, Berkeley
406ganglia/3.0.6 2007-12-14 gmond.conf(5)