Install agents:

# apt install ppem-agent

The ppem-agent.yml agent configuration file will be downloaded to your local device.

Create the DBMS user on behalf of which the agent will connect to the managed DBMS server database:

# sudo -u postgres createuser --pwprompt ppem_agent

When executing this command, specify the DBMS user password.

Grant the DBMS user the privilege to read the system catalog and run functions.

It is recommended to grant the following privileges:

GRANT pg_monitor, pg_maintain, pg_signal_backend, pg_read_all_settings TO ppem_agent;

Grant the DBMS user the following privileges on every database in the instance:

GRANT EXECUTE ON FUNCTION pg_catalog.pg_stat_file(TEXT) TO ppem_agent;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_stat_file(TEXT, BOOLEAN) TO ppem_agent;
GRANT SELECT ON pg_catalog.pg_statistic TO ppem_agent;
GRANT SELECT ON pg_catalog.pg_config TO ppem_agent;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_config() TO ppem_agent;
GRANT SELECT ON pg_catalog.pg_file_settings TO ppem_agent;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_show_all_file_settings() TO ppem_agent;
GRANT SELECT ON pg_catalog.pg_authid TO ppem_agent;

Grant the DBMS user the following privileges to manage backups:

ALTER ROLE ppem_agent WITH REPLICATION;

GRANT USAGE ON SCHEMA pg_catalog TO ppem_agent;
GRANT EXECUTE ON FUNCTION pg_catalog.current_setting(text) TO ppem_agent;
GRANT EXECUTE ON FUNCTION pg_catalog.set_config(text, text, boolean) TO ppem_agent;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_is_in_recovery() TO ppem_agent;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_backup_start(text, boolean) TO ppem_agent;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_backup_stop(boolean) TO ppem_agent;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_create_restore_point(text) TO ppem_agent;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_switch_wal() TO ppem_agent;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_last_wal_replay_lsn() TO ppem_agent;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current() TO ppem_agent;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current_snapshot() TO ppem_agent;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_snapshot_xmax(txid_snapshot) TO ppem_agent;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_control_checkpoint() TO ppem_agent;

You can grant privileges only for the database that will be used for connecting the user to the instance.

For more information about privileges, refer to the official Postgres Pro documentation on pg_probackup.

Ensure that the DBMS user can connect to the repository database:

# psql -h localhost -U ppem_agent -d ppem

In case of connection issues, ensure that the HBA rule allowing the DBMS user to connect to the database, as well as the authorization method, are specified in the pg_hba.conf configuration file.

For more information, refer to the official Postgres Pro documentation on the pg_hba.conf configuration file.

Get an API key to configure the agent:

In the ppem-agent.yml agent configuration file, specify agent parameters:

agent:
  name: "agent_name"
  manager:
    url: "URL_for_connecting_to_manager"
    api_key: "API_key_for_connecting_to_manager"
instance:
  connection_defaults:
    user: "DBMS_username"
    password: "DBMS_user_password"
http:
  server:
    address: "network_address_for_incoming_connections"
    port: "port_for_incoming_connections"

Where:

Create the main agent catalog and make the operating system user its owner:

  sudo mkdir /var/lib/ppem
  sudo chown ppem:ppem /var/lib/ppem

The main agent catalog is used for storing instances and their parameters, instance management units, and local storages.

Create additional agent catalogs:

  mkdir /var/lib/ppem/{instances,postgresql,systemd,backups}

You must specify the /var/lib/ppem/instances catalog when creating instances and the /var/lib/ppem/backups catalog when creating local storages.

Create a catalog for configuring systemd:

  sudo mkdir /etc/systemd/system.conf.d

Create the systemd configuration file:

  sudo nano /etc/systemd/system.conf.d/custom_path.conf

In the systemd configuration file, specify:

  [Manager]
  ManagerEnvironment="SYSTEMD_UNIT_PATH=/var/lib/ppem/systemd:"

Add the operating system user to the group for working with instances:

  sudo usermod -aG postgres ppem

In the sudoers configuration file, enable the operating system user to execute commands under the superuser by specifying:

  Cmnd_Alias PG_SYS_V = /usr/bin/systemctl status postgres*.service, \
  /usr/bin/systemctl start postgres*.service, \
  /usr/bin/systemctl stop postgres*.service, \
  /usr/bin/systemctl restart postgres*.service, \
  /usr/bin/systemctl reload postgres*.service, \
  /usr/bin/systemctl enable postgres*.service, \
  /usr/bin/systemctl disable postgres*.service, \
  /usr/bin/systemctl daemon-reload, \
  /usr/bin/mkdir --parents /var/lib/ppem/*, \
  /usr/bin/mkdir /var/lib/ppem/*, \
  /usr/bin/chmod --recursive 0[5-7][0-7][0-7] /var/lib/ppem/*, \
  /usr/bin/chmod 0[5-7][0-7][0-7] /var/lib/ppem/*, \
  /usr/bin/chown --recursive [a-z]*\:[a-z]* /var/lib/ppem/*, \
  /usr/bin/chown [a-z]*\:[a-z]* /var/lib/ppem/*, \
  /usr/bin/echo, \
  /usr/bin/test, \
  /usr/bin/sh -c /usr/bin/echo, \
  /usr/bin/mv, \
  /usr/bin/rm /var/lib/ppem/*, \
  /usr/bin/rm /tmp/*, \
  /usr/bin/rm --recursive --force /var/lib/ppem/*

  Cmnd_Alias PG_CTL_V = /usr/lib/postgresql/17/bin/pg_ctl, \
  /usr/lib/postgresql/17/bin/initdb, \
  /opt/pgpro/ent-17/bin/initdb, \
  /opt/pgpro/ent-17/bin/pg_ctl, \
  /opt/pgpro/ent-17/bin/pg_probackup

  ppem ALL = (root) NOPASSWD:SETENV: PG_SYS_V
  ppem ALL = (postgres) NOPASSWD:SETENV: PG_CTL_V

In the ppem-agent.yml agent configuration file, specify:

  system:
    postgresql_configs_path: "/var/lib/ppem/postgresql"
    systemd_units_path: "/var/lib/ppem/systemd"

Restart the server:

  sudo reboot

Configure the agent service to start on behalf of the operating system user:

Start the agent service and add it to the server startup:

# systemctl start ppem-agent
# systemctl enable ppem-agent