Install SNMP with Docker

Configure the BigPanda agent to send monitoring alerts from SNMP.

The BigPanda agent is a low-footprint utility installed on the master host of your monitoring tool. It consumes alerts from the tool in real-time and then transmits them to BigPanda via TLS-encrypted HTTP calls.

❗️

Python Compatibility

To use the Open Integration Manager for Agent-based integrations, Python version>= 3.8.0 and an Agent version >= 10.2 are required.

Prerequisites

Docker Desktop or Docker Engine must be installed prior to installing the BigPanda agent docker image.

  1. Follow the Docker Installation Guide for your system.

  2. If using Docker Compose, follow the Install Docker Compose guide to ensure the latest version of compose is installed on your system.

    • Docker Compose is built with the latest version of Docker Desktop.
    • If using Docker CLI, ensure Docker CLI's Compose Plugin is installed separately.

Note: If you have issues running any of the docker commands, you either need to run docker with sudo, or add your user to run in the docker group as a non-root user. 

Environment Variables

The docker image provides the following environment variables, which can be used to initialize the agent with the appropriate plugin.

  • BP_TOKEN: Initializes the BigPanda Agent Bearer Token
  • SNMP_APP_KEY: Initializes the BigPanda Agent Bearer Token
  • HTTP_PROXY: Adds the proxy settings to bigpanda.conf
  • FORCE_APP_KEY: Set to true to override the existing plugin app key
  • NAGIOS_APP_KEY: Sets the Nagios App Key and configures the plugin
  • NAGIOS_USER: Sets the Nagios Username and is required to set up Nagios plugin
  • ZABBIX_APP_KEY: Sets the Zabbix App Key and configures the plugin
  • ZENNOSS_APP_KEY: Sets the Zenoss App Key and configures the plugin
  • ICINGA_APP_KEY: Sets the Icinga App Key and configures the plugin

Pull the BigPanda docker image

  1. Pull the latest BigPanda agent docker image from the BigPanda JFrog Docker Registry:

     docker pull bigpandaio-int-docker.jfrog.io/bigpanda-agent:latest
    
    
  2. Check that the latest image was downloaded successfully:

     docker image ls
    
    

Optional:

You can configure a dedicated docker network for the agent. This is useful if you require the agent to communicate with other docker services.

  1. Create the docker network:

     docker network create <network-name>
    
    
  2. Check that the network was created:

     docker network ls
    

Configure the BigPanda SNMP Agent

If any MIBs are not included by default, they need to be compiled and added manually.

  1. Create a temp container and copy the compile_mib.sh script to the host machine:

    docker create --name tmp-agent bigpandaio-int-docker.jfrog.io/bigpanda-agent:latest
    docker cp tmp-agent:/opt/bigpanda/bigpanda-snmpd/mib_compiler/compile_mib.sh .
    
    
  2. Copy the /etc/bigpanda/snmpd directory to the host for SNMP configuration:

    sudo docker cp tmp-agent:/etc/bigpanda/snmpd /etc/bigpanda/snmpd
    
  3. Optional: You can remove the tmp container created in the previous step:

    docker container rm tmp-agent
    
  4. Run the MIB compiler and output the compiled MIBs to the snmpd/mibs/ directory:

    ./compile_mib.sh --input-directory <path to MIBs> --output-directory /etc/bigpanda/snmpd/conf/
    
  5. Modify Config Files

    For MIBs that are to be monitored, their respective Event Configuration files must be added to the bigpanda-snmpd configuration file:

    Edit /etc/bigpanda/snmpd/snmp-daemon.json, and add the paths to the event_config files to the processing.event-configs array.

    For example:

     sudo vim /etc/bigpanda/snmpd/snmp-daemon.json
    
     ...
    
     {
       <snip>
       "processing": {
         "mibs-dir": "/etc/bigpanda/snmpd/mibs",
         "event-configs": [
           event_configs/example.json,
           <ADD EVENT CONFIGS HERE>
         ],
         "target-dir": "/var/lib/bigpanda/queue",
         "stress_test": false
       }
       </snip>
     }
    

