Registering a PEM agent v9

Before a PEM agent can be used, you must register it with a PEM server. PEM agents installed by the PEM server package are registered automatically during server configuration. For all other agents, you must follow these instructions.

Note

After upgrading the PEM agent, you need to restart it. You don't need to register it again.

How to register PEM agents

On Linux and Windows hosts, the PEM agent package includes a command line utility called pemworker,. You can use it to perform management tasks, including registering the PEM agent.

On Windows, the PEM agent graphical installer allows you to register the agent when installing it. This convenience option doesn't support all the possibilities provided by the pemworker utility. If you don't want the installer to register the agent, clear the Register now checkbox. For more details, see the installation instructions.

Registering a PEM agent using the pemworker utility

The pemworker utility is installed automatically with the PEM agent. It's located in the /usr/edb/pem/agent/bin directory on Linux and C:\Program Files\edb\pem\agent-x64\bin on Windows. To register an agent, set the PEM server password, invoke the utility as shown in the examples, and add the relevant options from the table as needed. Follow each option with a corresponding value.

Linux

export PEM_SERVER_PASSWORD=edb
# Running as root
pemworker --register-agent

Windows

set PEM_SERVER_PASSWORD=edb
# Running as admin
./pemworker.exe REGISTER
OptionDescription
--pem-serverThe IP address of the PEM backend database server. This parameter is required.
--pem-portThe port of the PEM backend database server. The default value is 5432.
--pem-userThe name of the database user having superuser privileges of the PEM backend database server. This parameter is required.
--pem-agent-userThe agent user to connect the PEM server backend database server.
--cert-pathThe complete path to the directory where certificates are created. If you don't provide a path, certificates are created in ~/.pem on Linux and %APPDATA%/pem on Windows.
--config-dirThe directory path for the configuration file. The default is <pemworker path>/../etc.
--display-nameA user-friendly name for the agent to display in the PEM browser tree. In PEM 9.6 and later, the default is the host's fully qualified domain name (FQDN), falling back to the hostname if this option isn't set. For releases earlier than PEM 9.6, the default is the hostname.
--force-registrationInclude the force_registration clause to register the agent with the arguments provided. This clause is useful if you're overriding an existing agent configuration. The default value is Yes.
--groupThe name of the group in which the agent is displayed.
--teamThe name of the database role on the PEM backend database server with access to the monitored database server.
--ownerThe name of the database user on the PEM backend database server who owns the agent.
--allow_server_restartEnable the allow_server_restart parameter to allow PEM to restart the monitored server. The default value is True.
--allow-batch-probesEnable the allow-batch-probes parameter to allow PEM to run batch probes on this agent. The default value is False.
--batch-script-userThe operating system user to use for executing the batch/shell scripts. The default value is none. The scripts don't execute if you leave this parameter blank or the specified user doesn't exist.
--enable-heartbeat-connectionEnable the enable-heartbeat-connection parameter to create a dedicated heartbeat connection between the PEM agent and server to update the active status. The default value is False.
--enable-smtpEnable the enable-smtp parameter to allow the PEM agent to send the email on behalf of the PEM server. The default value is False.
--enable-snmpEnable the enable-snmp parameter to allow the PEM agent to send the SNMP traps on behalf of the PEM server. The default value is False.
-oSpecifies whether you want to override the configuration file options.
Allowing the agent to restart the database server

If you use any feature of PEM that requires a database server restart by the PEM agent (such as Audit Manager, Log Manager, or the Tuning Wizard), then you must set the value of allow_server_restart to true in the agent.cfg file or restart the server manually for changes to take effect.

Running shell/batch jobs

If you want to run shell/batch jobs using an agent, you must specify the user for the batch_script_user parameter. We strongly recommend that you use a non-root user to run the scripts. Using the root user might result in compromising the data security and operating system security.

Authenticating the pemworker utility

Before any changes are made on the PEM database, the connection is authenticated with the PEM database server. When invoking the pemworker utility, you must provide the password associated with the PEM server administrative user role (postgres). You can specify the administrative password in three ways:

  • Set the PEM_SERVER_PASSWORD environment variable.
  • Provide the password on the command line with the PGPASSWORD keyword.
  • Create an entry in the .pgpass file.

If you don't provide the password, a password authentication error occurs. After authentication succeeds, you're prompted for any other missing required information. When the registration is complete, the server confirms that the agent was successfully registered.

Unregistering a PEM agent

You can use the pemworker utility to unregister a PEM agent. To unregister an agent, invoke the pemworker utility as shown in the examples that follow.

Linux

# Running as root
pemworker --unregister-agent

Windows

./pemworker.exe UNREGISTER-AGENT

When invoking the pemworker utility, append command line options to the command string. Follow each option with a corresponding value.

OptionDescription
--pem-user <username>Specifies the name of the database user (member of pem_admin role) of the PEM backend database server. This parameter is required.
--config-dirSpecifies the directory path for the configuration file. The default is "<pemworker path>/../etc".

Advanced usage

The following are some advanced options for PEM agent registration.

Setting the agent ID

Each registered PEM agent must have a unique agent ID. The value max(id)+1 is assigned to each agent ID unless a value is provided using the -o options as shown below.

Overriding default configurations - examples

This example shows how to register the PEM agent overriding the default configurations.

