Skip to content
GuardiozBeta

What the installer changes on your server

The installer makes a fixed set of changes on the server that runs PostgreSQL. This page lists them, per operating system where they differ, and points at the file on your server that records them. The examples use the port 5432. Replace 5432 with the port of your PostgreSQL instance.

Changes in PostgreSQL

Section titled “Changes in PostgreSQL”

For each PostgreSQL instance it sets up, the installer creates a monitoring role, grants it pg_monitor, and then tests that the role can log in. When that test fails, the installer can add one rule to pg_hba.conf and reload the configuration. It creates no other object in the database, and it changes no PostgreSQL setting.

The monitoring role

Section titled “The monitoring role”

The installer creates the role guardioz_monitor with a password that it generates on your server. When a role with that name already exists, the installer does not create it: it gives that role a new password and the right to log in instead. Every run that reaches this step generates a new password.

PostgreSQL stores the password as a SCRAM-SHA-256 hash, also on a server whose password_encryption setting is md5. The rule that the installer can add to pg_hba.conf, shown below, accepts only a password stored that way, so an MD5 hash would stop the role from logging in. The installer computes that hash on your server and sends PostgreSQL the hash, not the password. PostgreSQL stores a password that arrives already hashed as it is, so the installer neither reads nor changes the password_encryption setting of your server. Where your server logs this statement, the log holds the hash, not the password.

The installer hands the password to other programs on standard input, and to its own connection test with psql in the PGPASSWORD environment variable of that one command. It never passes the password as a command-line argument, so the password appears neither in the process list nor in the command lines that sudo writes to the system log.

The password does not reach Guardioz. The installer writes it into the agent’s configuration file on your server, and the registration request does not carry it.

One privilege

Section titled “One privilege”

The installer grants pg_monitor to the monitoring role, and grants nothing else. pg_monitor is a role that PostgreSQL ships for monitoring; it allows reading monitoring views and functions. See Predefined Roles in the PostgreSQL 18 documentation. The installer gives the role no superuser rights, no right to create roles, and no rights on your tables.

The installer reports the grant without testing it afterwards. An account that can create roles but is not a superuser cannot grant pg_monitor, unless it holds that role with the admin option. In that case the installation runs to the end and the agent collects less than it could. To confirm the grant, connect to the database with psql or another SQL client. Any role that can connect may run this statement:

SELECT pg_has_role('guardioz_monitor', 'pg_monitor', 'member');

The answer t means that the grant is in place.

The pg_hba.conf lines, only when the role cannot log in

Section titled “The pg_hba.conf lines, only when the role cannot log in”

After it creates the role, the installer tests that the role can connect over the local Unix socket. When that connection works, pg_hba.conf is not changed.

When it does not work, the installer adds two lines to pg_hba.conf, the file in which PostgreSQL decides which connections it accepts. It leaves the file as it is when the file already carries a local rule for the monitoring role. The two lines are:

# Guardioz monitoring (read-only, local socket only)
local  all  guardioz_monitor  scram-sha-256

The lines go right after the line that starts with # TYPE, which names the columns of the file. When the file has no such line, they go at the top. PostgreSQL uses the first rule that matches, so the new rule stands before the general local rules. The installer then reloads the PostgreSQL configuration. It does not restart PostgreSQL.

When the installer cannot locate pg_hba.conf, it changes nothing, reloads nothing, and prints the rule for you to add by hand.

The rule allows a connection over the Unix socket with a password. It opens no network access to the database. To see where pg_hba.conf is on your server, connect to the database as a superuser and run SHOW hba_file;.

The installer reaches PostgreSQL over one fixed socket directory. To see the directory your instance uses, connect as a superuser and run SHOW unix_socket_directories;.

The installer uses the Unix socket directory /var/run/postgresql. An instance whose socket is in another directory is not supported.

Changes on the host

Section titled “Changes on the host”

Files and directories

Section titled “Files and directories”
  • Directory/opt/guardioz-agent/ the agent’s code, owned by root
    • Directoryguardioz_agent/ the Python files the service runs
      • …
    • Directoryvenv/ the Python libraries, on Linux only
      • …
    • pyproject.toml
    • LICENSE the licence of the agent
  • Directory/etc/guardioz-agent/
    • config-5432.yaml one file for each PostgreSQL port
    • install-manifest.txt the record of the changes on this host
  • Directory/var/lib/guardioz-agent/
    • state-config-5432.json when the daily and the weekly collection last ran, and when the server was registered

The agent’s code belongs to root. Directories have mode 0755, and files that are not executable have mode 0644, so the account that runs the service can read the code and cannot change it.

The configuration file belongs to root with mode 0640, and its group is the one the service runs under. The agent’s service reads it and never writes it; the installation writes it. It holds the collector key, the secret with which the agent identifies itself to Guardioz, and the password of the monitoring role. Do not paste this file into a message or a ticket. For every setting in the file, see Agent configuration.

The state directory has mode 0700 and belongs to the account that runs the service. The installation creates it, and on Linux the service sets its owner and its mode again at every start. The file in it holds three times: when the daily collection and the weekly collection last ran, and when the server was registered. It holds nothing from your database.

The system account and the service

Section titled “The system account and the service”

The installer creates a system account for the agent’s service, with no login shell and no home directory. When such an account already exists on the host, the installer uses it and leaves it unchanged. It needs a group with the same name for that account, and on FreeBSD the account has to be in that group. When that is not so, the installer stops before it changes anything and gives the command that creates the group or adds the account to it. The agent runs under this account, not as root. On FreeBSD the service also has a supervising process, daemon(8), which stays under root and starts the agent under this account. For what the service may and may not do, see Security and access.