Configure a docker container to work with the SNMPD agent

  1. Run the container in detached mode, passing both BP_TOKEN and SNMP_APP_KEY environment variables to docker run.

     docker run -dit \
     --name bp_agent \
     -p 5000:5000/udp \
     -e BP_TOKEN=<Your Org Bearer Token> \
     -e SNMP_APP_KEY=<Your App Key> \
     -v agent-configs:/etc/bigpanda \
     -v agent-queues:/var/lib/bigpanda \
     bigpandaio-int-docker.jfrog.io/bigpanda-agent:latest
    
  2. View the logs of the running docker container:

    docker container logs -f bp_agent
    

Optional - Docker Compose

Services can be managed via Docker Compose, which requires either the Docker Compose Plugin or the latest Docker Desktop installed.

  1. Create a file called docker-compose.yml:

    vim docker-compose.yml
    
  2. Add the BigPanda agent service configuration to docker-compose.yml:

     version: '3.9'
     services:
       bp_agent:
         image: bigpandaio-int-docker.jfrog.io/bigpanda-agent:latest
         container_name: bp_agent
         restart: always
         ports:
           - 5000:5000/udp
         environment:
           - BP_TOKEN=<Your Org Bearer Token>
           - SNMP_APP_KEY=<Your App Key>
         volumes:
           - agent-configs:/etc/bigpanda
           - agent-queues:/var/lib/bigpanda
         networks:
           - bigpanda
       volumes:
         agent-configs:
         agent-queues:
     networks:
       bigpanda:
    
    

    Note: Port binding should match the port configured in /etc/bigpanda/snmpd/snmp-daemon.json

    It’s important to note that the following commands are based on having Docker Engine 19+ installed, or Docker Desktop installed which has Docker Compose support. If the docker-compose plugin is installed separately, then the command will start with docker-compose vs docker compose.

  3. Bring up the agent container:

    docker compose up -d
    

    -d is used to run the container in detached mode.

  4. View the logs of the running docker container

    docker compose logs -f
    
  5. You can bring down the container with the down command:

    docker compose down
    

Test the Integration

  1. Install SNMP Utils (Debian/Ubuntu):

    sudo apt install -y snmp
    
  2. Send the test SNMP v2 trap:

    sudo snmptrap -v 2c -c public 127.0.0.1:5000 1 1.3.6.1.2.1.1 1.3.6.1.2.1.1.5 s "production-switch-1" 1.3.6.1.2.1.1.1 s "SNMP trap test"
    

    Note: Since it is a test message, it won’t be resolved automatically. Click Resolve incident in the BigPanda UI to manually resolve it.

  3. Set up the config file to receive SNMP v3 traps:

    Note: Network discovery must be performed to capture the engine id and user details prior to testing SNMP v3.

    Add the security object to the snmp config file: /etc/bigpanda/snmpd/snmp-daemon.json

          "security": {
              "local_engine_id": "8000000001020304",
              "users": [
              {
                  "username": "panda",
                  "level": "authPriv",
                  "auth_protocol": "usmHMACSHAAuthProtocol",
                  "privacy_protocol": "usmAesCfb128Protocol",
                  "auth_key": "snmpauthpass123",
                  "privacy_key": "snmpkeypass123",
                  "engine_id": "8000000008675309"
              },
              {
                  "username": "new-panda",
                  "level": "authPriv",
                  "auth_protocol": "usmHMACSHAAuthProtocol",
                  "privacy_protocol": "usmAesCfb128Protocol",
                  "auth_key": "snmpauthpass123",
                  "privacy_key": "snmpkeypass123",
                  "engine_id": "8000000008888888"
              }
            ]
          },
    

    Note: local_engine_id is the local client’s engine id, and can be ommitted. This engine id is generated in memory if not provided.

  4. Restart the docker container to pull in the new configuration:

    • Containers started with docker run:
      docker container restart bp_agent
      
    • Containers managed with Docker Compose:
      docker compose restart
      
    • Send an SNMP v3 test trap:
      sudo snmptrap -v3 -e 0x8000000008675309 -u panda -l authPriv -a SHA -A snmpauthpass123 -x AES -X snmpkeypass123 127.0.0.1:5000 "" 1.3.6.1.2.1.1 1.3.6.1.2.1.1.5 s "production-switch-v3" 1.3.6.1.2.1.1.1 s "SNMP v3 trap test"