Registering a PEM agent v8

You must register each PEM agent installed on a separate host with the PEM server. (The PEM agent is different from the PEM server host.) The registration process provides the PEM server with the information it needs to communicate with the agent. The PEM agent graphical installer for Windows supports self-registration for the agent. On a Linux host, you must use the pemworker utility to register the agent.

The PEM agent package installer places the PEM agent in the /usr/edb/pem/agent/bin directory. To register an agent, include the --register-agent keywords along with registration details when invoking the pemworker utility:

pemworker --register-agent

Append command line options to the command string when invoking the pemworker utility. Follow each option with a corresponding value.

If you want to use any PEM feature for which a database server restart is required by the pemagent (such as Audit Manager, Log Manager, or the Tuning Wizard), then you must set the value for allow_server_restart to true in the agent.cfg file.

Before any changes are made on the PEM database, the connecting agent 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_MONITORED_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. You are 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, include the --unregister-agent keywords along with the details when invoking the pemworker utility:

pemworker --unregister-agent

Append command line options to the command string when invoking the pemworker utility. Follow each option with a corresponding value:

Setting PEM agent configuration parameters

The PEM agent RPM installer creates a sample configuration file named agent.cfg.sample in the /usr/edb/pem/agent/etc directory. When you register the PEM agent, the pemworker program creates the actual agent configuration file, named agent.cfg.

You must add the location of the ca-bundle.crt certificate authority file. By default, the installer creates a ca-bundle.crt file in the location specified in your agent.cfg.sample file. You can copy the default parameter value from the sample file or, if you use a ca-bundle.crt file that's stored in a different location, specify that value in the ca_file parameter:

ca_file=/usr/libexec/libcurl-pem7/share/certs/ca-bundle.crt

Then, use a platform-specific command to start the PEM agent service. The service is named pemagent.

On a RHEL or CentOS 7.x or 8.x host, use systemctl to start the service:

systemctl start pemagent

The service confirms that it's starting the agent. When the agent is registered and started, it appears on the Global Overview dashboard and in the Object browser tree of the PEM web interface.

For information about using the pemworker utility to register a server, see Registering a database server.

Using a nonroot user account to register a PEM agent

To use a nonroot 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 nonroot user, such as edb. Then:

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

   Toggle WrapCopy

   $ 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:

   Toggle WrapCopy

   $ 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:

   Toggle WrapCopy

   $ 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:

   Toggle WrapCopy

   $ 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:

   Toggle WrapCopy

   $ 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:

   Toggle WrapCopy

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

• On this page
• Unregistering a PEM agent
• Setting PEM agent configuration parameters
• Using a nonroot user account to register a PEM agent