DocsAPI ReferenceRelease Notes
Docs
BigPanda AppRequest DemoBigPanda UniversityBigPanda Community

Install Icinga with Docker

Configure the BigPanda agent to send monitoring alerts from Icinga.

Suggest Edits

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 Icinga

Open the main Icinga configuration file (usually /usr/local/icinga/etc/icinga.cfg or /etc/icinga/icinga.cfg):

$ sudo vim /usr/local/icinga/etc/icinga.cfg
  • Set log_rotation_method to d (= daily log rotation)
  • Make sure log_archive_path is configured (= location of old logs)
  • Test that Icinga (usually nagios user) has write permissions to the log_archive_path folder

Reload the Icinga service for the changes to take effect.

sudo service icinga restart

Configure a docker container to work with Icinga

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

     docker run -dit \
 --name bp_agent \
 -e BP_TOKEN=<Your Org Bearer Token> \
 -e ICINGA_APP_KEY=<Your App Key> \
 -v /var/log/icinga/icinga.log:/var/log/icinga/icinga.log \
 -v /var/cache/icinga/status.dat:/var/cache/icinga/status.dat \
 -v /var/cache/icinga/objects.cache:/var/cache/icinga/objects.cache \
 bigpandaio-int-docker.jfrog.io/bigpanda-agent:latest

    Ensure the paths mounted coincide with the locations of LOGFILE.log, status.dat and objects.cache files.

  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>
       - _APP_KEY=<Your App Key>
     volumes:
       - /var/log/icinga/icinga.log:/var/log/icinga/incinga.log
       - /var/cache/icinga/status.dat:/var/cache/icinga/status.dat
       - /var/cache/icinga/objects.cache:/var/cache/icinga/objects.cache
     networks:
       - bigpanda

 networks:
   bigpanda:
     external: true

    Note: Ensure the paths mounted coincide with the locations of LOGFILE.log, status.dat and objects.cache files.

    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

Configure the Icinga plugin

The Icinga plugin requires configuration, which means that we need an interactive session to set it up. The problem when running a docker container in detached mode is the entrypoint script is running the shell session in the background. For this, we can attach to the running session to complete the configuration.

  1. Attach to the shell session to continue setting up Icinga

    docker attach --detach-keys="ctrl-q" agent

    Since ctrl-c will send a kill signal to the shell, stopping the container, --detach-keys passes an alternate key sequence.

  2. When prompted, specify the locations of LOGFILE.log, status.dat and objects.cache files.

    The script output should look like this:

     Log File Path: /var/log/SOURCE_SYSTEM_FOLDER/LOGFILE.log
 Status Dat Path: /var/cache/SOURCE_SYSTEM_FOLDER/status.dat
 Objects Cache Path: /var/cache/SOURCE_SYSTEM_FOLDER/objects.cache

    Of course, the actual paths will depend on your installation.

Update Permissions

  1. Give the agent read permissions to the objects.cache, status.dat and log files. A possible way to do it:

     docker exec -it bp_agent usermod -aG "<GROUP OF OBJECT CACHE FILE>,<GROUP OF LOG FILE>,<GROUP OF STATUS DAT FILE>" bigpanda

Test the Integration

  1. Run the following command inside the container:

    docker exec -it bp_agent /usr/bin/bigpanda-notification --send-test
    • docker exec executes a command inside a container.
    • A test alert should arrive in a few moments.

  2. In BigPanda, click the Incidents tab at the top of the screen.

  3. Confirm that the test alert was received.

  4. Since it's a test alert, it won't be resolved automatically. Click Resolve incident to manually resolve it.

Success

The next time Icinga sends a notification for an alert, you will see the alert in the Incident Dashboard.

Updated about 1 month ago