Register the PEM agent using the command line. Assign an agent_id value of 8 using the -o option.

# Running as root
/usr/edb/pem/agent/bin/pemworker --register-agent \
--pem-server pemserver \
--pem-user postgres \
--pem-port 5432 \
--display-name agent8 \
-o agent_id=8
Output
Postgres Enterprise Manager Agent registered successfully!

Because the agent_id of 8 is available, the PEM agent registers successfully. If the given ID is already in use by the existing agent, it throws an error.

Register the PEM agent using the command line. Assign the existing SSL certificates and key files to avoid generating new ones for a particular agent ID. The SSL certificates and key files must be valid for the database user agent<ID>, where <ID> must be the same as provided using the command line. Use the -o option.

# Running as root
# List the location of valid SSL certificates and key files.
ls -l /root/.pem/agent5.*
-rw------- 1 root root 2192 Nov  7 11:27 /root/.pem/agent5.crt
-rw------- 1 root root 3244 Nov  7 11:27 /root/.pem/agent5.key
   
# Register the PEM agent using command line. Assign the 
# SSL certificates and key files using the -o option.
/usr/edb/pem/agent/bin/pemworker --register-agent \
--pem-server pemserver \
--pem-user postgres \
--pem-port 5432 \
--config-dir /tmp/pem-config \
--display-name agent5 \
-o agent_id=5 \
-o agent_ssl_crt=/root/.pem/agent5.crt \
-o agent_ssl_key=/root/.pem/agent5.key
Output
Postgres Enterprise Manager Agent registered successfully!

Because the valid SSL certificates and key files are available at the given location with proper permissions, the PEM agent registers successfully. If the certificate or key files are not valid or do not have proper permissions it throws an error.

Using a non-root user account to register a PEM agent on Linux

To use a non-root user account to register a PEM agent, you must first install the PEM agent as a root user. After installation, assume the identity of a non-root user, such as edb. Then:

  1. Log in as edb. Create pem and logs directories and assign read, write, and execute permissions:

    # Running as nonroot user edb
    mkdir /home/edb/pem
    mkdir /home/edb/pem/logs
    chmod 700 /home/edb/pem
    chmod 700 /home/edb/pem/logs
  2. Register the agent with PEM server:

    export PEM_SERVER_PASSWORD=edb
    
    # Use the following command to create agent certificates and an agent 
    # configuration file (`agent.cfg`) in the `/home/edb/pem` directory. 
    /usr/edb/pem/agent/bin/pemworker --register-agent --pem-server <172.19.11.230> --pem-user postgres --pem-port 5432 --display-name non_root_pem_agent --cert-path /home/edb/pem --config-dir /home/edb/pem
    
    # Use the following command to assign read and write permissions to 
    # these files:
    chmod -R 600 /home/edb/pem/agent*
  3. Change the parameters of the agent.cfg file:

    vi /home/edb/pem/agent.cfg
    agent_ssl_key=/home/edb/pem/agent<id>.key
    agent_ssl_crt=/home/edb/pem/agent<id>.crt
    log_location=/home/edb/pem/worker.log
    agent_log_location=/home/edb/pem/agent.log

    Where <id> is the assigned PEM agent ID.

  4. Create a tmp directory, set the environment variable, and start the agent:

    mkdir /home/edb/pem/tmp
    
    # Create a script file, add the environment variable, give permissions, and execute:
    vi /home/edb/pem/run_pemagent.sh
    #!/bin/bash
    export TEMP=/home/edb/agent/tmp
    /usr/edb/pem/agent/bin/pemagent -c /home/edb/agent/agent.cfg
    chmod a+x /home/edb/pem/run_pemagent.sh
    cd /home/edb/pem
    ./run_pemagent.sh

    Your PEM agent is now registered and started with the edb user. If your machine restarts, then this agent doesn't restart automatically. You need to start it manually using the previous command.

  5. Optionally, you can create the service for this PEM agent as the root user to start this agent automatically at machine restart as follows:

    a. Update the values for the configuration file path and the user in the pemagent service file as superuser:

    # Running as superuser
    sudo vi  /usr/lib/systemd/system/pemagent.service
    [Service]
    Type=forking
    WorkingDirectory=/home/edb/pem
    Environment=LD_LIBRARY_PATH=/usr/edb/pem/agent/lib:/usr/libexec/edb-snmp++/lib 
    Environment=TEMP=/home/edb/pem/tmp
    ExecStart=/usr/edb/pem/agent/bin/pemagent -c /home/edb/pem/agent.cfg

    b. Stop the running agent process, and then restart the agent service:

    # Find the process id of the running pem agent and pem worker process and kill that process
    ps -ax | grep pemagent
    kill -9 <process_id_of_pemagent>
    ps -ax | grep pemworker
    kill -9 <process_id_of_pemworker>
    # Enable and start pemagent service
    sudo systemctl enable pemagent
    sudo systemctl start pemagent
    sudo systemctl status pemagent
  6. Check the agent status on the PEM dashboard.

Note
  • Any probes and jobs that require root permission or access to a file owned by another user (for example, enterprisedb) fail.
  • If you move the agent.cfg file from its default location to another, the PEM dashboard might display the agent status as unknown. See Troubleshooting agent issues, for more information.