From 9c2a75cc574a6a220b70877d59b879ad6ea3c6fc Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Tue, 30 Apr 2024 17:54:41 -0400 Subject: [PATCH 01/11] Edits to PEM PR5409 --- .../docs/pem/8/managing_pem_agent.mdx | 8 ++--- product_docs/docs/pem/8/registering_agent.mdx | 30 +++++++++---------- 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/product_docs/docs/pem/8/managing_pem_agent.mdx b/product_docs/docs/pem/8/managing_pem_agent.mdx index 1513e05db79..b0dc064de2b 100644 --- a/product_docs/docs/pem/8/managing_pem_agent.mdx +++ b/product_docs/docs/pem/8/managing_pem_agent.mdx @@ -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, to apply the changes you must restart the agent. 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. @@ -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/]` where `` 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, preceded the option with a header of the form `[WEBHOOK/]`, where `` 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. | | @@ -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\` where `` 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\`, where `` 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. | | diff --git a/product_docs/docs/pem/8/registering_agent.mdx b/product_docs/docs/pem/8/registering_agent.mdx index 03f5172b182..13f6b3109d8 100644 --- a/product_docs/docs/pem/8/registering_agent.mdx +++ b/product_docs/docs/pem/8/registering_agent.mdx @@ -10,22 +10,22 @@ 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 gets installed 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 +### Linux ```shell # Running as root @@ -33,7 +33,7 @@ export PEM_SERVER_PASSWORD=edb pemworker --register-agent ``` -#### Windows +### Windows ```shell set PEM_SERVER_PASSWORD=edb @@ -73,29 +73,29 @@ 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 +### Linux ``` shell # Running as root pemworker --unregister-agent ``` -#### Windows +### Windows ``` shell ./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 | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -103,7 +103,7 @@ Append command line options to the command string when invoking the pemworker ut | `--config-dir` | Specifies the directory path for the configuration file. The default is `"/../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 From 0496ab7c45c6212b3da54bbe5fa27f1aa1d9eaa0 Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Thu, 2 May 2024 14:17:07 -0400 Subject: [PATCH 02/11] Edits to PEM PR5409 --- product_docs/docs/pem/8/registering_agent.mdx | 6 +- .../pem/8/registering_database_server.mdx | 64 +++++++++-------- .../modifying_agent_configuration.mdx | 14 ++-- product_docs/docs/pem/9/registering_agent.mdx | 38 +++++------ .../pem/9/registering_database_server.mdx | 68 +++++++++---------- 5 files changed, 94 insertions(+), 96 deletions(-) diff --git a/product_docs/docs/pem/8/registering_agent.mdx b/product_docs/docs/pem/8/registering_agent.mdx index 13f6b3109d8..c941bcb748a 100644 --- a/product_docs/docs/pem/8/registering_agent.mdx +++ b/product_docs/docs/pem/8/registering_agent.mdx @@ -22,7 +22,7 @@ On Windows, the PEM agent graphical installer allows you to register the agent w 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 gets installed 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 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 @@ -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: @@ -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. diff --git a/product_docs/docs/pem/8/registering_database_server.mdx b/product_docs/docs/pem/8/registering_database_server.mdx index 98f45b6df3c..cd95b605baa 100644 --- a/product_docs/docs/pem/8/registering_database_server.mdx +++ b/product_docs/docs/pem/8/registering_database_server.mdx @@ -14,7 +14,7 @@ You can bind a database server to a remote agent (an agent that resides on a dif ## How to register a Postgres server There are three methods to register a server: - - [Use the pemworker utility to register a database server](#using-the-pemworker-utility-to-register-a-server) from the command line on the host where the agent you wish to bind is located. + - [Use the pemworker utility to register a database server](#using-the-pemworker-utility-to-register-a-server) from the command line on the host where the agent you want to bind is located. - [Use automatic server discovery](#registering-a-server-with-automatic-server-discovery) in the PEM web application to automatically register Postgres servers located on the same host as an agent. - [Manually register a Postgres server](#manually-registering-a-database-server) by adding all the details in the PEM web application. @@ -22,25 +22,25 @@ There are three methods to register a server: Registering a server does two things: - - It adds the server to the server tree in the PEM web application allowing users to open connections from the web application to the server - - It binds the server to a particular agent, meaning that agent will open connections to the server to execute probes and scheduled jobs + - It adds the server to the server tree in the PEM web application, allowing users to open connections from the web application to the server. + - It binds the server to a particular agent, meaning that agent will open connections to the server to execute probes and scheduled jobs. !!! Note Connections from the agent to the monitored server -During agent registration, you are required to provide connection details for the agent to connect to the monitored server. As is normal for Postgres, you must specify the database to connect to. -However, the PEM Agent will monitor **every database accessible to the specified user**, not just the database specified. +During agent registration, you're required to provide connection details for the agent to connect to the monitored server. As you normally do for Postgres, you must specify the database to connect to. +However, the PEM agent will monitor **every database accessible to the specified user**, not just the database specified. -After registration, the agent opens a connection to the specified database. It uses this connection to determine which other databases it can connect to with the same user and then spawns one connection to each. +After registration, the agent opens a connection to the specified database. It uses this connection to determine the other databases it can connect to with the same user and then spawns one connection to each. !!! ## Using the pemworker utility to register a server -You can use the pemworker utility to register a Postgres server. During registration, the pemworker utility binds the new server to the agent that resides on the system from which you invoked the registration command. To register a server: +You can use the pemworker utility to register a Postgres server. During registration, the pemworker utility binds the new server to the agent that resides on the system from which you invoked the registration command. -On a Linux host, use the command: +To register a server on a Linux host, use the command: `pemworker --register-server` -On a Windows host, use the command: +To register a server on a Windows host, use the command: `pemworker.exe REGISTER-SERVER` @@ -48,26 +48,26 @@ Append command line options to the command string when invoking the pemworker ut | Option                           | Description | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--pem-user` | Specifies the name of the PEM administrative user (must have the `pem_admin` role) on the PEM server to be used to write the server details to the PEM database. **Required**. | -| **Server parameters** | These parameters are used to populate the connection properties in the PEM web application. They are used when a user connects from the PEM web application to the monitored server. They are also used for connections from the agent to the monitored server unless overridden by Agent Server Binding parameters (see below). | -| `--server-addr` | Specifies the IP address or fully qualified domain name of the monitored server. On Linux systems, you can leave the address field blank to use the default PostgreSQL Unix Domain Socket on the local machine. Or you can set it to an alternate path containing a PostgreSQL socket. If you enter a path, the path must begin with a forward slash (/). **Required**. | -| `--server-port` | Specifies the port number of the monitored server. **Required**. | -| `--server-database` | Specifies the name of the database on the monitored server to which to connect. **Required**. | -| `--server-user` | Specifies the name of the user used to connect to the monitored server. **Required**. | -| `--server-service-name` | Specifies the name of the operating system service that manages the monitored Postgres server. For example, a systemd service unit on Linux. Optional. | -| **Agent-server binding parameters** | These parameters are used to override the server parameters above. Use these if you wish the agent to connect to the monitored server using different credentials than those used by the PEM web application. | +| `--pem-user` | Specifies the name of the PEM administrative user (must have the pem_admin role) on the PEM server to use to write the server details to the PEM database. Required. | +| **Server parameters** | These parameters are used to populate the connection properties in the PEM web application. They're used when a user connects from the PEM web application to the monitored server. They are also used for connections from the agent to the monitored server unless overridden by Agent Server Binding parameters (see **Agent-server binding parameters** in this table). | +| `--server-addr` | Specifies the IP address or fully qualified domain name of the monitored server. On Linux systems, you can leave the address field blank to use the default PostgreSQL Unix Domain Socket on the local machine. Or you can set it to an alternative path containing a PostgreSQL socket. If you enter a path, the path must begin with a forward slash (/). Required. | +| `--server-port` | Specifies the port number of the monitored server. Required. | +| `--server-database` | Specifies the name of the database on the monitored server to which to connect. Required. | +| `--server-user` | Specifies the name of the user used to connect to the monitored server. Required. | +| `--server-service-name` | Specifies the name of the operating system service that manages the monitored Postgres server, for example, a systemd service unit on Linux. Optional. | +| **Agent-server binding parameters** | These parameters are used to override the server parameters. Use these if you want the agent to connect to the monitored server using different credentials from those used by the PEM web application. | | `--asb-host-name` | Specifies the IP address or fully qualified domain name of the monitored server. Optional, defaults to `--server-addr` if not supplied. | | `--asb-host-port` | Specifies the port number of the monitored server. Optional, defaults to `--server-port` if not supplied. | | `--asb-host-db` | Specifies the name of the database on the monitored server to which the agent connects. Optional, defaults to `--server-database` if not supplied. | | `--asb-host-user` | Specifies the name of the user used by the agent to connect to the monitored server. Optional, defaults to `--server-user` if not supplied. | -| `--asb-ssl-mode` | Specifies the type of SSL authentication to use for connections. Supported values include: `prefer`, `require`, `disable`, `verify-CA`, `verify-full`. Optional, defaults to `prefer`. | +| `--asb-ssl-mode` | Specifies the type of SSL authentication to use for connections. Supported values include: `prefer`, `require`, `disable`, `verify-CA`, and `verify-full`. Optional, defaults to `prefer`. | | **Server metadata** | These parameters determine how the server is shown in the PEM web application. | | `--group` | Specifies the name of the group in which the server is displayed. Optional. | -| `--team` | Specifies a Postgres role on the PEM server to be assigned as the 'team' to which the monitored server belongs. Only users with this role will be able to access the server. Optional, defaults to none, meaning all users can access. | +| `--team` | Specifies a Postgres role on the PEM server to be assigned as the team to which the monitored server belongs. Only users with this role can access the server. Optional, defaults to none, meaning all users can access. | | `--owner` | Specifies a Postgres user on the PEM server to be assigned as the owner of the monitored server. Optional, defaults to `--pem-user`. | | `--display-name ` | Specifies the display name of the monitored database server. Optional, defaults to the system hostname. | | **Other parameters** | | -| `--remote-monitoring` | Set to `yes` if the server is not located on the same host as the agent. When remote monitoring is enabled (`yes`), agent level statistics for the monitored server aren't available for custom charts and dashboards, and the remote server isn't accessible by some PEM utilities (such as Audit Manager, Capacity Manager, Log Manager, Postgres Expert, and Tuning Wizard). Optional, defaults to `no`. | +| `--remote-monitoring` | Set to `yes` if the server isn't located on the same host as the agent. When remote monitoring is enabled (`yes`), agent level statistics for the monitored server aren't available for custom charts and dashboards, and the remote server isn't accessible by some PEM utilities, such as Audit Manager, Capacity Manager, Log Manager, Postgres Expert, and Tuning Wizard. Optional, defaults to `no`. | | `--efm-cluster-name` | Specifies the name of the EDB Failover Manager cluster that monitors the server (if applicable). Optional. | | `--efm-install-path` | Specifies the complete path to the installation directory of EDB Failover Manager (if applicable). Optional. | | `--config-dir` | Specifies the directory path of the agent configuration file. Optional, defaults to `/../etc`. | @@ -80,9 +80,9 @@ If you don't provide the password, a password authentication error occurs. The P #### Examples -The following example registers a server using only the required parameters. -The user `admin01` will be used to connect to the PEM server and the credentials supplied for the `--server-*` parameters will be used to create a connection from the agent to the monitored server. -The same details will also be used to populate the server connection details in the PEM web application. +This example registers a server using only the required parameters. +The user `admin01` is used to connect to the PEM server, and the credentials supplied for the `--server-*` parameters are used to create a connection from the agent to the monitored server. +The same details are also used to populate the server connection details in the PEM web application. ```shell pemworker --register-server \ @@ -93,11 +93,11 @@ pemworker --register-server \ --server-user prod_admin ``` -In the following example, we specify different parameters to be used for the connection from the agent to the monitored server. -We override the fully qualified domain name provided in `--server-addr` with `localhost` instead and override the user to use a `local_monitor` user. -This could be a user which is only permitted to connect from the same host for example. +This example specifies different parameters to use for the connection from the agent to the monitored server. +The example overrides the fully qualified domain name provided in `--server-addr` with `localhost` instead and overrides the user to use a `local_monitor` user. +This might be a user who is permitted to connect only from the same host for example. -We also specify a service name, `postgresql` which means the PEM Agent will be able to restart this server to apply configuration changes. +Also specified is a service name, `postgresql`, which means the PEM agent can restart this server to apply configuration changes. ```shell pemworker --register-server \ @@ -128,7 +128,7 @@ Append command line options to the command string when invoking the pemworker ut | Option | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--pem-user` | Specifies the name of the PEM administrative user. Required. | -| `--server-addr` | Specifies the IP address of the server host or the fully qualified domain name. On Unix-based systems, you can leave the address field blank to use the default PostgreSQL Unix Domain Socket on the local machine. Or, you can set it to an alternate path containing a PostgreSQL socket. If you enter a path, the path must begin with a forward slash (/). Required. | +| `--server-addr` | Specifies the IP address of the server host or the fully qualified domain name. On Unix-based systems, you can leave the address field blank to use the default PostgreSQL Unix Domain Socket on the local machine. Or, you can set it to an alternative path containing a PostgreSQL socket. If you enter a path, the path must begin with a forward slash (/). Required. | | `--server-port` | Specifies the port number of the host. Required. | | `--config-dir` | Specifies the directory path of the agent configuration file. The default is `"/../etc"`. | @@ -141,7 +141,7 @@ If you don't provide the password, a password authentication error occurs. The P If the server you want to monitor resides on the same host as the monitoring agent, you can use the Auto Discovery dialog box to simplify the registration and binding process. !!! Note Limitations of automatic discovery -Automatic server discovery does not perform an exhaustive search for Postgres binaries or services. It will only detect Postgres instances created directly by the package installer. +Automatic server discovery doesn't perform an exhaustive search for Postgres binaries or services. It detects only Postgres instances created directly by the package installer. !!! To enable auto discovery for a specific agent, you must enable the Server Auto Discovery probe. To do so, select the PEM agent in the PEM client tree, and select **Management > Manage Probes**. When the **Manage Probes** tab opens, confirm that the slider in the **Enabled?** column is set to **Yes**. @@ -188,7 +188,7 @@ Use the **General** tab to describe the general properties of the server: - Use the **Name** field to specify a name for the server. The name identifies the server in the PEM browser tree. - You can use groups to organize your servers and agents in the tree. Using groups can help you manage large numbers of servers more easily. For example, you can have a production group, a test group, or LAN-specific groups. Use the **Group** list to select the server group in which to display the new server. -- Use the **Team** field to specify a PostgreSQL role name. Only PEM users who are members of this role, who created the server initially, or have superuser privileges on the PEM server see this server when they log on to PEM. If this field is left blank, by default all PEM users see the server. You can use the `show_objects_with_no_team` parameter in the Server Configuration dialog box to change the behavior. If `show_objects_with_no_team` is set to `false`, the server with no team isn't visible to all other users. +- Use the **Team** field to specify a PostgreSQL role name. Only PEM users who are members of this role, who created the server initially, or have superuser privileges on the PEM server see this server when they log in to PEM. If this field is left blank, by default all PEM users see the server. You can use the `show_objects_with_no_team` parameter in the Server Configuration dialog box to change the behavior. If `show_objects_with_no_team` is set to `false`, the server with no team isn't visible to all other users. - Use the **Background** color selector to select the color to display in the PEM tree behind database objects that are stored on the server. - Use the **Foreground** color selector to select the font color of labels in the PEM tree for objects stored on the server. - Select **Connect now?** to attempt a server connection when you select **Save**. Clear **Connect now?** if you don't want the PEM client to validate the specified connection parameters until a later connection attempt. @@ -247,7 +247,7 @@ Use the **Advanced** tab to specify details that are used to manage the server: `sudo /usr/pgsql-x/bin/pg_ctl -D /var/lib/pgsql/x/data` - where `x` is the version of the PostgreSQL database server. + Where `x` is the version of the PostgreSQL database server. - If the server is a member of a Failover Manager cluster, you can use PEM to monitor the health of the cluster and to replace the primary node if necessary. To enable PEM to monitor Failover Manager, use the **EFM cluster name** field to specify the cluster name. The cluster name is the prefix of the name of the Failover Manager cluster properties file. For example, if the cluster properties file is named `efm.properties`, the cluster name is efm. @@ -334,5 +334,3 @@ When first connecting to a newly bound server, the Global Overview dashboard mig In a few minutes, bar graphs on the Global Overview dashboard show that the agent connected successfully. The new server is included in the **Postgres Server Status** list. If after five minutes the Global Overview dashboard still doesn't list the new server, check the logfiles for the monitoring agent for errors. Right-click the agent's name in the tree, and select the **Dashboards > Probe Log Analysis** from the context menu. - - diff --git a/product_docs/docs/pem/9/managing_pem_agent/modifying_agent_configuration.mdx b/product_docs/docs/pem/9/managing_pem_agent/modifying_agent_configuration.mdx index 31999136394..0e79bbf21e4 100644 --- a/product_docs/docs/pem/9/managing_pem_agent/modifying_agent_configuration.mdx +++ b/product_docs/docs/pem/9/managing_pem_agent/modifying_agent_configuration.mdx @@ -3,12 +3,12 @@ title: "Modifying agent configuration" navTitle: "Modifying agent configuration" --- -A number of configurable parameters control the behavior of the PEM agent. On Linux, these are stored in a configuration file. On Windows they are stored as registry keys. +A number of configurable parameters control the behavior of the PEM agent. On Linux, these are stored in a configuration file. On Windows they're stored as registry keys. 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. ## Contents of the configuration file @@ -28,8 +28,8 @@ On Linux systems, PEM configuration options are stored in the `agent.cfg` file, | long_wait | The maximum length of time (in seconds) for the PEM agent to wait before attempting to connect to the PEM server if an initial connection attempt fails. | 30 seconds | | short_wait | The minimum length of time (in seconds) for the PEM agent to wait before checking which probes are next in the queue waiting to run. | 10 seconds | | alert_threads | The number of alert threads to be spawned by the agent. For more information, see [About alert threads](#about-alert-threads). | Set to 1 for the agent that resides on the host of the PEM server, 0 for all other agents. | -| enable_smtp | When set to true this agent will attempt to send email notifications as configured in the PEM web application. | true for PEM server host, false for all others. | -| enable_snmp | When set to true this agent will attempt to send SNMP notifications as configured in the PEM web application. | true for PEM server host, false for all others. | +| enable_smtp | When set to true, this agent will attempt to send email notifications as configured in the PEM web application. | true for PEM server host, false for all others. | +| enable_snmp | When set to true, this agent will attempt to send SNMP notifications as configured in the PEM web application. | true for PEM server host, false for all others. | | enable_nagios | When set to true, Nagios alerting is enabled. | true for PEM server host, false for all others. | | enable_webhook | When set to true, Webhook alerting is enabled. | true for PEM server host, false for all others. | | max_webhook_retries | Used to set the maximum number of times pemAgent retries to call webhooks on failure. | Default 3. | @@ -41,9 +41,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 | Provides the path where script file (for alerting) is stored. | /tmp | | connection_custom_setup | Used 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 use instead of the platform default for verifying webhook server certificates. You can override this value with the `--webhook_ssl_ca_crt` option when defining webhooks. | Not set by default. | | batch_script_user | 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/]` where `` 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 preceded by a header of the form `[WEBHOOK/]`, where `` 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. | | @@ -83,7 +83,7 @@ The registry contains the entries shown in the following table. | BatchScriptDir | The path to store the script file for alerting. | /tmp | | ConnectionCustomSetup | Used 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\` where `` 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 TimeRanges. They must be placed in a subkey `Software\EnterpriseDB\PEM\agent\WEBHOOK\`, where `` is the name of a previously created webhook. These settings are automatically added when webhooks are created. We don't recommended 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. | | diff --git a/product_docs/docs/pem/9/registering_agent.mdx b/product_docs/docs/pem/9/registering_agent.mdx index 8e43d3c4ca7..ff387836662 100644 --- a/product_docs/docs/pem/9/registering_agent.mdx +++ b/product_docs/docs/pem/9/registering_agent.mdx @@ -11,23 +11,23 @@ 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, which you can use 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, uncheck the `register now` checkbox. For more details, refer to the [installation instructions](/pem/latest/installing/windows/). +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, set the PEM Server password, 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, 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 +### Linux ```shell export PEM_SERVER_PASSWORD=edb @@ -35,7 +35,7 @@ export PEM_SERVER_PASSWORD=edb pemworker --register-agent ``` -#### Windows +### Windows ```shell set PEM_SERVER_PASSWORD=edb @@ -49,7 +49,7 @@ set PEM_SERVER_PASSWORD=edb | `--pem-port` | The port of the PEM backend database server. The default value is `5432`. | | `--pem-user` | The name of the database user having superuser privileges of the PEM backend database server. This parameter is required. | | `--pem-agent-user` | The agent user to connect the PEM server backend database server. | -| `--cert-path` | The complete path to the directory where certificates are created. If you don't provide a path, certificates are created in `~/.pem` on Linux and `%APPDATA%/pem` on Windows | +| `--cert-path` | The complete path to the directory where certificates are created. 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 `/../etc`. | | `--display-name` | A user-friendly name for the agent to display in the PEM browser tree. The default is the system 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`. | @@ -75,30 +75,30 @@ 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: +Before any changes are made on the PEM database, the connection 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 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 in the examples that follow. -#### Linux +### Linux ``` shell # Running as root pemworker --unregister-agent ``` -#### Windows +### Windows ``` shell ./pemworker.exe UNREGISTER-AGENT ``` -Append command line options to the command string when invoking the pemworker utility. Follow each option with a corresponding value: +Append command line options to the command string when invoking the pemworker utility. Follow each option with a corresponding value. | Option | Description | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -107,7 +107,7 @@ Append command line options to the command string when invoking the pemworker ut ## Advanced usage -This section describes some advanced options for PEM agent registration. +The follow 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](#examples). @@ -131,7 +131,7 @@ 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. -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 in versions 9.0 and later. The SSL certificates and key files must be valid for the database user `agent` , where `` must be the same as provided using the command line. Use the `-o` option. +Register the PEM agent using the command line. In versions 9.0 and later, 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`, where `` must be the same as provided using the command line. Use the `-o` option. ```shell # Running as root @@ -141,7 +141,7 @@ ls -l /root/.pem/agent5.* -rw------- 1 root root 3244 Nov 7 11:27 /root/.pem/agent5.key # Register the PEM agent using command line. Assign the -# SSL ceritificates and key files using the -o option. +# SSL certificates and key files using the -o option. /usr/edb/pem/agent/bin/pemworker --register-agent \ --pem-server pemserver \ --pem-user postgres \ @@ -247,4 +247,4 @@ To use a non-root user account to register a PEM agent, you must first install t !!! Note - Any probes and jobs that require root permission or access to a file owned by another user (for example, enterprisedb) fail. - - If you move the `agent.cfg` file from its default location to another, the PEM dashboard might display the agent status as “unknown”. See [Troubleshooting agent issues](troubleshooting_agent/#updating-configuration-file-path-agent-status-displaying-as-unknown), for more information. + - If you move the `agent.cfg` file from its default location to another, the PEM dashboard might display the agent status as “unknown." See [Troubleshooting agent issues](troubleshooting_agent/#updating-configuration-file-path-agent-status-displaying-as-unknown), for more information. diff --git a/product_docs/docs/pem/9/registering_database_server.mdx b/product_docs/docs/pem/9/registering_database_server.mdx index eaea14e1ba9..66fb0df5f69 100644 --- a/product_docs/docs/pem/9/registering_database_server.mdx +++ b/product_docs/docs/pem/9/registering_database_server.mdx @@ -22,32 +22,32 @@ You can bind a database server to a remote agent (an agent that resides on a dif Registering a server does two things: - - It adds the server to the server tree in the PEM web application allowing users to open connections from the web application to the server - - It binds the server to a particular agent, meaning that agent will open connections to the server to execute probes and scheduled jobs + - It adds the server to the server tree in the PEM web application, allowing users to open connections from the web application to the server. + - It binds the server to a particular agent, meaning that agent will open connections to the server to execute probes and scheduled jobs. !!! Note Connections from the agent to the monitored server -During agent registration, you are required to provide connection details for the agent to connect to the monitored server. As is normal for Postgres, you must specify the database to connect to. -However, the PEM Agent will monitor **every database accessible to the specified user**, not just the database specified. +During agent registration, you're required to provide connection details for the agent to connect to the monitored server. As you must normally do for Postgres, you must specify the database to connect to. +However, the PEM agent will monitor **every database accessible to the specified user**, not just the database specified. -After registration, the agent opens a connection to the specified database. It uses this connection to determine which other databases it can connect to with the same user and then spawns one connection to each. +After registration, the agent opens a connection to the specified database. It uses this connection to determine the other databases it can connect to with the same user and then spawns one connection to each. !!! ## How to register a Postgres server There are three ways to register a server. - - [Use the pemworker utility to register a database server](#using-the-pemworker-utility-to-register-a-server) from the command line on the host where the agent you wish to bind is located. + - [Use the pemworker utility to register a database server](#using-the-pemworker-utility-to-register-a-server) from the command line on the host where the agent you want to bind is located. - [Use automatic server discovery](#registering-a-server-with-automatic-server-discovery) in the PEM web application to automatically register Postgres servers located on the same host as an agent. - [Manually register a Postgres server](#manually-registering-a-database-server) by adding all the details in the PEM web application. ## Using the pemworker utility to register a server -You can use the pemworker utility to register a Postgres server. During registration, the pemworker utility binds the new server to the agent that resides on the system from which you invoked the registration command. To register a server: +You can use the pemworker utility to register a Postgres server. During registration, the pemworker utility binds the new server to the agent that resides on the system from which you invoked the registration command. -On a Linux host, use the command: +To register a server on a Linux host, use the command: `pemworker --register-server` -On a Windows host, use the command: +To register a server on a Windows host, use the command: `pemworker.exe REGISTER-SERVER` @@ -55,40 +55,40 @@ Append command line options to the command string when invoking the pemworker ut | Option                           | Description | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--pem-user` | Specifies the name of the PEM administrative user (must have the `pem_admin` role) on the PEM server to be used to write the server details to the PEM database. **Required**. | -| **Server parameters** | These parameters are used to populate the connection properties in the PEM web application. They are used when a user connects from the PEM web application to the monitored server. They are also used for connections from the agent to the monitored server unless overridden by Agent Server Binding parameters (see below). | -| `--server-addr` | Specifies the IP address or fully qualified domain name of the monitored server. On Linux systems, you can leave the address field blank to use the default PostgreSQL Unix Domain Socket on the local machine. Or you can set it to an alternate path containing a PostgreSQL socket. If you enter a path, the path must begin with a forward slash (/). **Required**. | -| `--server-port` | Specifies the port number of the monitored server. **Required**. | -| `--server-database` | Specifies the name of the database on the monitored server to which to connect. **Required**. | -| `--server-user` | Specifies the name of the user used to connect to the monitored server. **Required**. | -| `--server-service-name` | Specifies the name of the operating system service that manages the monitored Postgres server. For example, a systemd service unit on Linux. Optional. | -| **Agent-server binding parameters** | These parameters are used to override the server parameters above. Use these if you wish the agent to connect to the monitored server using different credentials than those used by the PEM web application. | +| `--pem-user` | Specifies the name of the PEM administrative user (must have the pem_admin role) on the PEM server to use to write the server details to the PEM database. Required. | +| **Server parameters** | These parameters are used to populate the connection properties in the PEM web application. They're used when a user connects from the PEM web application to the monitored server. They're also used for connections from the agent to the monitored server unless overridden by Agent Server Binding parameters (see the Agent-server binding parameters in this table). | +| `--server-addr` | Specifies the IP address or fully qualified domain name of the monitored server. On Linux systems, you can leave the address field blank to use the default PostgreSQL Unix Domain Socket on the local machine. Or you can set it to an alternative path containing a PostgreSQL socket. If you enter a path, the path must begin with a forward slash (/). Required. | +| `--server-port` | Specifies the port number of the monitored server. Required. | +| `--server-database` | Specifies the name of the database on the monitored server to which to connect. Required. | +| `--server-user` | Specifies the name of the user used to connect to the monitored server. Required. | +| `--server-service-name` | Specifies the name of the operating system service that manages the monitored Postgres server, for example, a systemd service unit on Linux. Optional. | +| **Agent-server binding parameters** | Use these parameters to override the server parameters. Use these if you want the agent to connect to the monitored server using different credentials from those used by the PEM web application. | | `--asb-host-name` | Specifies the IP address or fully qualified domain name of the monitored server. Optional, defaults to `--server-addr` if not supplied. | | `--asb-host-port` | Specifies the port number of the monitored server. Optional, defaults to `--server-port` if not supplied. | | `--asb-host-db` | Specifies the name of the database on the monitored server to which the agent connects. Optional, defaults to `--server-database` if not supplied. | | `--asb-host-user` | Specifies the name of the user used by the agent to connect to the monitored server. Optional, defaults to `--server-user` if not supplied. | -| `--asb-ssl-mode` | Specifies the type of SSL authentication to use for connections. Supported values include: `prefer`, `require`, `disable`, `verify-CA`, `verify-full`. Optional, defaults to `prefer`. | +| `--asb-ssl-mode` | Specifies the type of SSL authentication to use for connections. Supported values include: `prefer`, `require`, `disable`, `verify-CA`, and `verify-full`. Optional, defaults to `prefer`. | | **Server metadata** | These parameters determine how the server is shown in the PEM web application. | | `--group` | Specifies the name of the group in which the server is displayed. Optional. | -| `--team` | Specifies a Postgres role on the PEM server to be assigned as the 'team' to which the monitored server belongs. Only users with this role will be able to access the server. Optional, defaults to none, meaning all users can access. | -| `--owner` | Specifies a Postgres user on the PEM server to be assigned as the owner of the monitored server. Optional, defaults to `--pem-user`. | +| `--team` | Specifies a Postgres role on the PEM server to be assigned as the team to which the monitored server belongs. Only users with this role can access the server. Optional, defaults to none, meaning all users can access. | +| `--owner` | Specifies a Postgres user on the PEM server to assign as the owner of the monitored server. Optional, defaults to `--pem-user`. | | `--display-name ` | Specifies the display name of the monitored database server. Optional, defaults to the system hostname. | | **Other parameters** | | -| `--remote-monitoring` | Set to `yes` if the server is not located on the same host as the agent. When remote monitoring is enabled (`yes`), agent level statistics for the monitored server aren't available for custom charts and dashboards, and the remote server isn't accessible by some PEM utilities (such as Audit Manager, Capacity Manager, Log Manager, Postgres Expert, and Tuning Wizard). Optional, defaults to `no`. | +| `--remote-monitoring` | Set to `yes` if the server isn't located on the same host as the agent. When remote monitoring is enabled (`yes`), agent-level statistics for the monitored server aren't available for custom charts and dashboards, and the remote server isn't accessible by some PEM utilities (such as Audit Manager, Capacity Manager, Log Manager, Postgres Expert, and Tuning Wizard). Optional, defaults to `no`. | | `--efm-cluster-name` | Specifies the name of the EDB Failover Manager cluster that monitors the server (if applicable). Optional. | | `--efm-install-path` | Specifies the complete path to the installation directory of EDB Failover Manager (if applicable). Optional. | | `--config-dir` | Specifies the directory path of the agent configuration file. Optional, defaults to `/../etc`. | Set the environment variable `PEM_SERVER_PASSWORD` to provide the password for the PEM server to allow the pemworker to connect as a PEM admin user. -Set the environment variable `PEM_MONITORED_SERVER_PASSWORD` to provide the password of the database server being registered and monitored by by the PEM agent. +Set the environment variable `PEM_MONITORED_SERVER_PASSWORD` to provide the password of the database server being registered and monitored by the PEM agent. If you don't provide the password, a password authentication error occurs. The PEM server acknowledges that the server was registered properly. #### Examples -The following example registers a server using only the required parameters. -The user `admin01` will be used to connect to the PEM server and the credentials supplied for the `--server-*` parameters will be used to create a connection from the agent to the monitored server. +This example registers a server using only the required parameters. +The user `admin01` is used to connect to the PEM server. The credentials supplied for the `--server-*` parameters are used to create a connection from the agent to the monitored server. The same details will also be used to populate the server connection details in the PEM web application. ```shell @@ -100,11 +100,11 @@ pemworker --register-server \ --server-user prod_admin ``` -In the following example, we specify different parameters to be used for the connection from the agent to the monitored server. -We override the fully qualified domain name provided in `--server-addr` with `localhost` instead and override the user to use a `local_monitor` user. -This could be a user which is only permitted to connect from the same host for example. +The following example specifies different parameters to used for the connection from the agent to the monitored server. +They override the fully qualified domain name provided in `--server-addr` with `localhost` instead. They also override the user to use a `local_monitor` user. +This might be a user who is permitted to connect only from the same host, for example. -We also specify a service name, `postgresql` which means the PEM Agent will be able to restart this server to apply configuration changes. +This example also specifies a service name, `postgresql`, which means the PEM agent can restart this server to apply configuration changes. ```shell pemworker --register-server \ @@ -133,9 +133,9 @@ Append command line options to the command string when invoking the pemworker ut | Option                | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--pem-user` | Specifies the name of the PEM administrative user. **Required**. | -| `--server-addr` | Specifies the IP address of the server host or the fully qualified domain name. On Unix-based systems, you can leave the address field blank to use the default PostgreSQL Unix Domain Socket on the local machine. Or, you can set it to an alternate path containing a PostgreSQL socket. If you enter a path, the path must begin with a forward slash (/). **Required**. | -| `--server-port` | Specifies the port number of the host. **Required**. | +| `--pem-user` | Specifies the name of the PEM administrative user. Required. | +| `--server-addr` | Specifies the IP address of the server host or the fully qualified domain name. On Unix-based systems, you can leave the address field blank to use the default PostgreSQL Unix Domain Socket on the local machine. Or, you can set it to an alternatibe path containing a PostgreSQL socket. If you enter a path, the path must begin with a forward slash (/). Required. | +| `--server-port` | Specifies the port number of the host. Required. | | `--config-dir` | Specifies the directory path of the agent configuration file. Optional, defaults to `/../etc`. | Use the `PEM_SERVER_PASSWORD` environment variable to provide the password for the PEM server to allow the pemworker utility to connect to the PEM server as `--pem-user`. @@ -147,7 +147,7 @@ If you don't provide the password, a password authentication error occurs. The P If the server you want to monitor resides on the same host as the monitoring agent, you can use the Auto Discovery dialog box to simplify the registration and binding process. !!! Note Limitations of automatic discovery -Automatic server discovery does not perform an exhaustive search for Postgres binaries or services. It will only detect Postgres instances created directly by the package installer. +Automatic server discovery doesn't perform an exhaustive search for Postgres binaries or services. It detects only the Postgres instances created directly by the package installer. !!! To enable auto discovery for a specific agent, you must enable the Server Auto Discovery probe. To do so, select the PEM agent in the PEM client tree, and select **Management > Manage Probes**. When the **Manage Probes** tab opens, confirm that the slider in the **Enabled?** column is set to **Yes**. @@ -165,7 +165,7 @@ The fields in the **Server Connection Details** box provide information about th - Use the **Host name/address** field to specify the IP address of the monitored server. - The **Port** field displays the port that's monitored by the server. You can't modify this field. - Provide the name of the service in the **Service ID** field. You must provide the service name to enable some PEM functionality. -- The **Maintenance database** field specifies which database to use for the initial connection and any global maintenance operations. Customize the content of the **Maintenance database** field for your installation. +- The **Maintenance database** field specifies the database to use for the initial connection and any global maintenance operations. Customize the content of the **Maintenance database** field for your installation. The fields in the **Agent Connection Details** box specify the properties for the PEM agent to use when connecting to the server: @@ -196,7 +196,7 @@ Use the **General** tab to describe the general properties of the server: - Use the **Name** field to specify a name for the server. The name identifies the server in the PEM browser tree. - You can use groups to organize your servers and agents in the tree. Using groups can help you manage large numbers of servers more easily. For example, you can have a production group, a test group, or LAN-specific groups. Use the **Group** list to select the server group in which to display the new server. -- Use the **Team** field to specify a PostgreSQL role name. Only PEM users who are members of this role, who created the server initially, or have superuser privileges on the PEM server see this server when they log on to PEM. If this field is left blank, by default all PEM users see the server. You can use the `show_objects_with_no_team` parameter in the Server Configuration dialog box to change the behavior. If `show_objects_with_no_team` is set to `false`, the server with no team isn't visible to all other users. +- Use the **Team** field to specify a PostgreSQL role name. Only PEM users who are members of this role, who created the server initially, or have superuser privileges on the PEM server see this server when they log in to PEM. If this field is left blank, by default all PEM users see the server. You can use the `show_objects_with_no_team` parameter in the Server Configuration dialog box to change the behavior. If `show_objects_with_no_team` is set to `false`, the server with no team isn't visible to all other users. - Use the **Background** color selector to select the color to display in the PEM tree behind database objects that are stored on the server. - Use the **Foreground** color selector to select the font color of labels in the PEM tree for objects stored on the server. - Select **Connect now?** to attempt a server connection when you select **Save**. Clear **Connect now?** if you don't want the PEM client to validate the specified connection parameters until a later connection attempt. From 06533e86925f979f87e0e87d5df72e56e45e7c9b Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Thu, 2 May 2024 14:18:36 -0400 Subject: [PATCH 03/11] Update product_docs/docs/pem/8/managing_pem_agent.mdx --- product_docs/docs/pem/8/managing_pem_agent.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/product_docs/docs/pem/8/managing_pem_agent.mdx b/product_docs/docs/pem/8/managing_pem_agent.mdx index b0dc064de2b..f9e36b06ed8 100644 --- a/product_docs/docs/pem/8/managing_pem_agent.mdx +++ b/product_docs/docs/pem/8/managing_pem_agent.mdx @@ -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, to apply the changes you must restart the agent. + 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. From bc91a36e52799bd3ab8217af48f473abeb1e8169 Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Thu, 2 May 2024 14:19:25 -0400 Subject: [PATCH 04/11] Update product_docs/docs/pem/8/managing_pem_agent.mdx --- product_docs/docs/pem/8/managing_pem_agent.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/product_docs/docs/pem/8/managing_pem_agent.mdx b/product_docs/docs/pem/8/managing_pem_agent.mdx index f9e36b06ed8..aba0be73125 100644 --- a/product_docs/docs/pem/8/managing_pem_agent.mdx +++ b/product_docs/docs/pem/8/managing_pem_agent.mdx @@ -230,7 +230,7 @@ On Linux systems, PEM configuration options are stored in the `agent.cfg` file, | 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. 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** | You can specify the following options multiple times. Each time, preceded the option with a header of the form `[WEBHOOK/]`, where `` 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 parameters** | You can specify the following options multiple times. Each time, precede the option with a header of the form `[WEBHOOK/]`, where `` 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. | | From 4fc0f5646432b210128184772d71d9cd6edbf78b Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Thu, 2 May 2024 14:21:32 -0400 Subject: [PATCH 05/11] Update product_docs/docs/pem/8/registering_agent.mdx --- product_docs/docs/pem/8/registering_agent.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/product_docs/docs/pem/8/registering_agent.mdx b/product_docs/docs/pem/8/registering_agent.mdx index c941bcb748a..a837072a955 100644 --- a/product_docs/docs/pem/8/registering_agent.mdx +++ b/product_docs/docs/pem/8/registering_agent.mdx @@ -25,7 +25,7 @@ If you don't want the installer to register the agent, clear the **Register now* 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 +#### Linux ```shell # Running as root From 892facf59d661903a105fa870528a28382f1a2f0 Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Thu, 2 May 2024 14:47:53 -0400 Subject: [PATCH 06/11] Apply suggestions from code review --- product_docs/docs/pem/8/registering_agent.mdx | 6 +++--- .../docs/pem/8/registering_database_server.mdx | 2 +- .../modifying_agent_configuration.mdx | 4 ++-- product_docs/docs/pem/9/registering_agent.mdx | 16 ++++++++-------- .../docs/pem/9/registering_database_server.mdx | 6 +++--- 5 files changed, 17 insertions(+), 17 deletions(-) diff --git a/product_docs/docs/pem/8/registering_agent.mdx b/product_docs/docs/pem/8/registering_agent.mdx index a837072a955..98108caa679 100644 --- a/product_docs/docs/pem/8/registering_agent.mdx +++ b/product_docs/docs/pem/8/registering_agent.mdx @@ -33,7 +33,7 @@ export PEM_SERVER_PASSWORD=edb pemworker --register-agent ``` -### Windows +#### Windows ```shell set PEM_SERVER_PASSWORD=edb @@ -84,13 +84,13 @@ If you don't provide the password, a password authentication error occurs. After ## 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 +#### Linux ``` shell # Running as root pemworker --unregister-agent ``` -### Windows +#### Windows ``` shell ./pemworker.exe UNREGISTER-AGENT ``` diff --git a/product_docs/docs/pem/8/registering_database_server.mdx b/product_docs/docs/pem/8/registering_database_server.mdx index cd95b605baa..c10a0c93eea 100644 --- a/product_docs/docs/pem/8/registering_database_server.mdx +++ b/product_docs/docs/pem/8/registering_database_server.mdx @@ -95,7 +95,7 @@ pemworker --register-server \ This example specifies different parameters to use for the connection from the agent to the monitored server. The example overrides the fully qualified domain name provided in `--server-addr` with `localhost` instead and overrides the user to use a `local_monitor` user. -This might be a user who is permitted to connect only from the same host for example. +This might be a user who's permitted to connect only from the same host for example. Also specified is a service name, `postgresql`, which means the PEM agent can restart this server to apply configuration changes. diff --git a/product_docs/docs/pem/9/managing_pem_agent/modifying_agent_configuration.mdx b/product_docs/docs/pem/9/managing_pem_agent/modifying_agent_configuration.mdx index 0e79bbf21e4..b41c8a541e9 100644 --- a/product_docs/docs/pem/9/managing_pem_agent/modifying_agent_configuration.mdx +++ b/product_docs/docs/pem/9/managing_pem_agent/modifying_agent_configuration.mdx @@ -43,7 +43,7 @@ On Linux systems, PEM configuration options are stored in the `agent.cfg` file, | connection_custom_setup | Used 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 use instead of the platform default for verifying webhook server certificates. You can override this value with the `--webhook_ssl_ca_crt` option when defining webhooks. | Not set by default. | | batch_script_user | The name of the user to use for executing the batch/shell scripts. | None | -| **Webhook parameters** | You can specify the following options multiple times, each time preceded by a header of the form `[WEBHOOK/]`, where `` 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 parameters** | You can specify the following options multiple times. Each time, precede the option with a header of the form `[WEBHOOK/]`, where `` 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. | | @@ -83,7 +83,7 @@ The registry contains the entries shown in the following table. | BatchScriptDir | The path to store the script file for alerting. | /tmp | | ConnectionCustomSetup | Used 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**| You can specify the following options multiple TimeRanges. They must be placed in a subkey `Software\EnterpriseDB\PEM\agent\WEBHOOK\`, where `` is the name of a previously created webhook. These settings are automatically added when webhooks are created. We don't recommended adding them manually.|| +| **Webhook parameters**| You can specify the following options multiple times. They must be placed in a subkey `Software\EnterpriseDB\PEM\agent\WEBHOOK\`, where `` is the name of a previously created webhook. These settings are automatically added when webhooks are created. We don't recommended 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. | | diff --git a/product_docs/docs/pem/9/registering_agent.mdx b/product_docs/docs/pem/9/registering_agent.mdx index ff387836662..3c2f38496a7 100644 --- a/product_docs/docs/pem/9/registering_agent.mdx +++ b/product_docs/docs/pem/9/registering_agent.mdx @@ -17,17 +17,17 @@ Before a PEM agent can be used, you must register it with a PEM server. 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](#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 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, 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 +#### Linux ```shell export PEM_SERVER_PASSWORD=edb @@ -35,7 +35,7 @@ export PEM_SERVER_PASSWORD=edb pemworker --register-agent ``` -### Windows +#### Windows ```shell set PEM_SERVER_PASSWORD=edb @@ -87,18 +87,18 @@ If you don't provide the password, a password authentication error occurs. After ## 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 in the examples that follow. -### Linux +#### Linux ``` shell # Running as root pemworker --unregister-agent ``` -### Windows +#### Windows ``` shell ./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 | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -107,7 +107,7 @@ Append command line options to the command string when invoking the pemworker ut ## Advanced usage -The follow are some advanced options for PEM agent registration. +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](#examples). diff --git a/product_docs/docs/pem/9/registering_database_server.mdx b/product_docs/docs/pem/9/registering_database_server.mdx index 66fb0df5f69..4e106ffad9b 100644 --- a/product_docs/docs/pem/9/registering_database_server.mdx +++ b/product_docs/docs/pem/9/registering_database_server.mdx @@ -26,7 +26,7 @@ Registering a server does two things: - It binds the server to a particular agent, meaning that agent will open connections to the server to execute probes and scheduled jobs. !!! Note Connections from the agent to the monitored server -During agent registration, you're required to provide connection details for the agent to connect to the monitored server. As you must normally do for Postgres, you must specify the database to connect to. +During agent registration, you're required to provide connection details for the agent to connect to the monitored server. As you normally do for Postgres, you must specify the database to connect to. However, the PEM agent will monitor **every database accessible to the specified user**, not just the database specified. After registration, the agent opens a connection to the specified database. It uses this connection to determine the other databases it can connect to with the same user and then spawns one connection to each. @@ -56,7 +56,7 @@ Append command line options to the command string when invoking the pemworker ut | Option                           | Description | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--pem-user` | Specifies the name of the PEM administrative user (must have the pem_admin role) on the PEM server to use to write the server details to the PEM database. Required. | -| **Server parameters** | These parameters are used to populate the connection properties in the PEM web application. They're used when a user connects from the PEM web application to the monitored server. They're also used for connections from the agent to the monitored server unless overridden by Agent Server Binding parameters (see the Agent-server binding parameters in this table). | +| **Server parameters** | These parameters are used to populate the connection properties in the PEM web application. They're used when a user connects from the PEM web application to the monitored server. They're also used for connections from the agent to the monitored server unless overridden by Agent Server Binding parameters (see the **Agent-server binding parameters** in this table). | | `--server-addr` | Specifies the IP address or fully qualified domain name of the monitored server. On Linux systems, you can leave the address field blank to use the default PostgreSQL Unix Domain Socket on the local machine. Or you can set it to an alternative path containing a PostgreSQL socket. If you enter a path, the path must begin with a forward slash (/). Required. | | `--server-port` | Specifies the port number of the monitored server. Required. | | `--server-database` | Specifies the name of the database on the monitored server to which to connect. Required. | @@ -102,7 +102,7 @@ pemworker --register-server \ The following example specifies different parameters to used for the connection from the agent to the monitored server. They override the fully qualified domain name provided in `--server-addr` with `localhost` instead. They also override the user to use a `local_monitor` user. -This might be a user who is permitted to connect only from the same host, for example. +This might be a user who's permitted to connect only from the same host, for example. This example also specifies a service name, `postgresql`, which means the PEM agent can restart this server to apply configuration changes. From 040dac502fcbe59cefef510ae609d9462fc1f31b Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Tue, 7 May 2024 09:10:46 -0400 Subject: [PATCH 07/11] Update product_docs/docs/pem/9/registering_agent.mdx Co-authored-by: Simon Notley <43099400+sonotley@users.noreply.github.com> --- product_docs/docs/pem/9/registering_agent.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/product_docs/docs/pem/9/registering_agent.mdx b/product_docs/docs/pem/9/registering_agent.mdx index 3c2f38496a7..9c970e63cfb 100644 --- a/product_docs/docs/pem/9/registering_agent.mdx +++ b/product_docs/docs/pem/9/registering_agent.mdx @@ -131,7 +131,7 @@ 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. -Register the PEM agent using the command line. In versions 9.0 and later, 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`, where `` must be the same as provided using the command line. Use the `-o` option. +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`, where `` must be the same as provided using the command line. Use the `-o` option. ```shell # Running as root From 7137d123f4d08dd1b0341a37af669ab87c75500b Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Tue, 7 May 2024 09:12:35 -0400 Subject: [PATCH 08/11] Update product_docs/docs/pem/8/registering_database_server.mdx --- product_docs/docs/pem/8/registering_database_server.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/product_docs/docs/pem/8/registering_database_server.mdx b/product_docs/docs/pem/8/registering_database_server.mdx index c10a0c93eea..3ba7d28be92 100644 --- a/product_docs/docs/pem/8/registering_database_server.mdx +++ b/product_docs/docs/pem/8/registering_database_server.mdx @@ -95,7 +95,7 @@ pemworker --register-server \ This example specifies different parameters to use for the connection from the agent to the monitored server. The example overrides the fully qualified domain name provided in `--server-addr` with `localhost` instead and overrides the user to use a `local_monitor` user. -This might be a user who's permitted to connect only from the same host for example. +This might be a user that can connect only from the same host, for example. Also specified is a service name, `postgresql`, which means the PEM agent can restart this server to apply configuration changes. From 9ecc0f0875056ec7486616ca5cba16d4007bfece Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Tue, 7 May 2024 09:25:28 -0400 Subject: [PATCH 09/11] Update product_docs/docs/pem/8/registering_database_server.mdx --- product_docs/docs/pem/8/registering_database_server.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/product_docs/docs/pem/8/registering_database_server.mdx b/product_docs/docs/pem/8/registering_database_server.mdx index 3ba7d28be92..0f462c63efe 100644 --- a/product_docs/docs/pem/8/registering_database_server.mdx +++ b/product_docs/docs/pem/8/registering_database_server.mdx @@ -81,8 +81,8 @@ If you don't provide the password, a password authentication error occurs. The P #### Examples This example registers a server using only the required parameters. -The user `admin01` is used to connect to the PEM server, and the credentials supplied for the `--server-*` parameters are used to create a connection from the agent to the monitored server. -The same details are also used to populate the server connection details in the PEM web application. +The user `admin01` will be used to connect to the PEM server, and the credentials supplied for the `--server-*` parameters will be used to create a connection from the agent to the monitored server. +The same details will also be used to populate the server connection details in the PEM web application. ```shell pemworker --register-server \ From 8c67ba6740876c3e22d310a2332fcdbac7633280 Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Tue, 7 May 2024 09:27:36 -0400 Subject: [PATCH 10/11] Update product_docs/docs/pem/9/registering_database_server.mdx --- product_docs/docs/pem/9/registering_database_server.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/product_docs/docs/pem/9/registering_database_server.mdx b/product_docs/docs/pem/9/registering_database_server.mdx index 4e106ffad9b..62d742913a5 100644 --- a/product_docs/docs/pem/9/registering_database_server.mdx +++ b/product_docs/docs/pem/9/registering_database_server.mdx @@ -88,7 +88,7 @@ If you don't provide the password, a password authentication error occurs. The P #### Examples This example registers a server using only the required parameters. -The user `admin01` is used to connect to the PEM server. The credentials supplied for the `--server-*` parameters are used to create a connection from the agent to the monitored server. +The user `admin01` will be used to connect to the PEM server. The credentials supplied for the `--server-*` parameters will be used to create a connection from the agent to the monitored server. The same details will also be used to populate the server connection details in the PEM web application. ```shell From 1178897638eef91bacd39e0d0497828724a70cc8 Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Tue, 14 May 2024 10:35:50 -0400 Subject: [PATCH 11/11] Update product_docs/docs/pem/9/registering_agent.mdx Co-authored-by: Simon Notley <43099400+sonotley@users.noreply.github.com> --- product_docs/docs/pem/9/registering_agent.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/product_docs/docs/pem/9/registering_agent.mdx b/product_docs/docs/pem/9/registering_agent.mdx index 9c970e63cfb..a316a9ff063 100644 --- a/product_docs/docs/pem/9/registering_agent.mdx +++ b/product_docs/docs/pem/9/registering_agent.mdx @@ -247,4 +247,4 @@ To use a non-root user account to register a PEM agent, you must first install t !!! Note - Any probes and jobs that require root permission or access to a file owned by another user (for example, enterprisedb) fail. - - If you move the `agent.cfg` file from its default location to another, the PEM dashboard might display the agent status as “unknown." See [Troubleshooting agent issues](troubleshooting_agent/#updating-configuration-file-path-agent-status-displaying-as-unknown), for more information. + - If you move the `agent.cfg` file from its default location to another, the PEM dashboard might display the agent status as `unknown`. See [Troubleshooting agent issues](troubleshooting_agent/#updating-configuration-file-path-agent-status-displaying-as-unknown), for more information.