Enterprise modules
SNMP
Simple Network Management Protocol (SNMP) offers a way to collect information about network devices. Having been around for decades, you’ll find it in many different types of devices such as routers, switches, servers, and printers. The HAProxy Enterprise SNMP module enables you to collect metrics from the load balancer. The module provides read access to load balancer statistics.
This guide demonstrates the setup using SNMPv3 and SNMPv2.
Install the management software Jump to heading
The SNMP management software is not, strictly speaking, required, but it does provide tools for creating SNMPv3 user accounts and testing that the setup works by making SNMP queries.
-
Install the SNMP management software package:
nixsudo apt updatesudo apt install snmpnixsudo apt updatesudo apt install snmpnixsudo yum install net-snmp-utilsnixsudo yum install net-snmp-utils -
On Debian and Ubuntu, perform these additional steps:
-
Configure the management software to load Management Information Bases (MIBs) by editing the file
/etc/snmp/snmp.conf
and commenting out themibs
line so that it looks like this:snmp.conftext# mibs :snmp.conftext# mibs : -
Append the path to the HAProxy Enterprise MIB directory,
/opt/hapee-extras/misc
, to the end of themibdirs
line, and uncomment it if it is commented out:snmp.conftextmibdirs /usr/share/snmp/mibs:/usr/share/snmp/mibs/iana:/usr/share/snmp/mibs/ietf:/opt/hapee-extras/miscsnmp.conftextmibdirs /usr/share/snmp/mibs:/usr/share/snmp/mibs/iana:/usr/share/snmp/mibs/ietf:/opt/hapee-extras/misc -
Add the
non-free
repository to the existing line in/etc/apt/sources.list
, which will allow you to install thesnmp-mibs-downloader
package:sources.listtextdeb https://deb.debian.org/debian bullseye main non-freesources.listtextdeb https://deb.debian.org/debian bullseye main non-free -
Add the MIB files by installing the
snmp-mibs-downloader
package:nixsudo apt updatesudo apt install snmp-mibs-downloadernixsudo apt updatesudo apt install snmp-mibs-downloader
-
Install the agent software Jump to heading
An SNMP agent is software that runs on the monitored device, which in this case is the load balancer. It returns metrics when queried by the management software.
-
Install the SNMP agent software package:
nixsudo apt updatesudo apt install snmpdnixsudo apt updatesudo apt install snmpdnixsudo yum install net-snmpnixsudo yum install net-snmp -
Enable the agent service:
nixsudo systemctl enable snmpdnixsudo systemctl enable snmpd -
Stop the agent service:
nixsudo systemctl stop snmpdnixsudo systemctl stop snmpd -
Configure the agent for the desired version. The agent supports both SNMPv2c and SNMPv3.
- SNMPv3 is recommended because its security model supports encrypted passwords instead of just plain-text community strings like SNMPv2c.
- SNMPv2c, on the other hand, is easier to configure. Configuration procedures for both are provided.
Configure SNMPv2c access Jump to heading
To configure agent access for SNMPv2c, which uses community strings, follow these steps:
-
Make a backup of the agent configuration file,
/etc/snmp/snmpd.conf
:nixsudo cp /etc/snmp/snmpd.conf /etc/snmp/snmpd.conf.originalnixsudo cp /etc/snmp/snmpd.conf /etc/snmp/snmpd.conf.original -
Open the agent configuration file for editing.
-
Locate the view and community definitions. To read both system information and HAProxy Enterprise information, add these definitions.
snmpd.conftext# System + hrSystem groupsview haproxyview included .1.3.6.1.2.1.1view haproxyview included .1.3.6.1.2.1.25.1# HAProxy Enterprise groupsview haproxyview included .1.3.6.1.4.1.23263.4.3view haproxyview included .1.3.6.1.4.1.58750.4.3rocommunity haproxy default -V haproxyviewrocommunity6 haproxy default -V haproxyviewsnmpd.conftext# System + hrSystem groupsview haproxyview included .1.3.6.1.2.1.1view haproxyview included .1.3.6.1.2.1.25.1# HAProxy Enterprise groupsview haproxyview included .1.3.6.1.4.1.23263.4.3view haproxyview included .1.3.6.1.4.1.58750.4.3rocommunity haproxy default -V haproxyviewrocommunity6 haproxy default -V haproxyview -
Optional: Add any other view and community definitions required to provide the desired access.
-
Add the following
pass_persist
lines to the end of the agent configuration file. They configure the SNMP agent service to pass requests through to the HAProxy Enterprise SNMP module:snmpd.conftext# HAPEE-LEGACY.MIBpass_persist .1.3.6.1.4.1.23263.4.3.1.3 /opt/hapee-extras/bin/hapee-snmp-lb# HAPEE.MIBpass_persist .1.3.6.1.4.1.58750.4.3.1.3 /opt/hapee-extras/bin/hapee-snmp-lbsnmpd.conftext# HAPEE-LEGACY.MIBpass_persist .1.3.6.1.4.1.23263.4.3.1.3 /opt/hapee-extras/bin/hapee-snmp-lb# HAPEE.MIBpass_persist .1.3.6.1.4.1.58750.4.3.1.3 /opt/hapee-extras/bin/hapee-snmp-lb -
On Debian and Ubuntu, to have the agent service listen on all interfaces instead of
127.0.0.1
, comment out the lineagentAddress udp:127.0.0.1:161
if it exists and add the lineagentAddress udp:161,udp6:[::1]:161
.snmpd.conftext# Listen for connections from the local system only# agentAddress udp:127.0.0.1:161# Listen for connections on all interfaces (both IPv4 *and* IPv6)agentAddress udp:161,udp6:[::1]:161snmpd.conftext# Listen for connections from the local system only# agentAddress udp:127.0.0.1:161# Listen for connections on all interfaces (both IPv4 *and* IPv6)agentAddress udp:161,udp6:[::1]:161 -
Save and close the agent configuration file.
-
Start the agent service:
nixsudo systemctl start snmpdnixsudo systemctl start snmpd -
Use
snmpwalk
to verify that you can make requests to the agent.Request a metric:
nixsnmpwalk -c public -v2c 127.0.0.1 sysUpTime.0nixsnmpwalk -c public -v2c 127.0.0.1 sysUpTime.0outputtextDISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (15234) 0:02:32.34outputtextDISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (15234) 0:02:32.34
Configure SNMPv3 access Jump to heading
To configure agent access for SNMPv3, which uses user profiles and encrypted passwords, follow these steps:
-
Make a backup of the agent configuration file,
/etc/snmp/snmpd.conf
:nixsudo cp /etc/snmp/snmpd.conf /etc/snmp/snmpd.conf.originalnixsudo cp /etc/snmp/snmpd.conf /etc/snmp/snmpd.conf.original -
Open the agent configuration file for editing.
-
Add the following
createUser
andrwuser
lines to the end of the file to create an initial user account with read-write access. Note that this applies to SNMPv3 only, since older versions of the protocol do not require user accounts and instead use a community string for authentication. This initial user account will become the template from which we will create other user accounts.snmpd.conftextcreateUser initial SHA setup_passphrase AES setup_passphraserwuser initialsnmpd.conftextcreateUser initial SHA setup_passphrase AES setup_passphraserwuser initialAdd another
rwuser
line to prepare a second user account with read-write access. Below, we define permissions for a user namedmyuser
:snmpd.conftextrwuser myusersnmpd.conftextrwuser myuser -
Locate the view definitions. To read both system information and HAProxy Enterprise information, add the following definitions.
snmpd.conftext# System + hrSystem groupsview haproxyview included .1.3.6.1.2.1.1view haproxyview included .1.3.6.1.2.1.25.1# HAProxy Enterprise groupsview haproxyview included .1.3.6.1.4.1.23263.4.3view haproxyview included .1.3.6.1.4.1.58750.4.3snmpd.conftext# System + hrSystem groupsview haproxyview included .1.3.6.1.2.1.1view haproxyview included .1.3.6.1.2.1.25.1# HAProxy Enterprise groupsview haproxyview included .1.3.6.1.4.1.23263.4.3view haproxyview included .1.3.6.1.4.1.58750.4.3 -
Optional: Add any other view definitions required to provide the desired access.
-
Add the following
pass_persist
lines to the end of the agent configuration file. They configure the SNMP agent service to pass requests through to the HAProxy Enterprise SNMP module:snmpd.conftext# HAPEE-LEGACY.MIBpass_persist .1.3.6.1.4.1.23263.4.3.1.3 /opt/hapee-extras/bin/hapee-snmp-lb# HAPEE.MIBpass_persist .1.3.6.1.4.1.58750.4.3.1.3 /opt/hapee-extras/bin/hapee-snmp-lbsnmpd.conftext# HAPEE-LEGACY.MIBpass_persist .1.3.6.1.4.1.23263.4.3.1.3 /opt/hapee-extras/bin/hapee-snmp-lb# HAPEE.MIBpass_persist .1.3.6.1.4.1.58750.4.3.1.3 /opt/hapee-extras/bin/hapee-snmp-lb -
On Debian and Ubuntu, to have the agent service listen on all interfaces instead of
127.0.0.1
, comment out the lineagentAddress udp:127.0.0.1:161
if it exists and add the lineagentAddress udp:161,udp6:[::1]:161
.snmpd.conftext# Listen for connections from the local system only# agentAddress udp:127.0.0.1:161# Listen for connections on all interfaces (both IPv4 *and* IPv6)agentAddress udp:161,udp6:[::1]:161snmpd.conftext# Listen for connections from the local system only# agentAddress udp:127.0.0.1:161# Listen for connections on all interfaces (both IPv4 *and* IPv6)agentAddress udp:161,udp6:[::1]:161 -
Start the agent service:
nixsudo systemctl start snmpdnixsudo systemctl start snmpd -
Using the
initial
user’s username and passphrase, create a new user account that you’ll use to make SNMP requests. This user will inherit settings from theinitial
user account. Below, we create a user namedmyuser
:nixsnmpusm -v3 -n "" -u initial -a SHA -A setup_passphrase -x AES -X setup_passphrase -l authPriv 127.0.0.1 create myuser initialnixsnmpusm -v3 -n "" -u initial -a SHA -A setup_passphrase -x AES -X setup_passphrase -l authPriv 127.0.0.1 create myuser initialoutputtextUser successfully created.outputtextUser successfully created. -
The new user account inherited the passphrase from the
initial
user account. Use thesnmpusm
command again to change the user’s passphrase. Below, we change themyuser
user account’s passphrase tomypassword
. In a production environment, be sure to use a strong password.nixsnmpusm -v3 -n "" -u myuser -a SHA -A setup_passphrase -x AES -X setup_passphrase -l authPriv 127.0.0.1 passwd setup_passphrase mypasswordnixsnmpusm -v3 -n "" -u myuser -a SHA -A setup_passphrase -x AES -X setup_passphrase -l authPriv 127.0.0.1 passwd setup_passphrase mypasswordoutputtextSNMPv3 Key(s) successfully changed.outputtextSNMPv3 Key(s) successfully changed. -
To verify that the user you created can make requests to the agent software, you can use the management software’s
snmpget
command to fetch some metrics. Try the following:nixsnmpget -v3 -n "" -u myuser -a SHA -A mypassword -x AES -X mypassword -l authPriv 127.0.0.1 sysUpTime.0nixsnmpget -v3 -n "" -u myuser -a SHA -A mypassword -x AES -X mypassword -l authPriv 127.0.0.1 sysUpTime.0outputtextDISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (34926) 0:05:49.26outputtextDISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (34926) 0:05:49.26
Install the HAProxy Enterprise SNMP module Jump to heading
-
Install the HAProxy Enterprise SNMP module:
nixsudo apt-get install hapee-extras-snmp-lbnixsudo apt-get install hapee-extras-snmp-lbnixsudo yum install hapee-extras-snmp-lbnixsudo yum install hapee-extras-snmp-lbnixsudo zypper install hapee-extras-snmp-lbnixsudo zypper install hapee-extras-snmp-lbnixsudo pkg install hapee-extras-snmp-lbnixsudo pkg install hapee-extras-snmp-lb -
In the
global
section of your load balancer configuration, add astats socket
line that points to/var/run/hapee-extras/hapee-lb.sock
. The SNMP module will connect to this socket to retrieve metrics data. Note that your configuration will likely come with astats socket
line that’s different from this. You can add a secondstats socket
line to support this feature:haproxyglobalstats socket /var/run/hapee-extras/hapee-lb.sock user hapee-lb group hapee mode 660 level userhaproxyglobalstats socket /var/run/hapee-extras/hapee-lb.sock user hapee-lb group hapee mode 660 level userOn Debian and Ubuntu, set the
group
parameter on this line toDebian-snmp
instead ofhapee
. That is the group in which the SNMP service runs. -
Optional: Add
id
directives to yourfrontend
andbackend
sections. Theid
directive’s value is an integer that indicates that section’s unique identifier, which will appear in the SNMP output, making it easier to tell onefrontend
orbackend
from another. Otherwise, an ID will be set for you. The IDs for a frontend and backend do not need to relate in any way.haproxyfrontend wwwid 1backend webserversid 10backend dbserversid 20haproxyfrontend wwwid 1backend webserversid 10backend dbserversid 20 -
Restart the HAProxy Enterprise service:
nixsudo systemctl restart hapee-3.0-lbnixsudo systemctl restart hapee-3.0-lb -
To verify that requests for load balancer metrics get passed to the module, use the
snmpwalk
command to return some data.-
Verify on SNMPv2c using the community created earlier:
nixsnmpwalk -v2c -c haproxy 127.0.0.1 HAPROXYTECH-MIB::lbStatsnixsnmpwalk -v2c -c haproxy 127.0.0.1 HAPROXYTECH-MIB::lbStats -
Verify on SNMPv3 using the user created earlier:
nix# On RedHatsnmpwalk -v3 -u myuser -a SHA -A mypassword -x AES -X mypassword -l authPriv -M /usr/share/snmp/mibs:/opt/hapee-extras/misc -m HAPROXYTECH-MIB 127.0.0.1 HAPROXYTECH-MIB::lbStatsnix# On RedHatsnmpwalk -v3 -u myuser -a SHA -A mypassword -x AES -X mypassword -l authPriv -M /usr/share/snmp/mibs:/opt/hapee-extras/misc -m HAPROXYTECH-MIB 127.0.0.1 HAPROXYTECH-MIB::lbStats
output fragmenttextHAPROXYTECH-MIB::lbProcessID.1 = INTEGER: 1HAPROXYTECH-MIB::lbProcessVersion.1 = STRING: "2.9.0-1.0.0-325.332"HAPROXYTECH-MIB::lbProcessReleaseDate.1 = STRING: "2024/05/03"HAPROXYTECH-MIB::lbProcessNbProc.1 = INTEGER: 1HAPROXYTECH-MIB::lbProcessProductName.1 = STRING: "hapee-lb"HAPROXYTECH-MIB::lbProcessSystemPID.1 = INTEGER: 7499HAPROXYTECH-MIB::lbProcessUptime.1 = STRING: "0d 0h06m38s"output fragmenttextHAPROXYTECH-MIB::lbProcessID.1 = INTEGER: 1HAPROXYTECH-MIB::lbProcessVersion.1 = STRING: "2.9.0-1.0.0-325.332"HAPROXYTECH-MIB::lbProcessReleaseDate.1 = STRING: "2024/05/03"HAPROXYTECH-MIB::lbProcessNbProc.1 = INTEGER: 1HAPROXYTECH-MIB::lbProcessProductName.1 = STRING: "hapee-lb"HAPROXYTECH-MIB::lbProcessSystemPID.1 = INTEGER: 7499HAPROXYTECH-MIB::lbProcessUptime.1 = STRING: "0d 0h06m38s" -
-
Configure your SNMP monitoring software to collect metrics from the HAProxy Enterprise server by using the SNMPv3 protocol with the username and passphrase you set.
How it works Jump to heading
The SNMP stack is split into two main components:
- The Operating system SNMP agent service, called
snmpd
. It listens on a network interface on port 161/UDP and handles SNMP requests from clients. - The SNMP module for HAProxy Enterprise, which collects data from the load balancer for
snmpd
.
The diagram below illustrates how the SNMP agent service monitors the system’s network, system disks, and HAProxy Enterprise:
Troubleshooting Jump to heading
You get the error ‘No Such Instance currently exists at this OID’
This error indicates that although the object at the given ID (the metric) was found on this server, no value was returned for it.
-
Try disabling SE Linux, which can interfere with the SNMP service.
-
Check that you are using the right object ID (OID). You can either use the human readable names or the numeric names. The
snmptranslate
command shows you the OIDs that are defined in the MIB file/opt/hapee-extras/misc/HAPEE.mib
.The MIBs are named
HAPROXYTECH-MIB
andHAPROXYTECH_LEGACY-MIB
, formerlyEXCELIANCE-MIB
.nixsnmptranslate -Pu -Tz -m HAPROXYTECH-MIBnixsnmptranslate -Pu -Tz -m HAPROXYTECH-MIBnixsnmptranslate -Pu -Tz -M /usr/share/snmp/mibs:/opt/hapee-extras/misc -m HAPROXYTECH-MIBnixsnmptranslate -Pu -Tz -M /usr/share/snmp/mibs:/opt/hapee-extras/misc -m HAPROXYTECH-MIBoutput fragmenttext"org" "1.3""dod" "1.3.6""internet" "1.3.6.1""directory" "1.3.6.1.1""mgmt" "1.3.6.1.2""mib-2" "1.3.6.1.2.1""transmission" "1.3.6.1.2.1.10""experimental" "1.3.6.1.3""private" "1.3.6.1.4""enterprises" "1.3.6.1.4.1""haproxytech" "1.3.6.1.4.1.58750"output fragmenttext"org" "1.3""dod" "1.3.6""internet" "1.3.6.1""directory" "1.3.6.1.1""mgmt" "1.3.6.1.2""mib-2" "1.3.6.1.2.1""transmission" "1.3.6.1.2.1.10""experimental" "1.3.6.1.3""private" "1.3.6.1.4""enterprises" "1.3.6.1.4.1""haproxytech" "1.3.6.1.4.1.58750" -
Check that the
pass_persist
is working. To debug thepass_persist
line in the agent configuration file, use the following commands to run the agent in debug mode:nixsudo systemctl stop snmpdsudo snmpd -f -Lo -Ducd-snmp/passnixsudo systemctl stop snmpdsudo snmpd -f -Lo -Ducd-snmp/passAfter invoking
snmpget
orsnmpwalk
, the debugger should show output like the following:output fragmenttextConnection from UDP: [127.0.0.1]:56077->[127.0.0.1]:161ucd-snmp/pass_persist: open_persist_pipe(2,'/opt/hapee-extras/bin/hapee-snmp-lb') recurse=0ucd-snmp/pass_persist: open_persist_pipe: opened the pipesucd-snmp/pass_persist: persistpass-sending:getnext.1.3.6.1.4.1.58750.4.3.1.3output fragmenttextConnection from UDP: [127.0.0.1]:56077->[127.0.0.1]:161ucd-snmp/pass_persist: open_persist_pipe(2,'/opt/hapee-extras/bin/hapee-snmp-lb') recurse=0ucd-snmp/pass_persist: open_persist_pipe: opened the pipesucd-snmp/pass_persist: persistpass-sending:getnext.1.3.6.1.4.1.58750.4.3.1.3When finished, stop the
snmpd
command and start thesnmpd
service. -
Check that your
stats socket
line is correct in the load balancer configuration file. It should use/var/run/hapee-extras/hapee-lb.sock
(you will probably need to add this as a new line in your configuration).To verify that requests are passing to the stats socket, you can place a proxy in front of the socket and then monitor the traffic. In the following example, we use
socat
as a proxy. It shows that the socket is being queried and is returning data:nixsudo systemctl restart hapee-3.0-lbsudo apt install socatsudo mv /var/run/hapee-extras/hapee-lb.sock /var/run/hapee-extras/hapee-lb.originalsudo socat -t100 -x -v UNIX-LISTEN:/var/run/hapee-extras/hapee-lb.sock,mode=777,reuseaddr,fork UNIX-CONNECT:/var/run/hapee-extras/hapee-lb.originalnixsudo systemctl restart hapee-3.0-lbsudo apt install socatsudo mv /var/run/hapee-extras/hapee-lb.sock /var/run/hapee-extras/hapee-lb.originalsudo socat -t100 -x -v UNIX-LISTEN:/var/run/hapee-extras/hapee-lb.sock,mode=777,reuseaddr,fork UNIX-CONNECT:/var/run/hapee-extras/hapee-lb.originalIn another shell, use
snmpwalk
to generate traffic.nixsnmpwalk -v2c -c haproxy 127.0.0.1 HAPROXYTECH-MIB::lbStatsnixsnmpwalk -v2c -c haproxy 127.0.0.1 HAPROXYTECH-MIB::lbStatsoutput fragmenttext> 2024/05/21 17:21:20.326295 length=10 from=0 to=973 68 6f 77 20 69 6e 66 6f 0a show info.--< 2024/05/21 17:21:20.333089 length=1228 from=0 to=12274e 61 6d 65 3a 20 68 61 70 65 65 2d 6c 62 0a Name: hapee-lb.56 65 72 73 69 6f 6e 3a 20 32 2e 39 2e 30 2d 31 Version: 2.9.0-12e 30 2e 30 2d 33 32 35 2e 33 33 32 0a .0.0-325.332.52 65 6c 65 61 73 65 5f 64 61 74 65 3a 20 32 30 Release_date: 2032 34 2f 30 35 2f 30 33 0a 24/05/03.4e 62 74 68 72 65 61 64 3a 20 32 0a Nbthread: 2.4e 62 70 72 6f 63 3a 20 31 0a Nbproc: 1.50 72 6f 63 65 73 73 5f 6e 75 6d 3a 20 31 0a Process_num: 1.50 69 64 3a 20 38 31 38 30 0a Pid: 8180.55 70 74 69 6d 65 3a 20 30 64 20 30 68 31 36 6d Uptime: 0d 0h16m34 37 73 0a 47s.output fragmenttext> 2024/05/21 17:21:20.326295 length=10 from=0 to=973 68 6f 77 20 69 6e 66 6f 0a show info.--< 2024/05/21 17:21:20.333089 length=1228 from=0 to=12274e 61 6d 65 3a 20 68 61 70 65 65 2d 6c 62 0a Name: hapee-lb.56 65 72 73 69 6f 6e 3a 20 32 2e 39 2e 30 2d 31 Version: 2.9.0-12e 30 2e 30 2d 33 32 35 2e 33 33 32 0a .0.0-325.332.52 65 6c 65 61 73 65 5f 64 61 74 65 3a 20 32 30 Release_date: 2032 34 2f 30 35 2f 30 33 0a 24/05/03.4e 62 74 68 72 65 61 64 3a 20 32 0a Nbthread: 2.4e 62 70 72 6f 63 3a 20 31 0a Nbproc: 1.50 72 6f 63 65 73 73 5f 6e 75 6d 3a 20 31 0a Process_num: 1.50 69 64 3a 20 38 31 38 30 0a Pid: 8180.55 70 74 69 6d 65 3a 20 30 64 20 30 68 31 36 6d Uptime: 0d 0h16m34 37 73 0a 47s.When finished, restart the HAProxy Enterprise service to restore the original socket.
nixsudo systemctl restart hapee-3.0-lbnixsudo systemctl restart hapee-3.0-lb
Do you have any suggestions on how we can improve the content of this page?