From faf8831227ba4a24334e54b1a3b82f531fc1a68b Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Thu, 19 Mar 2026 12:30:32 +0530 Subject: [PATCH 01/27] PBM-1268 Securely Store CLI Credentials using systemd --- docs/install/secure-credentials-systemd.md.md | 19 +++++++++++++++++++ mkdocs-base.yml | 1 + 2 files changed, 20 insertions(+) create mode 100644 docs/install/secure-credentials-systemd.md.md diff --git a/docs/install/secure-credentials-systemd.md.md b/docs/install/secure-credentials-systemd.md.md new file mode 100644 index 00000000..dfa5b3b4 --- /dev/null +++ b/docs/install/secure-credentials-systemd.md.md @@ -0,0 +1,19 @@ +# Secure credential management with systemd + +## Overview + +Percona Backup for MongoDB (PBM) requires access to sensitive credentials such as: + +- MongoDB connection URI (PBM_MONGODB_URI) + +- Object storage credentials defined in PBM configuration (pbm config) + +By default, these credentials are often stored in plaintext in environment variables or configuration files. This introduces security risks such as credential leakage and unauthorized access. + +This section describes how to securely manage PBM credentials using systemd service credentials. + +## Why use systemd credentails + +Storing credentials in plaintext significantly increases the risk of compromise. Secrets placed in configuration files or environment variables can be exposed through file access, process inspection, or unauthorized system access. + +`systemd` credentials mitigate these risks by enforcing strict runtime security controls. diff --git a/mkdocs-base.yml b/mkdocs-base.yml index 55f06498..a034fb7b 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -187,6 +187,7 @@ nav: - 2. Set up and configure: - Initial setup: install/initial-setup.md - install/configure-authentication.md + - Secure credentials with systemd: install/secure-credentials-systemd.md - install/backup-storage.md - Start the pbm-agent process: install/start-pbm-agent.md - Backup and restore: From b64558ea46fd87b0f522122c8b3091283497026c Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Thu, 19 Mar 2026 13:06:27 +0530 Subject: [PATCH 02/27] changed the filke name --- docs/install/secure-credentials-systemd.md | 67 +++++++++++++++++++ docs/install/secure-credentials-systemd.md.md | 19 ------ 2 files changed, 67 insertions(+), 19 deletions(-) create mode 100644 docs/install/secure-credentials-systemd.md delete mode 100644 docs/install/secure-credentials-systemd.md.md diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md new file mode 100644 index 00000000..9a2e4f3e --- /dev/null +++ b/docs/install/secure-credentials-systemd.md @@ -0,0 +1,67 @@ +# Secure credential management with systemd + +## Overview + +Percona Backup for MongoDB (PBM) requires access to sensitive credentials such as: + +- MongoDB connection URI (PBM_MONGODB_URI) + +- Object storage credentials defined in PBM configuration (pbm config) + +By default, these credentials are often stored in plaintext in environment variables or configuration files. This introduces security risks such as credential leakage and unauthorized access. + +This section describes how to securely manage PBM credentials using systemd service credentials. + +## Why use systemd credentails + +Storing credentials in plaintext significantly increases the risk of compromise. Secrets placed in configuration files or environment variables can be exposed through file access, process inspection, or unauthorized system access. + +`systemd` credentials mitigate these risks by enforcing strict runtime security controls. + + +## Prerequisites + +- systemd version 250 or higher +- Root or sudo privileges +- (Optional) TPM2 support for hardware-backed encryption +- Kernel 5.4+ + + +## Procedure + +Here are the steps to integrate PBM with systemd's [System and service credentials :octicons-link-external-16:](https://systemd.io/CREDENTIALS/) +{.power-number} + +1. Create a **temporary file** containing your connection string: + + ```sh + echo "mongodb-uri: mongodb://pbmuser:secretpwd@localhost:27017/?authSource=admin" > pbm_uri.yaml + ``` + +2. Encrypt the credential using the local system key (and Trusted Platform Module version 2.0 if available): + + ```sh + systemd-creds encrypt --name=pbm_connection.yaml pbm_uri.yaml pbm_connection.yaml.cred + ``` + +3. Securely delete the plain text file: + + ```sh + shred -u pbm_uri.yaml + ``` + +4. Update the PBM systemd unit file `(/lib/systemd/system/pbm-agent.service)`: + + ```sh + [Service] + # Path to the encrypted file created in Step 2 + LoadCredentialEncrypted=pbm_connection.yaml:/path/to/pbm_connection.yaml.cred + + # Enable namespacing so other services cannot see this credential directory + PrivateMounts=yes + + # Pass the credential file path to PBM via the file + # %d resolves to the systemd credentials directory + ExecStart=/usr/bin/pbm-agent -f /run/credentials/%n/pbm_connection.yaml + ``` + diff --git a/docs/install/secure-credentials-systemd.md.md b/docs/install/secure-credentials-systemd.md.md deleted file mode 100644 index dfa5b3b4..00000000 --- a/docs/install/secure-credentials-systemd.md.md +++ /dev/null @@ -1,19 +0,0 @@ -# Secure credential management with systemd - -## Overview - -Percona Backup for MongoDB (PBM) requires access to sensitive credentials such as: - -- MongoDB connection URI (PBM_MONGODB_URI) - -- Object storage credentials defined in PBM configuration (pbm config) - -By default, these credentials are often stored in plaintext in environment variables or configuration files. This introduces security risks such as credential leakage and unauthorized access. - -This section describes how to securely manage PBM credentials using systemd service credentials. - -## Why use systemd credentails - -Storing credentials in plaintext significantly increases the risk of compromise. Secrets placed in configuration files or environment variables can be exposed through file access, process inspection, or unauthorized system access. - -`systemd` credentials mitigate these risks by enforcing strict runtime security controls. From de45d284e43a43556de1364bb1ee48e435405b0f Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Thu, 19 Mar 2026 13:23:20 +0530 Subject: [PATCH 03/27] fix code block formatting --- docs/install/secure-credentials-systemd.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index 9a2e4f3e..da6804c2 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -50,18 +50,24 @@ Here are the steps to integrate PBM with systemd's [System and service credentia shred -u pbm_uri.yaml ``` -4. Update the PBM systemd unit file `(/lib/systemd/system/pbm-agent.service)`: +4. Update the PBM systemd unit file + + Edit: + + `(/lib/systemd/system/pbm-agent.service)` + + Update [Service]: ```sh [Service] # Path to the encrypted file created in Step 2 - LoadCredentialEncrypted=pbm_connection.yaml:/path/to/pbm_connection.yaml.cred + LoadCredentialEncrypted=pbm_connection.yaml:/path/to/pbm_connection.yaml.cred # Enable namespacing so other services cannot see this credential directory - PrivateMounts=yes +PrivateMounts=yes # Pass the credential file path to PBM via the file # %d resolves to the systemd credentials directory - ExecStart=/usr/bin/pbm-agent -f /run/credentials/%n/pbm_connection.yaml + ExecStart=/usr/bin/pbm-agent -f /run/credentials/%n/pbm_connection.yaml ``` From c65721d83f43d5486ba8eac4642b78b3ed0d117f Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Thu, 19 Mar 2026 13:29:25 +0530 Subject: [PATCH 04/27] Update secure-credentials-systemd.md --- docs/install/secure-credentials-systemd.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index da6804c2..106e30d4 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -58,16 +58,10 @@ Here are the steps to integrate PBM with systemd's [System and service credentia Update [Service]: - ```sh - [Service] - # Path to the encrypted file created in Step 2 - LoadCredentialEncrypted=pbm_connection.yaml:/path/to/pbm_connection.yaml.cred - - # Enable namespacing so other services cannot see this credential directory -PrivateMounts=yes - - # Pass the credential file path to PBM via the file - # %d resolves to the systemd credentials directory - ExecStart=/usr/bin/pbm-agent -f /run/credentials/%n/pbm_connection.yaml ``` + [Service] LoadCredentialEncrypted=pbm_connection.yaml:/path/to/pbm_connection.yaml.cred + PrivateMounts=yes + ExecStart=/usr/bin/pbm-agent -f /run/credentials/%n/pbm_connection.yaml + ``` + From 97d4af417abe98be2d8b39d54bc492e0bb2d0f24 Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Thu, 19 Mar 2026 13:31:47 +0530 Subject: [PATCH 05/27] Update secure-credentials-systemd.md --- docs/install/secure-credentials-systemd.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index 106e30d4..5682e0f6 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -58,8 +58,9 @@ Here are the steps to integrate PBM with systemd's [System and service credentia Update [Service]: - ``` - [Service] LoadCredentialEncrypted=pbm_connection.yaml:/path/to/pbm_connection.yaml.cred + ```ini + [Service] + LoadCredentialEncrypted=pbm_connection.yaml:/path/to/pbm_connection.yaml.cred PrivateMounts=yes ExecStart=/usr/bin/pbm-agent -f /run/credentials/%n/pbm_connection.yaml ``` From 0ceb2b8d676e174c51f22c31ce87e25062e9456c Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Thu, 19 Mar 2026 13:36:00 +0530 Subject: [PATCH 06/27] Update secure-credentials-systemd.md --- docs/install/secure-credentials-systemd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index 5682e0f6..dac80e8e 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -58,7 +58,7 @@ Here are the steps to integrate PBM with systemd's [System and service credentia Update [Service]: - ```ini + ``` [Service] LoadCredentialEncrypted=pbm_connection.yaml:/path/to/pbm_connection.yaml.cred PrivateMounts=yes From 77ab1b11768332d2dce79fb1fd16fcdac2476e22 Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Thu, 19 Mar 2026 15:17:46 +0530 Subject: [PATCH 07/27] Update secure-credentials-systemd.md --- docs/install/secure-credentials-systemd.md | 35 +++++++++++++++++----- 1 file changed, 27 insertions(+), 8 deletions(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index dac80e8e..941009ef 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -50,19 +50,38 @@ Here are the steps to integrate PBM with systemd's [System and service credentia shred -u pbm_uri.yaml ``` -4. Update the PBM systemd unit file - - Edit: - - `(/lib/systemd/system/pbm-agent.service)` - - Update [Service]: +4. Edit the systemd unit file (default location at `/lib/systemd/system/pbm-agent.service)` and in the `[Service]` section, add the `LoadCredentialEncrypted` and `PrivateMounts directives:` ``` [Service] - LoadCredentialEncrypted=pbm_connection.yaml:/path/to/pbm_connection.yaml.cred + LoadCredentialEncrypted=pbm_connection.yaml:/path/to/pbm_connection.yaml.cred PrivateMounts=yes ExecStart=/usr/bin/pbm-agent -f /run/credentials/%n/pbm_connection.yaml ``` +5. Reload the systemd manager configuration: + + ```sh + sudo systemctl daemon-reload + ``` + +6. Restart the PBM agent: + + ```sh + sudo systemctl restart pbm-agent + ``` + + ??? info "What happens under the hood" + Systemd automatically decrypts the credential during service startup and places it in a temporary, non-swappable directory. + - The path to the decrypted plaintext is stored in the $CREDENTIALS_DIRECTORY environment variable. + - In the example above, the PBM agent will read the contents of the file at `%d/pbm_connection.yaml` as its connection string. + + +## How to verify? + +Run the following command to ensure the service can see the credential (this only works while the service is active): + +```sh +sudo cat /run/credentials/pbm-agent.service/pbm_connection.yaml +``` From c9388cbb798acafe3aaec3caaa21cb64ae48e21f Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Thu, 19 Mar 2026 15:19:42 +0530 Subject: [PATCH 08/27] Update secure-credentials-systemd.md --- docs/install/secure-credentials-systemd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index 941009ef..e37fbdf0 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -4,7 +4,7 @@ Percona Backup for MongoDB (PBM) requires access to sensitive credentials such as: -- MongoDB connection URI (PBM_MONGODB_URI) +- MongoDB connection URI (`PBM_MONGODB_URI`) - Object storage credentials defined in PBM configuration (pbm config) From a61e1225be5ea10c8eaadddbe5a852d114b601fa Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Thu, 19 Mar 2026 15:28:53 +0530 Subject: [PATCH 09/27] crosslink for improving the docs --- docs/install/configure-authentication.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/install/configure-authentication.md b/docs/install/configure-authentication.md index 5ca6874c..bcc09bd7 100644 --- a/docs/install/configure-authentication.md +++ b/docs/install/configure-authentication.md @@ -62,6 +62,10 @@ You can change the `username` and `password` values and specify other options fo The `pbm-agent.service` systemd unit file includes the location of the environment file. You set the MongoDB URI connection string for the `PBM_MONGODB_URI` variable within the environment file for every `pbm-agent`. +!!! warning "Security recommendation" + Avoid storing credentials (such as `PBM_MONGODB_URI`) in plaintext environment variables or service files. Instead, use `systemd` credentials for secure, encrypted, runtime-only access. + + ??? tip "How to find the environment file" In Ubuntu and Debian, the pbm-agent.service systemd unit file is at the path `/lib/systemd/system/pbm-agent.service`. From 1139738aa67ca06b9a4ef81152682146481dbcfc Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Thu, 19 Mar 2026 16:15:12 +0530 Subject: [PATCH 10/27] Update secure-credentials-systemd.md --- docs/install/secure-credentials-systemd.md | 24 +++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index e37fbdf0..384efdbe 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -4,19 +4,28 @@ Percona Backup for MongoDB (PBM) requires access to sensitive credentials such as: -- MongoDB connection URI (`PBM_MONGODB_URI`) +- **MongoDB connection URI** (`PBM_MONGODB_URI`) -- Object storage credentials defined in PBM configuration (pbm config) +- **Object storage credentials** defined in PBM configuration (pbm config) By default, these credentials are often stored in plaintext in environment variables or configuration files. This introduces security risks such as credential leakage and unauthorized access. -This section describes how to securely manage PBM credentials using systemd service credentials. +This section describes how to securely manage PBM credentials using **systemd service credentials**. -## Why use systemd credentails +## Why use systemd credentials? -Storing credentials in plaintext significantly increases the risk of compromise. Secrets placed in configuration files or environment variables can be exposed through file access, process inspection, or unauthorized system access. +Storing credentials in plaintext significantly increases the risk of compromise. Secrets placed in configuration files or environment variables can be exposed through: -`systemd` credentials mitigate these risks by enforcing strict runtime security controls. +- File access +- Process inspection (e.g., `ps`, `/proc`) +- Unauthorized system access. + +**`systemd` credentials** mitigate these risks by: + +- Encrypting credentials at rest +- Decrypting them only at service runtime +- Storing them in a temporary, non-swappable directory +- Restricting access to the service itself ## Prerequisites @@ -73,13 +82,14 @@ Here are the steps to integrate PBM with systemd's [System and service credentia ??? info "What happens under the hood" Systemd automatically decrypts the credential during service startup and places it in a temporary, non-swappable directory. + - The path to the decrypted plaintext is stored in the $CREDENTIALS_DIRECTORY environment variable. - In the example above, the PBM agent will read the contents of the file at `%d/pbm_connection.yaml` as its connection string. ## How to verify? -Run the following command to ensure the service can see the credential (this only works while the service is active): +Run the following command to ensure the service can see the credential. This file is only accessible while the service is running and is stored in a secure, temporary directory. ```sh sudo cat /run/credentials/pbm-agent.service/pbm_connection.yaml From db640c090daf4f758e13ca1cf235f3c803c39390 Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Thu, 19 Mar 2026 16:15:55 +0530 Subject: [PATCH 11/27] Update secure-credentials-systemd.md --- docs/install/secure-credentials-systemd.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index 384efdbe..26e2d2dd 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -82,8 +82,8 @@ Here are the steps to integrate PBM with systemd's [System and service credentia ??? info "What happens under the hood" Systemd automatically decrypts the credential during service startup and places it in a temporary, non-swappable directory. - - - The path to the decrypted plaintext is stored in the $CREDENTIALS_DIRECTORY environment variable. + + - The path to the decrypted plaintext is stored in the `$CREDENTIALS_DIRECTORY` environment variable. - In the example above, the PBM agent will read the contents of the file at `%d/pbm_connection.yaml` as its connection string. From 79184c1d5e4bded586e737d273d941383ae4aa0a Mon Sep 17 00:00:00 2001 From: Rasika Chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Fri, 20 Mar 2026 14:00:49 +0530 Subject: [PATCH 12/27] Update docs/install/secure-credentials-systemd.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/install/secure-credentials-systemd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index 26e2d2dd..846831d4 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -59,7 +59,7 @@ Here are the steps to integrate PBM with systemd's [System and service credentia shred -u pbm_uri.yaml ``` -4. Edit the systemd unit file (default location at `/lib/systemd/system/pbm-agent.service)` and in the `[Service]` section, add the `LoadCredentialEncrypted` and `PrivateMounts directives:` +4. Edit the systemd unit file (default location at `/lib/systemd/system/pbm-agent.service`) and in the `[Service]` section, add the `LoadCredentialEncrypted` and `PrivateMounts` directives: ``` [Service] From 97075f7d55de1e5b6e1183c2aec5de5a54130657 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 20 Mar 2026 08:31:33 +0000 Subject: [PATCH 13/27] Initial plan From bfe771ba79d17cda44d9daabf1be7624fe346b12 Mon Sep 17 00:00:00 2001 From: Rasika Chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Fri, 20 Mar 2026 14:02:05 +0530 Subject: [PATCH 14/27] Update docs/install/configure-authentication.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/install/configure-authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/configure-authentication.md b/docs/install/configure-authentication.md index bcc09bd7..6c0b37f3 100644 --- a/docs/install/configure-authentication.md +++ b/docs/install/configure-authentication.md @@ -63,7 +63,7 @@ You can change the `username` and `password` values and specify other options fo The `pbm-agent.service` systemd unit file includes the location of the environment file. You set the MongoDB URI connection string for the `PBM_MONGODB_URI` variable within the environment file for every `pbm-agent`. !!! warning "Security recommendation" - Avoid storing credentials (such as `PBM_MONGODB_URI`) in plaintext environment variables or service files. Instead, use `systemd` credentials for secure, encrypted, runtime-only access. + Avoid storing credentials (such as `PBM_MONGODB_URI`) in plaintext environment variables or service files. Instead, use `systemd` credentials for secure, encrypted, runtime-only access. For step-by-step instructions, see [Secure credentials with systemd](secure-credentials-systemd.md). ??? tip "How to find the environment file" From 69131bb160b5d15c51adaa39966b01e94261e21f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 20 Mar 2026 08:32:41 +0000 Subject: [PATCH 15/27] Clarify Step 1 creates a PBM agent YAML config file, not a raw URI file Co-authored-by: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> --- docs/install/secure-credentials-systemd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index 846831d4..6974a97a 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -41,7 +41,7 @@ Storing credentials in plaintext significantly increases the risk of compromise. Here are the steps to integrate PBM with systemd's [System and service credentials :octicons-link-external-16:](https://systemd.io/CREDENTIALS/) {.power-number} -1. Create a **temporary file** containing your connection string: +1. Create a **temporary PBM agent YAML config file** containing the `mongodb-uri` key with your connection string: ```sh echo "mongodb-uri: mongodb://pbmuser:secretpwd@localhost:27017/?authSource=admin" > pbm_uri.yaml From f08523555277da5eb9e8167c5afeb1007ab459bb Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Tue, 31 Mar 2026 20:38:05 +0530 Subject: [PATCH 16/27] Update configure-authentication.md --- docs/install/configure-authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/configure-authentication.md b/docs/install/configure-authentication.md index 6c0b37f3..7630c85a 100644 --- a/docs/install/configure-authentication.md +++ b/docs/install/configure-authentication.md @@ -63,7 +63,7 @@ You can change the `username` and `password` values and specify other options fo The `pbm-agent.service` systemd unit file includes the location of the environment file. You set the MongoDB URI connection string for the `PBM_MONGODB_URI` variable within the environment file for every `pbm-agent`. !!! warning "Security recommendation" - Avoid storing credentials (such as `PBM_MONGODB_URI`) in plaintext environment variables or service files. Instead, use `systemd` credentials for secure, encrypted, runtime-only access. For step-by-step instructions, see [Secure credentials with systemd](secure-credentials-systemd.md). + We recommend against storing credentials (such as `PBM_MONGODB_URI`) in plaintext environment variables or service files. Instead, use `systemd` credentials for secure, encrypted, runtime-only access. For step-by-step instructions, see [Secure credentials with systemd](secure-credentials-systemd.md). ??? tip "How to find the environment file" From 4790bcd83c477858a6cc24df2c0434ac9006296b Mon Sep 17 00:00:00 2001 From: Rasika Chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Wed, 1 Apr 2026 11:10:46 +0530 Subject: [PATCH 17/27] Update docs/install/secure-credentials-systemd.md Co-authored-by: Radoslaw Szulgo --- docs/install/secure-credentials-systemd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index 6974a97a..15b9c6e7 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -4,7 +4,7 @@ Percona Backup for MongoDB (PBM) requires access to sensitive credentials such as: -- **MongoDB connection URI** (`PBM_MONGODB_URI`) +- **MongoDB connection URI** - **Object storage credentials** defined in PBM configuration (pbm config) From 9ff2c656b06eb80bbd5f2b626993a751b25673e7 Mon Sep 17 00:00:00 2001 From: Rasika Chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Wed, 1 Apr 2026 11:11:12 +0530 Subject: [PATCH 18/27] Update docs/install/secure-credentials-systemd.md Co-authored-by: Radoslaw Szulgo --- docs/install/secure-credentials-systemd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index 15b9c6e7..4a00cbc2 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -6,7 +6,7 @@ Percona Backup for MongoDB (PBM) requires access to sensitive credentials such a - **MongoDB connection URI** -- **Object storage credentials** defined in PBM configuration (pbm config) +- **Object storage credentials** defined in PBM configuration By default, these credentials are often stored in plaintext in environment variables or configuration files. This introduces security risks such as credential leakage and unauthorized access. From e2242ffcd3d045ea9cafe02089a3969354a08402 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 1 Apr 2026 05:42:18 +0000 Subject: [PATCH 19/27] Address PR review comments: use %d specifier, add OS list, soften warning language Agent-Logs-Url: https://github.com/percona/pbm-docs/sessions/be3bac97-9ab1-4251-9d43-ebae69d1c02f Co-authored-by: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> --- docs/install/configure-authentication.md | 2 +- docs/install/secure-credentials-systemd.md | 16 ++++++++++++++-- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/install/configure-authentication.md b/docs/install/configure-authentication.md index 7630c85a..ef895329 100644 --- a/docs/install/configure-authentication.md +++ b/docs/install/configure-authentication.md @@ -63,7 +63,7 @@ You can change the `username` and `password` values and specify other options fo The `pbm-agent.service` systemd unit file includes the location of the environment file. You set the MongoDB URI connection string for the `PBM_MONGODB_URI` variable within the environment file for every `pbm-agent`. !!! warning "Security recommendation" - We recommend against storing credentials (such as `PBM_MONGODB_URI`) in plaintext environment variables or service files. Instead, use `systemd` credentials for secure, encrypted, runtime-only access. For step-by-step instructions, see [Secure credentials with systemd](secure-credentials-systemd.md). + We recommend using `systemd` credentials for secure, encrypted, runtime-only access rather than storing credentials (such as `PBM_MONGODB_URI`) in plaintext environment variables or service files. For step-by-step instructions, see [Secure credentials with systemd](secure-credentials-systemd.md). ??? tip "How to find the environment file" diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index 4a00cbc2..baa30de1 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -30,7 +30,19 @@ Storing credentials in plaintext significantly increases the risk of compromise. ## Prerequisites -- systemd version 250 or higher +- systemd version 250 or higher. To check your version, run: + + ```sh + systemctl --version + ``` + + The following operating systems meet this requirement: + + - RHEL/OL/Rocky Linux 9 + - Ubuntu 24.04 + - Debian 12 + - Amazon Linux 2023 + - Root or sudo privileges - (Optional) TPM2 support for hardware-backed encryption - Kernel 5.4+ @@ -65,7 +77,7 @@ Here are the steps to integrate PBM with systemd's [System and service credentia [Service] LoadCredentialEncrypted=pbm_connection.yaml:/path/to/pbm_connection.yaml.cred PrivateMounts=yes - ExecStart=/usr/bin/pbm-agent -f /run/credentials/%n/pbm_connection.yaml + ExecStart=/usr/bin/pbm-agent -f %d/pbm_connection.yaml ``` 5. Reload the systemd manager configuration: From 3c5b7b9a706918d64e3b87a19b9b0a3312d649ca Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Wed, 1 Apr 2026 11:19:13 +0530 Subject: [PATCH 20/27] Update secure-credentials-systemd.md --- docs/install/secure-credentials-systemd.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index baa30de1..b0a4ce24 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -30,12 +30,21 @@ Storing credentials in plaintext significantly increases the risk of compromise. ## Prerequisites -- systemd version 250 or higher. To check your version, run: +- systemd version 250 or higher. - ```sh + To check the installed `systemd` version on your system, run: + + ```bash systemctl --version ``` + ??? example "Output" + + ```sh + systemd 252 (252.5-2ubuntu3) + +PAM +AUDIT +SELINUX ... + ``` + The following operating systems meet this requirement: - RHEL/OL/Rocky Linux 9 From c30b52ca1c39b6d157e1af24c80fffa9c6d16366 Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Wed, 1 Apr 2026 11:38:12 +0530 Subject: [PATCH 21/27] Update secure-credentials-systemd.md --- docs/install/secure-credentials-systemd.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index b0a4ce24..7b5ec8b8 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -45,12 +45,12 @@ Storing credentials in plaintext significantly increases the risk of compromise. +PAM +AUDIT +SELINUX ... ``` - The following operating systems meet this requirement: + The following operating systems meet this requirement: - - RHEL/OL/Rocky Linux 9 - - Ubuntu 24.04 - - Debian 12 - - Amazon Linux 2023 + - RHEL/OL/Rocky Linux 9 + - Ubuntu 24.04 + - Debian 12 + - Amazon Linux 2023 - Root or sudo privileges - (Optional) TPM2 support for hardware-backed encryption From bd1b2abbd4465c5897ef062f9044478144ed6975 Mon Sep 17 00:00:00 2001 From: Rasika Chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Wed, 1 Apr 2026 11:40:10 +0530 Subject: [PATCH 22/27] Update docs/install/secure-credentials-systemd.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/install/secure-credentials-systemd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index 7b5ec8b8..ac2a0323 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -80,7 +80,7 @@ Here are the steps to integrate PBM with systemd's [System and service credentia shred -u pbm_uri.yaml ``` -4. Edit the systemd unit file (default location at `/lib/systemd/system/pbm-agent.service`) and in the `[Service]` section, add the `LoadCredentialEncrypted` and `PrivateMounts` directives: +4. Edit the systemd unit file (for example, `/lib/systemd/system/pbm-agent.service` or `/usr/lib/systemd/system/pbm-agent.service`, depending on your distribution; see the earlier *How to find the environment file* section) and in the `[Service]` section, add the `LoadCredentialEncrypted` and `PrivateMounts` directives: ``` [Service] From b5a6dc9ad583be2d4d9f2d5d5b77abcb36aed693 Mon Sep 17 00:00:00 2001 From: Rasika Chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Wed, 1 Apr 2026 11:40:51 +0530 Subject: [PATCH 23/27] Update docs/install/secure-credentials-systemd.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/install/secure-credentials-systemd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index ac2a0323..ca3cad4b 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -105,7 +105,7 @@ Here are the steps to integrate PBM with systemd's [System and service credentia Systemd automatically decrypts the credential during service startup and places it in a temporary, non-swappable directory. - The path to the decrypted plaintext is stored in the `$CREDENTIALS_DIRECTORY` environment variable. - - In the example above, the PBM agent will read the contents of the file at `%d/pbm_connection.yaml` as its connection string. + - In the example above, the PBM agent will read the YAML configuration file at `%d/pbm_connection.yaml`, which contains the `mongodb-uri` setting with its connection string. ## How to verify? From 4bd99028a63ef1857ef04e86fd7d2c919228fbcd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 1 Apr 2026 06:12:41 +0000 Subject: [PATCH 24/27] Narrow overview scope to pbm-agent mongodb-uri; note technique applies to other credentials Agent-Logs-Url: https://github.com/percona/pbm-docs/sessions/67e80530-fa05-4022-bb93-dc886f07bd31 Co-authored-by: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> --- docs/install/secure-credentials-systemd.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index ca3cad4b..386223e9 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -2,15 +2,9 @@ ## Overview -Percona Backup for MongoDB (PBM) requires access to sensitive credentials such as: +This guide describes how to securely store the **MongoDB connection URI** (`mongodb-uri`) for `pbm-agent` using **systemd service credentials**. The same technique can be applied to other sensitive PBM credentials, such as object storage credentials in the PBM configuration. -- **MongoDB connection URI** - -- **Object storage credentials** defined in PBM configuration - -By default, these credentials are often stored in plaintext in environment variables or configuration files. This introduces security risks such as credential leakage and unauthorized access. - -This section describes how to securely manage PBM credentials using **systemd service credentials**. +By default, credentials are often stored in plaintext in environment variables or configuration files. This introduces security risks such as credential leakage and unauthorized access. ## Why use systemd credentials? From 7edfaed6cac9e14fe27c3cbe92df4277d48d2619 Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Wed, 1 Apr 2026 11:48:46 +0530 Subject: [PATCH 25/27] Update secure-credentials-systemd.md --- docs/install/secure-credentials-systemd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index ca3cad4b..90b10e4e 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -45,7 +45,7 @@ Storing credentials in plaintext significantly increases the risk of compromise. +PAM +AUDIT +SELINUX ... ``` - The following operating systems meet this requirement: + The following operating systems meet this requirement: - RHEL/OL/Rocky Linux 9 - Ubuntu 24.04 From 46db4f5269293c57c6638076dfd06b02ad9ae3e1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 1 Apr 2026 06:22:56 +0000 Subject: [PATCH 26/27] Fix Step 4: mention ExecStart update and remove broken section reference Agent-Logs-Url: https://github.com/percona/pbm-docs/sessions/2c98a8a1-351d-4633-920e-5f3b7ca033a5 Co-authored-by: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> --- docs/install/secure-credentials-systemd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index ec6ee1b4..97c86bd5 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -74,7 +74,7 @@ Here are the steps to integrate PBM with systemd's [System and service credentia shred -u pbm_uri.yaml ``` -4. Edit the systemd unit file (for example, `/lib/systemd/system/pbm-agent.service` or `/usr/lib/systemd/system/pbm-agent.service`, depending on your distribution; see the earlier *How to find the environment file* section) and in the `[Service]` section, add the `LoadCredentialEncrypted` and `PrivateMounts` directives: +4. Edit the systemd unit file (for example, `/lib/systemd/system/pbm-agent.service` on Debian/Ubuntu or `/usr/lib/systemd/system/pbm-agent.service` on RHEL-based distributions). In the `[Service]` section, add the `LoadCredentialEncrypted` and `PrivateMounts` directives, and update `ExecStart` to pass the decrypted credential file to `pbm-agent`: ``` [Service] From 5bf1ba4074cb9d411c1b62fcf3974ff3867a0939 Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Wed, 1 Apr 2026 11:56:35 +0530 Subject: [PATCH 27/27] Update secure-credentials-systemd.md --- docs/install/secure-credentials-systemd.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md index ec6ee1b4..a5ba5b03 100644 --- a/docs/install/secure-credentials-systemd.md +++ b/docs/install/secure-credentials-systemd.md @@ -41,10 +41,10 @@ Storing credentials in plaintext significantly increases the risk of compromise. The following operating systems meet this requirement: - - RHEL/OL/Rocky Linux 9 - - Ubuntu 24.04 - - Debian 12 - - Amazon Linux 2023 + - RHEL/OL/Rocky Linux 9 + - Ubuntu 24.04 + - Debian 12 + - Amazon Linux 2023 - Root or sudo privileges - (Optional) TPM2 support for hardware-backed encryption