diff --git a/docs/install/configure-authentication.md b/docs/install/configure-authentication.md index 5ca6874c..6c0b37f3 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. For step-by-step instructions, see [Secure credentials with systemd](secure-credentials-systemd.md). + + ??? 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`. diff --git a/docs/install/secure-credentials-systemd.md b/docs/install/secure-credentials-systemd.md new file mode 100644 index 00000000..6974a97a --- /dev/null +++ b/docs/install/secure-credentials-systemd.md @@ -0,0 +1,97 @@ +# 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 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 (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 + +- 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 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 + ``` + +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. 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 + 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 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 +``` + 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: