Install on Linux

This page takes you from an empty Servers list to the first findings for one PostgreSQL 18 instance on a Linux server. It has four parts: get the install command in Guardioz, run it on the server, watch the setup page, and open the results. The installer does not restart PostgreSQL.

Before you start

A Guardioz account. To create one, see Create an account and sign in.
A server that runs Linux with systemd and PostgreSQL 18. The installer needs bash, curl, tar, psql, openssl and Python 3.11 or newer with the venv module (the python3-venv package on Debian and Ubuntu) on that server. On Ubuntu 22.04 and the Enterprise Linux 9 family the system python3 is older, so install python3.11 next to it first. The full list is in Requirements.
Administrator rights on that server: the root account, or an account that can use sudo. The installer needs them, and the agent runs without them. See Why the installer needs administrator rights.
A way for the installer to reach PostgreSQL with a database role that can create roles and grant pg_monitor. The installer tries, in this order: the role named in the PGUSER environment variable, a role with the name of the account you run the command from, and the operating-system account that runs PostgreSQL (postgres on most Linux systems). It tries them on the port of each PostgreSQL instance it finds running, not only on 5432, and that last account connects with its own settings, without the PG variables of your session such as PGUSER. On a default installation that last account connects as a superuser, so you need to do nothing. A role that can only create roles creates the monitoring role, but PostgreSQL then refuses the pg_monitor grant, and the installer continues without it. When none of those accounts is allowed to create a role, the installer stops before it changes anything, with Error: Guardioz connected to PostgreSQL, but no account it can use may create a role., and names the accounts that connected.
Outbound HTTPS from that server to https://app.guardioz.com/, and access to the Python package index at pypi.org and files.pythonhosted.org while the installer runs. The agent has no proxy setting, so a server that reaches the internet only through an HTTP proxy is not supported. The installer also uses your distribution’s package repository, but only when the acl package is missing.
A server that runs one PostgreSQL instance. A server that runs more than one is not supported, because the settings recommendations that depend on hardware are computed for the whole server, not for one instance. Requirements says what is affected. On such a server the installer asks which PostgreSQL 18 instance to register, and it changes nothing on the others. If you want Guardioz on such a server, write to contact@guardioz.com.

Guardioz supports PostgreSQL 18 only. When the installer finds no PostgreSQL 18 instance, it stops before it changes anything on the server.

Get the install command

Sign in at https://app.guardioz.com/.
Open Servers, and then click + Add server. When your organization has no server yet, Guardioz opens the page behind that button by itself, and you can skip this step.
Click Self-Managed PostgreSQL. That means PostgreSQL you run yourself, on your own server, which is what Guardioz monitors today. A managed service (Amazon RDS, Aurora, Azure Database for PostgreSQL) is not supported. Support for Amazon RDS for PostgreSQL is planned. The page Configure Self-Managed PostgreSQL opens and generates the command by itself.
Keep Linux selected, and then click Copy command. The label of the button changes to Copied! for two seconds.

The command has this shape:

curl -fsSL "https://app.guardioz.com/api/v1/setup/install.sh?token=..." | bash

The three dots stand for a one-time token that belongs to this command alone, so copy the command from the screen instead of typing it from this page. It is valid for 60 minutes and works once.

Run it once, from beginning to end. An expired command, or one that was already used, still gives the monitoring role a new password before Guardioz refuses the registration. On a server that Guardioz already monitors, the agent installed there can then no longer log in to PostgreSQL, because its configuration still holds the old password. When a run does not finish, generate a new command on the setup page instead of running the same one again. The messages you can see are in Installation problems.

Leave the browser page open. It follows this installation and shows its progress. A reload generates another command and then follows only that one.

Run the command

The installer needs administrator rights on the server: it creates the monitoring role, creates a system account for the agent, and installs a service that runs under that account, not as root. Run it in a terminal where you can type: sudo can ask you for your password, and on a server with more than one PostgreSQL 18 instance the installer asks which one to register. To run it without a terminal, see Choose the instance without a question. To install without the data-directory access grant, use the command in Install without the data-directory access grant.

Connect to the server that runs PostgreSQL, for example over SSH, as root or as an account that can use sudo. Do not run the command on your own computer. The agent reads the database over the local socket, so the agent must run on the same server.
Paste the install command, and then run it. It needs no sudo in front of it. The installer detects by itself whether it is already root or needs sudo, and prints which of the two it uses.

From an account that uses sudo, the installer first checks whether sudo runs a command for this account without asking for a password. When it does, the installer goes on without asking for your password. When sudo needs your password, the installer prints the following before it changes anything, and sudo then asks for the password:
```
This run needs administrator rights to set up monitoring on this server.
sudo may ask you to authenticate. Nothing has been installed or changed by
Guardioz yet.
```
If the installer found more than one PostgreSQL 18 instance, it asks which one to register. It first lists the instances in a table, with the port, version and data directory of each, and then numbers them. Enter the number of the instance you want to monitor, and then press Enter. The installer changes nothing on the other instances.

The output is similar to the following, with 2 typed as the answer:
```
...
  Found 2 PostgreSQL instance(s):

  Port    Version           Data directory
  ------  ----------------  ----------------------------
  5432    PostgreSQL 18.0   /var/lib/postgresql/18/main
  5433    PostgreSQL 18.0   /var/lib/postgresql/18/second

  One install command registers one instance. Choose the instance to register:
    1  port 5432
    2  port 5433
  Instance number (1-2): 2
  Registering the instance on port 5433.
```
The question takes exactly one number. An empty line, all, or several numbers make the installer print Enter one number from 1 to 2. and ask again. With one instance the installer prints Single instance detected - registering automatically. and asks nothing.
Wait for the installer to finish. It prints its progress while it runs. While it registers the server, the agent’s own log lines appear in that output, each starting with a timestamp. One of them contains Registration complete. Start the agent with:, followed by a command. Do not run that command: the installer installs the service and starts it.

