Install on FreeBSD

Install the Guardioz agent on a FreeBSD server that runs PostgreSQL 18. You copy one command in Guardioz and run it on that server. The installation does not restart PostgreSQL. It takes a few minutes, and longer when the installer has to install packages with pkg. At the end the server is registered, and the results of its first snapshot appear on the Findings page within a few minutes. A snapshot is one set of measurements that the agent reads from your server and sends to Guardioz.

Before you start

You need the following:

An account in Guardioz. To create one, see Create an account and sign in.
A FreeBSD server that runs PostgreSQL 18. Guardioz supports PostgreSQL 18 only. On another major version the installer stops before it changes anything on the server.
Root access to that server, or an account on it that can use sudo. When the account is not root and sudo is not installed, the installer stops before it changes anything. The installer needs those rights, and the agent’s process runs without them. See Why the installer needs administrator rights.
The psql command in one of these directories: /usr/local/sbin, /usr/local/bin, /usr/sbin, /usr/bin, /sbin, /bin. The installer searches only those directories. To see where your psql is, run command -v psql in a shell on the server. When it is in another directory, the installer stops before it changes anything.
A way for the installer to reach PostgreSQL with a database role that can create roles. The installer tries, in this order: the role named in the PGUSER environment variable, a role with the name of the operating-system account that you run the command from, and psql run as the operating-system account postgres. It expects that account to own the cluster, and that account connects with its own settings, without the PG variables of your session such as PGUSER. The installer tries them on the port of each PostgreSQL instance it finds running, not only on 5432. When none of them works, the installer stops before it changes anything.
Access from the server to a pkg repository. The agent needs three Python packages from it: psycopg2, pyyaml and requests, all built for the same Python version. Python does not have to be installed first. The installer installs a Python version for which the repository has all three. When a python3.X in /usr/local/bin already imports all three, the installer installs no package at all.
An outbound HTTPS connection from the server to app.guardioz.com. The agent opens that connection itself, so no inbound port is needed. The agent reaches PostgreSQL through the local socket, so no database port has to be opened either.

A server that runs more than one PostgreSQL instance 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. One install command registers one PostgreSQL instance: 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.

For the full list of requirements, see Requirements.

Get the install command

In your browser, sign in at https://app.guardioz.com/ and open Servers.
Click + Add server.
Click Self-Managed PostgreSQL. The page Configure Self-Managed PostgreSQL opens and generates the command by itself.
The page shows the Linux command first. Click FreeBSD. The command on the page then starts with fetch.
Click Copy command. The button reads Copied! for two seconds.

The command has this shape, and the page fills in a one-time token at the end:
Terminal window
```
fetch -qo - "https://app.guardioz.com/api/v1/setup/install-freebsd.sh?token=..." | sh
```
Copy the command from the page instead of typing this one. The command can be used once, and it expires after 60 minutes.

Keep the setup page open. It reports the progress of the installation. A reload generates another command, and the page then follows only that new one.

Run the command

The installer prints each step at the terminal, including the PostgreSQL instances that it found and their versions. For every change that it makes on the server and in PostgreSQL, see What the installer changes on your server.

By default the installer gives the agent’s system account permission to pass through the PostgreSQL data directory. The agent needs that permission to measure the free space on the disk that holds the transaction log. To install without it, see Access to the data directory.

Running the install command again on a server that already runs the agent is not an update. It gives the monitoring role a new password. It also issues a new collector key, the key that the agent uses to send its data to Guardioz. The installation stays on the same server only when the agent configuration on this host still holds a working key. That key must belong to a server of your organization, and the configuration must point to the same Guardioz address. Otherwise Guardioz adds a new server, which starts without the history the earlier server collected.

A command that has expired or was already used still gives the monitoring role a new password. Guardioz then refuses the registration. The agent’s configuration is not rewritten, so the agent keeps the old password and stops sending data. To repair that, copy a new command in Guardioz and let that run finish. To update the agent, see Update the agent.

On the server that runs PostgreSQL, open a shell as root, or as an account that can use sudo.
Paste the command that you copied, and then run it. It needs no sudo in front of it.

The installer first prints whether it is already root or uses sudo. From an account that uses sudo, it then checks whether sudo runs a command for this account without asking for a password. When it does, the installer goes on without asking. When sudo needs a password, the installer prints the following before it changes anything, and sudo then asks you to authenticate:
```
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, before it installs any package. 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:
```
...
Scanning for PostgreSQL instances...
  Port 5432: PostgreSQL 18.0
  Port 5433: PostgreSQL 18.0

  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. To choose the instance without a question, see Choose the instance without a question.
