This article explains how to configure PGHOST when the PostgreSQL agent cannot connect using a non-default Unix socket.

LAST TESTED ON CHECKMK 2.4.0P1

Starting with Checkmk 3.0.0, the PostgreSQL agent plugin supports configuring PGHOST directly in the instance .env file.

Werk #17379: Enable using PGHOST via mk_postgres.py

Table of Contents

1 Overview
2 Problem
3 Cause
4 Solution
5 Verification
6 Limitations
7 Related articles

Overview

The mk_postgres.py agent plugin uses the psql client to collect monitoring data from PostgreSQL.

If PostgreSQL uses a Unix socket outside the default location, such as /tmp, the agent plugin may fail to connect because older Checkmk versions do not support configuring the PGHOST environment variable.

Problem

The PostgreSQL services are missing, or the agent plugin returns an error similar to the following:

psql: error: could not connect to server: No such file or directory

Is the server running locally and accepting connections on Unix domain socket
"/var/run/postgresql/.s.PGSQL.5432"?

Cause

By default, psql attempts to connect using the standard PostgreSQL Unix socket location.

If PostgreSQL is configured to use a different socket directory, for example /tmp, the connection fails because the plugin searches the wrong location.

Older versions of the PostgreSQL agent plugin do not provide a way to configure PGHOST or specify the socket directory in postgres.cfg. As a result, the plugin relies on the default environment when executing psql.

Solution

Configure the PGHOST environment variable for the operating system user defined in postgres.cfg.

For example, if the PostgreSQL user is myuser, switch to that user and add the following line to either ~/.bash_profile or ~/.bashrc:

export PGHOST=/tmp

Reload the shell environment:

source ~/.bash_profile

or

source ~/.bashrc

The PostgreSQL agent plugin will then use the correct Unix socket directory when connecting to the database.

Verification

Run the PostgreSQL agent plugin manually:

mk_postgres.py

The plugin should complete successfully without any connection errors.

Limitations

This workaround applies the same PGHOST value to every PostgreSQL instance running under the same operating system user.

If multiple PostgreSQL instances use different Unix socket directories but share the same operating system user, this workaround is not suitable.