Debian Codegraph @

gmond/gmond.conf.html

raw
1 <?xml version="1.0" ?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml">
4 <head>
5 <title>Ganglia Monitoring Daemon v3.7.2 Configuration</title>
6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
7 <link rev="made" href="mailto:root@localhost" />
8 </head>
9
10 <body style="background-color: white">
11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
13 <big><strong><span class="block">&nbsp;Ganglia Monitoring Daemon v3.7.2 Configuration</span></strong></big>
14 </td></tr>
15 </table>
16
17
18 <!-- INDEX BEGIN -->
19 <div name="index">
20 <p><a name="__index__"></a></p>
21
22 <ul>
23
24 <li><a href="#name">NAME</a></li>
25 <li><a href="#description">DESCRIPTION</a></li>
26 <li><a href="#sections_and_attributes">SECTIONS AND ATTRIBUTES</a></li>
27 <ul>
28
29 <li><a href="#cluster">cluster</a></li>
30 <li><a href="#host">host</a></li>
31 <li><a href="#globals">globals</a></li>
32 <li><a href="#udp_send_channel">udp_send_channel</a></li>
33 <li><a href="#udp_recv_channel">udp_recv_channel</a></li>
34 <li><a href="#tcp_accept_channel">tcp_accept_channel</a></li>
35 <li><a href="#collection_group">collection_group</a></li>
36 <li><a href="#modules">Modules</a></li>
37 <li><a href="#sflow">sFlow</a></li>
38 <li><a href="#include">Include</a></li>
39 </ul>
40
41 <li><a href="#access_control">ACCESS CONTROL</a></li>
42 <li><a href="#example">EXAMPLE</a></li>
43 <li><a href="#see_also">SEE ALSO</a></li>
44 <li><a href="#notes">NOTES</a></li>
45 <li><a href="#copyright">COPYRIGHT</a></li>
46 </ul>
47
48 <hr name="index" />
49 </div>
50 <!-- INDEX END -->
51
52 <p>
53 </p>
54 <hr />
55 <h1><a name="name">NAME</a></h1>
56 <p><strong>gmond.conf</strong> - configuration file for ganglia monitoring
57 daemon (gmond)</p>
58 <p>
59 </p>
60 <hr />
61 <h1><a name="description">DESCRIPTION</a></h1>
62 <p>The gmond.conf file is used to configure the ganglia
63 monitoring daemon (gmond) which is part of the <strong>Ganglia
64 Distributed Monitoring System</strong>.</p>
65 <p>
66 </p>
67 <hr />
68 <h1><a name="sections_and_attributes">SECTIONS AND ATTRIBUTES</a></h1>
69 <p>All sections and attributes are case-insensitive. For example,
70 <strong>name</strong> or <strong>NAME</strong> or <strong>Name</strong> or <strong>NaMe</strong> are all equivalent.</p>
71 <p>Some sections can be included in the configuration file multiple
72 times and some sections are singular. For example, you can
73 have only one <strong>cluster</strong> section to define the attributes of
74 the cluster being monitored; however, you can have multiple
75 <strong>udp_recv_channel</strong> sections to allow gmond to receive message
76 on multiple UDP channels.</p>
77 <p>
78 </p>
79 <h2><a name="cluster">cluster</a></h2>
80 <p>There should only be one <strong>cluster</strong> section defined. This
81 section controls how gmond reports the attributes of the
82 cluster that it is part of.</p>
83 <p>The <strong>cluster</strong> section has four attributes: <strong>name</strong>,
84 <strong>owner</strong>, <strong>latlong</strong> and <strong>url</strong>.</p>
85 <p>For example,</p>
86 <pre>
87 cluster {
88 name = &quot;Millennium Cluster&quot;
89 owner = &quot;UC Berkeley CS Dept.&quot;
90 latlong = &quot;N37.37 W122.23&quot;
91 url = &quot;<a href="http://www.millennium.berkeley.edu/&quot">http://www.millennium.berkeley.edu/&quot</a>;
92 }</pre>
93 <p>The <strong>name</strong> attributes specifies the name of the cluster of
94 machines. The <strong>owner</strong> tag specifies the administrators of
95 the cluster. The pair <strong>name</strong>/<strong>owner</strong> should be unique
96 to all clusters in the world.</p>
97 <p>The <strong>latlong</strong> attribute is the latitude and longitude GPS
98 coordinates of this cluster on earth. Specified to 1 mile
99 accuracy with two decimal places per axis in decimal.</p>
100 <p>The <strong>url</strong> for more information on the <strong>cluster</strong>.
101 Intended to give purpose, owner, administration, and account details
102 for this cluster.</p>
103 <p>There directives directly control the XML output of gmond. For
104 example, the cluster configuration example above would translate
105 into the following XML.</p>
106 <pre>
107 &lt;CLUSTER NAME=&quot;Millennium Cluster&quot; OWNER=&quot;UC Berkeley CS Dept.&quot;
108 LATLONG=&quot;N37.37 W122.23&quot; URL=&quot;<a href="http://www.millennium.berkeley.edu/">http://www.millennium.berkeley.edu/</a>&quot;&gt;
109 ...
110 &lt;/CLUSTER&gt;</pre>
111 <p>
112 </p>
113 <h2><a name="host">host</a></h2>
114 <p>The <strong>host</strong> section provides information about the host running this
115 instance of <strong>gmond</strong>. Currently only the <strong>location</strong> string attribute is
116 supported. Example:</p>
117 <pre>
118 host {
119 location = &quot;1,2,3&quot;
120 }</pre>
121 <p>The numbers represent Rack, Rank and Plane respectively.</p>
122 <p>
123 </p>
124 <h2><a name="globals">globals</a></h2>
125 <p>The <strong>globals</strong> section controls general characteristics of gmond
126 such as whether is should daemonize, what user it should run as,
127 whether is should send/receive date and such. The <strong>globals</strong>
128 section has the following attributes: <strong>daemonize</strong>, <strong>setuid</strong>, <strong>user</strong>,
129 <strong>debug_level</strong>, <strong>mute</strong>, <strong>deaf</strong>, <strong>allow_extra_data</strong>, <strong>host_dmax</strong>,
130 <strong>host_tmax</strong>, <strong>cleanup_threshold</strong>, <strong>gexec</strong>, <strong>send_metadata_interval</strong>
131 and <strong>module_dir</strong>.</p>
132 <p>For example,</p>
133 <pre>
134 globals {
135 daemonize = true
136 setuid = true
137 user = nobody
138 host_dmax = 3600
139 host_tmax = 40
140 }</pre>
141 <p>The <strong>daemonize</strong> attribute is a boolean. When true, <strong>gmond</strong> will
142 daemonize. When false, <strong>gmond</strong> will run in the foreground.</p>
143 <p>The <strong>setuid</strong> attribute is a boolean. When true, <strong>gmond</strong> will
144 set its effective UID to the uid of the user specified by the <strong>user</strong>
145 attribute. When false, <strong>gmond</strong> will not change its effective user.</p>
146 <p>The <strong>debug_level</strong> is an integer value. When set to zero (0), <strong>gmond</strong>
147 will run normally. A <strong>debug_level</strong> greater than zero will result in
148 <strong>gmond</strong> running in the foreground and outputting debugging information.
149 The higher the <strong>debug_level</strong> the more verbose the output.</p>
150 <p>The <strong>mute</strong> attribute is a boolean. When true, <strong>gmond</strong> will not
151 send data regardless of any other configuration directives.</p>
152 <p>The <strong>deaf</strong> attribute is a boolean. When true, <strong>gmond</strong> will not
153 receive data regardless of any other configuration directives.</p>
154 <p>The <strong>allow_extra_data</strong> attribute is a boolean. When false, <strong>gmond</strong> will
155 not send out the EXTRA_ELEMENT and EXTRA_DATA parts of the XML. This might
156 be useful if you are using your own frontend to the metric data and will
157 like to save some bandwith.</p>
158 <p>The <strong>host_dmax</strong> value is an integer with units in seconds. When set
159 to zero (0), <strong>gmond</strong> will never delete a host from its list even when
160 a remote host has stopped reporting. If <strong>host_dmax</strong> is set to a
161 positive number then <strong>gmond</strong> will flush a host after it has not heard
162 from it for <strong>host_dmax</strong> seconds. By the way, dmax means &quot;delete max&quot;.</p>
163 <p>The <strong>host_tmax</strong> value is an integer with units in seconds. This value
164 represents the maximum amount of time that <strong>gmond</strong> should wait between
165 updates from a host. As messages may get lost in the network, <strong>gmond</strong>
166 will consider the host as being down if it has not received any messages
167 from it after 4 times this value. For example, if <strong>host_tmax</strong> is set
168 to 20, the host will appear as down after 80 seconds with no messages
169 from it. By the way, tmax means &quot;timeout max&quot;.</p>
170 <p>The <strong>cleanup_threshold</strong> is the minimum amount of time before gmond
171 will cleanup any hosts or metrics where <strong>tn</strong> &gt; <strong>dmax</strong> a.k.a. expired
172 data.</p>
173 <p>The <strong>gexec</strong> boolean allows you to specify whether gmond will announce
174 the hosts availability to run gexec jobs. <strong>Note</strong>: this requires
175 that <strong>gexecd</strong> is running on the host and the proper keys have been
176 installed.</p>
177 <p>The <strong>send_metadata_interval</strong> establishes an interval in which gmond
178 will send or resend the metadata packets that describe each enabled
179 metric. This directive by default is set to 0 which means that gmond will
180 only send the metadata packets at startup and upon request from other
181 gmond nodes running remotely. If a new machine running gmond is added
182 to a cluster, it needs to announce itself and inform all other nodes of the
183 metrics that it currently supports. In multicast mode, this isn't a problem
184 because any node can request the metadata of all other nodes in the cluster.
185 However in unicast mode, a resend interval must be established. The interval
186 value is the minimum number of seconds between resends.</p>
187 <p>The <strong>override_hostname</strong> and <strong>override_ip</strong> parameters allow an arbitrary
188 hostname and/or IP (hostname can be optionally specified without IP) to
189 use when identifying metrics coming from this host.</p>
190 <p>The <strong>module_dir</strong> is an optional parameter indicating the directory where
191 the DSO modules are to be located. If absent, the value to use is set at
192 configure time with the --with-moduledir option which will default if omitted
193 to the a subdirectory named &quot;ganglia&quot; in the directory where libganglia will
194 be installed.</p>
195 <p>For example, in a 32-bit Intel compatible Linux host that is usually:</p>
196 <pre>
197 /usr/lib/ganglia</pre>
198 <p>
199 </p>
200 <h2><a name="udp_send_channel">udp_send_channel</a></h2>
201 <p>You can define as many <strong>udp_send_channel</strong> sections as you like within
202 the limitations of memory and file descriptors. If <strong>gmond</strong> is configured
203 as <strong>mute</strong> this section will be ignored.</p>
204 <p>The <strong>udp_send_channel</strong> has a total of seven attributes: <strong>mcast_join</strong>,
205 <strong>mcast_if</strong>, <strong>host</strong>, <strong>port</strong>, <strong>ttl</strong>, <strong>bind</strong> and <strong>bind_hostname</strong>.
206 <strong>bind</strong> and <strong>bind_hostname</strong> are mutually exclusive.</p>
207 <p>For example, the 2.5.x version gmond would send on the following single channel
208 by default...</p>
209 <pre>
210 udp_send_channel {
211 mcast_join = 239.2.11.71
212 port = 8649
213 }</pre>
214 <p>The <strong>mcast_join</strong> and <strong>mcast_if</strong> attributes are optional. When specified
215 <strong>gmond</strong> will create the UDP socket and join the <strong>mcast_join</strong> multicast group
216 and send data out the interface specified by <strong>mcast_if</strong>.</p>
217 <p>You can use the <strong>bind</strong> attribute to bind to a particular local address to
218 be used as the source for the multicast packets sent or let gmond resolve the
219 default hostname if <strong>bind_hostname</strong> = yes.</p>
220 <p>If only a <strong>host</strong> and <strong>port</strong> are specified then <strong>gmond</strong> will send unicast UDP
221 messages to the hosts specified.</p>
222 <p>You could specify multiple unicast hosts for redundancy as <strong>gmond</strong> will send
223 UDP messages to all UDP channels.</p>
224 <p>Be careful though not to mix multicast and unicast attributes in the same
225 udp_send_channel definition.</p>
226 <p>For example...</p>
227 <pre>
228 udp_send_channel {
229 host = host.foo.com
230 port = 2389
231 }
232 udp_send_channel {
233 host = 192.168.3.4
234 port = 2344
235 }</pre>
236 <p>would configure gmond to send messages to two hosts. The <strong>host</strong> specification
237 can be an IPv4/IPv6 address or a resolvable hostname.</p>
238 <p>The <strong>ttl</strong> attribute lets you modify the Time-To-Live (TTL) of outgoing messages
239 (unicast or multicast).</p>
240 <p>
241 </p>
242 <h2><a name="udp_recv_channel">udp_recv_channel</a></h2>
243 <p>You can specify as many <strong>udp_recv_channel</strong> sections as you like within the
244 limits of memory and file descriptors. If <strong>gmond</strong> is configured <strong>deaf</strong>
245 this attribute will be ignored.</p>
246 <p>The <strong>udp_recv_channel</strong> section has following attributes:
247 <strong>mcast_join</strong>, <strong>bind</strong>, <strong>port</strong>, <strong>mcast_if</strong>, <strong>family</strong>, <strong>retry_bind</strong>
248 and <strong>buffer</strong>.
249 The <strong>udp_recv_channel</strong> can also have an <strong>acl</strong> definition (see
250 ACCESS CONTROL LISTS below).</p>
251 <p>For example, the 2.5.x gmond ran with a single udp receive channel...</p>
252 <pre>
253 udp_recv_channel {
254 mcast_join = 239.2.11.71
255 bind = 239.2.11.71
256 port = 8649
257 }</pre>
258 <p>The <strong>mcast_join</strong> and <strong>mcast_if</strong> should only be used if you want to
259 have this UDP channel receive multicast packets the multicast
260 group <strong>mcast_join</strong> on interface <strong>mcast_if</strong>. If you do not specify
261 multicast attributes then <strong>gmond</strong> will simply create a UDP server
262 on the specified <strong>port</strong>.</p>
263 <p>You can use the <strong>bind</strong> attribute to bind to a particular local address.</p>
264 <p>The family address is set to <strong>inet4</strong> by default. If you want to bind
265 the port to an <strong>inet6</strong> port, you need to specify that in the family
266 attribute. Ganglia will not allow IPV6=&gt;IPV4 mapping (for portability
267 and security reasons). If you want to listen on both <strong>inet4</strong> and
268 <strong>inet6</strong> for a particular port, explicitly state it with the following:</p>
269 <pre>
270 udp_recv_channel {
271 port = 8666
272 family = inet4
273 }
274 udp_recv_channel {
275 port = 8666
276 family = inet6
277 }</pre>
278 <p>If you specify a bind address, the family of that address takes precedence.
279 f your IPv6 stack doesn't support IPV6_V6ONLY, a warning will be issued
280 but gmond will continue working (this should rarely happen).</p>
281 <p>Multicast Note: for multicast, specifying a <strong>bind</strong> address with the same
282 value used for <strong>mcast_join</strong> will prevent unicast UDP messages to the same
283 <strong>port</strong> from being processed.</p>
284 <p>The sFlow protocol (see <a href="http://www.sflow.org)">http://www.sflow.org)</a> can be used to collect
285 a standard set of performance metrics from servers. For servers that
286 don't include embedded sFlow agents, an open source sFlow agent is available
287 on SourceForge (see <a href="http://host-sflow.sourceforge.net).">http://host-sflow.sourceforge.net).</a></p>
288 <p>To configure <strong>gmond</strong> to receive sFlow datagrams, simply
289 add a <strong>udp_recv_channel</strong> with the <strong>port</strong> set to 6343 (the IANA registered
290 port for sFlow):</p>
291 <pre>
292 udp_recv_channel {
293 port = 6343
294 }</pre>
295 <p>Note: sFlow is unicast protocol, so don't include <strong>mcast_join</strong> join.
296 Note: To use some other port for sFlow, set it here and then specify the port
297 in an <strong>sflow</strong> section (see below).</p>
298 <p><strong>gmond</strong> will fail to run if it can't bind to all defined
299 <strong>udp_recv_channel</strong>s. Sometimes, on machines configured by DHCP,
300 for example, the <strong>gmond</strong> daemon starts before a network address is
301 assigned to the interface. Consequently, the bind fails and the
302 <strong>gmond</strong> daemon does not run. To assist in this situation, the
303 boolean parameter <strong>retry_bind</strong> can be set to the value <strong>true</strong>
304 and then the daemon will not abort on failure, it will enter a
305 loop and repeat the bind attempt every 60 seconds:</p>
306 <pre>
307 udp_recv_channel {
308 port = 6343
309 retry_bind = true
310 }</pre>
311 <p>If you have a large system with lots of metrics, you might experience
312 UDP drops. This happens when <strong>gmond</strong> is not able to process the UDP
313 fast enough from the network. In this case you might consider changing
314 your setup into a more distributed setup using aggregator <strong>gmond</strong> hosts.
315 Alternatively you can choose to create a bigger receive <strong>buffer</strong>:</p>
316 <pre>
317 udp_recv_channel {
318 port = 6343
319 buffer = 10485760
320 }
321 B&lt;buffer&gt; is specified in bytes, i.e.: 10485760 will allow 10MB UDP
322 to be buffered in memory.</pre>
323 <p>Note: increasing buffer size will increase memory usage by <strong>gmond</strong></p>
324 <p>
325 </p>
326 <h2><a name="tcp_accept_channel">tcp_accept_channel</a></h2>
327 <p>You can specify as many <strong>tcp_accept_channel</strong> sections as you like
328 within the limitations of memory and file descriptors. If <strong>gmond</strong>
329 is configured to be <strong>mute</strong>, then these sections are ignored.</p>
330 <p>The <strong>tcp_accept_channel</strong> has the following attributes: <strong>bind</strong>, <strong>port</strong>,
331 <strong>interface</strong>, <strong>family</strong> and <strong>timeout</strong>. A <strong>tcp_accept_channel</strong> may also have
332 an <strong>acl</strong> section specified (see ACCESS CONTROL LISTS below).</p>
333 <p>For example, 2.5.x gmond would accept connections on a single TCP
334 channel.</p>
335 <pre>
336 tcp_accept_channel {
337 port = 8649
338 }</pre>
339 <p>The <strong>bind</strong> address is optional and allows you to specify which
340 local address <strong>gmond</strong> will bind to for this channel.</p>
341 <p>The <strong>port</strong> is an integer than specifies which port to answer
342 requests for data.</p>
343 <p>The <strong>family</strong> address is set to <strong>inet4</strong> by default. If you want to bind
344 the port to an <strong>inet6</strong> port, you need to specify that in the family
345 attribute. Ganglia will not allow IPV6=&gt;IPV4 mapping (for portability
346 and security reasons). If you want to listen on both <strong>inet4</strong> and
347 <strong>inet6</strong> for a particular port, explicitly state it with the following:</p>
348 <pre>
349 tcp_accept_channel {
350 port = 8666
351 family = inet4
352 }
353 tcp_accept_channel {
354 port = 8666
355 family = inet6
356 }</pre>
357 <p>If you specify a bind address, the family of that address takes precedence.
358 If your IPv6 stack doesn't support IPV6_V6ONLY, a warning will be issued
359 but gmond will continue working (this should rarely happen).</p>
360 <p>The <strong>timeout</strong> attribute allows you to specify how many microseconds to block
361 before closing a connection to a client. The default is set to -1 (blocking
362 IO) and will never abort a connection regardless of how slow the client is
363 in fetching the report data.</p>
364 <p>The <strong>interface</strong> is not implemented at this time (use <strong>bind</strong>).</p>
365 <p>
366 </p>
367 <h2><a name="collection_group">collection_group</a></h2>
368 <p>You can specify as many <strong>collection_group</strong> section as you like
369 within the limitations of memory. A <strong>collection_group</strong> has
370 the following attributes: <strong>collect_once</strong>, <strong>collect_every</strong>
371 and <strong>time_threshold</strong>. A <strong>collection_group</strong> must also contain one
372 or more <strong>metric</strong> sections.</p>
373 <p>The <strong>metric</strong> section has the following attributes: (one of <strong>name</strong>
374 or <strong>name_match</strong>; <strong>name_match</strong> is only permitted if pcre support is
375 compiled in), <strong>value_threshold</strong> and <strong>title</strong>. For a list of
376 available metric names, run the following command:</p>
377 <pre>
378 % gmond -m</pre>
379 <p>Here is an example of a collection group for a static metric...</p>
380 <pre>
381 collection_group {
382 collect_once = yes
383 time_threshold = 1800
384 metric {
385 name = &quot;cpu_num&quot;
386 title = &quot;Number of CPUs&quot;
387 }
388 }</pre>
389 <p>This <strong>collection_group</strong> entry would cause gmond to collect the
390 <strong>cpu_num</strong> metric once at startup (since the number of CPUs will not
391 change between reboots). The metric <strong>cpu_num</strong> would be send
392 every 1/2 hour (1800 seconds). The default value for the <strong>time_threshold</strong>
393 is 3600 seconds if no <strong>time_threshold</strong> is specified.</p>
394 <p>The <strong>time_threshold</strong> is the maximum amount of time that can pass before
395 gmond sends all <strong>metric</strong>s specified in the <strong>collection_group</strong> to all
396 configured <strong>udp_send_channel</strong>s. A <strong>metric</strong> may be sent before this
397 <strong>time_threshold</strong> is met if during collection the value surpasses the
398 <strong>value_threshold</strong> (explained below).</p>
399 <p>Here is an example of a collection group for a volatile metric...</p>
400 <pre>
401 collection_group {
402 collect_every = 60
403 time_threshold = 300
404 metric {
405 name = &quot;cpu_user&quot;
406 value_threshold = 5.0
407 title = &quot;CPU User&quot;
408 }
409 metric {
410 name = &quot;cpu_idle&quot;
411 value_threshold = 10.0
412 title = &quot;CPU Idle&quot;
413 }
414 }</pre>
415 <p>This collection group would collect the <strong>cpu_user</strong> and <strong>cpu_idle</strong> metrics
416 every 60 seconds (specified in <strong>collect_every</strong>). If <strong>cpu_user</strong> varies by
417 5.0% or <strong>cpu_idle</strong> varies by 10.0%, then the entire <strong>collection_group</strong>
418 is sent. If no <strong>value_threshold</strong> is triggered within <strong>time_threshold</strong>
419 seconds (in this case 300), the entire <strong>collection_group</strong> is sent.</p>
420 <p>Each time the metric value is collected the new value is compared with
421 the old value collected. If the difference between the last value and
422 the current value is greater than the <strong>value_threshold</strong>, the entire
423 collection group is send to the <strong>udp_send_channel</strong>s defined.</p>
424 <p>It's important to note that all metrics in a collection group are sent
425 even when only a single <strong>value_threshold</strong> is surpassed.</p>
426 <p>In addition a user friendly title can be substituted for the metric name
427 by including a <strong>title</strong> within the <strong>metric</strong> section.</p>
428 <p>By using the <strong>name_match</strong> parameter instead of <strong>name</strong>, it is possible
429 to use a single definition to configure multiple metrics that match a
430 regular expression. The perl compatible regular expression (pcre) syntax
431 is used. This approach is particularly useful for a series of metrics
432 that may vary in number between reboots (e.g. metric names that
433 are generated for each individual NIC or CPU core).</p>
434 <p>Here is an example of using the <strong>name_match</strong> directive to enable
435 the multicpu metrics:</p>
436 <pre>
437 metric {
438 name_match = &quot;multicpu_([a-z]+)([0-9]+)&quot;
439 value_threshold = 1.0
440 title = &quot;CPU-\\2 \\1&quot;
441 }</pre>
442 <p>Note that in the example above, there are two matches: the alphabetical
443 match matches the variations of the metric name (e.g. <strong>idle</strong>, <strong>system</strong>)
444 while the numeric match matches the CPU core number. The second thing
445 to note is the use of substitutions within the argument to <strong>title</strong>.</p>
446 <p>If both <strong>name</strong> and <strong>name_match</strong> are specified, then <strong>name</strong> is ignored.</p>
447 <p>
448 </p>
449 <h2><a name="modules">Modules</a></h2>
450 <p>A <strong>modules</strong> section contains the parameters that are necessary to load a
451 metric module. A metric module is a dynamically loadable module that
452 extends the available metrics that gmond is able to collect. Each <strong>modules</strong>
453 section contains at least one <strong>module</strong> section. Within a <strong>module</strong> section
454 are the directives <strong>name</strong>, <strong>language</strong>, <strong>enabled</strong>, <strong>path</strong> and <strong>params</strong>.
455 The module <strong>name</strong> is the name of the module as determined by the module
456 structure if the module was developed in C/C++. Alternatively, the
457 <strong>name</strong> can be the name of the source file if the module has been
458 implemented in a interpreted language such as python. A <strong>language</strong>
459 designation must be specified as a string value for each module. The
460 <strong>language</strong> directive must correspond to the source code language in
461 which the module was implemented (ex. language = &quot;python&quot;). If a
462 <strong>language</strong> directive does not exist for the module, the assumed
463 language will be &quot;C/C++&quot;. The <strong>enabled</strong> directive allows a metric module
464 to be easily enabled or disabled through the configuration file. If the
465 <strong>enabled</strong> directive is not included in the module configuration, the
466 enabled state will default to &quot;yes&quot;. One thing to note is that if a
467 module has been disabled yet the metric which that module implements
468 is still listed as part of a collection group, gmond will produce a
469 warning message. However gmond will continue to function normally
470 by simply ignoring the metric. The <strong>path</strong> is the path from which
471 gmond is expected to load the module (C/C++ compiled dynamically
472 loadable module only). The <strong>params</strong> directive can be used to pass
473 a single string parameter directly to the module initialization
474 function (C/C++ module only). Multiple parameters can be passed to
475 the module's initialization function by including one or more
476 <strong>param</strong> sections. Each <strong>param</strong> section must be named and contain
477 a <strong>value</strong> directive. Once a module has been loaded, the additional
478 metrics can be discovered by invoking <strong>gmond -m</strong>.</p>
479 <pre>
480 modules {
481 module {
482 name = &quot;example_module&quot;
483 language = &quot;C/C++&quot;
484 enabled = yes
485 path = &quot;modexample.so&quot;
486 params = &quot;An extra raw parameter&quot;
487 param RandomMax {
488 value = 75
489 }
490 param ConstantValue {
491 value = 25
492 }
493 }
494 }</pre>
495 <p>
496 </p>
497 <h2><a name="sflow">sFlow</a></h2>
498 <p>The <strong>sflow</strong> group is optional and has the following optional
499 attributes: <strong>udp_port</strong>, <strong>accept_vm_metrics</strong>, <strong>accept_http_metrics</strong>,
500 <strong>accept_memcache_metrics</strong>, <strong>accept_jvm_metrics</strong>,
501 <strong>multiple_http_instances</strong>,<strong>multiple_memcache_instances</strong>,
502 <strong>multiple_jvm_instances</strong>. By default, a
503 <strong>udp_recv_channel</strong> on port 6343 (the IANA registered port for
504 sFlow) is all that is required to accept and process sFlow
505 datagrams. To receive sFlow on some other port requires both
506 a <strong>udp_recv_channel</strong> for the other port and a <strong>udp_port</strong>
507 setting here. For example:</p>
508 <pre>
509 udp_recv_channel {
510 port = 7343
511 }</pre>
512 <pre>
513 sflow {
514 udp_port = 7343
515 }</pre>
516 <p>An sFlow agent running on a hypervisor may also be sending
517 metrics for its local virtual machines. By default these
518 metrics are ignored, but the <strong>accept_vm_metrics</strong> flag can
519 be used to accept those metrics too, and prefix them with
520 an identifier for each virtual machine.</p>
521 <pre>
522 sflow {
523 accept_vm_metrics = yes
524 }</pre>
525 <p>The sFlow feed may also contain metrics sent from HTTP or memcached
526 servers, or from Java VMs. Extra options can be used to ignore
527 or accept these metrics, and to indicate that there may be multiple
528 instances per host. For example:</p>
529 <pre>
530 sflow {
531 accept_http_metrics = yes
532 multiple_http_instances = yes
533 }</pre>
534 <p>will allow the HTTP metrics, and also mark them with a distinguishing
535 identifier so that each instance can be trended separately. (If multiple
536 instances are reporting and this flag is not set, the results are likely
537 to be garbled.)</p>
538 <p>
539 </p>
540 <h2><a name="include">Include</a></h2>
541 <p>This directive allows the user to include additional configuration files
542 rather than having to add all gmond configuration directives to the
543 gmond.conf file. The following example includes any file with the extension
544 of .conf contained in the directory conf.d as if the contents of the included
545 configuration files were part of the original gmond.conf file. This allows
546 the user to modularize their configuration file. One usage example might
547 be to load individual metric modules by including module specific .conf files.</p>
548 <p>include ('/etc/ganglia/conf.d/*.conf')</p>
549 <p>
550 </p>
551 <hr />
552 <h1><a name="access_control">ACCESS CONTROL</a></h1>
553 <p>The <strong>udp_recv_channel</strong> and <strong>tcp_accept_channel</strong> directives
554 can contain an Access Control List (ACL). This ACL allows you to specify
555 exactly which hosts gmond process data from.</p>
556 <p>An example of an <strong>acl</strong> entry looks like</p>
557 <pre>
558 acl {
559 default = &quot;deny&quot;
560 access {
561 ip = 192.168.0.4
562 mask = 32
563 action = &quot;allow&quot;
564 }
565 }</pre>
566 <p>This ACL will by default reject all traffic that is not specifically from
567 host 192.168.0.4 (the mask size for an IPv4 address is 32, the mask size
568 for an IPv6 address is 128 to represent a single host).</p>
569 <p>Here is another example</p>
570 <pre>
571 acl {
572 default = &quot;allow&quot;
573 access {
574 ip = 192.168.0.0
575 mask = 24
576 action = &quot;deny&quot;
577 }
578 access {
579 ip = ::ff:1.2.3.0
580 mask = 120
581 action = &quot;deny&quot;
582 }
583 }</pre>
584 <p>This ACL will by default allow all traffic unless it comes from the
585 two subnets specified with action = &quot;deny&quot;.</p>
586 <p>
587 </p>
588 <hr />
589 <h1><a name="example">EXAMPLE</a></h1>
590 <p>The default behavior for a 2.5.x gmond would be specified as...</p>
591 <pre>
592 udp_recv_channel {
593 mcast_join = 239.2.11.71
594 bind = 239.2.11.71
595 port = 8649
596 }
597 udp_send_channel {
598 mcast_join = 239.2.11.71
599 port = 8649
600 }
601 tcp_accept_channel {
602 port = 8649
603 }</pre>
604 <p>To see the complete default configuration for gmond simply run:</p>
605 <pre>
606 % gmond -t</pre>
607 <p>gmond will print out its default behavior in a configuration file
608 and then exit. Capturing this output to a file can serve as
609 a useful starting point for creating your own custom configuration.</p>
610 <pre>
611 % gmond -t &gt; custom.conf</pre>
612 <p>edit <strong>custom.conf</strong> to taste and then</p>
613 <pre>
614 % gmond -c ./custom.conf</pre>
615 <p>
616 </p>
617 <hr />
618 <h1><a name="see_also">SEE ALSO</a></h1>
619 <p><code>gmond(1)</code>.</p>
620 <p>
621 </p>
622 <hr />
623 <h1><a name="notes">NOTES</a></h1>
624 <p>The ganglia web site is at <a href="http://ganglia.info/.">http://ganglia.info/.</a></p>
625 <p>
626 </p>
627 <hr />
628 <h1><a name="copyright">COPYRIGHT</a></h1>
629 <p>Copyright (c) 2005 The University of California, Berkeley</p>
630 <table border="0" width="100%" cellspacing="0" cellpadding="3">
631 <tr><td class="block" style="background-color: #cccccc" valign="middle">
632 <big><strong><span class="block">&nbsp;Ganglia Monitoring Daemon v3.7.2 Configuration</span></strong></big>
633 </td></tr>
634 </table>
635
636 </body>
637
638 </html>