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.
Install the management software
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:
$ # On Debian/Ubuntu $ sudo apt update $ sudo apt install snmp $ # On RedHat $ sudo 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:# 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:mibdirs /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:deb https://deb.debian.org/debian bullseye main non-free
-
Add the MIB files by installing the
snmp-mibs-downloader
package:$ sudo apt update $ sudo apt install snmp-mibs-downloader
-
Install the agent software
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:
$ # On Debian/Ubuntu $ sudo apt update $ sudo apt install snmpd $ # On RedHat $ sudo yum install net-snmp
-
Enable the agent service:
$ sudo systemctl enable snmpd
-
Stop the agent service:
$ sudo systemctl stop snmpd
Edit the agent configuration file,
/etc/snmp/snmpd.conf
, and make the following changes:
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
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
:$ sudo cp /etc/snmp/snmpd.conf /etc/snmp/snmpd.conf.original
Open the agent configuration file for editing.
-
Locate the community definitions. Create a view and community for reading both system information and HAProxy information.
view haproxyview included .1.3.6.1.2.1.1 view haproxyview included .1.3.6.1.2.1.25.1 view haproxyview included .1.3.6.1.4.1.23263.4.3 rocommunity haproxy default -V haproxyview rocommunity6 haproxy default -V haproxyview
Optional: Add any other view and community definitions required to provide the desired access.
-
Add the following
pass_persist
line to the end of the agent configuration file. It configures the SNMP agent service to pass requests through to the HAProxy Enterprise SNMP module:pass_persist .1.3.6.1.4.1.23263.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
.# 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:
$ sudo systemctl start snmpd
-
Use
snmpwalk
to verify that you can make requests to the agent.Request a metric:
$ snmpwalk -c public -v2c 127.0.0.1 sysUpTime.0
DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (15234) 0:02:32.34
Access information about HAProxy Enterprise:
$ snmpwalk -c haproxy -v2c 127.0.0.1 .1.3.6.1.4.1.23263.4.3
SNMPv2-SMI::enterprises.23263.4.3.1.3.1.1.1.1 = INTEGER: 1 SNMPv2-SMI::enterprises.23263.4.3.1.3.1.1.2.1 = STRING: "2.5.0-1.0.0-302.939" SNMPv2-SMI::enterprises.23263.4.3.1.3.1.1.3.1 = STRING: "2023/10/04" SNMPv2-SMI::enterprises.23263.4.3.1.3.1.1.4.1 = INTEGER: 1 SNMPv2-SMI::enterprises.23263.4.3.1.3.1.1.5.1 = STRING: "hapee-lb"
Configure SNMPv3 access
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
:$ sudo 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.createUser initial SHA setup_passphrase AES setup_passphrase rwuser initial
Add another
rwuser
line to prepare a second user account with read-write access. Below, we define permissions for a user namedmyuser
:
rwuser myuser
Add the following
pass_persist
line to the end of the file. It configures the SNMP agent service to pass requests through to the HAProxy Enterprise SNMP module:
pass_persist .1.3.6.1.4.1.23263.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
.
# 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:
$ sudo 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
:$ snmpusm -v3 -n "" -u initial -a SHA -A setup_passphrase -x AES -X setup_passphrase -l authPriv 127.0.0.1 create myuser initial
User 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.$ snmpusm -v3 -n "" -u myuser -a SHA -A setup_passphrase -x AES -X setup_passphrase -l authPriv 127.0.0.1 passwd setup_passphrase mypassword
SNMPv3 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:$ snmpget -v3 -n "" -u myuser -a SHA -A mypassword -x AES -X mypassword -l authPriv 127.0.0.1 sysUpTime.0
DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (34926) 0:05:49.26
Install the HAProxy Enterprise SNMP module
-
Install the HAProxy Enterprise SNMP module:
$ # On Debian/Ubuntu $ sudo apt-get install hapee-extras-snmp-lb
$ # On CentOS/RedHat/Oracle/Photon OS $ sudo yum install hapee-extras-snmp-lb
$ # On SUSE $ sudo zypper install hapee-extras-snmp-lb
$ # On FreeBSD $ sudo 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:global stats socket
/var/run/hapee-extras/hapee-lb.sockuser 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.frontend www id 1 backend webservers id 10 backend dbservers id 20
-
Restart the HAProxy Enterprise service:
$ sudo systemctl restart hapee-2.5-lb
-
To verify that requests for load balancer metrics get passed to the module, use the
snmpwalk
command to return some data. The nameEXCELIANCE
refers to a company acquired by HAProxy Technologies.-
Verify on SNMPv2c using the community created earlier:
$ snmpwalk -v2c -c haproxy 127.0.0.1 EXCELIANCE-MIB::lbStats
-
Verify on SNMPv3 using the user created earlier:
$ # On RedHat $ snmpwalk -v3 -u myuser -a SHA -A mypassword -x AES -X mypassword -l authPriv -M /usr/share/snmp/mibs:/opt/hapee-extras/misc -m EXCELIANCE-MIB 127.0.0.1 EXCELIANCE-MIB::lbStats
Note that
EXCELIANCE
is the company acquired by HAProxy Technologies.EXCELIANCE-MIB::lbProcessID.1 = INTEGER: 1 EXCELIANCE-MIB::lbProcessVersion.1 = STRING: "2.7.0-1.0.0-301.904" EXCELIANCE-MIB::lbProcessReleaseDate.1 = STRING: "2023/09/07" EXCELIANCE-MIB::lbProcessNbProc.1 = INTEGER: 1 EXCELIANCE-MIB::lbProcessProductName.1 = STRING: "hapee-lb" EXCELIANCE-MIB::lbProcessSystemPID.1 = INTEGER: 9494 EXCELIANCE-MIB::lbProcessUptime.1 = STRING: "0d 0h21m29s"
-
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
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
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 name of the MIB is
EXCELIANCE-MIB
, from the company Exceliance that HAProxy Technologies acquired.$ # On Debian/Ubuntu $ snmptranslate -Pu -Tz -m EXCELIANCE-MIB $ # On RedHat $ snmptranslate -Pu -Tz -M /usr/share/snmp/mibs:/opt/hapee-extras/misc -m EXCELIANCE-MIB
"hapee" "1.3.6.1.4.1.23263.4.3" "lbcompat1" "1.3.6.1.4.1.23263.4.3.1" "lbProductInfo" "1.3.6.1.4.1.23263.4.3.1.1" "lbStats" "1.3.6.1.4.1.23263.4.3.1.3" "lbProcessTable" "1.3.6.1.4.1.23263.4.3.1.3.1" "lbProcessTableEntry" "1.3.6.1.4.1.23263.4.3.1.3.1.1" "lbProcessID" "1.3.6.1.4.1.23263.4.3.1.3.1.1.1"
-
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:$ sudo systemctl stop snmpd $ sudo snmpd -f -Lo -Ducd-snmp/pass
After invoking
snmpget
orsnmpwalk
, the debugger should show output like the following:getnext .1.3.6.1.4.1.23263.4.3.1.3.4.1.27.1.5.3 Connection from UDP: [127.0.0.1]:52720->[127.0.0.1]:161 ucd-snmp/pass_persist: open_persist_pipe(1,'/opt/hapee-extras/bin/hapee-snmp-lb') recurse=0 ucd-snmp/pass_persist: persistpass-sending:
When 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:$ sudo systemctl restart hapee-2.7-lb $ sudo apt install socat $ sudo mv /var/run/hapee-extras/hapee-lb.sock /var/run/hapee-extras/hapee-lb.original $ sudo 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.original
> 2023/09/21 21:30:29.555027 length=10 from=0 to=9 73 68 6f 77 20 69 6e 66 6f 0a show info. -- < 2023/09/21 21:30:29.583831 length=1158 from=0 to=1157 4e 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 37 2e 30 2d 31 Version: 2.7.0-1 2e 30 2e 30 2d 33 30 31 2e 39 30 34 0a .0.0-301.904. 52 65 6c 65 61 73 65 5f 64 61 74 65 3a 20 32 30 Release_date: 20 32 33 2f 30 39 2f 30 37 0a 23/09/07. 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 39 36 32 37 0a Pid: 9627. 55 70 74 69 6d 65 3a 20 30 64 20 30 68 30 30 6d Uptime: 0d 0h00m 32 32 73 0a 22s.
When finished, restart the HAProxy Enterprise service to restore the original socket.
Next up
Monitoring