Skip to content

Commit

Permalink
Merge pull request #5573 from EnterpriseDB/docs/edits_to_PEM_pr5409
Browse files Browse the repository at this point in the history 
Edits to PEM pr5409
  • Loading branch information
@nidhibhammar
nidhibhammar authored May 15, 2024
2 parents 345712a + 1178897 commit 327533f
Show file tree
Hide file tree
Showing 6 changed files with 103 additions and 105 deletions.
8 changes: 4 additions & 4 deletions product_docs/docs/pem/8/managing_pem_agent.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,7 @@ A number of configurable parameters control the behavior of the PEM agent. On Li
Most agent configuration is managed automatically. We recommend against manually modifying any of these configuration parameters unless specifically directed to do so.

!!! Note
If you add, remove or modify any of the parameters the agent must be restarted to apply the changes.
If you add, remove, or modify any of the parameters, you must restart the agent to apply the changes .

On Linux systems, PEM configuration options are stored in the `agent.cfg` file, located in `/usr/edb/pem/agent/etc`. The `agent.cfg` file contains the following entries.

Expand Down Expand Up @@ -228,9 +228,9 @@ On Linux systems, PEM configuration options are stored in the `agent.cfg` file,
| heartbeat_connection | When set to TRUE, a dedicated connection is used for sending the heartbeats. | false |
| batch_script_dir | Provide the path where script file (for alerting) is stored. | /tmp |
| connection_custom_setup | Use to provide SQL code to invoke when a new connection with a monitored server is made. | Not set by default. |
| ca_file | The path to a CA certificate to be used instead of the platform default for verifying webhook server certificates. Note this can be overridden with the `--webhook_ssl_ca_crt` option when defining webhooks. | Not set by default. |
| ca_file | The path to a CA certificate to be used instead of the platform default for verifying webhook server certificates. When defining webhooks, you can override this behavior with the `--webhook_ssl_ca_crt` option. | Not set by default. |
| batch_script_user | Provide the name of the user to use for executing the batch/shell scripts. | None |
| **Webhook parameters** | The following options can be specified multiple times, each time preceded by a header of the form `[WEBHOOK/<name>]` where `<name>` is the name of a previously created webhook. These settings are automatically added when webhooks are created. It is not recommended to add them manually. ||
| **Webhook parameters** | You can specify the following options multiple times. Each time, precede the option with a header of the form `[WEBHOOK/<name>]`, where `<name>` is the name of a previously created webhook. These settings are automatically added when webhooks are created. We don't recommend adding them manually. ||
| webhook_ssl_key | The complete path to the webhook's SSL client key file. | |
| webhook_ssl_crt | The complete path to the webhook's SSL client certificate file. | |
| webhook_ssl_crl | The complete path of the CRL file to validate webhook server certificate. | |
Expand Down Expand Up @@ -268,7 +268,7 @@ The registry contains the entries shown in the table.
| BatchScriptDir | Provide the path to store the script file for alerting. | /tmp |
| ConnectionCustomSetup | Use to provide SQL code to invoke when a new connection with a monitored server is made. | Not set by default. |
| AllowBatchJobSteps | If set to true, the batch/shell scripts are executed. Scripts are executed by the user account under which the PEM agent is running. | None |
| **Webhook parameters**| The following options can be specified multiple times and must be placed in a subkey `Software\EnterpriseDB\PEM\agent\WEBHOOK\<name>` where `<name>` is the name of a previously created webhook. These settings are automatically added when webhooks are created. It is not recommended to add them manually.||
| **Webhook parameters**| You can specify the following options multiple times. Place them in a subkey `Software\EnterpriseDB\PEM\agent\WEBHOOK\<name>`, where `<name>` is the name of a previously created webhook. These settings are automatically added when webhooks are created. We don't recommend adding them manually.||
| WebhookSSLKey | The complete path to the webhook's SSL client key file. | |
| WebhookSSLCrt | The complete path to the webhook's SSL client certificate file. | |
| WebhookSSLCrl | The complete path of the CRL file to validate webhook server certificate. | |
Expand Down
26 changes: 13 additions & 13 deletions product_docs/docs/pem/8/registering_agent.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,20 @@ redirects:
---

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 the instructions below.
**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`, which you can use to perform management tasks, including registering the PEM agent, as described [below](#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.
If you don't want the installer to register the agent, uncheck the `register now` checkbox. For more details, refer to the [installation instructions](/pem/latest/installing/windows/).
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](/pem/latest/installing/windows/).

## Registering a PEM agent using the pemworker utility
The the pemworker utility is installed automatically with the PEM Agent. It is 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 as shown below and add the relevant options from the table as needed. Follow each option with a corresponding value.
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

Expand Down Expand Up @@ -73,16 +73,16 @@ set PEM_SERVER_PASSWORD=edb
### 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:
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 are prompted for any other missing required information. When the registration is complete, the server confirms that the agent was successfully registered.
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, invoking the pemworker utility as shown below.
You can use the pemworker utility to unregister a PEM agent. To unregister an agent, invoke the pemworker utility as shown.

#### Linux
``` shell
Expand All @@ -95,15 +95,15 @@ pemworker --unregister-agent
./pemworker.exe UNREGISTER-AGENT
```

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

| 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"`. |

## Advanced usage
This section describes some advanced options for PEM agent registration.
These are some advanced options for PEM agent registration.

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

Expand Down Expand Up @@ -161,7 +161,7 @@ To use a non-root user account to register a PEM agent, you must first install t

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

Expand Down Expand Up @@ -192,4 +192,4 @@ To use a non-root user account to register a PEM agent, you must first install t
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.
Any probes and jobs that require root permission or access to a file owned by another user (for example, enterprisedb) fail.
Loading

0 comments on commit 327533f

Please sign in to comment.