Agent Manual Installation


We recommend installing agent using standard method or Docker method. But if those methods don’t fit your needs, this article explains how to install the Bleemeo agent with standard tools.

Before installing Bleemeo agent, please check that you meet the System Requirements.

Agent Installation

  • Bleemeo agent don’t need to be run as root, so it’s better to create a bleemeo user:

    $ sudo adduser --system bleemeo
  • To avoid mixing manually installed files with your system files, “virtualenv” is used to isolate installed files. Virtualenv is a standard tool available for most platform.

  • Installation needs few system packages: virtualenv, git, python-dev and gcc:

    $ sudo apt-get install python-virtualenv git python3-dev gcc
  • Create the virtualenv, for example using /opt/bleemeo-agent as installation folder:

    $ sudo virtualenv --python /usr/bin/python3 /opt/bleemeo-agent
  • Install Bleemeo agent using “pip”, the standard tool for Python package:

    $ sudo /opt/bleemeo-agent/bin/pip install git+[bleemeo]
  • Create a configuration file in /etc/bleemeo/agent.conf.d/30-install.conf with the following content:

        account_id: <YOUR-ACCOUNT-ID>
        registration_key: <YOUR-REGISTRATION-KEY>
        state_file: /var/lib/bleemeo/state.json
        facts_file: /var/lib/bleemeo/facts.yaml
  • Ensure this file has limited access:

    $ sudo chown bleemeo /etc/bleemeo/agent.conf.d/30-install.conf
    $ sudo chmod 0640 /etc/bleemeo/agent.conf.d/30-install.conf
  • Create a folder for state file, and make sure bleemeo user could write in it:

    $ sudo mkdir /var/lib/bleemeo
    $ sudo chown bleemeo /var/lib/bleemeo
  • Then start the agent. Depending on what you prefer, you should create a init.d script, systemd service or configure supervisor to run agent.

    To run is on foreground:

    $ sudo -u bleemeo /opt/bleemeo-agent/bin/bleemeo-agent

Telegraf Installation

Telegraf is a tool that gathers various metrics about your system and running services. Bleemeo agent uses it as primary source of metrics.

  • Install Telegraf, Bleemeo provides a Debian/Ubuntu repository:

    $ echo "deb $(lsb_release --codename | cut -f2) main" | sudo tee /etc/apt/sources.list.d/bleemeo-telegraf.list
    $ sudo apt-key adv --keyserver hkp:// --recv-keys 9B8BDA4BE10E9F2328D40077E848FD17FC23F27E
    $ sudo apt-get update
    $ sudo apt-get install telegraf
  • Ensure that Telegraf is started with -config-directory /etc/telegraf/telegraf.d.

    This is the default configuration for packaged Telegraf

  • Add the following lines to /etc/telegraf/telegraf.d/bleemeo.conf:

      servers = ["localhost:2003"]
      prefix = "telegraf"
      graphite_tag_support = true
  • (Re)start Telegraf:

    $ sudo service telegraf restart

Bleemeo Agent Discovery & Telegraf

Bleemeo agent can discover services running on your system and reconfigure Telegraf to gather metrics from those services.

But this requires Bleemeo agent to write configuration for Telegraf and restart it. The agent will write configuration in /etc/telegraf/telegraf.d/bleemeo-generated.conf, and will use sudo service telegraf restart to restart Telegraf.

The bleemeo user must have the permissions needed to perform those actions:

  • Create an empty bleemeo-generated.conf and give bleemeo user the write permission to it:

    $ sudo touch /etc/telegraf/telegraf.d/bleemeo-generated.conf
    $ sudo chown bleemeo /etc/telegraf/telegraf.d/bleemeo-generated.conf
  • Edit sudoers (with visudo) and add the following entry:

    bleemeo     ALL=(root) NOPASSWD: /usr/sbin/service telegraf restart
  • Restart the Agent:

    $ sudo -u bleemeo pkill bleemeo-agent
    $ sudo -u bleemeo /opt/bleemeo-agent/bin/bleemeo-agent