Skip to content
GuardiozBeta

Install the agent

Guardioz monitors a PostgreSQL server through an agent that runs on that server and collects about once an hour, on a schedule that keeps its load on your database small. You install the agent with one command that Guardioz generates for you. This page says what that command does, how to read the script before you run it, and where the steps for your operating system are. Before you run anything on the server, confirm that it meets the Requirements.

What the installer does

Section titled “What the installer does”

The installer is a shell script. The download address that Guardioz generates for you already contains your one-time token. On the server, the installer:

  • installs the agent under /opt/guardioz-agent, creates a system account and runs the agent under it, so the agent does not run as root. On FreeBSD, daemon(8), the program that supervises the agent, stays under root. This is why the installer needs administrator rights and the agent runs without them: see Why the installer needs administrator rights;
  • creates the monitoring role guardioz_monitor in PostgreSQL and grants it pg_monitor. That is a role PostgreSQL ships with: it allows reading statistics and configuration, and it does not allow reading the rows of your tables;
  • adds two lines to the pg_hba.conf file, which decides who can connect to PostgreSQL, and then asks PostgreSQL to read its configuration again. This is a reload, not a restart: PostgreSQL keeps running and open connections stay open. The installer does this only when the monitoring role cannot log in over the local socket;
  • registers the server in Guardioz and sends the first snapshot, which is one set of readings that the agent takes from PostgreSQL. Then it installs one service for each registered instance;
  • writes a record of the changes it made, with the command that reverses each change it can reverse, to /etc/guardioz-agent/install-manifest.txt.

The installer changes no PostgreSQL configuration parameter and opens no inbound port on the server. The only PostgreSQL file whose contents it changes is pg_hba.conf. The data directory keeps its contents. The installer adds one permission on it, so that the agent’s service account can pass through the directory and measure free space on the disk that holds the transaction log (WAL).

PostgreSQL accepts the pg_monitor grant from a superuser, or from a role that holds the admin option on pg_monitor. The installer does not stop when PostgreSQL refuses that grant, so run the command with a role that can grant it. For the complete list of changes, per operating system, see What the installer changes on your server.

The install command

Section titled “The install command”

Guardioz generates the command on the setup page, when you add a server. The steps are in Install on Linux and Install on FreeBSD. Four facts about the command:

  • It carries a one-time token. The command is valid for 60 minutes and works once.
  • It registers one PostgreSQL instance. A server that runs more than one PostgreSQL instance is not supported, see Requirements. On such a server the installer asks which PostgreSQL 18 instance to register and changes nothing on the others.
  • It needs no sudo in front of it. The installer detects by itself whether it is already root or needs sudo, and asks for your password when sudo needs one.
  • It runs on the server that runs PostgreSQL, not on your own computer. The agent reads the database over the local socket, so the agent must run on the same server.

Read the script before you run it

Section titled “Read the script before you run it”

The install command downloads the script and runs it in one step. To read the script first, download it to a file, read the file, and then run it. Do all three on the server that runs PostgreSQL, from the same account you use for the install command: root, or an account that can use sudo.

First get your install command: follow Install on Linux or Install on FreeBSD up to Copy command.

Download the script:

Terminal window
curl -fsSL "INSTALL_URL" -o guardioz-install.sh

Replace INSTALL_URL with everything between the double quotes in the command you copied. That address already contains your token.

Read the file. It is a plain shell script:

Terminal window
less guardioz-install.sh

Run the file with the same rights as the install command, as root or from an account that can use sudo. It does the same as the one-line command:

Terminal window
bash guardioz-install.sh

To install without the data-directory access grant, add --no-pgdata-access to the end of that command. What the grant is for, and what you lose without it, is in What the installer changes on your server.

The file contains your one-time token. Do not share the file, and delete it when the installation is done:

Terminal window
rm guardioz-install.sh

The token is valid for 60 minutes from the moment the setup page generated the command, and Guardioz checks it when the installer registers the server, some minutes after the start. Start the run early enough in that hour. After the installation, the agent’s own source is on the server, under /opt/guardioz-agent.

To read the agent’s source before you install it, download the archive that the installer downloads. It needs no account and no token:

Terminal window
curl -fsSL https://app.guardioz.com/api/v1/setup/agent-source -o guardioz-agent.tar.gz
tar xzf guardioz-agent.tar.gz

The statements that the agent runs against PostgreSQL are in guardioz_agent/collector.py, and the operating-system commands in guardioz_agent/os_collector.py. See What the agent reads and sends.

Choose your operating system

Section titled “Choose your operating system”

Each page takes you from the install command to the first findings for your server.

Install on LinuxThe full procedure for a Linux server with systemd.
Install on FreeBSDThe full procedure for a FreeBSD server.