| Ganglia Monitoring Daemon v3.0.3 Configuration |
gmond.conf - configuration file for ganglia monitoring daemon (gmond)
The gmond.conf file is used to configure the ganglia monitoring daemon (gmond) which is part of the Ganglia Distributed Monitoring System.
All sections and attributes are case-insensitive. For example, name or NAME or Name or NaMe are all equivalent.
Some sections can be included in the configuration file multiple times and some sections are singular. For example, you can have only one cluster section to define the attributes of the cluster being monitored; however, you can have multiple udp_recv_channel sections to allow gmond to receive message on multiple UDP channels.
There should only be one cluster section defined. This section controls how gmond reports the attributes of the cluster that it is part of.
The cluster section has four attributes: name, owner, latlong and url.
For example,
cluster {
name = "Millennium Cluster"
owner = "UC Berkeley CS Dept."
latlong = "N37.37 W122.23"
url = "http://www.millennium.berkeley.edu/";
}
The name attributes specifies the name of the cluster of machines. The owner tag specifies the administrators of the cluster. The pair name/owner should be unique to all clusters in the world.
The latlong attribute is the latitude and longitude GPS coordinates of this cluster on earth. Specified to 1 mile accuracy with two decimal places per axis in decimal.
The url for more information on the cluster. Intended to give purpose, owner, administration, and account details for this cluster.
There directives directly control the XML output of gmond. For example, the cluster configuration example above would translate into the following XML.
<CLUSTER NAME="Millennium Cluster" OWNER="UC Berkeley CS Dept."
LATLONG="N37.37 W122.23" URL="http://www.millennium.berkeley.edu/">
...
</CLUSTER>
NOTE: Currently gmetad cannot process data sources that do not have a cluster tag. This will be remedied in the future.
The host section provides information about the host running this instance of gmond. Currently only the location string attribute is supported. Example:
host {
location = "(1,2,3)"
}
The globals 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 globals section has the following attributes: daemonize, setuid, user, debug_level, mute, deaf, host_dmax, cleanup_threshold, and gexec.
For example,
globals {
daemonize = true
setuid = true
user = nobody
host_dmax = 3600
}
The daemonize attribute is a boolean. When true, gmond will daemonize. When false, gmond will run in the foreground.
The setuid attribute is a boolean. When true, gmond will set its effective UID to the uid of the user specified by the user attribute. When false, gmond will not change its effective user.
The debug_level is an integer value. When set to zero (0), gmond will run normally. A debug_level greater than zero will result in gmond running in the foreground and outputting debugging information. The higher the debug_level the more verbose the output.
The mute attribute is a boolean. When true, gmond will not send data regardless of any other configuration directives.
The deaf attribute is a boolean. When true, gmond will not receive data regardless of any other configuration directives.
The host_dmax value is an integer with units in seconds. When set to zero (0), gmond will never delete a host from its list even when a remote host has stopped responding. If host_dmax is set to a positive number then gmond will flush a host after it has not heard from it for host_dmax seconds. By the way, dmax means ``delete max''.
The cleanup_threshold is the minimum about of time before gmond will cleanup and hosts or metrics where tn > dmax a.k.a. expired data.
The gexec boolean allows you to specify whether gmond will announce the hosts availability to run gexec jobs. Note: this requires the gexecd is running on the host and the proper keys have been installed.
You can define as many udp_send_channel sections as you like within the limitations of memory and file descriptors. If gmond is configured as mute this section will be ignored.
The udp_send_channel has a total of five attributes: mcast_join, mcast_if, host, port and ttl.
For example, the 2.5.x version gmond would send on the following single channel by default...
udp_send_channel {
mcast_join = 239.2.11.71
port = 8649
}
The mcast_join and mcast_if attributes are optional. When specified gmond will create the UDP socket and join the mcast_join multicast group and send data out the interface specified by mcast_if.
If only a host and port are specified then gmond will send unicast UDP messages to the hosts specified. You could specify multiple unicast hosts for redundancy as gmond will send UDP messages to all UDP channels.
For example...
udp_send_channel {
host = host.foo.com
port = 2389
}
udp_send_channel {
host = 192.168.3.4
port = 2344
}
would configure gmond to send messages to two hosts. The host specification can be an IPv4/IPv6 address or a resolvable hostname.
You can specify as many udp_recv_channel sections as you like within the limits of memory and file descriptors. If gmond is configured deaf this attribute will be ignored.
The udp_recv_channel section has following attributes: mcast_join, bind, port, mcast_if, family. The udp_recv_channel can also have an acl definition (see ACCESS CONTROL LISTS below).
For example, the 2.5.x gmond ran with a single udp receive channel...
udp_recv_channel {
mcast_join = 239.2.11.71
bind = 239.2.11.71
port = 8649
}
The mcast_join and mcast_if should only be used if you want to have this UDP channel receive multicast packets the multicast group mcast_join on interface mcast_if. If you do not specify multicast attributes then gmond will simply create a UDP server on the specified port.
You can use the bind attribute to bind to a particular local address.
The family address is set to inet4 by default. If you want to bind the port to an inet6 port, you need to specify that in the family attribute. Ganglia will not allow IPV6=>IPV4 mapping (for portability and security reasons). If you want to listen on both inet4 and inet6 for a particular port, explicitly state it with the following:
udp_recv_channel {
port = 8666
family = inet4
}
udp_recv_channel {
port = 8666
family = inet6
}
If you specify a bind address, the family of that address takes precedence. f your IPv6 stack doesn't support IPV6_V6ONLY, a warning will be issued but gmond will continue working (this should rarely happen).
Multicast Note: for multicast, specifying a bind address that equals the mcast_join address will prevent unicast UDP messages to the same port from being processed.
You can specify as many tcp_accept_channel sections as you like within the limitations of memory and file descriptors. If gmond is configured to be mute, then these sections are ignored.
The tcp_accept_channel has the following attributes: bind, port, interface, family and timeout. A tcp_accept_channel may also have an acl section specified (see ACCESS CONTROL LISTS below).
For example, 2.5.x gmond would accept connections on a single TCP channel.
tcp_accept_channel {
port = 8649
}
The bind address is optional and allows you to specify which local address gmond will bind to for this channel.
The port is an integer than specifies which port to answer requests for data.
The family address is set to inet4 by default. If you want to bind the port to an inet6 port, you need to specify that in the family attribute. Ganglia will not allow IPV6=>IPV4 mapping (for portability and security reasons). If you want to listen on both inet4 and inet6 for a particular port, explicitly state it with the following:
tcp_accept_channel {
port = 8666
family = inet4
}
tcp_accept_channel {
port = 8666
family = inet6
}
If you specify a bind address, the family of that address takes precedence. If your IPv6 stack doesn't support IPV6_V6ONLY, a warning will be issued but gmond will continue working (this should rarely happen).
The timeout attribute allows you to specify how many microseconds to block before closing a connection to a client. The default is set to 1 second (1000000 usecs). If you have a very slow connection you may need to increase this value.
The interface is not implemented at this time (use bind).
You can specify as many collection_group section as you like within the limitations of memory. A collection_group has the following attributes: collect_once, collect_every and time_threshold. A collection_group must also contain one or more metric sections.
The metric section has the following attributes: name and value_threshold. For a list of available metric names, run the following command:
% gmond -m
Here is an example of a collection group for a static metric...
collection_group {
collect_once = yes
time_threshold = 1800
metric {
name = "cpu_num"
}
}
This collection_group entry would cause gmond to collect the cpu_num metric once at startup (since the number of CPUs will not change between reboots). The metric cpu_num would be send every 1/2 hour (1800 seconds). The default value for the time_threshold is 3600 seconds if no time_threshold is specified.
The time_threshold is the maximum amount of time that can pass before gmond sends all metrics specified in the collection_group to all listed udp_send_channels. A metric may be sent before this time_threshold is met if during collection the value surpasses the value_threshold (explained below).
Here is an example of a collection group for a volatile metric...
collection_group {
collect_every = 60
time_threshold = 300
metric {
name = "cpu_user"
value_threshold = 5.0
}
metric {
name = "cpu_idle"
value_threshold = 10.0
}
}
This collection group would collect the cpu_user and cpu_idle metrics every 60 seconds (specified in collect_every). If cpu_user varies by 5.0% or cpu_idle varies by 10.0%, then the entire collection_group is sent. If no value_threshold is triggered within time_threshold seconds (in this case 300), the entire collection_group is sent.
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 current value is greater than the value_threshold, the entire collection group is send to the udp_send_channels defined.
It's important to note that all metrics in a collection group are sent even when only a single value_threshold is surpassed.
Useful if you want to include another configuration file; for example:
include("globals.conf")
udp_send_channel {
mcast_join = 239.2.11.71
port = 8649
}
The udp_recv_channel and tcp_accept_channel directives can contain an Access Control List (ACL). This ACL allows you to specify exactly which hosts gmond process data from.
An example of an acl entry looks like
acl {
default = "deny"
access {
ip = 192.168.0.4
mask = 32
action = "allow"
}
}
This ACL 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).
Here is another example
acl {
default = "allow"
access {
ip = 192.168.0.0
mask = 24
action = "deny"
}
access {
ip = ::ff:1.2.3.0
mask = 120
action = "deny"
}
}
This ACL will by default allow all traffic unless it comes from the two subnets specified with action = ``deny''.
The default behavior for a 2.5.x gmond would be specified as...
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
}
To see the complete default configuration for gmond simply run:
% gmond -t
gmond will print out it 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.
% gmond -t > custom.conf
edit custom.conf to taste and then
% gmond -c ./custom.conf
The ganglia web site is at http://ganglia.info/.
Copyright (c) 2005 The University of California, Berkeley
| Ganglia Monitoring Daemon v3.0.3 Configuration |