Skip to content

Commit

Permalink
Edits to Clarify which values are optional. #6346
Browse files Browse the repository at this point in the history
  • Loading branch information
@ebgitelman
ebgitelman committed Jan 10, 2025
1 parent d41dd1e commit 75cad88
Showing 1 changed file with 31 additions and 25 deletions.
56 changes: 31 additions & 25 deletions product_docs/docs/pem/9/registering_agent.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,21 +11,23 @@ redirects:
- /pem/latest/pem_online_help/02_toc_pem_agent/07_pem_agent_self_registration/
---

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.
Before you can use a PEM agent, 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, 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](#registering-a-pem-agent-using-the-pemworker-utility).

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](#registering-a-pem-agent-using-the-pemworker-utility).

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](/pem/latest/installing/windows/).

## 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.
The pemworker utility is installed with the PEM agent. It's located in `/usr/edb/pem/agent/bin` 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
Expand All @@ -48,23 +50,23 @@ set PEM_SERVER_PASSWORD=edb
|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--pem-server` | The IP address of the PEM backend database server. This parameter is required. |
| `--pem-port` | The port of the PEM backend database server. The default value is `5432`. |
| `--pem-user` | The name of a database user with the `pem_admin` role and the `rolcreaterole` flag set (or a superuser) on the PEM backend database server. This user will be used to connect to the PEM server to perform agent registration. This parameter is required. |
| `--pem-agent-user` | The name of a database user on the PEM backend database server. After registration, the agent will use this user to open connections to the PEM database server to write probe data, evaluate alerts, etc. This parameter is optional. If omitted, the agent will connect using a new user created during registration named `agent<N>` where `<N>` is the agent ID. Note that this user is always created and even if you specify a `pem-agent-user` the agent will use `SET ROLE agent<N>` to switch roles after the connection is made. |
| `--pem-ssl-mode` | The [SSL mode](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION) to be used by the PEM agent user (see above). The possible values are `prefer`, `require`,`disable`,`verify-CA`, and `verify-full`. The default value is `require`. |
| `--cert-path` | The complete path to a directory in which certificates will be stored. If you don't provide a path, certificates are created in `~/.pem` on Linux and `%APPDATA%/pem` on Windows. |
| `--pem-user` | The name of a database user with the pem_admin role and the `rolcreaterole` flag set on the PEM backend database server, or a superuser. This user will be used to connect to the PEM server to perform agent registration. This parameter is required. |
| `--pem-agent-user` | The name of a database user on the PEM backend database server. After registration, the agent will use this user to open connections to the PEM database server to write probe data, evaluate alerts, and so on. This parameter is optional. If this option is omitted, the agent connects using a new user named `agent<N>` created during registration, where `<N>` is the agent ID. This user is always created. Even if you specify a `pem-agent-user`, the agent will use `SET ROLE agent<N>` to switch roles after the connection is made. |
| `--pem-ssl-mode` | The [SSL mode](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION) for the PEM agent user to use (see above). The possible values are `prefer`, `require`, `disable`, `verify-CA`, and `verify-full`. The default value is `require`. |
| `--cert-path` | The complete path to a directory in which to store certificates. If you don't provide a path, certificates are created in `~/.pem` on Linux and `%APPDATA%/pem` on Windows. |
| `--config-dir` | The directory path for the configuration file. The default is `<pemworker path>/../etc`. |
| `--display-name` | A 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-registration` | Include 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`. |
| `--group` | The name of a group in which to place the agent. This parameter is optional, if omitted the agent will not be placed in a group. |
| `--team` | The name of a database role on the PEM backend database server. Access to this agent will be restricted to only the named role, the owner, and the `pem_admin` role. This parameter is optional. No team will be assigned if omitted, meaning all users can access this agent. |
| `--owner` | The name of a database user on the PEM backend database server. This user will be assigned as the owner of the agent. The specified `pem-user` will be assigned as the owner if omitted. |
| `--allow_server_restart` | Enable the `allow_server_restart` parameter to allow PEM to restart the monitored server. The default value is `True`. |
| `--allow-batch-probes` | Enable the `allow-batch-probes` parameter to allow PEM to run batch probes on this agent. The default value is `False`. |
| `--batch-script-user` | The 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-connection` | Enable 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-smtp` | Enable 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-snmp` | Enable 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`. |
| `-o` | Used to override the configuration file options. See the below [example](#overriding-default-configurations---examples) for usage. |
| `--group` | The name of a group in which to place the agent. This parameter is optional. If omitted, the agent isn't placed in a group. |
| `--team` | The name of a database role on the PEM backend database server. Access to this agent is restricted to only the named role, the owner, and the pem_admin role. This parameter is optional. If omitted, no team is assigned, meaning all users can access this agent. |
| `--owner` | The name of a database user on the PEM backend database server. This user will be assigned as the owner of the agent. If omitted, the specified `pem-user` is assigned as the owner. |
| `--allow_server_restart` | Allow PEM to restart the monitored server. The default value is `True`. |
| `--allow-batch-probes` | Allow PEM to run batch probes on this agent. The default value is `False`. |
| `--batch-script-user` | The operating system user to use for executing the batch/shell scripts. The default value is none. If you leave this parameter blank or the specified user doesn't exist, the scripts don't execute. |
| `--enable-heartbeat-connection` | Create a dedicated heartbeat connection between the PEM agent and server to update the active status. The default value is `False`. |
| `--enable-smtp` | Allow the PEM agent to send the email on behalf of the PEM server. The default value is `False`. |
| `--enable-snmp` | Allow the PEM agent to send the SNMP traps on behalf of the PEM server. The default value is `False`. |
| `-o` | Override the configuration file options. See the following [example](#overriding-default-configurations---examples) for usage. |

!!! Note 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.
Expand Down Expand Up @@ -102,18 +104,21 @@ When invoking the pemworker utility, append command line options to the command

| Option | Description |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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-dir` | Specifies the directory path for the configuration file. The default is `"<pemworker path>/../etc"`. |
| `--pem-user <username>` | The name of the database user (member of pem_admin role) of the PEM backend database server. This parameter is required. |
| `--config-dir` | 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).

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 [in these examples](#overriding-default-configurations---examples).

### Overriding default configurations - examples
This example shows how to register the PEM agent overriding the default configurations.

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

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

Expand All @@ -129,7 +134,7 @@ __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.
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, an error occurs.

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.

Expand All @@ -155,9 +160,10 @@ __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.
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 aren't valid or don't have proper permissions, an error occurs.

### 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:
Expand Down Expand Up @@ -228,7 +234,7 @@ To use a non-root user account to register a PEM agent, you must first install t
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:
b. Stop the running agent process and restart the agent service:

```shell
# Find the process id of the running pem agent and pem worker process and kill that process
Expand Down

0 comments on commit 75cad88

Please sign in to comment.