diff --git a/product_docs/docs/epas/15/epas_compat_ora_dev_guide/02_about_the_examples_used_in_this_guide.mdx b/product_docs/docs/epas/15/epas_compat_ora_dev_guide/02_about_the_examples_used_in_this_guide.mdx index 62d59aa5f74..507d11eec86 100644 --- a/product_docs/docs/epas/15/epas_compat_ora_dev_guide/02_about_the_examples_used_in_this_guide.mdx +++ b/product_docs/docs/epas/15/epas_compat_ora_dev_guide/02_about_the_examples_used_in_this_guide.mdx @@ -39,13 +39,13 @@ Also note the following points: ``` - The examples use the sample tables, `dept`, `emp`, and `jobhist`, created and loaded when EDB Postgres Advanced Server was installed. The `emp` table is installed with triggers that you must disable to reproduce the same results as the examples. Log into EDB Postgres Advanced Server as the `enterprisedb` superuser and disable the triggers by issuing the following command: - +- ```sql ALTER TABLE emp DISABLE TRIGGER USER; ``` - -You can later reactivate the triggers on the `emp` table with the following command: - + + You can later reactivate the triggers on the `emp` table with the following command: + ```sql ALTER TABLE emp ENABLE TRIGGER USER; ``` diff --git a/product_docs/docs/epas/15/epas_compat_sql/64_grant.mdx b/product_docs/docs/epas/15/epas_compat_sql/64_grant.mdx index 94e796f2776..2c5b3c6ae8a 100644 --- a/product_docs/docs/epas/15/epas_compat_sql/64_grant.mdx +++ b/product_docs/docs/epas/15/epas_compat_sql/64_grant.mdx @@ -97,8 +97,8 @@ You don't need to grant privileges to the owner of an object (usually the user t Depending on the type of object, the initial default privileges can include granting some privileges to `PUBLIC`. The default is no public access for tables and `EXECUTE` privilege for functions, procedures, and packages. The object owner can revoke these privileges. -!!! Note - For maximum security, issue the `REVOKE` in the same transaction that creates the object. This approach prevents a window from occurring in which another user can use the object. +!!! Note + For maximum security, issue the `REVOKE` in the same transaction that creates the object. This approach prevents a window from occurring in which another user can use the object. The possible privileges are: diff --git a/product_docs/docs/epas/15/epas_compat_sql/65a_merge.mdx b/product_docs/docs/epas/15/epas_compat_sql/65a_merge.mdx new file mode 100644 index 00000000000..aea7394ae73 --- /dev/null +++ b/product_docs/docs/epas/15/epas_compat_sql/65a_merge.mdx @@ -0,0 +1,154 @@ +--- +title: "MERGE" +--- + +## Name + +`MERGE` — conditionally insert, update, or delete rows of a table. + +## Synopsis + +```sql +MERGE INTO target_table_name [ target_alias ] +USING data_source [ source_alias ] ON ( join_condition ) +-- merge_update_clause +WHEN MATCHED THEN + UPDATE SET column = value, ... [ WHERE where_condition ] + [ DELETE [ WHERE where_condition ] ] + +-- merge_insert_clause +WHEN NOT MATCHED THEN + INSERT [(col_list)] VALUES (val_list) [ WHERE where_condition ] +``` + +## Description + +`MERGE` allows you to select rows from one or more sources for update or insertion into a table. You specify the join condition to determine whether to update or insert into the target table. You specify conditional UPDATE and INSERT statements using the WHERE clause in the MERGE statement. + +It allows you to combine multiple operations and avoid multiple INSERT, UPDATE, and DELETE DML statements. + +For more information, see [MERGE statement](https://www.postgresql.org/docs/current/sql-merge.html). + + +## Parameters + +`target_table_name` + + The name (optionally schema-qualified) of the target table to merge into. + +`target_alias` + + A substitute name for the target table. When an alias is provided, it completely hides the actual name of the table. + +`data_source` + + The name (optionally schema-qualified) of the source table or a source query. The source table is the source table name, view name, or transition table name. The source query (SELECT or VALUES statement) supplies the rows to be merged into the target_table_name. + +`source_alias` + + A substitute name for the data source. When an alias is provided, it completely hides the actual name of the table. + +`join_condition` + + An expression resulting in a value of type boolean similar to a WHERE clause that specifies which rows in the data_source match rows in the target_table_name. + +`merge_update_clause` + + Specifies the new column values of the target table. It performs this update if the join_condition of the ON clause is true. + + Specify the where_condition if you want the database to execute the update operation only if the specified condition is true. The condition can refer to either the data source or the target table. If the condition is not true, then the database skips the update operation when merging the row into the table. + + Specify the DELETE where_condition to clean up data in a table while populating or updating it. The only rows affected by this clause are those rows in the target table that are updated by the merge operation. The DELETE WHERE condition evaluates the updated value, not the original value that was evaluated by the UPDATE SET ... WHERE condition. If a row of the target table meets the DELETE condition but is not included in the join defined by the ON clause, then it is not deleted. + + You can specify this clause by itself or with the merge_insert_clause. If you specify both, then they can be in either order. + +`merge_insert_clause` + + The merge_insert_clause specifies values to insert into the column of the target table if the condition of the ON clause is false. If you omit the column list after the INSERT keyword, then the number of columns in the target table must match the number of values in the VALUES clause. + + To insert all of the source rows into the table, you can use a constant filter predicate in the ON clause condition. An example of a constant filter predicate is `ON (0=1)`. It recognizes such a predicate and makes an unconditional insert of all source rows into the table. This approach is different from omitting the merge_update_clause. In that case, the database still must perform a join. With constant filter predicate, no join is performed. + + Specify the where_clause if you want the database to execute the insert operation only if the specified condition is true. The condition can refer only to the data source table. Database skips the insert operation for all rows for which the condition is not true. + + You can specify this clause by itself or with the merge_update_clause. If you specify both, then they can be in either order. + + +## Examples + +Create tables `target` and `source`: + +```sql +CREATE TABLE target (tid integer, balance integer); +CREATE TABLE source (sid integer, delta integer); +``` + +Add rows to both the tables: + +```sql +# Insert rows into target table +INSERT INTO target VALUES (1, 0); +INSERT INTO target VALUES (2, 20); +INSERT INTO target VALUES (3, 0); + +# Insert rows into source table +INSERT INTO source VALUES (1, 100); +INSERT INTO source VALUES (2, 200); +INSERT INTO source VALUES (3, 300); +INSERT INTO source VALUES (4, 100); +INSERT INTO source VALUES (5, 300); +INSERT INTO source VALUES (6, 600); +``` + +This example shows how to use the WHERE condition for conditional UPDATE and INSERT statements in the MERGE statement: + +```sql +BEGIN; +MERGE INTO target t +USING source s +ON (t.tid = s.sid) +WHEN MATCHED THEN + UPDATE SET balance = s.delta WHERE balance = 0 +WHEN NOT MATCHED THEN + INSERT VALUES (s.sid, s.delta) WHERE s.sid >= 5; +``` + +This example shows how to use PostgreSQL style UPDATE and conditional INSERT in the MERGE statement: + +```sql +BEGIN; +MERGE INTO target t +USING source s +ON (t.tid = s.sid) +WHEN MATCHED AND balance > 0 THEN + UPDATE SET balance = s.delta +WHEN NOT MATCHED THEN + INSERT VALUES (s.sid, s.delta) WHERE s.sid >= 5; +``` + +This example shows how to use conditional UPDATE and PostgreSQL style UPDATE in the MERGE statement: + +```sql +BEGIN; +MERGE INTO target t +USING source s +ON (t.tid = s.sid) +WHEN MATCHED THEN + UPDATE SET balance = s.delta WHERE balance > 0 +WHEN NOT MATCHED AND s.sid >= 5 THEN + INSERT VALUES (s.sid, s.delta); +``` + +This example shows how to use the WHERE condition for UPDATE and DELETE statements, and also WHEN MATCHED THEN DELETE: + +```sql +MERGE INTO target t +USING source s +ON (t.tid = s.sid) +WHEN MATCHED THEN + UPDATE SET t.balance = t.balance + 100 WHERE t.balance = 20 + DELETE WHERE t.balance = 30 +WHEN NOT MATCHED THEN + INSERT VALUES (s.sid, s.delta) +WHEN MATCHED THEN + DELETE; +``` \ No newline at end of file diff --git a/product_docs/docs/jdbc_connector/42.5.4.1/06_executing_sql_commands_with_executeUpdate().mdx b/product_docs/docs/jdbc_connector/42.5.4.1/06_executing_sql_commands_with_executeUpdate().mdx index 07ae75f5691..e0d7ee62edb 100644 --- a/product_docs/docs/jdbc_connector/42.5.4.1/06_executing_sql_commands_with_executeUpdate().mdx +++ b/product_docs/docs/jdbc_connector/42.5.4.1/06_executing_sql_commands_with_executeUpdate().mdx @@ -19,65 +19,95 @@ The signature of the `executeUpdate()` method is: int executeUpdate(String sqlStatement) ``` -Provide this method a single parameter of type `String` containing the SQL command that you want to execute. +Provide this method with a single parameter of type `String` containing the SQL command that you want to execute. + +!!! Warning "Avoid user-sourced values" + We recommend that this string does not contain any user-sourced values. Avoid concatenating strings and values to compose your SQL command. Instead, use [PreparedStatements](#using-preparedstatements-to-send-sql-commands) which are reusable, parameterized SQL statements which safely manage the use of variable values in the SQL statement. + ## Using executeUpdate() to INSERT data The example that follows shows using the `executeUpdate()` method to add a row to the `emp` table. -!!! Note - The following example isn't a complete application, only a method. These code samples don't include the code required to set up and tear down a `Connection`. To experiment with the example, you must provide a class that invokes the sample code. +!!! Note Code samples + The following examples are not a complete application, only example methods. These code samples don't include the code required to set up and tear down a `Connection`. To experiment with the example, you must provide a class that invokes the sample code. ```java - public void updateEmployee(Connection con) + public void addOneEmployee(Connection con) { - try - { - int rowcount = stmt.executeUpdate("INSERT INTO " - + "emp(empno, ename) VALUES(6000,'Jones')"); - System.out.println(""); - System.out.println("Success - "+rowcount+ - " rows affected."); - } catch(Exception err) { - System.out.println("An error has occurred."); - System.out.println("See full details below."); - err.printStackTrace(); - } + try (Statement stmt=con.createStatement();) + { + int rowcount = stmt.executeUpdate("INSERT INTO emp(empno, ename) VALUES(6000,'Jones')"); + System.out.println(); + System.out.printf("Success - %d - rows affected.\n",rowcount); + } catch(Exception err) { + System.out.println("An error has occurred."); + System.out.println("See full details below."); + err.printStackTrace(); + } } ``` -The `updateEmployee()` method expects a single argument from the caller, a `Connection` object that must be connected to an EDB Postgres Advanced Server database: +The `addOneEmployee()` method expects a single argument from the caller, a `Connection` object that must be connected to an EDB Postgres Advanced Server database: ```java - public void updateEmployee(Connection con); + public void addOneEmployee(Connection con); +``` + +A `Statement` object is needed to run `ExecuteUpdate()`. This can be obtained by using `createStatement()` on the Connection object. We use the try-resource style here to ensure the statement object is released when the try block is exited. + +```java + try (Statement stmt=con.createStatement()) { ``` The `executeUpdate()` method returns the number of rows affected by the SQL statement (an `INSERT` typically affects one row, but an `UPDATE` or `DELETE` statement can affect more). ```java - int rowcount = stmt.executeUpdate("INSERT INTO emp(empno, ename)" - +" VALUES(6000,'Jones')"); + int rowcount = stmt.executeUpdate("INSERT INTO emp(empno, ename) VALUES(6000,'Jones')"); ``` -If `executeUpdate()` returns without an error, the call to `System.out.println` displays a message to the user that shows the number of rows affected. +If `executeUpdate()` returns without an error, the call to `System.out.printf` displays a message to the user that shows the number of rows affected. ```java - System.out.println(""); - System.out.println("Success - "+rowcount+" rows affected."); + System.out.println(); + System.out.printf("Success - %d - rows affected.\n",rowcount); ``` The catch block displays an appropriate error message to the user if the program encounters an exception: ```java - { - System.out.println("An error has occurred."); - System.out.println("See full details below."); - err.printStackTrace(); + } catch (Exception err){ + System.out.println("An error has occurred."); + System.out.println("See full details below."); + err.printStackTrace(); } ``` -You can use `executeUpdate()` with any SQL command that doesn't return a result set. However, you probably want to use `PrepareStatements` when the queries can be parameterized. +You can use `executeUpdate()` with any SQL command that doesn't return a result set. It is best suited to situations where a specific command needs to be executed and that command takes no parameters. + +To use the `DROP TABLE` command to delete a table from a database: + +```java + Statement stmt=con.createStatement(); + stmt.executeUpdate("DROP TABLE tableName"); +``` + +To use the `CREATE TABLE` command to add a new table to a database: + +```java + Statement stmt=con.createStatement(); + stmt.executeUpdate("CREATE TABLE tablename (fieldname NUMBER(4,2), fieldname2 VARCHAR2(30))"; +``` + +To use the `ALTER TABLE` command to change the attributes of a table: + +```java + Statement stmt=con.createStatement(); + stmt.executeUpdate("ALTER TABLE tablename ADD COLUMN colname BOOLEAN "; +``` + +However, you should use `PreparedStatement` when passing values to an SQL insert or update statement, especially if those values have come from user input. ## Using PreparedStatements to send SQL commands @@ -86,24 +116,24 @@ Many applications execute the same SQL statement over and over again, changing o The following shows invoking a `PreparedStatement` that accepts an employee ID and employee name and inserts that employee information in the `emp` table: ```java - public void AddEmployee(Connection con) - { - try { - Console c = System.console(); - String command = "INSERT INTO emp(empno,ename) VALUES(?,?)"; - PreparedStatement stmt = con.prepareStatement(command); - stmt.setObject(1,new Integer(c.readLine("ID:"))); - stmt.setObject(2,c.readLine("Name:")); - stmt.execute(); - System.out.println("The procedure successfully executed."); - } catch(Exception err) { - System.out.println("An error has occurred."); - System.out.println("See full details below."); - err.printStackTrace(); - } + public void addEmployee(Connection con, Integer id, String name) + { + String command = "INSERT INTO emp(empno,ename) VALUES(?,?)"; + try(PreparedStatement addstmt = con.prepareStatement(command) { + addstmt.setObject(1,id); + addstmt.setObject(2,name); + addstmt.execute(); + System.out.println("Employee added"); + } catch(Exception err) { + System.out.println("An error has occurred."); + System.out.println("See full details below."); + err.printStackTrace(); + } } ``` +This version of an add employee method takes as parameters the connection and values for the employee number (an integer) and name (a string). + Instead of hard coding data values in the SQL statement, you insert placeholders to represent the values to change with each iteration. The example shows an `INSERT` statement that includes two placeholders (each represented by a question mark): ```java @@ -113,7 +143,7 @@ Instead of hard coding data values in the SQL statement, you insert placeholders With the parameterized SQL statement in hand, the `AddEmployee()` method can ask the `Connection` object to prepare that statement and return a `PreparedStatement` object: ```java - PreparedStatement stmt = con.prepareStatement(command); + try(PreparedStatement addstmt = con.prepareStatement(command) { ``` At this point, the `PreparedStatement` has parsed and planned the `INSERT` statement, but it doesn't know the values to add to the table. Before executing `PreparedStatement`, you must supply a value for each placeholder by calling a `setter` method. `setObject()` expects two arguments: @@ -121,17 +151,17 @@ At this point, the `PreparedStatement` has parsed and planned the `INSERT` state - A parameter number. Parameter number one corresponds to the first question mark, parameter number two corresponds to the second question mark, etc. - The value to substitute for the placeholder. -The `AddEmployee()` method prompts the user for an employee ID and name and calls `setObject()` with the values supplied by the user: +The `AddEmployee()` method prompts the user for an employee ID and name and calls `setObject()` with the values supplied in the parameters: ```java - stmt.setObject(1,new Integer(c.readLine("ID:"))); - stmt.setObject(2, c.readLine("Name:")); + addstmt.setObject(1,id); + addstmt.setObject(2,name); ``` It then asks the `PreparedStatement` object to execute the statement: ```java - stmt.execute(); + addstmt.execute(); ``` If the SQL statement executes as expected, `AddEmployee()` displays a message that confirms the execution. If the server encounters an exception, the error handling code displays an error message. @@ -141,33 +171,47 @@ Some simple syntax examples using `PreparedStatement` sending SQL commands follo To use the `UPDATE` command to update a row: ```java - String command = " UPDATE emp SET ename=? WHERE empno=?"; - PreparedStatement stmt = con.prepareStatement(command); - stmt.setObject(1, c.readLine("Name:")); - stmt.setObject(2,new Integer(c.readLine("ID:"))); - stmt.execute(); + public static void updateEmployee(Connection con, Integer id, String name) + { + String command = "UPDATE emp SET ename=? where empno=?"; + try (PreparedStatement updateStmt = con.prepareStatement(command)) { + updateStmt.setObject(1,id); + updateStmt.setObject(2,name); + updateStmt.execute(); + } catch(Exception err) { + System.out.println("An error has occurred."); + System.out.println("See full details below."); + err.printStackTrace(); + } + } ``` -To use the `DROP TABLE` command to delete a table from a database: +For regularly and repeatedly used statements, the prepared statement can be initialized and reused. ```java - String command = "DROP TABLE tableName"; - PreparedStatement stmt = con.prepareStatement(command); - stmt.execute(); -``` - -To use the `CREATE TABLE` command to add a new table to a database: + PreparedStatement preparedAddStmt; + + public void prepareStatements(Connection con) { + try { + preparedAddStmt=con.prepareStatement("INSERT INTO emp(empno,ename) VALUES(?,?)"); + } catch (SQLException e) { + throw new RuntimeException(e); + } + } -```java - String command = ("CREATE TABLE tablename (fieldname NUMBER(4,2), fieldname2 VARCHAR2(30))"; - PreparedStatement stmt = con.prepareStatement(command); - stmt.execute(); + public void addPreparedEmployee(Integer id, String name) + { + try { + preparedAddStmt.setObject(1,id); + preparedAddStmt.setObject(2,name); + preparedAddStmt.execute(); + } catch(Exception err) { + System.out.println("An error has occurred."); + System.out.println("See full details below."); + err.printStackTrace(); + } + } ``` -To use the `ALTER TABLE` command to change the attributes of a table: +This saves the system having to reparse and initialize the statement every time it is executed. Note that the prepared statement is prepared without a try-with-resource wrapper to ensure it is not closed when it leaves the `prepareStatements` method. -```java - String command ="ALTER TABLE tablename ADD COLUMN colname BOOLEAN "; - PreparedStatement stmt = con.prepareStatement(command); - stmt.execute(); -``` \ No newline at end of file diff --git a/product_docs/docs/pem/9/certificates/index.mdx b/product_docs/docs/pem/9/certificates/index.mdx new file mode 100644 index 00000000000..67189cc8622 --- /dev/null +++ b/product_docs/docs/pem/9/certificates/index.mdx @@ -0,0 +1,363 @@ +--- +title: "Managing SSL certificates" +navTitle: "Managing SSL certificates" +legacyRedirectsGenerated: + # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. + - "/edb-docs/d/edb-postgres-enterprise-manager/user-guides/administrators-guide/8.0/managing_certificates.html" +# This file is moved from pem_admin/04_managing_certificates +redirects: +- /pem/latest/managing_certificates/ +- /pem/latest/pem_admin/04_managing_certificates/ +navigation: +- replacing_ssl_certificates +- regenerating_agent_certificates +--- + +PEM uses self-signed SSL certificates: + +- To secure requests to the [web server](#web-server-certificates) (Apache httpd), which provides the user interface and REST API. +- To secure and authenticate the [PEM agent connections to the PEM backend database](#pem-backend-database-server-and-agent-connection-certificates). + +## Web-server certificates + +PEM uses self-signed SSL certificates for the Apache httpd server. The self-signed SSL certificate and key files for the Apache httpd server are generated during PEM installation. + +To use your own SSL certificate for PEM, update the Apache HTTP configuration file `edb-ssl-pem.conf`. + +Update these two SSL directives in the PEM VirtualHost section: + +- `SSLCertificateFile` is your certificate file, for example, `your_domain_name.crt`. +- `SSLCertificateKeyFile` is the `.key` file generated when you created the certificate signing request (CSR), for example, `your_private.key`. + +For example, make the following updates: + +```shell +# Change the server name and file names in the configuration file to +# match your certificate files. +SSLEngine on +SSLCertificateFile /path/to/your_domain_name.crt +SSLCertificateKeyFile /path/to/your_private.key +``` + +To increase security, you can replace the httpd self-signed SSL certificates with trusted CA signed certificates in PEM. For more information, see [Replacing httpd self-signed SSL certificates](https://www.enterprisedb.com/postgres-tutorials/how-replacing-httpd-self-signed-ssl-certificates-trusted-ca-signed-certificates). + +## PEM backend database server and agent connection certificates + +By default, PEM implements secured SSL/TLS connections between PEM agents and the backend database. It also acts as its own certificate authority (CA) to generate certificates and keys for the PEM server and agent. The self-signed SSL certificates and keys for the PEM server and agent are generated during PEM installation. These certificates and keys encrypt the connection from agent to server. In addition, PEM agents are authenticated using their certificate rather than a password. + +You can replace the PEM self-signed SSL certificates and keys with the trusted CA certificates and keys. For more information, see [Trusted CA certificates and keys](/pem/latest/certificates/#use-certificates-and-keys-signed-by-trusted-CA). + +### How PEM self-signed SSL certificates work + +The PEM server configuration script generates self-signed SSL certificate and key files for the PEM backend database server. The backend database server uses these certificates and keys to authenticate and encrypt the agent connections. Each certificate has an expiry date. Regenerate the certificates when they near expiration. For more information, see [Regenerating server self-signed SSL certificates](/pem/latest/certificates/replacing_ssl_certificates). + +The PEM agent connects to the PEM backend database server using the libpq interface, acting as a client of the backend database server. The agent self-signed SSL certificates and keys get generated during [agent registration](/pem/latest/registering_agent). PEM agent establishes the connection with the PEM backend database server using the self-signed SSL certificate and key files. + +Each agent has a unique identifier, and the agent certificates and keys have the corresponding identifier. Each certificate has an expiry date. Regenerate the certificates when they near expiration. For more information, see [Regenerating agent self-signed SSL certificates](/pem/latest/certificates/regenerating_agent_certificates). + +If required, you can use the same certificate for all agents rather than one certificate per agent. For more information, see [Generate common agent certificate and key pair](/pem/lates/certificates/#generate-a-common-agent-certificate-and-key-pair). + +For more information on using the SSL certificates to connect in Postgres, see [Securing TCP/IP connections with SSL](https://www.postgresql.org/docs/current/ssl-tcp.html). + +### Certificate and key files generation + +The PEM server generates the certificates and key files in the data directory of the backend database server: + +- `ca_certificate.crt` +- `ca_key.key` +- `root.crt` +- `root.crl` +- `server.crt` +- `server.key` + +The `ca_certificate.crt` and `ca_key.key` files are used during the agent registration process to generate the agent's SSL certificates and key files. + +The `root.crt` file is a copy of the `ca_certificate.crt` file. You use the root certificate for the backend database server by setting the `ssl_ca_file` parameter as `root.crt` in the `postgresql.conf` file. + +The `root.crl` has the certificate revocation list (CRL) of digital certificates revoked by the issuing CA before their actual or assigned expiration date. + +The `server.crt` file is the signed certificate for the PEM server, and the `server.key` file is the private key to the certificate. The PEM agent certificates are generated using these server certificate and key files. + +### PEM self-signed SSL certificate renewal + +The PEM agent installed with the PEM server monitors the expiration date of the `ca_certificate.crt` file. When the certificate is about to expire, PEM: + +- Makes a backup of the existing certificate files +- Creates new certificate files and appends the new CA certificate file to the `root.crt` file on the PEM server +- Creates a job to renew the certificate file of any active agents +- Restarts the PEM server + +## Generate a common agent certificate and key pair + +By creating and using a single Postgres user for all PEM agents rather than one user per agent (the default), you can use the same certificate for all agents. + +Create a user, generate an agent certificate and key pair, and use them for all PEM agents. + +1. Create one common agent user in the PEM backend database. Grant the `pem_agent` role to the user. + + ```shell + # Running as enterprisedb + psql -p 5444 -U enterprisedb -d pem + CREATE USER pem_agent_common_user; + GRANT pem_agent TO pem_agent_common_user; + ``` + +1. Generate an agent key: + + ```shell + # Running as root + openssl genrsa -out agent.key 4096 + ``` + +1. Generate a CSR for the agent: + + ```shell + openssl req -new -key agent.key -out agent.csr -subj '/C=IN/ST=MH/L=Pune/O=PEM/CN=' + ``` + + Where `-subj` is provided as per your requirements. + +1. Use the `openssl x509` command to sign the CSR and generate an agent certificate: + + ```shell + openssl x509 -req -days 365 -in agent.csr -CA ca_certificate.crt -CAkey ca_key.key -CAcreateserial -out agent.crt + ``` + +1. Change the permissions on the `agent.crt` and `agent.key` file: + + ```shell + chmod 600 agent.crt agent.key + ``` + +1. Use this agent certificate and key pair: + + - For registering the new PEM agent from the remote host to the PEM server. + + a. Copy the agent certificate and key pair to the remote agent host and register the agent: + + ```shell + export PEM_SERVER_PASSWORD=edb + + /usr/edb/pem/agent/bin/pemworker --register-agent \ + --pem-server 192.168.99.130 \ + --pem-user enterprisedb \ + --pem-port 5444 \ + --pem-agent-user pem_agent_common_user \ + -o agent_ssl_crt= agent.crt \ + -o agent_ssl_key= agent.key + ``` + + b. Enable and start the pemagent services: + + ```shell + systemctl enable pemagent + systemctl start pemagent + ``` + + - To replace the agent certificate and key pair with the registered agent. + + a. Edit the `agent_user`, `agent_ssl_key`, and `agent_ssl_crt` parameters in `agent.cfg` file of the agent host: + + ```shell + vi /usr/edb/pem/agent/etc/agent.cfg + # Edit the agent username + agent_user=pem_agent_common_user + # Edit the ssl parameters with new certificate and key file location + agent_ssl_key=/agent.key + agent_ssl_crt=/agent.crt + ``` + + b. Restart the pemagent service: + + ```shell + systemctl restart pemagent + ``` + + +## Use certificates and keys signed by trusted CA + +Replace the PEM self-signed SSL certificates and keys with certificates and keys signed by a trusted CA. + +After obtaining the trusted CA certificates and keys, replace the [server](/pem/latest/certificates/#replace-the-self-signed-server-ssl-certificates-with-the-certificates-signed-by-the-trusted-ca) and [agent](/pem/latest/certificates/#replace-the-self-signed-agent-ssl-certificates-with-the-certificates-signed-by-the-trusted-ca) certificates and keys. + +### Replace the self-signed server SSL certificates with the certificates signed by the trusted CA + +1. Back up the old server certificate and key files: + + ```shell + # Running as root + mkdir /var/lib/edb/as/data/certs + cd /var/lib/edb/as/data/ + mv server.* root.* ca_* /var/lib/edb/as/data/certs + ``` + +1. Generate a private key for the server: + + ```shell + openssl genrsa -out server.key 4096 + ``` + +1. Generate a CSR for the server: + + ```shell + openssl req -new -key server.key -out server.csr -subj '/C=IN/ST=MH/L=Pune/O=EDB/CN=PEM' + ``` + + Where `-subj` is provided as per your requirements. We recommend using the hostname or domain qualified full name of the PEM server host for `CN`. + +1. Obtain the CA certificate (`trusted_ca.crt`) from a trusted CA. + +1. Ask your CA to sign the CSR and generate the server certificate for you. + +1. Verify the details of the new server certificate aren't tampered with and match your provided details: + + ```shell + openssl x509 -noout -text -in server.crt + ``` + +1. Use the new certificate obtained from the CA as the `root.crt` file: + + ```shell + cp trusted_ca.crt root.crt + ``` + +1. if the trusted CA doesn't provide CRL, disable CRL usage by the server. To disable the CRL usage, comment the `ssl_crl_file` parameter in the `postgresql.conf` file. + +1. Copy the new `root.crt`, `server.key`, and `server.crt` files to the data directory of the backend database server: + + ```shell + cp root.crt server.key server.crt /var/lib/edb/as/data + ``` + +1. Change the owner and permissions of the new certificates and key files to be the same as the data directory: + + ```shell + cd /var/lib/edb/as/data/ + chown enterprisedb server.* root.crt ca_certificate.crt + chmod 600 server.* root.crt ca_certificate.crt + ``` + + !!! Note + Don't restart the PEM server now. If you restart the PEM server, all the registered agents will stop working. + +1. Replace each PEM agent SSL certificates with the trusted CA certificates. For more information, see these [instructions](/pem/latest/certificates/#replace-the-self-signed-agent-ssl-certificates-with-the-certificates-signed-by-the-trusted-ca). + +1. Restart the PEM server. + + - On Linux: + + ```shell + # Running as root + systemctl start edb-as- + ``` + + Restarting the backend database server restarts the PEM server. + +### Replace the self-signed agent SSL certificates with the certificates signed by the trusted CA + +Replace the self-signed agent SSL certificates only after replacing the self-signed server certificates `server.crt` and `server.key` and CA certificate `root.crt`. + +1. Use psql to find all the agent identifiers (IDs) needed to replace the SSL certificates: + + ```shell + psql -U enterprisedb -d pem --no-psqlrc -t -A -c "SELECT id FROM pem.agent WHERE active=true" + ``` + +1. After identifying the agents that need key files, generate an `agent.key` for each agent: + + ```shell + openssl genrsa -out agent.key 4096 + ``` + + Where `` is the agent identifier. + +1. Generate a CSR for each agent: + + ```shell + openssl req -new -key agent.key -out agent.csr -subj '/C=IN/ST=MH/L=Pune/O=PEM/CN=agent' + ``` + + Where `-subj` is provided as per your requirements. Replace `` in `CN` with an appropriate agent identifier. + +!!! Note + If you prefer to use a single certificate for all PEM agents rather than one per agent, create a common Postgres user + and supply this username in place of `ID`. See [Generate a common agent certificate and key pair](/pem/latest/certificates/#generate-a-common-agent-certificate-and-key-pair). + +1. Ask your CA to sign the CSR and generate the agent certificate for you. + +1. Copy the certificate and key files on the respective hosts, where `` matches the `agent_id` in the `/usr/edb/pem/agent/etc/agent.cfg` file. + +1. Change the ownership and permission on the new `agent.crt` and `agent.key` file: + + ```shell + chown root agent.crt agent.key + chmod 600 agent.crt agent.key + ``` + +1. Back up the old agent certificate and key file: + + ```shell + # Running as root + mkdir root/.pem/certs + mv root/.pem/agent.* root/.pem/certs + ``` + +1. Replace each agent's certificate and key file with the newly generated files: + + ```shell + cp agent.key agent.crt root/.pem + ``` + +7. Restart the PEM agent service. + + - On Linux: + + ```shell + # Running as root + systemctl restart pemagent + ``` + + - On Windows: + Use the Services applet to restart the PEM agent. The PEM agent service is named Postgres Enterprise Manager Agent. Select the service name in the Services dialog box, and select **Restart the service**. + +## Testing certificates + +If you experience authentication problems, you can use these tests to validate certificates. + +### Validate a certificate against the root certificate + +To check whether a PEM agent certificate is trusted according to the server's `root.crt`, copy both certificates to the same machine. Then execute the following command: + +```shell +openssl verify -verbose -CAfile root.crt agent1.crt +``` + +This command returns `agent1.crt: OK` on success or an explanatory message on failure. + +### Make a test connection to the PEM backend database + +To verify whether the agent user can connect using a certificate, on the server where the agent is located, execute the following commands as root: + +```shell +PGHOST= +PGPORT= +PGUSER=agent +PGSSLCERT=/root/.pem/agent.crt +PGSSLKEY=/root/.pem/agent.key +PGSSLMODE=require + +export PGHOST PGPORT PGUSER PGSSLCERT PGSSLKEY PGSSLMODE + + -A -t -c "SELECT version()" +``` +Where: +- `` is the full path to the psql executable, for example `/usr/edb/as15/bin/psql`. +- `` is the hostname or IP address of PEM server. +- `` is the PEM backend database server port. +- `` is the ID of the agent you're testing, as defined in the file `/usr/edb/pem/agent/etc/agent.cfg`. + +!!! Note +If you used the instructions in [Generate a common agent certificate and key pair](/pem/latest/certificates/#generate-a-common-agent-certificate-and-key-pair) +you must set `PGUSER` to the common agent username. + +If the connection succeeds, it returns the Postgres version of the database server. Success means that your certificate is valid and the Postgres user is correctly configured. diff --git a/product_docs/docs/pem/9/certificates/regenerating_agent_certificates.mdx b/product_docs/docs/pem/9/certificates/regenerating_agent_certificates.mdx new file mode 100644 index 00000000000..2fb9916de1a --- /dev/null +++ b/product_docs/docs/pem/9/certificates/regenerating_agent_certificates.mdx @@ -0,0 +1,95 @@ +--- +title: "Regenerating the agent self-signed SSL certificates" + +redirects: +- /pem/latest/managing_certificates/#updating-agent-ssl-certificates +--- + +You need to regenerate the agent certificates and key files: +- If the PEM server certificates are regenerated +- If the PEM agent certificates are near expiring + +You must regenerate a certificate and a key for each agent interacting with the PEM server and copy it to the agent. + +Each agent has a unique identifier that's stored in the pem.agent table of the pem database. You must replace the certificate and key files with the certificate or key files that corresponds to the agent's identifier. + +Prerequisites: +- PEM server has self-signed certificates. +- `ca_certificate.crt` and `ca_key.key` are in the data directory of the PEM backend database server. +- `ca_certificate.crt` is the same as `root.crt`. +- `ca_certificate.crt` and `ca_key.key` are valid SSL certificates and keys. + +To generate a PEM agent certificate and key file pair: + +1. Use psql to find the number of agents and their corresponding identifiers: + + ```shell + # Running as enterprisedb + psql -p 5444 -U enterprisedb -d pem --no-psqlrc -t -A -c "SELECT id FROM pem.agent WHERE active=true" + ``` + +1. Stop all the running PEM agents: + + ```shell + # Running as root + systemctl stop pemagent + ``` + + On Windows, use the Services applet to stop the PEM agent. The PEM agent service is named Postgres Enterprise Manager Agent. In the Services dialog box, select the service name, and select **Stop the service**. + +1. After identifying the agents that need key files, generate an `agent.key` for each agent: + + ```shell + openssl genrsa -out agent.key 4096 + ``` + + Where `ID` is the agent identifier. + +1. Generate a certificate signing request (CSR) for each agent: + + ```shell + openssl req -new -key agent.key -out agent.csr -subj '/C=IN/ST=MH/L=Pune/O=PEM/CN=agent' + ``` + + Where `CN` is the `agent`. + +1. Use the `openssl x509` command to sign the CSR and generate an agent certificate: + + ```shell + openssl x509 -req -days 365 -in agent.csr -CA ca_certificate.crt -CAkey ca_key.key -CAcreateserial -out agent.crt + ``` + + Where `-req` indicates the input is a CSR. The `-CA` and `-CAkey` options specify the root certificate and private key to use for signing the CSR. + + Before generating the next certificate and key file pair, move the `agent.key` and `agent.crt` files generated in the steps 2 and 4 on their respective PEM agent host. + +1. Change the permission on the new `agent.crt` and `agent.key` file: + + ```shell + chmod 600 agent.crt agent.key + ``` + +1. Back up the old agent certificate and key files: + + ```shell + mkdir root/.pem/certs + mv root/.pem/agent.* root/.pem/certs + ``` + +1. Replace each agent's certificate and key file with the newly generated files: + + ```shell + cp agent.key agent.crt root/.pem + ``` + +1. Start the PEM agent service. + + - On Linux: + + ```shell + # Running as root + systemctl start pemagent + ``` + + - On Windows: + Use the Services applet to start the PEM agent. The PEM agent service is named Postgres Enterprise Manager Agent. In the Services dialog box, select the service name, and select **Start the service**. diff --git a/product_docs/docs/pem/9/certificates/replacing_ssl_certificates.mdx b/product_docs/docs/pem/9/certificates/replacing_ssl_certificates.mdx new file mode 100644 index 00000000000..7aaca767554 --- /dev/null +++ b/product_docs/docs/pem/9/certificates/replacing_ssl_certificates.mdx @@ -0,0 +1,130 @@ +--- +title: "Regenerating the server self-signed SSL certificates" + +redirects: +- /pem/latest/managing_certificates/#replacing-ssl-certificates +--- + +If the PEM backend database server certificates are near expiring, plan to regenerate the certificates and key files. + +To replace the self-signed SSL certificates: + +1. Stop all running PEM agents, first on the server host and then on any monitored host. + - On Linux: + + ```shell + # Running as root + systemctl stop pemagent + ``` + + - On Windows: + Use the Services applet to stop the PEM agent. The PEM agent service is named Postgres Enterprise Manager Agent. In the Services dialog box, select the service name, and select **Stop the service**. + +1. Back up the existing SSL certificates and keys: + + ```shell + cd /var/lib/edb/as/data + mkdir certs + mv server.* root.* ca_* certs/ + ``` + +1. Use the `openssl` command to generate the `ca_key.key` file: + + ```shell + openssl genrsa -out ca_key.key 4096 + ``` + +1. Move the `ca_key.key` file to the data directory of the backend server, and change the permissions: + + ```shell + mv ca_key.key /var/lib/edb/as/data + chmod 600 /var/lib/edb/as/data/ca_key.key + ``` + +1. Use `ca_key.key` to generate the `ca_certificate.crt` file: + + ```shell + openssl req -x509 -nodes -days 3650 -newkey rsa:4096 -keyout ca_key.key -out ca_certificate.crt + ``` + +1. Change the permissions of the `ca_certificate.crt` file: + + ```shell + chmod 600 /var/lib/edb/as/data/ca_certificate.crt + ``` + +1. Reuse the `ca_certificate.crt` file as the `root.crt` file: + + ```shell + cp /var/lib/edb/as/data/ca_certificate.crt /var/lib/edb/as/data/root.crt + ``` + +1. Change the owner and permissions on the `root.crt` file: + + ```shell + chown enterprisedb /var/lib/edb/as/data/root.crt + chmod 600 /var/lib/edb/as/data/root.crt + ``` + +1. Use the `openssl_rsa_generate_crl()` function to create the certificate revocation list `root.crl`: + + ```shell + psql -U enterprisedb -d pem --no-psqlrc -t -A -c + "SELECT openssl_rsa_generate_crl('/var/lib/edb/as/data/ca_certificate.crt', '/var/lib/edb/as/data/ca_key.key')" > /var/lib/edb/as/data/root.crl + ``` + +1. Change the ownership and permissions of the `root.crl` file: + + ```shell + chown enterprisedb /var/lib/edb/as/data/root.crl + chmod 600 /var/lib/edb/as/data/root.crl + ``` + +1. Use the `openssl` command to generate the `server.key` file: + + ```shell + openssl genrsa -out server.key 4096 + ``` + +1. Move the `server.key` to the data directory of the backend server, and change the ownership and permissions: + + ```shell + mv server.key /var/lib/edb/as/data + chown enterprisedb /var/lib/edb/as/data/server.key + chmod 600 /var/lib/edb/as/data/server.key + ``` + +1. Use the `openssl req` command to create the CSR: + + ```shell + openssl req -new -key server.key -out server.csr -subj '/C=IN/ST=MH/L=Pune/O=EDB/CN=PEM' + ``` + + Where `-subj` is provided as per your requirements. You define `CN` asthe hostname/domain name of the PEM server host. + +1. Use the `openssl x509` command to sign the CSR and generate a server certificate. Move the `server.crt` to the data directory of the backend database server: + + ```shell + openssl x509 -req -days 365 -in server.csr -CA ca_certificate.crt -CAkey ca_key.key -CAcreateserial -out server.crt + mv server.crt /var/lib/edb/as/data + ``` + + Where `-req` indicates the input is a CSR. The `-CA` and `-CAkey` options specify the root certificate and private key to use for signing the CSR. + +1. Change the owner and the permissions on the `server.crt` file: + + ```shell + chown enterprisedb /var/lib/edb/as/data/server.crt + chmod 600 /var/lib/edb/as/data/server.crt + ``` + +1. Restart the PEM server: + + ```shell + systemctl restart edb-as- + ``` + + Restarting the backend database server restarts the PEM server. + +1. Regenerate each PEM agent's self-signed SSL certificates. For more information, see [Regenerating agent SSL certificates](/pem/latest/certificates/regenerating_agent_certificates). + diff --git a/product_docs/docs/pem/9/considerations/pem_pgbouncer/configuring_the_pem_agent.mdx b/product_docs/docs/pem/9/considerations/pem_pgbouncer/configuring_the_pem_agent.mdx index f87e6b34a13..3bebefdbc2c 100644 --- a/product_docs/docs/pem/9/considerations/pem_pgbouncer/configuring_the_pem_agent.mdx +++ b/product_docs/docs/pem/9/considerations/pem_pgbouncer/configuring_the_pem_agent.mdx @@ -16,10 +16,7 @@ Don't configure the PEM agent responsible for sending SNMP notifications with pg After using an RPM package to install the PEM agent, you must configure it to work against a particular PEM database server. Use the following command: ```shell -$ PGSSLMODE=require PEM_SERVER_PASSWORD=pem_admin1_password -/usr/edb/pem/agent/bin/pemworker --register-agent --pem-server -pem_agent_user1 --display-name "Agent Name" - +$ PGSSLMODE=require PEM_SERVER_PASSWORD=pem_admin1_password /usr/edb/pem/agent/bin/pemworker --register-agent --pem-server 172.16.254.22 --pem-port 6432 --pem-user pem_admin1 --pem-agent-user pem_agent_user1 --display-name *Agent_Name* Postgres Enterprise Manager Agent registered successfully! ``` diff --git a/product_docs/docs/pem/9/index.mdx b/product_docs/docs/pem/9/index.mdx index 6196514ff6b..22dd5094773 100644 --- a/product_docs/docs/pem/9/index.mdx +++ b/product_docs/docs/pem/9/index.mdx @@ -23,7 +23,7 @@ navigation: - managing_pem_server - managing_database_server - managing_pem_agent - - managing_certificates + - certificates - managing_configuration_settings - troubleshooting_agent - "#Using" diff --git a/product_docs/docs/pem/9/managing_certificates.mdx b/product_docs/docs/pem/9/managing_certificates.mdx deleted file mode 100644 index 94f57660dba..00000000000 --- a/product_docs/docs/pem/9/managing_certificates.mdx +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: "Managing certificates" -navTitle: "Certificates" -legacyRedirectsGenerated: - # This list is generated by a script. If you need add entries, use the `legacyRedirects` key. - - "/edb-docs/d/edb-postgres-enterprise-manager/user-guides/administrators-guide/8.0/managing_certificates.html" -# This file is moved from pem_admin/04_managing_certificates -redirects: -- /pem/latest/pem_admin/04_managing_certificates/ ---- - -Files stored in the data directory of the PEM server backing database contain information that helps the PEM server use secure connections: - -- `ca_certificate.crt` -- `ca_key.key` -- `server.crt` -- `server.key` -- `root.crl` -- `root.crt` - -The PEM agent that's installed with the PEM server monitors the expiration date of the `ca_certificate.crt` file. When the certificate is about to expire, PEM: - -- Makes a backup of the existing certificate files. -- Creates new certificate files, appending the new CA certificate file to the `root.crt` file on the PEM server. -- Creates a job that renews the certificate file of any active agents. -- Restarts the PEM server. - -When you uninstall an agent, the certificate associated with that agent is added to the certificate revocation list maintained in the `root.crl` file to ensure that you can't use the certificate to connect to the PEM server. - -You can manually replace certificate files. - -## Replacing SSL certificates - -You can replace the SSL certificates on an existing PEM installation. If you plan to upgrade your server to a new version at the same time, invoke all of the PEM installers (first the server installer, then agent installers) before replacing the SSL certificates. Then: - -1. Stop all running PEM agents, first on the server host, and then on any monitored node. - - To stop a PEM agent on a Linux host, open a terminal window, assume superuser privileges, and enter the command: - - On Linux with systemd, for example, Centos 7 or 8 - - ```shell - systemctl stop pemagent - ``` - - On a Windows host, you can use the Services applet to stop the PEM agent. The PEM agent service is named Postgres Enterprise Manager Agent. Select the service name in the Services dialog box and select **Stop the service**. - -2. Take a backup of the existing SSL keys and certificates. The SSL keys and certificates are stored in the `data` directory under your PEM installation. For example, the default location on a Linux system is: - - `/var/lib/pgsql/x/data`, where `x` is the PostgreSQL database version - - Copy the following files, adding an extension to each file to make the name unique: - - - `ca_certificate.crt` - - `ca_key.key` - - `root.crt` - - `root.crl` - - `server.key` - - `server.crt` - - For example, to creates a backup of the `ca_certificate` file with the word `old` appended to the entry, use this command: - - ```shell - # cp ca_certificate.crt ca_certificate_old.crt - ``` - -3. Use the `openssl_rsa_generate_key()` function to generate the `ca_key.key` file: - - ```shell - /usr/pgsql-x.x/bin/psql -U postgres -d pem --no-psqlrc -t -A -c "SELECT public.openssl_rsa_generate_key(1024)" > /var/lib/pgsql/x/data/ca_key.key - ``` - - After creating the `ca_key.key` file, `cat` the contents to the variable `CA_KEY` for use when generating the `ca_certificate.crt` file. Modify the privileges on the `ca_key.key` file: - - ```shell - CA_KEY=$(cat /var/lib/pgsql/x/data/ca_key.key) - - chmod 600 /var/lib/pgsql/x/data/ca_key.key - ``` - -4. Use the key to generate the `ca_certificate.crt` file. For simplicity, place the SQL query in a temporary file with a unique name: - - ```shell - echo "SELECT openssl_csr_to_crt(openssl_rsa_key_to_csr('${CA_KEY}', - 'PEM','US', 'MA', 'Bedford', 'Postgres Enterprise Manager', - 'support@enterprisedb.com'), NULL, - '/var/lib/pgsql/x/data/ca_key.key')" > /tmp/_random.$$ - ``` - - Then use the variable to execute the query, placing the content in the `ca_certificate.crt` file. - - ```shell - /usr/pgsql-x/bin/psql -U postgres -d pem --no-psqlrc -t -A -f /tmp/_random.$$ > /var/lib/pgsql/x/data/ca_certificate.crt - ``` - - Modify the permissions of the `ca_certificate.crt` file, and remove the temporary file that contained the SQL command: - - ```shell - chmod 600 /var/lib/pgsql/x/data/ca_certificate.crt - - rm -f /tmp/_random.$$ - ``` - -5. Reuse the `ca_certificate.crt` file as the `root.crt` file: - - ```shell - cp /var/lib/pgsql/x/data/ca_certificate.crt /var/lib/pgsql/x/data/root.crt - ``` - - Modify the permissions of the `root.crt` file: - - ```shell - chmod 600 /var/lib/pgsql/x/data/root.crt - ``` - -6. Use the `openssl_rsa_generate_crl()` function to create the certificate revocation list (`root.crl`): - - ```shell - /usr/pgsql-x/bin/psql -U postgres -d pem --no-psqlrc -t -A -c - "SELECT openssl_rsa_generate_crl('/var/lib/pgsql/x/data/ca_certificate.crt', '/var/lib/pgsql/x/data/ca_key.key')" > /var/lib/pgsql/x/data/root.crl - ``` - - Modify the permissions of the `root.crl` file: - - ```shell - chmod 600 /var/lib/pgsql/x/data/root.crl - ``` - -7. Use the `openssl_rsa_generate_key()` function to generate the `server.key` file: - - ```shell - /usr/pgsql-x/bin/psql -U postgres -d pem --no-psqlrc -t -A -c "SELECT public.openssl_rsa_generate_key(1024)" >> /var/lib/pgsql/x/data/server.key - ``` - - After creating the `server.key` file, `cat` the contents to the variable `SSL_KEY` for use when generating the `server.crt` file and modify the privileges on the `server.key` file: - - ```shell - SSL_KEY=$(cat /var/lib/pgsql/x/data/server.key) - - chmod 600 /var/lib/pgsql/x/data/server.key - ``` - -8. Use the `SSL_KEY` to generate the server certificate. Save the certificate in the `server.crt` file. For simplicity, first place the SQL query into a temporary file with a unique name: - - ```shell - echo "SELECT openssl_csr_to_crt(openssl_rsa_key_to_csr('${SSL_KEY}', - 'PEM','US', 'MA', 'Bedford', 'Postgres Enterprise Manager', - 'support@enterprisedb.com'), - '/var/lib/pgsql/x/data/ca_certificate.crt', - '/var/lib/pgsql/x/data/ca_key.key')" > /tmp/_random.$$ - - /usr/pgsql-x/bin/psql -U postgres -d pem --no-psqlrc -t -A -f /tmp/_random.$$ >> /var/lib/pgsql/x/data/server.crt - ``` - -9. Modify the privileges on the `server.crt` file, and delete the temporary file: - - ```shell - chmod 600 /var/lib/pgsql/x/data/server.crt - - rm -f /tmp/_random.$$ - ``` - -10. Restart the Postgres server: - - On Linux with `init.d`, for example, on a Centos6 host: - - ```shell - /etc/init.d/postgresql-x restart - ``` - - On Linux with `systemd`, for example, on a Centos7 host: - - ```shell - systemctl restart postgresql-x - ``` - -## Updating agent SSL certificates - -For each agent that interacts with the PEM server, you must: - -- Generate an rsa key and a certificate. -- Copy the key and certificate to the agent. -- Restart the agent. - -Each agent has a unique identifier that's stored in the `pem.agent` table in the `pem` database. You must replace the key and certificate files with the key or certificate that corresponds to the agent's identifier. You must move the `agent.key` and `agent.crt` files generated in Steps 2 and 3 into place on their respective PEM agent host before generating the next key file pair. Subsequent commands overwrite the previously generated file. - -To generate a PEM agent key file pair: - -1. Use psql to find the number of agents and their corresponding identifiers: - - ```shell - /usr/pgsql-x/bin/psql -U postgres -d pem --no-psqlrc -t -A -c "SELECT ID FROM pem.agent" - ``` - -- On Linux, you can also find the agent identifier and location of the keys and certificates in the `PEMagent` section of the `/etc/postgres-reg.ini` file. - -- On Windows, the information is stored in the registry: - - - On a 64-bit Windows installation, check: - - ```shell - HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\EnterpriseDB\PEM\agent - ``` - - - On a 32-bit Windows installation, check: - - ```shell - HKEY_LOCAL_MACHINE\SOFTWARE\EnterpriseDB\PEM\agent - ``` - -2. After identifying the agents that need key files, generate an `agent.key` for each agent. To generate the key, execute the following command, capturing the output in a file: - - ```shell - /usr/pgsql-x/bin/psql -U postgres -d pem --no-psqlrc -t -A -c "SELECT openssl_rsa_generate_key(1024)" > agent.key - ``` - - Modify the privileges of the `agent.key` file: - - ```shell - chmod 600 agent.key - ``` - -3. Generate a certificate for each agent. To generate a certificate, execute the following command, capturing the output in a certificate file: - - ```shell - /usr/pgsql-x/bin/psql -U postgres -d pem --no-psqlrc -t -A -c - "SELECT openssl_csr_to_crt(openssl_rsa_key_to_csr('$(cat agent.key)', - 'agent<$ID>', 'US', 'MA', 'Bedford', 'Postgres Enterprise Manager', - 'support@enterprisedb.com'), - '/var/lib/pgsql/x/data/ca_certificate.crt', - '/var/lib/pgsql/x/data/ca_key.key')" > agent.crt - ``` - - Where `$ID` is the agent number of the agent (retrieved by the psql command line). - -4. Modify the privileges of the `agent.crt` file: - - ```shell - chmod 600 agent.crt - ``` - -5. Replace each agent's key and certificate file with the newly generated files before restarting the PEM agent service: - - On Linux with `init.d`, restart the service with the command: - - ```shell - /etc/init.d/pemagent start - ``` - - On Linux with `systemd`, restart the service with the command: - - ```shell - systemctl start pemagent - ``` - - On a Windows host, you can use the Services applet to start the PEM agent. The PEM agent service is named Postgres Enterprise Manager Agent. Select the service name in the Services dialog box and select **Start the service**. diff --git a/product_docs/docs/pem/9/registering_database_server.mdx b/product_docs/docs/pem/9/registering_database_server.mdx index 566bd0f0077..7b45f0ff24a 100644 --- a/product_docs/docs/pem/9/registering_database_server.mdx +++ b/product_docs/docs/pem/9/registering_database_server.mdx @@ -20,7 +20,8 @@ To manage or monitor a database server with PEM, you must: You can use the Create Server dialog box to provide registration information for a server, bind a PEM agent, and display the server in the PEM client tree. To open the Create Server dialog box, select **Object > Create > Server**. !!! Note - You must ensure the `pg_hba.conf` file of the Postgres server that you're registering allows connections from the host of the PEM client before attempting to connect. +- You must ensure the `pg_hba.conf` file of the Postgres server that you're registering allows connections from the host of the PEM client before attempting to connect. +- Only database superusers or users with the `pem_admin` role can bind a database server to a PEM agent. Use the **General** tab to describe the general properties of the server: diff --git a/product_docs/docs/pgd/5/quickstart/quick_start_aws.mdx b/product_docs/docs/pgd/5/quickstart/quick_start_aws.mdx index adebaff3aa0..f48da5555c4 100644 --- a/product_docs/docs/pgd/5/quickstart/quick_start_aws.mdx +++ b/product_docs/docs/pgd/5/quickstart/quick_start_aws.mdx @@ -134,7 +134,7 @@ tpaexec configure democluster \ ``` We specify the PGD-Always-ON architecture (`--architecture PGD-Always-ON`): this sets up the configuration for [PGD 5's Always On architectures](/pgd/latest/architectures/). As part of the default architecture, -this configures our cluster with three data nodes, co-hosting three [PGD Proxy](routing/proxy/) servers, along with a [Barman](backup#physical-backup) node for backup. +this configures our cluster with three data nodes, co-hosting three [PGD Proxy](../routing/proxy/) servers, along with a [Barman](../backup#physical-backup) node for backup. We specify using AWS (`--platform aws`) and eu-west-1 as the region (`--region eu-west-1`). @@ -169,7 +169,8 @@ less democluster/config.yml ```shell tpaexec configure --architecture PGD-Always-ON --help ``` - - More details on PGD-Always-ON configuration options in [Deploying with TPA](tpa) + - More details on PGD-Always-ON configuration options in [Deploying with TPA](../tpa) + - [PGD-Always-ON](/tpa/latest/architecture-PGD-Always-ON/) in the Trusted Postgres Architect documentation - [`tpaexec configure`](/tpa/latest/tpaexec-configure/) in the Trusted Postgres Architect documentation - [AWS platform](/tpa/latest/platform-aws/) in the Trusted Postgres Architect documentation diff --git a/product_docs/docs/pgd/5/quickstart/quick_start_docker.mdx b/product_docs/docs/pgd/5/quickstart/quick_start_docker.mdx index d33dfd44568..187fdab4b4e 100644 --- a/product_docs/docs/pgd/5/quickstart/quick_start_docker.mdx +++ b/product_docs/docs/pgd/5/quickstart/quick_start_docker.mdx @@ -160,8 +160,8 @@ tpaexec configure democluster \ --hostnames-unsorted ``` -We specify the PGD-Always-ON architecture (`--architecture PGD-Always-ON`): this sets up the configuration for [PGD 5's Always On architectures](/pgd/latest/architectures/). As part of the default architecture, -this configures our cluster with three data nodes, co-hosting three [PGD Proxy](routing/proxy/) servers, along with a [Barman](backup#physical-backup) node for backup. +We specify the PGD-Always-ON architecture (`--architecture PGD-Always-ON`): this sets up the configuration for [PGD 5's Always On architectures](../architectures/). As part of the default architecture, +this configures our cluster with three data nodes, co-hosting three [PGD Proxy](../routing/proxy/) servers, along with a [Barman](../backup#physical-backup) node for backup. We specify using Docker (`--platform docker`). By default, TPA configures Rocky Linux as the default image for all nodes. @@ -189,8 +189,8 @@ less democluster/config.yml ```shell tpaexec configure --architecture PGD-Always-ON --help ``` - - More details on PGD-Always-ON configuration options in [Deploying with TPA](tpa) - - [PGD-Always-ON](architecture-PGD-Always-ON/) in the Trusted Postgres Architect documentation + - More details on PGD-Always-ON configuration options in [Deploying with TPA](../tpa) + - [PGD-Always-ON](/tpa/latest/architecture-PGD-Always-ON/) in the Trusted Postgres Architect documentation - [`tpaexec configure`](/tpa/latest/tpaexec-configure/) in the Trusted Postgres Architect documentation - [Docker platform](/tpa/latest/platform-docker/) in the Trusted Postgres Architect documentation diff --git a/product_docs/docs/pgd/5/tpa.mdx b/product_docs/docs/pgd/5/tpa.mdx index 0a846f0a337..6eebed73561 100644 --- a/product_docs/docs/pgd/5/tpa.mdx +++ b/product_docs/docs/pgd/5/tpa.mdx @@ -48,12 +48,14 @@ The available configuration options include: | Flags | Description | | ------------------ | ----------- | | `--architecture` | Required. Set to `PGD-Always-ON` for EDB Postgres Distributed deployments. | +| `–-postgresql `
or
`--edb-postgres-advanced `
or
`--edb-postgres-extended ` | Required. Specifies the distribution and version of Postgres to use. For more details, see [Cluster configuration: Postgres flavour and version](/tpa/latest/tpaexec-configure/#postgres-flavour-and-version). | +| `--redwood` or `--noredwood` | Required when `--edb-postgres-advanced` flag is present. Specifies whether Oracle database compatibility features are desired. | | `--location-names l1 l2 l3` | Required. Specifies the number and name of the locations PGD will be deployed to. | | `--data-nodes-per-location N` | Specifies number of data nodes per location. Default 3. | | `--add-witness-node-per-location` | For even number of data nodes per location, this will add witness node to allow for local consensus. This is enabled by default for 2 data node locations. | -| `--cohost-proxies` | Whether to put PGD-Proxies to data nodes. By default proxies are installed to separate hosts | +| `--add-proxy-nodes-per-location` | Whether to separate PGD-Proxies from data nodes, and how many to configure. By default one proxy is configured and cohosted for each data node. | | `--active-locations l2 l3` | Which locations should have local connection routing configured. By default global routing is configured. | -| `--add-witness-only-location loc` | This designates one of the cluster location as witness only (no data nodes will be present in that location) | +| `--add-witness-only-location loc` | This designates one of the cluster location as witness only (no data nodes will be present in that location). | | `--enable-camo` | Sets up CAMO pair in each location. This only works with 2 data node per location. | More configuration options are listed in the TPA documentation for [PGD-Always-ON](/tpa/latest/architecture-PGD-Always-ON/). @@ -70,7 +72,7 @@ For example: The first argument must be the cluster directory, for example, `speedy` or `~/clusters/speedy` (the cluster is named `speedy` in both cases). We recommend that you keep all your clusters in a common directory, for example, `~/clusters`. The next argument must be `--architecture` to select an architecture, followed by options. -The command creates a directory named ~/clusters/speedy and generates a configuration file named `config.yml` that follows the layout of the PGD-Always-ON architecture. You can use the `tpcaexec info` command to see what values are supported for the configuration options based on what you specified when running the configure command. +The command creates a directory named ~/clusters/speedy and generates a configuration file named `config.yml` that follows the layout of the PGD-Always-ON architecture. You can use the `tpaexec configure --architecture PGD-Always-ON --help` command to see what values are supported for the configuration options in this architecture. ### Common configuration options @@ -125,7 +127,7 @@ Optionally, use `--edb-repositories repository …` to specify EDB repositories ### Software versions -By default TPA uses the latest major version of Postgres. Specify `--postgres-version` to install an earlier supported major version. +By default TPA uses the latest major version of Postgres. Specify `--postgres-version` to install an earlier supported major version, or specify both version and distribution via one of the flags described under [Configure](#configure), above. By default, TPA always installs the latest version of every package. This is usually the desired behavior, but in some testing scenarios, it may be necessary to select specific package versions. For example, diff --git a/src/constants/products.js b/src/constants/products.js index e8a9ea8574b..43434f8b891 100644 --- a/src/constants/products.js +++ b/src/constants/products.js @@ -11,7 +11,7 @@ export const products = { edb_plus: { name: "EDB*Plus" }, efm: { name: "Failover Manager", iconName: IconNames.EDB_EFM }, epas: { name: "EDB Postgres Advanced Server", iconName: IconNames.EDB_EPAS }, - epd: { name: "EDB Postgres Distributed", iconName: IconNames.EDB_EPAS }, + pgd: { name: "EDB Postgres Distributed", iconName: IconNames.EDB_EPAS }, eprs: { name: "EDB Replication Server", iconName: IconNames.EDB_EPAS }, hadoop_data_adapter: { name: "Hadoop Data Adapter",