Wait for the run to finish. While it installs the packages, pkg prints its own progress. The last lines of the output are similar to the following:
```
...
=== Setup finished ===

  Registered instances: 1
  Config dir: /etc/guardioz-agent/
  Services: service -e | grep guardioz_agent
  Dashboard: https://app.guardioz.com/servers
```
The service is named guardioz_agent_ followed by the port of your PostgreSQL instance. The FreeBSD installer prints === Setup finished === whether or not the registration succeeded, so read the line that starts with Registered instances:. It counts the instances that were registered. Registered instances: 0 means that no instance was registered, and the installer then ends with exit code 1. The reason stands earlier in the output, before the line === Setup finished ===. 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 '| sh' to '| env GUARDIOZ_PORT=<port> sh', for example:
    ... | env GUARDIOZ_PORT=5432 sh

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

fetch -qo - "https://app.guardioz.com/api/v1/setup/install-freebsd.sh?token=..." | env GUARDIOZ_PORT=5433 sh

The command uses env so that it works in sh and in csh alike: csh, the login shell of root on FreeBSD 13, does not accept a variable in front of a command. The installer 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.

Access to the data directory

To measure the free space on the disk that holds pg_wal, the agent needs permission to pass through the PostgreSQL data directory. pg_wal is the directory where PostgreSQL keeps its transaction log.

The installer asks PostgreSQL for the path of the data directory. It then tries to add one access control list (ACL) entry for the agent’s system account. The entry grants the permission to pass through that directory. It does not allow the account to list the directory or to read the files in it.

The owner and the group of the directory stay as they are, and the installer runs no chmod. On FreeBSD the form of an ACL depends on the file system, so the installer tries two forms. With the form that UFS uses, ls -l then shows a + and --x in the group column, which on a directory with an access-control list shows the ACL mask; the group of the directory gains no permission. When one of the two forms is accepted, the installer prints the directory and the command that removes the entry again, and writes both into /etc/guardioz-agent/install-manifest.txt.

When the file system accepts neither form, the installer prints the following line and the installation continues:

    could not set an ACL on DATA_DIRECTORY; the WAL disk figures read as not measured.

DATA_DIRECTORY is the path of the data directory of your instance. The agent then records the figures for that disk as not measured and collects everything else as usual. Not measured is a result, not an error: Guardioz does not estimate the value.

To install without this grant, change the end of the command that you copied from | sh to | env GUARDIOZ_NO_PGDATA_ACCESS=1 sh. The command uses env for the same reason as GUARDIOZ_PORT: it then works in sh and in csh. The installer then prints:

  Skipping the data-directory traversal grant (--no-pgdata-access);
  the WAL-directory disk figures will be recorded as not measured.

Watch the setup page

While the installer runs, the setup page in your browser reports the progress. It shows one of three lines:

Waiting for server registration… - Guardioz has not received the registration yet.
Server registered, installing agent… - the server is registered. Guardioz is waiting for the installer to report that the agent service runs.
Agent installed and running! - the installation is complete.

At the third line the page shows Setup complete! with the buttons Go to dashboard, Go to server and Server list. After four seconds the browser opens the Findings page by itself.

When the page stays on Server registered, installing agent…, the server is registered and you find it under Servers. The installer did not report that the agent service runs. See Installation problems.

See the first results

The registration step sends a complete first snapshot: the hourly statistics, the catalog of tables and indexes, and the size measurements. Guardioz runs its checks on that snapshot, and the first results appear within a few minutes of the setup page reporting success.

Open Findings to read them. 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. For what the page shows, 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 a snapshot. When the service starts it writes two lines to its log file: that it is starting, and that it waits before the first collection. After those it adds no line for about an hour. That is normal. To confirm that the agent works, see Check that the agent works.

If something goes wrong

The installer stopped, or the setup page keeps waiting: Installation problems.
The server is in Guardioz, and no data arrives: Agent and data problems.
Nothing matches what you see: write to contact@guardioz.com. For what to include, see Get help.

Next steps

Check that the agent worksConfirm the service, the log and what Guardioz shows.

Read your findingsRead the results of the first snapshot.

What the installer changes on your serverEvery change on the host and in PostgreSQL.