3.3 Installing a PEM Agent

3.3 Installing a PEM Agent

The PEM agent executes tasks scheduled via the PEM server, and reports statistics from the agent's operating system and one or more monitored Postgres servers.

3.3.1 Using the Graphical Installer to Install an Agent

To invoke the PEM agent installer, assume superuser (or Administrative) privileges and navigate into the directory that contains the installer. Then, invoke the installer with the command:

pem_agent-7.x.x-x-platform.ext

The Setup… page opens, welcoming you to the PEM Agent installer (as shown in Figure 3.60).

Figure 3.60 - The PEM Agent Installer's Welcome dialog.

Click Next to continue to the License Agreement (shown in Figure 3.61).

Figure 3.61 - The PEM License Agreement.

Carefully review the license agreement before highlighting the appropriate radio button and accepting the agreement; click Next to continue to the Installation Directory dialog (shown in Figure 3.62).

Figure 3.62 - Specify an Installation Directory

By default, the PEM agent is installed in the /home/opt/PEM directory. You can accept the default installation directory, or modify the contents of the Installation Directory field, specifying an alternate installation directory for the PEM agent.

By default, the PEM agent installer places a certificate in ~root/.pem (on Linux) or in the Administrator’s %APPDATA%\pem directory (on Windows). Check the Show advanced options box to indicate that you would like the PEM agent installer to include a dialog that allows you to specify an alternate path for the certificate file.

Check the box next to Register now? to instruct the installer to register the newly installed PEM agent with the PEM server.

Click Next to continue to the PEM Server Installation Details dialog (shown in Figure 3.63).

Figure 3.63 - Provide PEM server installation details

Enter the connection details for the PEM server:

•	Specify the name or IP address of the system on which the PEM database server resides in the Host field. Please note: If the ApacheHTTPD web server and PEM database are hosted on different systems, you must specify the host of the PEM database.

•	Specify the name of the database superuser in the User Name field.

•	Specify the password associated with the database superuser in the Password field.

•	Specify the port that PostgreSQL is monitoring in the Port field.

Click Next to continue. The installer will attempt to connect to the server to verify that the details are correct.

Please Note: The PEM server must allow connections from the PEM agent installer. If you encounter a connection error, confirm the connection properties specified on the PEM Server Installation Details dialog are correct, and confirm that the pg_hba.conf file (on the PEM server) will allow a connection to the server described in the error message. For information about modifying the pg_hba.conf file, see Section 8.1.

Figure 3.64 - Specify a descriptive name for the PEM agent

The tree control displayed in the Browser panel of the PEM web interface displays the value entered in the Description field (shown in Figure 3.64) to identify the PEM agent. Specify a descriptive name for the agent, such as the hostname of the machine the agent is installed on, or a name that reflects the host's functionality.

Provide a descriptive name, or accept the default provided by the PEM agent host, and click Next to continue.

If you checked the Show advanced options checkbox shown in Figure 3.24, the Advanced options dialog opens (shown in Figure 3.65).

Figure 3.65 – Provide the certificate path

By default, the PEM agent installer places the certificate in the /root/.pem directory. Specify an alternate path for the certificate or accept the default and click Next.

The wizard is now ready to install the PEM agent; click Back to amend the installation directory, or Next to continue.

Figure 3.66 - The PEM Agent installation is ready to begin

Click Next on the Ready to Install dialog (shown in Figure 3.66) to instruct the installer to copy files to the system and register the agent on the PEM server.

Figure 3.67 - Progress bars mark the installation's progress

The PEM agent installer displays progress bars (shown in Figure 3.67) to mark the PEM agent's installation progress.

Figure 3.68 - The PEM Agent installation is complete

When the installation has completed, the PEM agent will be running and reporting operating system and host data to the PEM server. To start monitoring Postgres instances on the host of the PEM agent, they must now be added to PEM’s enterprise directory and bound to the agent.

3.3.2 Installing an Agent with an RPM Package

On a Linux system, you can use the yum package manager to install a PEM agent. Please note that before using a package manager to install the PEM agent, the host must contain the following packages:

epel-release

wxBase

After providing the pre-requisite packages, you can install the PEM agent:

1.	Download the edb-repo installation package from:

http://yum.enterprisedb.com/

The edb-repo package creates the repository configuration file (named edb.repo). The edb.repo file defines multiple repositories hosted at EnterpriseDB.com.

