Enterprise modules

SNMP

On this page

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.

  1. Install the SNMP management software package:

    nix
    sudo apt update
    sudo apt install snmp
    nix
    sudo apt update
    sudo apt install snmp
    nix
    sudo yum install net-snmp-utils
    nix
    sudo yum install net-snmp-utils

  2. 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 the mibs line so that it looks like this:

      snmp.conf
      text
      # mibs :
      snmp.conf
      text
      # mibs :

    • Append the path to the HAProxy Enterprise MIB directory, /opt/hapee-extras/misc, to the end of the mibdirs line, and uncomment it if it is commented out:

      snmp.conf
      text
      mibdirs /usr/share/snmp/mibs:/usr/share/snmp/mibs/iana:/usr/share/snmp/mibs/ietf:/opt/hapee-extras/misc
      snmp.conf
      text
      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 the snmp-mibs-downloader package:

      sources.list
      text
      deb https://deb.debian.org/debian bullseye main non-free
      sources.list
      text
      deb https://deb.debian.org/debian bullseye main non-free

    • Add the MIB files by installing the snmp-mibs-downloader package:

      nix
      sudo apt update
      sudo apt install snmp-mibs-downloader
      nix
      sudo apt update
      sudo 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.

  1. Install the SNMP agent software package:

    nix
    sudo apt update
    sudo apt install snmpd
    nix
    sudo apt update
    sudo apt install snmpd
    nix
    sudo yum install net-snmp
    nix
    sudo yum install net-snmp

  2. Enable the agent service:

    nix
    sudo systemctl enable snmpd
    nix
    sudo systemctl enable snmpd

  3. Stop the agent service:

    nix
    sudo systemctl stop snmpd
    nix
    sudo systemctl stop snmpd

  4. Edit the agent configuration file, /etc/snmp/snmpd.conf.

    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:

  1. Make a backup of the agent configuration file, /etc/snmp/snmpd.conf:

    nix
    sudo cp /etc/snmp/snmpd.conf /etc/snmp/snmpd.conf.original
    nix
    sudo cp /etc/snmp/snmpd.conf /etc/snmp/snmpd.conf.original

  2. Open the agent configuration file for editing.

  3. Locate the community definitions. Create a view and community for reading both system information and HAProxy information.

    snmpd.conf
    text
    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
    snmpd.conf
    text
    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

  4. Optional: Add any other view and community definitions required to provide the desired access.

  5. 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:

    snmpd.conf
    text
    pass_persist  .1.3.6.1.4.1.23263.4.3.1.3 /opt/hapee-extras/bin/hapee-snmp-lb
    snmpd.conf
    text
    pass_persist  .1.3.6.1.4.1.23263.4.3.1.3 /opt/hapee-extras/bin/hapee-snmp-lb

  6. On Debian and Ubuntu, to have the agent service listen on all interfaces instead of 127.0.0.1, comment out the line agentAddress udp:127.0.0.1:161 if it exists and add the line agentAddress udp:161,udp6:[::1]:161.

    snmpd.conf
    text
    # 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
    snmpd.conf
    text
    # 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

  7. Save and close the agent configuration file.

  8. Start the agent service:

    nix
    sudo systemctl start snmpd
    nix
    sudo systemctl start snmpd

  9. Use snmpwalk to verify that you can make requests to the agent.

    Request a metric:

    nix
    snmpwalk -c public -v2c 127.0.0.1 sysUpTime.0
    nix
    snmpwalk -c public -v2c 127.0.0.1 sysUpTime.0
    output
    text
    DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (15234) 0:02:32.34
    output
    text
    DISMAN-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:

  1. Make a backup of the agent configuration file, /etc/snmp/snmpd.conf:

    nix
    sudo cp /etc/snmp/snmpd.conf /etc/snmp/snmpd.conf.original
    nix
    sudo cp /etc/snmp/snmpd.conf /etc/snmp/snmpd.conf.original

  2. Open the agent configuration file for editing.

  3. Add the following createUser and rwuser 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.conf
    text
    createUser initial SHA setup_passphrase AES setup_passphrase
    rwuser initial
    snmpd.conf
    text
    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 named myuser:

    snmpd.conf
    text
    rwuser myuser
    snmpd.conf
    text
    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:

    snmpd.conf
    text
    pass_persist  .1.3.6.1.4.1.23263.4.3.1.3 /opt/hapee-extras/bin/hapee-snmp-lb
    snmpd.conf
    text
    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 line agentAddress udp:127.0.0.1:161 if it exists and add the line agentAddress udp:161,udp6:[::1]:161.

    snmpd.conf
    text
    # 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
    snmpd.conf
    text
    # 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

  4. Start the agent service:

    nix
    sudo systemctl start snmpd
    nix
    sudo systemctl start snmpd

  5. 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 the initial user account. Below, we create a user named myuser:

    nix
    snmpusm -v3 -n "" -u initial -a SHA -A setup_passphrase -x AES -X setup_passphrase -l authPriv 127.0.0.1 create myuser initial
    nix
    snmpusm -v3 -n "" -u initial -a SHA -A setup_passphrase -x AES -X setup_passphrase -l authPriv 127.0.0.1 create myuser initial
    output
    text
    User successfully created.
    output
    text
    User successfully created.

  6. The new user account inherited the passphrase from the initial user account. Use the snmpusm command again to change the user’s passphrase. Below, we change the myuser user account’s passphrase to mypassword. In a production environment, be sure to use a strong password.

    nix
    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
    nix
    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
    output
    text
    SNMPv3 Key(s) successfully changed.
    output
    text
    SNMPv3 Key(s) successfully changed.

  7. 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:

    nix
    snmpget -v3 -n "" -u myuser -a SHA -A mypassword -x AES -X mypassword -l authPriv 127.0.0.1 sysUpTime.0
    nix
    snmpget -v3 -n "" -u myuser -a SHA -A mypassword -x AES -X mypassword -l authPriv 127.0.0.1 sysUpTime.0
    output
    text
    DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (34926) 0:05:49.26
    output
    text
    DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (34926) 0:05:49.26

