1. Ensure that prerequisites are met.

2. Create operating system users.

3. Configure the manager.

4. Configure agents.

Prerequisites

1. Prepare servers for installing PPEM according to hardware and software requirements.

   You will need at least one server.

2. Install a Postgres Pro DBMS instance on at least one server.

   For more information about installation, refer to the official Postgres Pro documentation.

Creating Operating System Users

Create separate operating system users on all servers:

# useradd ppem

Manager and agent services will start under these operating system users.

Configure the Manager

On the Postgres Pro DBMS instance server:

1. Install the repository:

   # wget -O pgpro-repo-add.sh https://repo.postgrespro.ru/ppem/ppem/keys/pgpro-repo-add.sh
   # sh pgpro-repo-add.sh
   

2. Install the manager:

   # apt install ppem ppem-gui
   

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

3. Create a DBMS user on behalf of whom the manager will connect to the repository database:

   # sudo -u postgres createuser --pwprompt ppem
   

   When executing this command, specify the DBMS user password.

4. Create the repository database:

   # sudo -u postgres createdb -O ppem ppem
   

5. Ensure that the DBMS user can connect to the database:

   # psql -h localhost -U ppem -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.

6. In the ppem-manager.yml manager configuration file:

   • Specify the repository database name using the repo.name parameter:

     repo:
       name: "ppem"
     

   • Specify the DBMS username and password using repo.user and repo.password parameters:

     repo:
       user: "ppem"
       password: "DBMS_user_password"
     

   • Specify the URL for connecting the manager to the repository database using the repo.url parameter:

     repo:
       url: "postgres://ppem:DBMS_user_password@localhost/ppem"
     

     For more information about the URL format, refer to the official Postgres Pro documentation on connection strings.

7. Configure the manager service to start under the operating system user:

   1. Start editing the systemd unit:

      # systemctl edit ppem
      

   2. In the [Service] section, specify the name of the operating system user:

      [Service]
      User=ppem
      

   3. Ensure that the operating system user is granted the privilege to read the ppem-manager.yml manager configuration file.

      If the privilege is not granted, execute:

      # chown ppem:ppem /etc/ppem-manager.yml
      # chmod 400 /etc/ppem-manager.yml
      

   4. Save systemd unit parameters, then reload it:

      # systemctl daemon-reload
      

8. Start the manager service and add it to the server startup:

   # systemctl start ppem
   # systemctl enable ppem
   

Configuring Agents

On all servers:

1. Install agents:

   # apt install ppem-agent
   

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

2. Create the DBMS user on behalf of which the agent will connect to the repository database:

   # sudo -u postgres createuser --pwprompt ppem_agent
   

   When executing this command, specify the DBMS user password.

3. 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.

4. 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.

5. Get an API key for configuring the agent:

   1. Log in to the web application.

   2. Copy the API key from the displayed agent installation instruction and save this key.

6. 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:

   • agent.name: The unique agent name.

   • agent.manager.url: The URL for connecting the agent to the manager in the scheme://manager_network_address/path_to_API_version format.

   • agent.manager.api_key: The previously obtained API key for connecting the agent to the manager.

   • agent.instance.connection_defaults.user and agent.instance.connection_defaults.password: The DBMS user name and password.

   • http.server.address and http.server.port: The network address of the server and the port number for incoming network connections.

     To enable listening of all network addresses and ports, do not specify any values for these parameters.

7. 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.

8. 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.

9. Create a catalog for configuring systemd:

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

10. Create the systemd configuration file:

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

11. In the systemd configuration file, specify:

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

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

      sudo usermod -aG postgres ppem
    

13. 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
    
      pgpro ALL = (root) NOPASSWD:SETENV: PG_SYS_V
      pgpro ALL = (postgres) NOPASSWD:SETENV: PG_CTL_V
    

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

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

15. Restart the server:

      sudo reboot
    

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

    1. Start editing the systemd unit:

       # systemctl edit ppem-agent
       

    2. In the [Service] section, specify the operating system user:

       [Service]
       User=ppem
       

    3. Ensure that the operating system user is granted the privilege to read the ppem-agent.yml agent configuration file.

       If the privilege is not granted, execute:

       # chown ppem:ppem /etc/ppem-agent.yml
       # chmod 400 /etc/ppem-agent.yml
       

    4. Save systemd unit parameters, then reload it:

       # systemctl daemon-reload
       

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

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