Registering a PEM agent v8

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.

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 pemworker. 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, invoke the utility and add the relevant options from the table as needed. Follow each option with a corresponding value.

Linux

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

Windows

set PEM_SERVER_PASSWORD=edb
# Running as admin
./pemworker.exe REGISTER

Authenticating the pemworker utility

Before any changes are made on the PEM database, the connecting 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.

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.

Advanced usage

These are some advanced options for PEM agent registration.

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:

   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 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
• How to register PEM agents
• Registering a PEM agent using the pemworker utility
• Unregistering a PEM agent
• Advanced usage