2.	Assume superuser privileges and use the following command to install the edb-repo package, and create the repository configuration file:

rpm -Uvh edb-repo-9.x-x.noarch.rpm

Where x specifies the version of the file.

Then, use your choice of editor to modify the configuration file, enabling the enterprisedb-tools and enterprisedb-dependencies repositories. The configuration file is named edb.repo; it resides in /etc/yum.repos.d.

To enable a repository, change the value of the enabled parameter to 1 and replace the user_name and password placeholders in the baseurl specification with your repository credentials. Contact EnterpriseDB for repository credentials.

For example:

[enterprisedb-tools]

name=EnterpriseDB Tools $releasever - $basearch

baseurl=http://user_name:password@yum.enterprisedb.com/tools/redhat/rhel-$releasever-$basearch

enabled=1

gpgcheck=1

gpgkey=file:///etc/pki/rpm-gpg/ENTERPRISEDB-GPG-KEY

 

[enterprisedb-dependencies]

name=EnterpriseDB Dependencies $releasever - $basearch

baseurl=http://user_name:password@yum.enterprisedb.com/dependencies/redhat/rhel-$releasever-$basearch

enabled=1

gpgcheck=1

gpgkey=file:///etc/pki/rpm-gpg/ENTERPRISEDB-GPG-KEY

 

[edbas96]

name=EnterpriseDB Advanced Server 9.6 $releasever - $basearch

baseurl=http://user_name:password@yum.enterprisedb.com/9.6/redhat/rhel-$releasever-$basearch

enabled=1

gpgcheck=1

gpgkey=file:///etc/pki/rpm-gpg/ENTERPRISEDB-GPG-KEY

 

 

3.	After modifying the content of the repository configuration file, you can use yum to install the PEM agent:

yum install pem-agent

When the installation is complete, yum will display a list of the installed packages and dependencies (see Figure 3.69).

Figure 3.69 – Using an RPM package to install the PEM agent.

When you install an RPM package that is signed by a source that is not recognized by your system, yum may ask for your permission to import the key to your local server. If prompted, and you are satisfied that the packages come from a trustworthy source, enter a y, and press Return to continue.

During the installation, yum may encounter a dependency that it cannot resolve. If it does, it will provide a list of the required dependencies that you must manually resolve.

3.3.2.1 Registering an Agent

After an installation, you must register the PEM agent. The registration process provides the PEM server with the information it needs to communicate with the agent. You can use the pemworker utility to register the agent if you:

•	install a PEM agent with an RPM package.

•	skip the PEM agent registration step during the agent installation.

The RPM installer places the PEM agent in the /usr/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. Each option should be followed by a corresponding value:

Option	Description
--pem-server	Specifies the IP address of the PEM server. This parameter is required.
--pem-user	Specifies the name of the PEM user. This parameter is required.
--pem-port	Specifies the port that PEM monitors for connections. The default value is 5432.
--certificate-path	Specifies the complete path to the directory in which certificates will be created. If you do not provide a path, certificates will be created in: On Linux, ~/.pem On Windows, %APPDATA%/pem
--display-name	Specifies a user-friendly name that will be displayed in the PEM Browser tree control. The default is the system hostname.
--force-registration	Include the force_registration clause to instruct the PEM server to register the agent with the arguments provided; this clause is usefule if you are overriding an existing agent configuration. The default value is Yes.

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). There are three ways to specify the administrative password; you can:

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

Failure to provide the password will result in a password authentication error; you will be prompted for any other required but omitted information. When the registration is complete, the server will confirm that the agent has been successfully registered.

Setting PEM Agent Configuration Parameters

The PEM agent RPM installer creates a sample configuration file named agent.cfg.sample. When you register the PEM agent, the pemworker program creates the actual agent configuration file (named agent.cfg). If you have performed an RPM installation, both files reside in /usr/pem-7.x/etc. You must modify the agent.cfg file, adding the following configuration parameter:

heartbeat_connection = true

You must also add the location of the ca-bundle.crt file (the certificate authority). 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 is 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, start the PEM agent service:

# /etc/init.d/pemagent

The service will confirm that it is starting the agent; when the agent is registered and started, it will be displayed on the Global Overview dashboard and in the Object browser tree control of the PEM web interface.

For more information about the agent configuration file, see Section 8.