File: gmond.conf.5

package info (click to toggle)
ganglia 3.6.0-7
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid, stretch
  • size: 6,484 kB
  • ctags: 3,880
  • sloc: ansic: 27,874; sh: 11,052; python: 6,695; makefile: 565; perl: 366; php: 126; xml: 28
file content (816 lines) | stat: -rw-r--r-- 29,825 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "gmond.conf 5"
.TH gmond.conf 5 "2013-05-07" "ganglia/3.6.0" "Ganglia Monitoring System"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
\&\fBgmond.conf\fR \- configuration file for ganglia monitoring
daemon (gmond)
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The gmond.conf file is used to configure the ganglia
monitoring daemon (gmond) which is part of the \fBGanglia
Distributed Monitoring System\fR.
.SH "SECTIONS AND ATTRIBUTES"
.IX Header "SECTIONS AND ATTRIBUTES"
All sections and attributes are case-insensitive.  For example,
\&\fBname\fR or \fB\s-1NAME\s0\fR or \fBName\fR or \fBNaMe\fR are all equivalent.
.PP
Some sections can be included in the configuration file multiple
times and some sections are singular.  For example, you can
have only one \fBcluster\fR section to define the attributes of
the cluster being monitored; however, you can have multiple
\&\fBudp_recv_channel\fR sections to allow gmond to receive message
on multiple \s-1UDP\s0 channels.
.SS "cluster"
.IX Subsection "cluster"
There should only be one \fBcluster\fR section defined.  This
section controls how gmond reports the attributes of the
cluster that it is part of.
.PP
The \fBcluster\fR section has four attributes: \fBname\fR,
\&\fBowner\fR, \fBlatlong\fR and \fBurl\fR.
.PP
For example,
.PP
.Vb 6
\&  cluster {
\&    name = "Millennium Cluster"
\&    owner = "UC Berkeley CS Dept."
\&    latlong = "N37.37 W122.23"
\&    url = "http://www.millennium.berkeley.edu/"
\&  }
.Ve
.PP
The \fBname\fR attributes specifies the name of the cluster of 
machines.  The \fBowner\fR tag specifies the administrators of 
the cluster.  The pair \fBname\fR/\fBowner\fR should be unique
to all clusters in the world.
.PP
The \fBlatlong\fR attribute is the latitude and longitude \s-1GPS\s0 
coordinates of this cluster on earth.  Specified to 1 mile 
accuracy with two decimal places per axis in decimal.
.PP
The \fBurl\fR for more information on the \fBcluster\fR. 
Intended to give purpose, owner, administration, and account details 
for this cluster.
.PP
There directives directly control the \s-1XML\s0 output of gmond.  For
example, the cluster configuration example above would translate
into the following \s-1XML\s0.
.PP
.Vb 4
\&  <CLUSTER NAME="Millennium Cluster" OWNER="UC Berkeley CS Dept."
\&           LATLONG="N37.37 W122.23" URL="http://www.millennium.berkeley.edu/">
\&  ...
\&  </CLUSTER>
.Ve
.SS "host"
.IX Subsection "host"
The \fBhost\fR section provides information about the host running this
instance of \fBgmond\fR. Currently only the \fBlocation\fR string attribute is
supported. Example:
.PP
.Vb 3
\& host {
\&   location = "1,2,3"
\& }
.Ve
.PP
The numbers represent Rack, Rank and Plane respectively.
.SS "globals"
.IX Subsection "globals"
The \fBglobals\fR section controls general characteristics of gmond
such as whether is should daemonize, what user it should run as,
whether is should send/receive date and such.  The \fBglobals\fR
section has the following attributes: \fBdaemonize\fR, \fBsetuid\fR, \fBuser\fR,
\&\fBdebug_level\fR, \fBmute\fR, \fBdeaf\fR, \fBallow_extra_data\fR, \fBhost_dmax\fR,
\&\fBhost_tmax\fR, \fBcleanup_threshold\fR, \fBgexec\fR, \fBsend_metadata_interval\fR
and \fBmodule_dir\fR.
.PP
For example,
.PP
.Vb 7
\&  globals {
\&    daemonize = true
\&    setuid = true
\&    user = nobody
\&    host_dmax = 3600
\&    host_tmax = 40
\&  }
.Ve
.PP
The \fBdaemonize\fR attribute is a boolean.  When true, \fBgmond\fR will 
daemonize.  When false, \fBgmond\fR will run in the foreground.
.PP
The \fBsetuid\fR attribute is a boolean.  When true, \fBgmond\fR will
set its effective \s-1UID\s0 to the uid of the user specified by the \fBuser\fR
attribute.  When false, \fBgmond\fR will not change its effective user.
.PP
The \fBdebug_level\fR is an integer value.  When set to zero (0), \fBgmond\fR
will run normally.  A \fBdebug_level\fR greater than zero will result in
\&\fBgmond\fR running in the foreground and outputting debugging information.
The higher the \fBdebug_level\fR the more verbose the output.
.PP
The \fBmute\fR attribute is a boolean.  When true, \fBgmond\fR will not 
send data regardless of any other configuration directives.
.PP
The \fBdeaf\fR attribute is a boolean.  When true, \fBgmond\fR will not 
receive data regardless of any other configuration directives.
.PP
The \fBallow_extra_data\fR attribute is a boolean.  When false, \fBgmond\fR will
not send out the \s-1EXTRA_ELEMENT\s0 and \s-1EXTRA_DATA\s0 parts of the \s-1XML\s0.  This might
be useful if you are using your own frontend to the metric data and will
like to save some bandwith.
.PP
The \fBhost_dmax\fR value is an integer with units in seconds.  When set 
to zero (0), \fBgmond\fR will never delete a host from its list even when 
a remote host has stopped reporting.  If \fBhost_dmax\fR is set to a
positive number then \fBgmond\fR will flush a host after it has not heard
from it for \fBhost_dmax\fR seconds.  By the way, dmax means \*(L"delete max\*(R".
.PP
The \fBhost_tmax\fR value is an integer with units in seconds. This value
represents the maximum amount of time that \fBgmond\fR should wait between
updates from a host. As messages may get lost in the network, \fBgmond\fR
will consider the host as being down if it has not received any messages
from it after 4 times this value. For example, if \fBhost_tmax\fR is set 
to 20, the host will appear as down after 80 seconds with no messages
from it. By the way, tmax means \*(L"timeout max\*(R".
.PP
The \fBcleanup_threshold\fR is the minimum amount of time before gmond
will cleanup any hosts or metrics where \fBtn\fR > \fBdmax\fR a.k.a. expired
data.
.PP
The \fBgexec\fR boolean allows you to specify whether gmond will announce
the hosts availability to run gexec jobs.  \fBNote\fR: this requires
that \fBgexecd\fR is running on the host and the proper keys have been
installed.
.PP
The \fBsend_metadata_interval\fR establishes an interval in which gmond
will send or resend the metadata packets that describe each enabled 
metric. This directive by default is set to 0 which means that gmond will
only send the metadata packets at startup and upon request from other 
gmond nodes running remotely. If a new machine running gmond is added
to a cluster, it needs to announce itself and inform all other nodes of the
metrics that it currently supports. In multicast mode, this isn't a problem
because any node can request the metadata of all other nodes in the cluster.
However in unicast mode, a resend interval must be established. The interval
value is the minimum number of seconds between resends.
.PP
The \fBoverride_hostname\fR and \fBoverride_ip\fR parameters allow an arbitrary
hostname and/or \s-1IP\s0 (hostname can be optionally specified without \s-1IP\s0) to
use when identifying metrics coming from this host.
.PP
The \fBmodule_dir\fR is an optional parameter indicating the directory where
the \s-1DSO\s0 modules are to be located.  If absent, the value to use is set at
configure time with the \-\-with\-moduledir option which will default if omitted
to the a subdirectory named \*(L"ganglia\*(R" in the directory where libganglia will
be installed.
.PP
For example, in a 32\-bit Intel compatible Linux host that is usually:
.PP
.Vb 1
\&  /usr/lib/ganglia
.Ve
.SS "udp_send_channel"
.IX Subsection "udp_send_channel"
You can define as many \fBudp_send_channel\fR sections as you like within
the limitations of memory and file descriptors.  If \fBgmond\fR is configured
as \fBmute\fR this section will be ignored.
.PP
The \fBudp_send_channel\fR has a total of seven attributes: \fBmcast_join\fR,
\&\fBmcast_if\fR, \fBhost\fR, \fBport\fR, \fBttl\fR, \fBbind\fR and \fBbind_hostname\fR.
\&\fBbind\fR and \fBbind_hostname\fR are mutually exclusive.
.PP
For example, the 2.5.x version gmond would send on the following single channel
by default...
.PP
.Vb 4
\&  udp_send_channel {
\&    mcast_join = 239.2.11.71
\&    port       = 8649
\&  }
.Ve
.PP
The \fBmcast_join\fR and \fBmcast_if\fR attributes are optional.  When specified
\&\fBgmond\fR will create the \s-1UDP\s0 socket and join the \fBmcast_join\fR multicast group
and send data out the interface specified by \fBmcast_if\fR.
.PP
You can use the \fBbind\fR attribute to bind to a particular local address to
be used as the source for the multicast packets sent or let gmond resolve the
default hostname if \fBbind_hostname\fR = yes.
.PP
If only a \fBhost\fR and \fBport\fR are specified then \fBgmond\fR will send unicast \s-1UDP\s0
messages to the hosts specified.
.PP
You could specify multiple unicast hosts for redundancy as \fBgmond\fR will send
\&\s-1UDP\s0 messages to all \s-1UDP\s0 channels.
.PP
Be careful though not to mix multicast and unicast attributes in the same
udp_send_channel definition.
.PP
For example...
.PP
.Vb 8
\&  udp_send_channel {
\&    host = host.foo.com
\&    port = 2389
\&  }
\&  udp_send_channel {
\&    host = 192.168.3.4
\&    port = 2344
\&  }
.Ve
.PP
would configure gmond to send messages to two hosts.  The \fBhost\fR specification
can be an IPv4/IPv6 address or a resolvable hostname.
.PP
The \fBttl\fR attribute lets you modify the Time-To-Live (\s-1TTL\s0) of outgoing messages
(unicast or multicast).
.SS "udp_recv_channel"
.IX Subsection "udp_recv_channel"
You can specify as many \fBudp_recv_channel\fR sections as you like within the 
limits of memory and file descriptors.  If \fBgmond\fR is configured \fBdeaf\fR
this attribute will be ignored.
.PP
The \fBudp_recv_channel\fR section has following attributes:
\&\fBmcast_join\fR, \fBbind\fR, \fBport\fR, \fBmcast_if\fR, \fBfamily\fR, \fBretry_bind\fR
and \fBbuffer\fR.
The \fBudp_recv_channel\fR can also have an \fBacl\fR definition (see
\&\s-1ACCESS\s0 \s-1CONTROL\s0 \s-1LISTS\s0 below).
.PP
For example, the 2.5.x gmond ran with a single udp receive channel...
.PP
.Vb 5
\&  udp_recv_channel {
\&    mcast_join = 239.2.11.71
\&    bind       = 239.2.11.71
\&    port       = 8649
\&  }
.Ve
.PP
The \fBmcast_join\fR and \fBmcast_if\fR should only be used if you want to 
have this \s-1UDP\s0 channel receive multicast packets the multicast
group \fBmcast_join\fR on interface \fBmcast_if\fR.  If you do not specify
multicast attributes then \fBgmond\fR will simply create a \s-1UDP\s0 server
on the specified \fBport\fR.
.PP
You can use the \fBbind\fR attribute to bind to a particular local address.
.PP
The family address is set to \fBinet4\fR by default.  If you want to bind
the port to an \fBinet6\fR port, you need to specify that in the family
attribute.  Ganglia will not allow IPV6=>\s-1IPV4\s0 mapping (for portability
and security reasons).  If you want to listen on both \fBinet4\fR and
\&\fBinet6\fR for a particular port, explicitly state it with the following:
.PP
.Vb 8
\&  udp_recv_channel {
\&    port = 8666
\&    family = inet4
\&  }
\&  udp_recv_channel {
\&    port = 8666
\&    family = inet6
\&  }
.Ve
.PP
If you specify a bind address, the family of that address takes precedence.
f your IPv6 stack doesn't support \s-1IPV6_V6ONLY\s0, a warning will be issued
but gmond will continue working (this should rarely happen).
.PP
Multicast Note: for multicast, specifying a \fBbind\fR address with the same
value used for \fBmcast_join\fR will prevent unicast \s-1UDP\s0 messages to the same
\&\fBport\fR from being processed.
.PP
The sFlow protocol (see http://www.sflow.org) can be used to collect
a standard set of performance metrics from servers. For servers that
don't include embedded sFlow agents, an open source sFlow agent is available
on SourceForge (see http://host\-sflow.sourceforge.net).
.PP
To configure \fBgmond\fR to receive sFlow datagrams, simply
add a \fBudp_recv_channel\fR with the \fBport\fR set to 6343 (the \s-1IANA\s0 registered
port for sFlow):
.PP
.Vb 3
\&  udp_recv_channel {
\&    port = 6343
\&  }
.Ve
.PP
Note: sFlow is unicast protocol, so don't include \fBmcast_join\fR join.
Note: To use some other port for sFlow, set it here and then specify the port
in an \fBsflow\fR section (see below).
.PP
\&\fBgmond\fR will fail to run if it can't bind to all defined
\&\fBudp_recv_channel\fRs.  Sometimes, on machines configured by \s-1DHCP\s0,
for example, the \fBgmond\fR daemon starts before a network address is
assigned to the interface.  Consequently, the bind fails and the 
\&\fBgmond\fR daemon does not run.  To assist in this situation, the
boolean parameter \fBretry_bind\fR can be set to the value \fBtrue\fR
and then the daemon will not abort on failure, it will enter a
loop and repeat the bind attempt every 60 seconds:
.PP
.Vb 4
\&  udp_recv_channel {
\&    port = 6343
\&    retry_bind = true
\&  }
.Ve
.PP
If you have a large system with lots of metrics, you might experience
\&\s-1UDP\s0 drops. This happens when \fBgmond\fR is not able to process the \s-1UDP\s0
fast enough from the network. In this case you might consider changing
your setup into a more distributed setup using aggregator \fBgmond\fR hosts.
Alternatively you can choose to create a bigger receive \fBbuffer\fR:
.PP
.Vb 6
\&  udp_recv_channel {
\&    port = 6343
\&    buffer = 10485760
\&  }
\&B<buffer> is specified in bytes, i.e.: 10485760 will allow 10MB UDP 
\&to be buffered in memory.
.Ve
.PP
Note: increasing buffer size will increase memory usage by \fBgmond\fR
.SS "tcp_accept_channel"
.IX Subsection "tcp_accept_channel"
You can specify as many \fBtcp_accept_channel\fR sections as you like
within the limitations of memory and file descriptors.  If \fBgmond\fR
is configured to be \fBmute\fR, then these sections are ignored.
.PP
The \fBtcp_accept_channel\fR has the following attributes: \fBbind\fR, \fBport\fR, 
\&\fBinterface\fR, \fBfamily\fR and \fBtimeout\fR.  A \fBtcp_accept_channel\fR may also have
an \fBacl\fR section specified (see \s-1ACCESS\s0 \s-1CONTROL\s0 \s-1LISTS\s0 below).
.PP
For example, 2.5.x gmond would accept connections on a single \s-1TCP\s0
channel.
.PP
.Vb 3
\&  tcp_accept_channel {
\&    port = 8649
\&  }
.Ve
.PP
The \fBbind\fR address is optional and allows you to specify which 
local address \fBgmond\fR will bind to for this channel.
.PP
The \fBport\fR is an integer than specifies which port to answer 
requests for data.
.PP
The \fBfamily\fR address is set to \fBinet4\fR by default.  If you want to bind
the port to an \fBinet6\fR port, you need to specify that in the family
attribute.  Ganglia will not allow IPV6=>\s-1IPV4\s0 mapping (for portability
and security reasons).  If you want to listen on both \fBinet4\fR and
\&\fBinet6\fR for a particular port, explicitly state it with the following:
.PP
.Vb 8
\&  tcp_accept_channel {
\&    port = 8666
\&    family = inet4
\&  }
\&  tcp_accept_channel {
\&    port = 8666
\&    family = inet6
\&  }
.Ve
.PP
If you specify a bind address, the family of that address takes precedence.
If your IPv6 stack doesn't support \s-1IPV6_V6ONLY\s0, a warning will be issued
but gmond will continue working (this should rarely happen).
.PP
The \fBtimeout\fR attribute allows you to specify how many microseconds to block
before closing a connection to a client.  The default is set to \-1 (blocking
\&\s-1IO\s0) and will never abort a connection regardless of how slow the client is
in fetching the report data.
.PP
The \fBinterface\fR is not implemented at this time (use \fBbind\fR).
.SS "collection_group"
.IX Subsection "collection_group"
You can specify as many \fBcollection_group\fR section as you like
within the limitations of memory.  A \fBcollection_group\fR has
the following attributes: \fBcollect_once\fR, \fBcollect_every\fR
and \fBtime_threshold\fR.  A \fBcollection_group\fR must also contain one
or more \fBmetric\fR sections.
.PP
The \fBmetric\fR section has the following attributes: (one of \fBname\fR 
or \fBname_match\fR; \fBname_match\fR is only permitted if pcre support is
compiled in), \fBvalue_threshold\fR and \fBtitle\fR.  For a list of 
available metric names, run the following command:
.PP
.Vb 1
\&  % gmond \-m
.Ve
.PP
Here is an example of a collection group for a static metric...
.PP
.Vb 8
\&  collection_group {
\&    collect_once   = yes
\&    time_threshold = 1800
\&    metric {
\&     name = "cpu_num"
\&     title = "Number of CPUs"
\&    }
\&  }
.Ve
.PP
This \fBcollection_group\fR entry would cause gmond to collect the 
\&\fBcpu_num\fR metric once at startup (since the number of CPUs will not 
change between reboots).  The metric \fBcpu_num\fR would be send
every 1/2 hour (1800 seconds).  The default value for the \fBtime_threshold\fR
is 3600 seconds if no \fBtime_threshold\fR is specified.
.PP
The \fBtime_threshold\fR is the maximum amount of time that can pass before
gmond sends all \fBmetric\fRs specified in the \fBcollection_group\fR to all
configured \fBudp_send_channel\fRs.  A \fBmetric\fR may be sent before this
\&\fBtime_threshold\fR is met if during collection the value surpasses the
\&\fBvalue_threshold\fR (explained below).
.PP
Here is an example of a collection group for a volatile metric...
.PP
.Vb 10
\&  collection_group {
\&    collect_every = 60
\&    time_threshold = 300
\&    metric {
\&      name = "cpu_user"
\&      value_threshold = 5.0
\&      title = "CPU User"
\&    }
\&    metric {
\&      name = "cpu_idle"
\&      value_threshold = 10.0
\&      title = "CPU Idle"
\&    }
\&  }
.Ve
.PP
This collection group would collect the \fBcpu_user\fR and \fBcpu_idle\fR metrics
every 60 seconds (specified in \fBcollect_every\fR).  If \fBcpu_user\fR varies by
5.0% or \fBcpu_idle\fR varies by 10.0%, then the entire \fBcollection_group\fR
is sent.  If no \fBvalue_threshold\fR is triggered within \fBtime_threshold\fR
seconds (in this case 300), the entire \fBcollection_group\fR is sent.
.PP
Each time the metric value is collected the new value is compared with
the old value collected.  If the difference between the last value and
the current value is greater than the \fBvalue_threshold\fR, the entire
collection group is send to the \fBudp_send_channel\fRs defined.
.PP
It's important to note that all metrics in a collection group are sent
even when only a single \fBvalue_threshold\fR is surpassed.
.PP
In addition a user friendly title can be substituted for the metric name
by including a \fBtitle\fR within the \fBmetric\fR section.
.PP
By using the \fBname_match\fR parameter instead of \fBname\fR, it is possible
to use a single definition to configure multiple metrics that match a
regular expression.  The perl compatible regular expression (pcre) syntax
is used.  This approach is particularly useful for a series of metrics
that may vary in number between reboots (e.g. metric names that
are generated for each individual \s-1NIC\s0 or \s-1CPU\s0 core).
.PP
Here is an example of using the \fBname_match\fR directive to enable
the multicpu metrics:
.PP
.Vb 5
\&  metric {
\&    name_match = "multicpu_([a\-z]+)([0\-9]+)"
\&    value_threshold = 1.0
\&    title = "CPU\-\e\e2 \e\e1"
\&  }
.Ve
.PP
Note that in the example above, there are two matches: the alphabetical
match matches the variations of the metric name (e.g. \fBidle\fR, \fBsystem\fR)
while the numeric match matches the \s-1CPU\s0 core number.  The second thing
to note is the use of substitutions within the argument to \fBtitle\fR.
.PP
If both \fBname\fR and \fBname_match\fR are specified, then \fBname\fR is ignored.
.SS "Modules"
.IX Subsection "Modules"
A \fBmodules\fR section contains the parameters that are necessary to load a
metric module. A metric module is a dynamically loadable module that 
extends the available metrics that gmond is able to collect. Each \fBmodules\fR
section contains at least one \fBmodule\fR section.  Within a \fBmodule\fR section
are the directives \fBname\fR, \fBlanguage\fR, \fBenabled\fR, \fBpath\fR and \fBparams\fR.  
The module \fBname\fR is the name of the module as determined by the module 
structure if the module was developed in C/\*(C+.  Alternatively, the 
\&\fBname\fR can be the name of the source file if the module has been 
implemented in a interpreted language such as python.  A \fBlanguage\fR 
designation must be specified as a string value for each module.  The 
\&\fBlanguage\fR directive must correspond to the source code language in 
which the module was implemented (ex. language = \*(L"python\*(R").  If a 
\&\fBlanguage\fR directive does not exist for the module, the assumed 
language will be \*(L"C/\*(C+\*(R". The \fBenabled\fR directive allows a metric module
to be easily enabled or disabled through the configuration file. If the
\&\fBenabled\fR directive is not included in the module configuration, the 
enabled state will default to \*(L"yes\*(R". One thing to note is that if a 
module has been disabled yet the metric which that module implements 
is still listed as part of a collection group, gmond will produce a 
warning message.  However gmond will continue to function normally 
by simply ignoring the metric. The \fBpath\fR is the path from which 
gmond is expected to load the  module (C/\*(C+ compiled dynamically 
loadable module only).  The \fBparams\fR directive can be used to pass 
a single string parameter directly to the module initialization 
function (C/\*(C+ module only). Multiple parameters can be passed to 
the module's initialization function by including one or more 
\&\fBparam\fR sections. Each \fBparam\fR section must be named and contain 
a \fBvalue\fR directive. Once a module has been loaded, the additional 
metrics can be discovered by invoking \fBgmond \-m\fR.
.PP
.Vb 10
\&   modules {
\&     module {
\&       name = "example_module"
\&       language = "C/C++"
\&       enabled = yes
\&       path = "modexample.so"
\&       params = "An extra raw parameter"
\&       param RandomMax {
\&         value = 75
\&       }
\&       param ConstantValue {
\&         value = 25
\&       }
\&     }
\&   }
.Ve
.SS "sFlow"
.IX Subsection "sFlow"
The \fBsflow\fR group is optional and has the following optional
attributes: \fBudp_port\fR, \fBaccept_vm_metrics\fR, \fBaccept_http_metrics\fR,
\&\fBaccept_memcache_metrics\fR, \fBaccept_jvm_metrics\fR,
\&\fBmultiple_http_instances\fR,\fBmultiple_memcache_instances\fR,
\&\fBmultiple_jvm_instances\fR. By default, a
\&\fBudp_recv_channel\fR on port 6343 (the \s-1IANA\s0 registered port for
sFlow) is all that is required to accept and process sFlow
datagrams.  To receive sFlow on some other port requires both
a \fBudp_recv_channel\fR for the other port and a \fBudp_port\fR
setting here. For example:
.PP
.Vb 3
\&   udp_recv_channel {
\&     port = 7343
\&   }
\&
\&   sflow {
\&     udp_port = 7343
\&   }
.Ve
.PP
An sFlow agent running on a hypervisor may also be sending
metrics for its local virtual machines.  By default these
metrics are ignored, but the \fBaccept_vm_metrics\fR flag can
be used to accept those metrics too,  and prefix them with
an identifier for each virtual machine.
.PP
.Vb 3
\&   sflow {
\&     accept_vm_metrics = yes
\&   }
.Ve
.PP
The sFlow feed may also contain metrics sent from \s-1HTTP\s0 or memcached
servers,  or from Java VMs.  Extra options can be used to ignore
or accept these metrics,  and to indicate that there may be multiple
instances per host.  For example:
.PP
.Vb 4
\&    sflow {
\&      accept_http_metrics = yes
\&      multiple_http_instances = yes
\&    }
.Ve
.PP
will allow the \s-1HTTP\s0 metrics, and also mark them with a distinguishing
identifier so that each instance can be trended separately.  (If multiple
instances are reporting and this flag is not set,  the results are likely
to be garbled.)
.SS "Include"
.IX Subsection "Include"
This directive allows the user to include additional configuration files
rather than having to add all gmond configuration directives to the
gmond.conf file.  The following example includes any file with the extension
of .conf contained in the directory conf.d as if the contents of the included 
configuration files were part of the original gmond.conf file. This allows 
the user to modularize their configuration file.  One usage example might 
be to load individual metric modules by including module specific .conf files.
.PP
include ('/etc/ganglia/conf.d/*.conf')
.SH "ACCESS CONTROL"
.IX Header "ACCESS CONTROL"
The \fBudp_recv_channel\fR and \fBtcp_accept_channel\fR directives
can contain an Access Control List (\s-1ACL\s0).  This \s-1ACL\s0 allows you to specify
exactly which hosts gmond process data from.
.PP
An example of an \fBacl\fR entry looks like
.PP
.Vb 8
\&  acl {
\&    default = "deny"
\&    access {
\&      ip = 192.168.0.4
\&      mask = 32
\&      action = "allow"
\&    }
\&  }
.Ve
.PP
This \s-1ACL\s0 will by default reject all traffic that is not specifically from
host 192.168.0.4 (the mask size for an IPv4 address is 32, the mask size
for an IPv6 address is 128 to represent a single host).
.PP
Here is another example
.PP
.Vb 10
\&  acl {
\&    default = "allow"
\&    access {
\&      ip = 192.168.0.0
\&      mask = 24
\&      action = "deny"
\&    }
\&    access {
\&      ip = ::ff:1.2.3.0
\&      mask = 120
\&      action = "deny"
\&    }
\&  }
.Ve
.PP
This \s-1ACL\s0 will by default allow all traffic unless it comes from the 
two subnets specified with action = \*(L"deny\*(R".
.SH "EXAMPLE"
.IX Header "EXAMPLE"
The default behavior for a 2.5.x gmond would be specified as...
.PP
.Vb 12
\&  udp_recv_channel {
\&    mcast_join = 239.2.11.71
\&    bind       = 239.2.11.71
\&    port       = 8649
\&  }
\&  udp_send_channel {
\&    mcast_join = 239.2.11.71
\&    port       = 8649
\&  }
\&  tcp_accept_channel {
\&    port       = 8649
\&  }
.Ve
.PP
To see the complete default configuration for gmond simply run:
.PP
.Vb 1
\&  % gmond \-t
.Ve
.PP
gmond will print out its default behavior in a configuration file
and then exit.  Capturing this output to a file can serve as
a useful starting point for creating your own custom configuration.
.PP
.Vb 1
\&  % gmond \-t > custom.conf
.Ve
.PP
edit \fBcustom.conf\fR to taste and then
.PP
.Vb 1
\&  % gmond \-c ./custom.conf
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIgmond\fR\|(1).
.SH "NOTES"
.IX Header "NOTES"
The ganglia web site is at http://ganglia.info/.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2005 The University of California, Berkeley