Skip to content

Install the agent

This page document a quick way of installing the agent. For production system, you may want to use trusted certificate and other enhancement.

Prerequisites

In order to run temBoard agent, you need:

  • Linux as underlying OS.
  • PostgreSQL 13+, listening on UNIX socket. Check with sudo -u postgres psql.
  • openssl.
  • Python 3.9+. Check with python3 --version.
  • bash, curl and sudo for setup script.
  • A running temBoard UI.

Note

The temBoard agent must run on the same host as the PostgreSQL instance. Running an agent on a remote host is not yet supported.

Install

temBoard RPM are published on Dalibo Labs RPM repository. Start by enabling that repo.

$ sudo dnf install -y epel-release
$ sudo dnf install -y https://yum.dalibo.org/labs/dalibo-labs-4-1.noarch.rpm

Warning

Do NOT use temBoard agent rpm from PGDG. They are known to be broken.

With the RPM repository configured, you can install temBoard agent with:

$ sudo dnf install temboard-agent
$ temboard-agent --version

Offline install

Some production infrastructure are offline for security reasons. In this situation, the temboard-agent package and its dependencies can be dowloaded with the following commands :

$ dnf download --resolve --destdir /tmp/temboard-packages temboard-agent

Then the downloaded packages can be transfered to the production server and installed with :

$ dnf --disablerepo=* localinstall *.rpm

temBoard debs are published on Dalibo Labs APT repository. temBoard agent supports Debian buster and newer. Start by enabling Dalibo Labs APT repository.

# echo deb http://apt.dalibo.org/labs $(lsb_release -cs)-dalibo main > /etc/apt/sources.list.d/dalibo-labs.list
# curl -fsSL -o /etc/apt/trusted.gpg.d/dalibo-labs.gpg https://apt.dalibo.org/labs/debian-dalibo.gpg
# apt update  # You may use apt-get here.

You can install now temBoard agent with:

# apt install temboard-agent
# temboard-agent --version

Since version 10, installing temBoard with pip is not possible. The last version published on PyPI is obsolete.

Configure

The quickest way to setup temBoard agent is to use the auto_configure.sh script, installed in /usr/share/temboard-agent.

You must run this script as root, with PG* env vars set to connect to the Postgres cluster you want to manage. By default, the script uses postgres UNIX user to connect to Postgres cluster.

Note

Each instance is identified by the fully qualified hostname. If hostname --fqdn can't resolve the FQDN of your HOST, simply overwrite it using TEMBOARD_HOSTNAME envvar. Remember that localhost or even a short hostname is not enough. auto_configure.sh enforces this.

# /usr/share/temboard-agent/auto_configure.sh https://temboard.acme.tld:8888

The script shows you some important information for the next steps:

  • agent TCP port (usually 2345 if this is your first agent on this host).
  • the path to the main agent configuration file like /etc/temboard-agent/17/main/temboard-agent.conf

Next you need to fetch the signing public key of temBoard UI. An agent accepts requests from a single temBoard UI. temBoard UI signs each requests using an asymetric key. Use temboard-agent fetch-key to download the signing key from the configured UI. Or push the signing using a configuration management service.

# temboard-agent --config /etc/temboard-agent/17/main/temboard-agent.conf fetch-key

Start

Now start the agent using the command suggested by auto_configure.sh. On most systems now, it's a systemd service:

# systemctl enable --now temboard-agent@17-main

Check that it has started successfully:

# systemctl status temboard-agent@17-main

Note

temBoard agent OOM score is configured to 15, so that OOM killer will likely kill temBoard agent before Postgres. A good practice is to disable memory overcommit on PostgreSQL host by setting sysctl vm.overcommit_memory = 2.

Register

Register from the monitored instance

Now you can register the agent in the UI using temboard-agent register. It needs the configuration file path, the agent host and port and the path to the temBoard UI.:

# sudo -u postgres temboard-agent -c /etc/temboard-agent/17/main/temboard-agent.conf register --environment default

temboard-agent register will ask you credentials to the temBoard UI with admin privileges.

Note

the --environment (or -e) option replaces the --groups (or g) option that was used in version 8.

Register from the UI

Alternatively it is possible to register an instance on the temBoard server.

This can be done either by running the following command line on the temboard server:

# sudo -u temboard temboard register-instance foo.acme.tld -e default --if-not-exists

( Replace foo.acme.tld by the named of the monitored instance )

Or connect to the web interface, go to the Settings > Instances page and click on the Add new instance button.

It’s up!

Congratulation! You can continue on the UI and see the agent appeared, and monitoring data being graphed.

You can repeat the above setup for each instance on the same host.

Clean the agent installation

If you need to clean a single agent installation either to uninstall it or to run auto_configure.sh again, use purge.sh with cluster name.

# /usr/share/temboard-agent/purge.sh 17/main
Stopping and disabling systemd service.
Removed /etc/systemd/system/multi-user.target.wants/temboard-agent@17-main.service.
Cleaning files and directories...
removed '/etc/temboard-agent/17/main/temboard-agent.conf'
removed '/etc/temboard-agent/17/main/temboard-agent.conf.d/auto.conf'
removed directory '/etc/temboard-agent/17/main/temboard-agent.conf.d'
removed '/etc/temboard-agent/17/main/users'
removed directory '/etc/temboard-agent/17/main/'
removed directory '/var/lib/temboard-agent/17/main/'
temBoard agent 17-main stopped and cleaned.
#

( Replace 17/main with the version and name of the PostgreSQL monitored instance. )