Update the agent

An update replaces the agent code on your server and restarts every agent service on that server. After a restart the agent waits one full collection interval before it collects again. The installer sets that interval to one hour, so the next snapshot arrives about an hour later. The update keeps the server identity, the collector key and the configuration file, so the server in Guardioz keeps its history.

The same update script runs on Linux and on FreeBSD. Where the commands differ, a tab shows each. The examples use the port 5432. On FreeBSD a service name uses underscores, for example guardioz_agent_5432, and the FreeBSD commands are written for root.

Nothing on your server updates itself. There is no timer and no automatic update, Guardioz does not report which agent version a server runs, and the update script has no option that prints the installed version. To find out whether the agent on a server is current, write to contact@guardioz.com. An update on a server that already has the current code writes the same code again, keeps one more copy of it, and restarts the services, so the next snapshot follows one full interval later.

Before you start

• Administrator rights on the server that runs PostgreSQL: the root account, or an account that can use sudo.
• The address that the agent sends its snapshots to. For a server registered in Guardioz that address is https://app.guardioz.com, and that is what you pass to the update command. The script compares it with the address in the agent’s configuration file and stops when the two differ.
• An outbound HTTPS connection from that server to https://app.guardioz.com/. The updater downloads the agent code from there. It needs no install command and no token.

Start the update

1. Sign in to the server that runs PostgreSQL, as root or as an account that can use sudo.

2. Optional: Save the script before you run it. The updater is a plain file, and the download needs no account and no token. This command writes the file update-agent.sh into the directory you are in:

   Linux

   curl -fsSL https://app.guardioz.com/static/update-agent.sh -o update-agent.sh

   FreeBSD

   fetch -qo update-agent.sh https://app.guardioz.com/static/update-agent.sh

   Read it with any text viewer, for example less update-agent.sh. To start the update from the saved file, stay in that directory and use the following command instead of the command in step 3. It takes the same address as its first argument.

   Linux

   sudo sh update-agent.sh https://app.guardioz.com

   FreeBSD

   sh update-agent.sh https://app.guardioz.com

3. Start the update. The script needs administrator rights: it replaces the code under /opt/guardioz-agent and restarts the services.

   Linux

   curl -fsSL https://app.guardioz.com/static/update-agent.sh | sudo sh -s -- https://app.guardioz.com

   FreeBSD

   fetch -qo - https://app.guardioz.com/static/update-agent.sh | sh -s -- https://app.guardioz.com

   The address after -- is the first argument of the script, and the script stops without it. As root, leave out sudo. From an account that is not root, the script uses sudo for the steps that need administrator rights. In the output, 5432 stands for the port of a monitored instance.

   The output is similar to the following:

   Downloading the agent from https://app.guardioz.com...
   Keeping the current version as guardioz_agent.20260918T141206Z
   ...
     Restarting guardioz-agent-5432
   ...
   
   Update complete. Verify that a snapshot arrives:
     journalctl -u 'guardioz-agent-*' -n 30 --no-pager
   
   To go back:  curl -fsSL https://app.guardioz.com/static/update-agent.sh | sh -s -- https://app.guardioz.com --rollback 20260918T141206Z

   On FreeBSD the line under Update complete. reads tail -n 30 /var/log/guardioz_agent_*.log, and on a server without curl the command after To go back: starts with fetch -qo - instead of curl -fsSL. When you ran the update from a saved copy, that command is sh update-agent.sh with the same arguments.

   The timestamp names the version that the update kept. Keep the line that starts with To go back:. The command after it restores that version. That line carries no sudo, because the sudo in your command had already made the script root. It works as it stands from an account that can use sudo: the script asks for administrator rights by itself. When you ran the update with --allow-url-change, the line ends with that flag too, because a rollback checks the address in the same way as an update.

4. Read the output and look for lines that begin with two spaces and an exclamation mark. The script prints one for each service that did not restart, for example on Linux:

     ! guardioz-agent-5432 failed to restart - continuing with the others.

   It prints a second line of the same shape when a service restarted but does not run under the system account that the agent’s service uses. After either line the script also prints (some instances need attention - see above). When you see one of these lines, see Update and removal problems.

   On FreeBSD a third line of that shape can appear before the restarts:

     ! guardioz_agent_5432: could not read the interpreter from /usr/local/etc/rc.d/guardioz_agent_5432 - left unchanged.

   The script then left the service script of that port as it was, and the service restarts with that old script. No (some instances need attention - see above) follows this line. Write to contact@guardioz.com when you see it.

The script prints Update complete. and ends with the same exit code whether every service restarted or not, so read the output and not the exit code.

Check that it worked

On the server that runs PostgreSQL, with administrator rights, show the last lines that the agent services wrote to their log:

Linux

sudo journalctl -u 'guardioz-agent-*' -n 30 --no-pager

FreeBSD

tail -n 30 /var/log/guardioz_agent_*.log

Right after the update, each service has written a starting message and a waiting message. The output is similar to the following, with /tmp in place of /var/run/postgresql on FreeBSD:

Guardioz Agent starting (interval=3600s, dsn=user=guardioz_monitor dbname=postgres host=/var/run/postgresql port=5432 )
Waiting 3600s before first collection (registration already sent a snapshot).

The second message mentions the registration because the agent prints the same line every time it starts. After an update it means only this: the next collection follows one full interval later. The message that proves a snapshot arrived comes with that collection:

Snapshot sent (HTTP 202)

To get a snapshot now instead of waiting for the next collection, run one collection by hand. See Manage the agent service.

Roll back to the version you had