The last lines are similar to the following:
```
...
=== Setup complete! ===

  Registered instances: 1
  Config dir: /etc/guardioz-agent/
  Services: systemctl list-units 'guardioz-agent-*'
  Dashboard: https://app.guardioz.com/servers
```
The address on the last line opens the Servers list.

The heading reads === Setup finished with errors === instead when the registration failed, or when the agent’s service did not come up running under its own system account. Read the output again and find the step that reports the failure. The line Registered instances: says whether the server was registered. When it reads 0, the installer ends with exit code 1. When it reads 1, the installer ends with exit code 0, also under that heading: the server is registered, and its service did not come up as it should. Other failures do not change the heading. Most of them stop the installer before the summary, with an error message and a non-zero exit code, and a few are reported in the output while the run goes on. For what each message means, see Installation problems.

Choose the instance without a question

The installer asks its question on the terminal of your session. When the run has no terminal, for example in a script or a configuration-management tool, and the server runs more than one PostgreSQL 18 instance, the installer stops before it changes anything and prints:

Error: this server runs 2 PostgreSQL 18 instances, and one install command
registers one of them. This run has no terminal to ask which one.
The PostgreSQL 18 instances on this server that Guardioz can register:
    port 5432
    port 5433
To choose one without a question, run the same install command again with its end
changed from '| bash' to '| env GUARDIOZ_PORT=<port> bash', for example:
    ... | env GUARDIOZ_PORT=5432 bash

To choose the instance in advance, change the end of the command you copied from | bash to | env GUARDIOZ_PORT= followed by the port of the instance and bash, so that it reads:

curl -fsSL "https://app.guardioz.com/api/v1/setup/install.sh?token=..." | env GUARDIOZ_PORT=5433 bash

The installer then registers the instance on that port and asks nothing. When no PostgreSQL 18 instance on the server uses that port, it stops before it changes anything, with an error that starts with Error: GUARDIOZ_PORT is set to. After either stop the command is still unused, so you can run it again while it is valid. A run without a terminal also needs root, or an account whose sudo does not ask for a password, because sudo has nowhere to ask.

Install without the data-directory access grant

By default the installer gives the agent’s service account permission to pass through the PostgreSQL data directory, and through each parent directory that blocks the way. When the transaction-log directory is stored outside the data directory, its path is granted the same way. The agent needs this to measure free space on the disk that holds the transaction log (WAL).

The account can pass through those directories. It cannot list or read anything inside them. The installer changes neither the owner nor the group of a directory, and runs no chmod on it. The permission is an access-control list entry. ls -l then shows the directory with a + and with --x in the group column, which now shows the ACL mask, the most that the new entry can grant. The group of the directory gains no permission.

To install without that permission, add -s -- --no-pgdata-access to the end of the command you copied, so that it reads:

curl -fsSL "https://app.guardioz.com/api/v1/setup/install.sh?token=..." | bash -s -- --no-pgdata-access

The installer then prints that it skips the grant, and the agent records the disk figures of the transaction-log directory as not measured. When a directory above the data directory blocks the account, for example /var/lib/pgsql on Red Hat Enterprise Linux and its relatives, the disk figures of the data directory are recorded as not measured too. Not measured is a result, not an error: a check that needs one of those figures reaches its verdict without them, instead of working from an estimate.

Watch the setup page

While the command runs, the setup page in your browser follows it. The page shows one of these three lines:

Line on the page	What it means
Waiting for server registration…	Guardioz has not received the registration yet. While the installer prints new steps in your terminal, it is still working.
Server registered, installing agent…	Guardioz registered the server. The installer is now sending the first snapshot, and then it starts the agent’s service. This step takes longer on a large database.
Agent installed and running!	The installer confirmed that the service runs.

After the third line, the card Setup complete! appears with the buttons Go to dashboard, Go to server and Server list. If you do not click one of them, the browser opens the Findings page four seconds later.

When the page stays on Waiting for server registration… and the installer prints nothing new, the last lines in your terminal say why. When the page stays on Server registered, installing agent…, the server is registered and appears under Servers. What is missing is the installer’s confirmation that the agent’s service runs. Both cases are in Installation problems.

See the first results

The installer sends the first snapshot while it registers the server. A snapshot is one set of readings that the agent takes from PostgreSQL and sends to Guardioz. This first collection runs every part of the agent’s schedule at once: the hourly readings, the table and index catalog, and the size measurements. Within a few minutes of the setup page showing Agent installed and running!, the Findings page lists what Guardioz found on this server.

The page opens on Issues only. Switch the view to All checks to see every check, including the ones that passed. A server with no issues is a real result: Guardioz looked and found nothing to fix. To read a finding and apply a recommendation, see Read your findings.

From now on the agent collects once an hour. After the installation it waits one full hour before its next collection, because the registration already sent one. See When the agent collects.

If something goes wrong

The installer stopped, or the setup page keeps waiting: Installation problems.
The server is in the list, but no data or no findings appear: Agent and data problems.
Your problem is not in this list: write to us, see Get help.

Next steps

Check that the agent worksThe service state, the log line that proves a snapshot was sent, and what you see in Guardioz.

What the installer changes on your serverEvery change on the host and in PostgreSQL, and the record that reverses each one.

Read your findingsHow to read a finding, its evidence and its recommended next step.