Install the HAProxy Enterprise SNMP module Jump to heading

  1. Install the HAProxy Enterprise SNMP module:

    nix
    sudo apt-get install hapee-extras-snmp-lb
    nix
    sudo apt-get install hapee-extras-snmp-lb
    nix
    sudo yum install hapee-extras-snmp-lb
    nix
    sudo yum install hapee-extras-snmp-lb
    nix
    sudo zypper install hapee-extras-snmp-lb
    nix
    sudo zypper install hapee-extras-snmp-lb
    nix
    sudo pkg install hapee-extras-snmp-lb
    nix
    sudo pkg install hapee-extras-snmp-lb

  2. In the global section of your load balancer configuration, add a stats 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 a stats socket line that’s different from this. You can add a second stats socket line to support this feature:

    haproxy
    global
      stats socket /var/run/hapee-extras/hapee-lb.sock user hapee-lb group hapee mode 660 level user
    haproxy
    global
      stats socket /var/run/hapee-extras/hapee-lb.sock user hapee-lb group hapee mode 660 level user

    On Debian and Ubuntu, set the group parameter on this line to Debian-snmp instead of hapee. That is the group in which the SNMP service runs.

  3. Optional: Add id directives to your frontend and backend sections. The id 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 one frontend or backend 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.

    haproxy
    frontend www
      id 1
    backend webservers
      id 10
    backend dbservers
      id 20
    haproxy
    frontend www
      id 1
    backend webservers
      id 10
    backend dbservers
      id 20

  4. Restart the HAProxy Enterprise service:

    nix
    sudo systemctl restart hapee-2.8-lb
    nix
    sudo systemctl restart hapee-2.8-lb

  5. To verify that requests for load balancer metrics get passed to the module, use the snmpwalk command to return some data. The name EXCELIANCE refers to a company acquired by HAProxy Technologies.

    • Verify on SNMPv2c using the community created earlier:

      nix
      snmpwalk -v2c -c haproxy 127.0.0.1 EXCELIANCE-MIB::lbStats
      nix
      snmpwalk -v2c -c haproxy 127.0.0.1 EXCELIANCE-MIB::lbStats

    • Verify on SNMPv3 using the user created earlier:

      nix
      # 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
      nix
      # 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.

    output
    text
    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"
    output
    text
    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"

  6. 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:

HAProxy Enterprise SNMP service

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 name of the MIB is EXCELIANCE-MIB, from the company Exceliance that HAProxy Technologies acquired.

    nix
    snmptranslate -Pu -Tz -m EXCELIANCE-MIB
    nix
    snmptranslate -Pu -Tz -m EXCELIANCE-MIB
    nix
    snmptranslate -Pu -Tz -M /usr/share/snmp/mibs:/opt/hapee-extras/misc -m EXCELIANCE-MIB
    nix
    snmptranslate -Pu -Tz -M /usr/share/snmp/mibs:/opt/hapee-extras/misc -m EXCELIANCE-MIB
    output
    text
    "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"
    output
    text
    "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 the pass_persist line in the agent configuration file, use the following commands to run the agent in debug mode:

    nix
    sudo systemctl stop snmpd
    sudo snmpd -f -Lo -Ducd-snmp/pass
    nix
    sudo systemctl stop snmpd
    sudo snmpd -f -Lo -Ducd-snmp/pass

    After invoking snmpget or snmpwalk, the debugger should show output like the following:

    output
    text
    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:
    output
    text
    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 the snmpd 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:

    nix
    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
    nix
    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
    output
    text
    > 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.
    output
    text
    > 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.

Do you have any suggestions on how we can improve the content of this page?

Previous page SAML Next page Traffic mirroring
© 2024 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences