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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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