Every update keeps a copy of the code that was running, next to the new code, as /opt/guardioz-agent/guardioz_agent.TIMESTAMP. A rollback moves that copy back into place and restarts the services. It restarts them exactly as an update does, so the next snapshot follows one full interval later.

To list the versions that are kept on the server, run the following on that server:

ls -d /opt/guardioz-agent/guardioz_agent.*

To go back to one of them, run the update command with two more arguments: --rollback, and directly after it the timestamp. Replace TIMESTAMP with the part of the directory name after guardioz_agent.:

Linux

curl -fsSL https://app.guardioz.com/static/update-agent.sh | sudo sh -s -- https://app.guardioz.com --rollback TIMESTAMP

FreeBSD

fetch -qo - https://app.guardioz.com/static/update-agent.sh | sh -s -- https://app.guardioz.com --rollback TIMESTAMP

The script ends with Rolled back to TIMESTAMP.. Two consequences follow:

• The restored version is no longer kept. That timestamp is gone, and a second rollback to it stops with a message that starts with Error: no kept version at and lists the timestamps of the versions that are left.
• The code that ran before the rollback is not kept. To return to the current agent code, run a normal update again.

Confirm a rollback the same way as an update: read the output for lines that begin with two spaces and an exclamation mark, then read the journal on the server, where the same starting message and waiting message appear.

Each update keeps one more version, and an update deletes none of them. Only a rollback consumes the version it restores. To remove a kept version yourself, delete its directory on the server, with administrator rights:

sudo rm -rf /opt/guardioz-agent/guardioz_agent.TIMESTAMP

That removes the way back to that version and nothing else. The agent runs from /opt/guardioz-agent/guardioz_agent and keeps running.

The arguments of the update command

Argument	What it does
The address	Names where the updater downloads the agent code from. The script compares it with the address in the agent’s configuration file and stops when the two differ. A trailing slash is ignored. It is required.
--rollback TIMESTAMP	Restores the version kept under that timestamp instead of updating. The timestamp comes directly after --rollback.
--allow-url-change	Downloads the agent code from the address you passed although the agent’s configuration file names a different one. It does not write the configuration file.

The arguments can come in any order. The script has no other arguments, and no option that prints its version or shows what it would do. An argument that it cannot read stops it before it changes anything, with a line that starts with Error: and names that argument. See Update and removal problems.

For a server registered in Guardioz you need no --allow-url-change. When the script stops with a message that starts with Error: the URL given, the address you passed is not the address the agent is configured with: run the command again with https://app.guardioz.com. Use the flag only for an address you control, because the agent code that this server installs and runs then comes from the address you pass.

The flag changes nothing in the configuration: the agent keeps sending its snapshots to the address that stands in its configuration file. To read that address, run the following on the server, with administrator rights:

sudo grep '^api_url' /etc/guardioz-agent/config-5432.yaml

Replace 5432 with the port of your PostgreSQL instance. The full message and what to do about it: Update and removal problems.

What an update changes, keeps and does not touch

An update changes the following on the server:

• the agent code under /opt/guardioz-agent, with the code that was running kept next to it;
• the agent services, which it restarts;
• on Linux, the system account that the agent’s service uses, which it creates when that account is missing;
• on Linux, the group and the mode of each agent configuration file, and each systemd unit file, which it writes again from the definition that the script carries;
• on FreeBSD, the group and the mode of each agent configuration file, each rc.d script and each log rotation rule under /usr/local/etc/newsyslog.conf.d, which it writes again from the definition that the script carries.

It writes nothing to the install manifest.

The update keeps the content of the agent’s configuration file as it is: the address, the collector key, the connection string, the interval and the log level. The server in Guardioz keeps its identity and its history, and the agent keeps the record of when its daily and weekly collections last ran. See Agent configuration.

The update touches nothing in PostgreSQL. It changes no role, no password and no pg_hba.conf line, and it reloads nothing. It also leaves the installed Python libraries as they are.

The update does not repair the permission that lets the agent reach the transaction-log directory. When that permission is gone, for example because the data directory was created again, Guardioz reports the disk figures of that directory as not measured, and the rest of the collection is not affected. What that permission is: What the installer changes on your server. How to have it granted again: Update and removal problems.

The install command is not an update

The install command sets a server up from the beginning. Running it again on a server that already has the agent does more than replace the code:

• It needs a new install command from Guardioz. A command is valid for 60 minutes and works once.
• It gives the monitoring role a new password, and Guardioz issues a new collector key. When the run connects to the existing server, the previous key stops working. In every other case the configuration file no longer holds it.
• It writes the agent’s configuration file again, so a change you made in that file by hand is lost.
• It keeps the server and its history only under one condition: the configuration file for that port still holds a working key for a server of your organization, and it names the same Guardioz address. In every other case the run adds a second server in Guardioz, and that server starts without history. Several checks read earlier snapshots, so on a server without history they start again from their first reading.

An install command that has expired or has been used still changes the password

The installer gives the monitoring role a new password before it sends the registration. When Guardioz then refuses the registration, the agent’s configuration file still holds the old password, and the running agent can no longer log in to PostgreSQL. To repair it, take a fresh install command as described in Install the agent, and run that command on the server to the end.

If something goes wrong

• The script refused to run, a service did not restart, or a rollback failed: Update and removal problems.
• The update finished and no snapshot arrives: Agent and data problems.
• Nothing matches what you see: write to contact@guardioz.com. For what to include, see Get help.

Next steps

Manage the agent serviceRead the log, restart the service, and run one collection now.

When the agent collectsWhat the agent collects every hour, every day and every week.

Remove Guardioz from a serverRemove the agent, undo the changes in PostgreSQL, and delete the server.