Creating this account, and making root the owner of the agent’s code, are among the steps that need administrator rights. That is why the installer needs those rights and the agent runs without them. See Why the installer needs administrator rights.

The installer writes one systemd unit per instance, /etc/systemd/system/guardioz-agent-5432.service, enables it so that it starts at boot, and starts it. The service writes its log to the system journal.

Software the installer can install

Section titled “Software the installer can install”

The installer creates a Python virtual environment in /opt/guardioz-agent/venv, upgrades pip inside it, and installs three libraries into it from the Python package index, with the libraries they require: psycopg2-binary, requests and pyyaml. They stay in that directory, separate from the Python packages of your system.

acl is the only system package the installer can add, and it adds it only when the command setfacl is missing. setfacl sets the access-control list entries that let the account running the service pass through the PostgreSQL data directory, described in the section Access to the data directory.

Access to the data directory

Section titled “Access to the data directory”

The agent measures the free space of the disk that holds pg_wal, the directory of the transaction log (WAL). To reach that directory, the account that runs the service needs permission to pass through the PostgreSQL data directory. The installer grants exactly that, with access-control list (ACL) entries: the account can enter a directory, and cannot list or read what is inside. The owner and the group of each directory stay as they are, and the installer runs no chmod. On Linux, and on FreeBSD with UFS, ls -l then shows a + and --x in the group column: on a directory with an access-control list, that column shows the ACL mask, the most that an added entry can grant. The group of the directory gains no permission, and PostgreSQL accepts its data directory in that state.

As the service account, the installer tries to enter the data directory and every directory above it. It adds one entry on each directory where entering fails, and on no other. When pg_wal is a link to another directory, the installer grants the same access along that path.

The entries need the command setfacl. When that command is missing, the installer tries to install the acl package first.

When the grant does not happen, because the file system refuses the entry or because setfacl is missing and cannot be installed, the installer writes a message in its output and runs to the end. The agent then records the free space of the transaction-log directory as not measured, and Guardioz puts no estimate in its place. When a directory above the data directory blocks the service account as well, the disk figures of the data directory are recorded as not measured too. Not measured is a result, not an error. The install manifest records only the entries that the file system accepted.

To skip this grant, use the install command with the option --no-pgdata-access. The option has to reach the script and not the shell that the command pipes into, so on Linux the command ends in | bash -s -- --no-pgdata-access. On FreeBSD, change the end of the command from | sh to | env GUARDIOZ_NO_PGDATA_ACCESS=1 sh, which sets the environment variable GUARDIOZ_NO_PGDATA_ACCESS for the shell that runs the script. The command uses env so that it works in sh and in csh alike. Any value that is not empty skips the grant, including 0 and false. Install on Linux and Install on FreeBSD show the full command with the option in place. The cost is the same as a refused entry: the disk figures of the transaction-log directory are recorded as not measured, and everything the agent reads through its database connection is collected as usual.

The install manifest

Section titled “The install manifest”

The installer keeps a record of its changes in /etc/guardioz-agent/install-manifest.txt. The file belongs to root and every account on the host can read it (mode 0644). Each run appends to it and rewrites nothing, so a second run adds a second set of entries.

An entry is two lines: a description that starts with #, and the command that reverses that change, or for the acl package a note on how to remove it. Nothing in the file runs on its own. It is a record for you, and the basis for a removal. The command recorded for the pg_hba.conf lines removes every line of that file that names guardioz_monitor, and leaves the comment line above the rule, so do not run it: delete the two lines by hand, as Remove Guardioz from a server shows.

The file records:

  • the agent directory and the state directory,
  • the system account, when this run created it,
  • the monitoring role, when this run created it, and the pg_monitor grant,
  • the pg_hba.conf lines, when this run added them,
  • each agent configuration file and each systemd unit,
  • each ACL entry on the path to the data directory,
  • the acl package, when this run installed it.

A new password given to a monitoring role that already existed is not recorded here. The section The monitoring role says what that means.

What the installer never touches

Section titled “What the installer never touches”
  • Your data. No statement the installer runs reads or changes rows in your tables. Its statements test the connection, create or alter the monitoring role, grant pg_monitor, reload the configuration in the pg_hba.conf step, and read the server version, the data directory path, the pg_hba.conf path, whether the instance is a replica, whether the monitoring role exists, and whether the account it connects with can create a role.
  • PostgreSQL settings. Neither installer edits postgresql.conf, and neither runs ALTER SYSTEM. pg_hba.conf is the only PostgreSQL file either of them can change.
  • The running database. The installer does not restart PostgreSQL. It reloads the configuration in the pg_hba.conf step and nowhere else.
  • Network access to the database. The only rule the installer can add is a local rule for the Unix socket. It adds no host rule, opens no port, and changes no firewall.
  • Other roles. The installer creates or changes no role other than guardioz_monitor.
  • The data directory. Its owner and its group stay as they are, and the installer runs no chmod on it. The installer adds ACL entries for the service account and nothing else; on Linux and on UFS the group column of ls -l then shows the ACL mask, as described above.
  • A system account that already exists. The installer creates the service account only when it is missing. It does not change an account that already exists, and it does not create a group for one: when the group is missing, it stops before it changes anything.
  • The rest of the software on the host. The installer installs only the software described on this page and what those packages require. It runs no command that upgrades all of your software. On FreeBSD, pkg can upgrade a package that is already installed when one of the new packages needs a newer version of it, and pkg lists such packages in its output.

Next steps

Section titled “Next steps”
Install the agentThe install command, and the procedure for Linux and for FreeBSD.
Check that the agent worksThe service, the log line that proves a snapshot was sent, and what you see in Guardioz.
Remove Guardioz from a serverUndo every change on the host and in PostgreSQL.