Skip to content
logo
Percona Backup for MongoDB
Set up and configure
Initializing search
    percona/pbm-docs
    percona/pbm-docs
    • Home
      • How PBM works
      • Components
      • Supported MongoDB versions
      • Supported MongoDB deployments
      • Install
      • Set up and configure
        • Configure authentication in MongoDB
          • Create the pbm user
          • Set the MongoDB connection URI for pbm-agent
            • Passwords with special characters
          • Set the MongoDB connection URI for pbm CLI
          • External authentication support in Percona Backup for MongoDB
        • Configure remote backup storage
        • Start the pbm-agent process
          • How to see the pbm-agent log
      • Overview
      • Physical backups
      • Incremental physical backups
      • Logical backups
      • Selective backups
      • Point-in-Time Recovery
      • Start a backup
      • List backups
      • Restore a backup
      • View restore progress
      • Cancel a backup
      • Delete backups
      • View backup logs
      • Replay oplog from arbitrary start time
      • Architecture
      • Authentication
        • Overview
        • Remote backup configuration examples
      • Schedule backups
      • Configure PBM remotely
      • Upgrade PBM
      • Troubleshoot PBM
      • Automate access to S3 buckets for PBM
      • Remove PBM
    • FAQ
      • PBM commands
        • Configuration file
        • Remote backup storage options
        • Point-in-time recovery options
        • Backup options
        • Restore options
      • Glossary
      • Release notes index
      • Percona Backup for MongoDB 2.0.4 (2023-02-21)
      • Percona Backup for MongoDB 2.0.3 (2023-01-11)
      • Percona Backup for MongoDB 2.0.2 (2022-10-27)
      • Percona Backup for MongoDB 2.0.1 (2022-10-12)
      • Percona Backup for MongoDB 2.0.0 (2022-09-21)
      • Percona Backup for MongoDB 1.8.1 (2022-07-12)
      • Percona Backup for MongoDB 1.8.0 (2022-06-09)
      • Percona Backup for MongoDB 1.7.0 (2022-04-18)
      • Percona Backup for MongoDB 1.6.1 (2021-11-04)
      • Percona Backup for MongoDB 1.6.0 (2021-08-16)
      • Percona Backup for MongoDB 1.5.0 (2021-05-10)
      • Percona Backup for MongoDB 1.4.1 (2021-01-28)
      • Percona Backup for MongoDB 1.4.0 (2020-12-24)
      • Percona Backup for MongoDB 1.3.4 (2020-11-19)
      • Percona Backup for MongoDB 1.3.3 (2020-11-04)
      • Percona Backup for MongoDB 1.3.2 (2020-10-14)
      • Percona Backup for MongoDB 1.3.1 (2020-09-03)
      • Percona Backup for MongoDB 1.3.0 (2020-08-26)
      • Percona Backup for MongoDB 1.2.1 (2020-07-27)
      • Percona Backup for MongoDB 1.2.0 (2020-05-13)
      • Percona Backup for MongoDB 1.1.3 (2020-04-14)
      • Percona Backup for MongoDB 1.1.1 (2020-01-31)
      • Percona Backup for MongoDB 1.1.0 (2020-01-16)
      • Percona Backup for MongoDB 1.0.0 (2019-09-19)
      • Percona Backup for MongoDB 0.5.0 (2019-06-17)
    • Submitting bug reports or feature requests
    • Copyright and Licensing
    • Trademark policy

    • Configure authentication in MongoDB
      • Create the pbm user
      • Set the MongoDB connection URI for pbm-agent
        • Passwords with special characters
      • Set the MongoDB connection URI for pbm CLI
      • External authentication support in Percona Backup for MongoDB
    • Configure remote backup storage
    • Start the pbm-agent process
      • How to see the pbm-agent log

    Initial setup¶

    After you installed Percona Backup for MongoDB on every server with the mongod node that is not an arbiter node, the setup steps are the following:

    1. Configure authentication in MongoDB

    2. Configure the remote backup storage

    3. Start pbm-agent process

    The following diagram outlines the installation and setup steps:

    image

    Configure authentication in MongoDB¶

    Percona Backup for MongoDB uses the authentication and authorization subsystem of MongoDB. This means that to authenticate Percona Backup for MongoDB, you need to:

    • create a corresponding pbm user in the admin database
    • set a valid MongoDB connection URI string for pbm-agent
    • set a valid MongoDB connection URI string for pbm CLI

    Create the pbm user¶

    1. Create the role that allows any action on any resource.

      db.getSiblingDB("admin").createRole({ "role": "pbmAnyAction",
            "privileges": [
               { "resource": { "anyResource": true },
                 "actions": [ "anyAction" ]
               }
            ],
            "roles": []
         });
      
    2. Create the user and assign the role you created to it.

      db.getSiblingDB("admin").createUser({user: "pbmuser",
             "pwd": "secretpwd",
             "roles" : [
                { "db" : "admin", "role" : "readWrite", "collection": "" },
                { "db" : "admin", "role" : "backup" },
                { "db" : "admin", "role" : "clusterMonitor" },
                { "db" : "admin", "role" : "restore" },
                { "db" : "admin", "role" : "pbmAnyAction" }
             ]
          });
      

    You can specify the username and password values and other options of the createUser command as you require so long as the roles shown above are granted.

    Create the pbm user on every replica set. In a sharded cluster, this means on every shard replica set and the config server replica set.

    Tip

    To list all the host+port lists for the shard replica sets in a cluster, run the following command:

    db.getSiblingDB(“config”).shards.find({}, {“host”: true, “_id”: false}) 
    

    The replica set name at the front of these “host” strings will have to be placed as a “/?replicaSet=xxxx” argument in the parameters part of the connection URI (see below).

    Set the MongoDB connection URI for pbm-agent¶

    A pbm-agent process connects to its localhost mongod node with a standalone type of connection.

    To set the MongoDB URI connection string means to configure a service init script (pbm-agent.service systemd unit file) that runs a pbm-agent.

    The pbm-agent.service systemd unit file includes the environment file. You set the MongoDB URI connection string for the PBM_MONGODB_URI variable within the environment file for every pbm-agent.

    How to find the environment file

    The path to the environment file is specified in the pbm-agent.service systemd unit file.

    In Ubuntu and Debian, the pbm-agent.service systemd unit file is at the path /lib/systemd/system/pbm-agent.service.

    In Red Hat and CentOS, the path to this file is /usr/lib/systemd/system/pbm-agent.service.

    Example of pbm-agent.service systemd unit file

    [Unit]
    Description=pbm-agent
    After=time-sync.target network.target
    
    [Service]
    EnvironmentFile=-/etc/default/pbm-agent
    Type=simple
    User=pbm
    Group=pbm
    PermissionsStartOnly=true
    ExecStart=/usr/bin/pbm-agent
    
    [Install]
    WantedBy=multi-user.target
    

    Edit the environment file /etc/default/pbm-agent and specify the MongoDB connection URI string for the pbm user to the local mongod node.

    For example, if mongod node listens on port 27018, the MongoDB connection URI string will be the following:

    PBM_MONGODB_URI="mongodb://pbmuser:secretpwd@localhost:27018/?authSource=admin"
    

    Edit the environment file /etc/sysconfig/pbm-agent and specify the MongoDB connection URI string for the pbm user to the local mongod node.

    For example, if mongod node listens on port 27018, the MongoDB connection URI string will be the following:

    PBM_MONGODB_URI="mongodb://pbmuser:secretpwd@localhost:27018/?authSource=admin"
    

    Configure the service init script for every pbm-agent.

    Passwords with special characters¶

    If the password includes special characters like #, @, / and so on, you must convert these characters using the percent-encoding mechanism when passing them to Percona Backup for MongoDB. For example, the password secret#pwd should be passed as follows in PBM_MONGODB_URI:

    PBM_MONGODB_URI="mongodb://pbmuser:secret%23pwd@localhost:27018/?authSource=admin"
    

    Set the MongoDB connection URI for pbm CLI¶

    Set the MongoDB URI connection string for pbm CLI in your shell. This allows you to call pbm commands without the --mongodb-uri flag.

    Use the following command:

    export PBM_MONGODB_URI="mongodb://pbmuser:secretpwd@localhost:27018/?authSource=admin&replSetName=xxxx"
    

    For more information what connection string to specify, refer to the pbm connection string section.

    External authentication support in Percona Backup for MongoDB¶

    In addition to SCRAM, Percona Backup for MongoDB supports other authentication methods that you use in MongoDB or Percona Server for MongoDB.

    For external authentication, you create the pbm user in the format used by the authentication system and set the MongoDB connection URI string to include both the authentication method and authentication source.

    For example, for Kerberos authentication, create the pbm user in the $external database in the format <username@KERBEROS_REALM> (e.g. pbm@PERCONATEST.COM).

    Specify the following string for MongoDB connection URI:

    PBM_MONGODB_URI="mongodb://<username>%40<KERBEROS_REALM>@<hostname>:27018/?authMechanism=GSSAPI&authSource=%24external&replSetName=xxxx"
    

    Note that you must first obtain the ticket for the pbm user with the kinit command before you start the pbm-agent:

    sudo -u {USER} kinit pbm
    

    Note that the {USER} is the user that you will run the pbm-agent process.

    For authentication and authorization via Native LDAP, you only create roles for LDAP groups in MongoDB as the users are stored and managed on the LDAP server. However, you still define the $external database as your authentication source:

    PBM_MONGODB_URI="mongodb://<user>:<password>@<hostname>:27018/?authMechanism=PLAIN&authSource=%24external&replSetName=xxxx"
    

    Configure remote backup storage¶

    The easiest way to provide remote backup storage configuration is to specify it in a YAML config file and upload this file to Percona Backup for MongoDB using pbm CLI.

    The storage configuration itself is out of scope of the present document. We assume that you have configured one of the supported remote backup storages.

    1. Create a config file (e.g. pbm_config.yaml).

    2. Specify the storage information within.

      The following is the sample configuration for Amazon AWS:

      storage:
        type: s3
        s3:
          region: us-west-2
          bucket: pbm-test-bucket
          prefix: data/pbm/backup
          credentials:
            access-key-id: <your-access-key-id-here>
            secret-access-key: <your-secret-key-here>
          serverSideEncryption:
            sseAlgorithm: aws:kms
            kmsKeyID: <your-kms-key-here>
      

      This is the sample configuration for Microsoft Azure Blob storage:

      storage:
        type: azure
        azure:
          account: <your-account>
          container: <your-container>
          prefix: pbm
          credentials:
            key: <your-access-key>
      

      This is the sample configuration for filesystem storage:

      storage:
        type: filesystem
        filesystem:
          path: /data/local_backups
      

      See more examples in Configuration file examples.

    3. Insert the config file

    pbm config --file pbm_config.yaml
    

    For a sharded cluster, run this command whilst connecting to config server replica set. Otherwise connect to the non-sharded replica set as normal.

    To learn more about Percona Backup for MongoDB configuration, see Percona Backup for MongoDB configuration in a cluster (or non-sharded replica set).

    Start the pbm-agent process¶

    Start pbm-agent on every server with the mongod node installed. It is best to use the packaged service scripts to run pbm-agent.

    sudo systemctl start pbm-agent
    sudo systemctl status pbm-agent
    

    For example, imagine that you put configsvr nodes (listen port 27019) collocated on the same servers as the first shard’s mongod nodes (listen port 27018, replica set name sh1rs). In this server there should be two pbm-agent processes, one connected to the shard (e.g. “mongodb://username:password@localhost:27018/”) and one to the configsvr node (e.g. “mongodb://username:password@localhost:27019/”).

    For reference, the following is an example of starting pbm-agent manually. The output is redirected to a file and the process is backgrounded.

    Important

    Start the pbm-agent as the mongod user. The pbm-agent requires write access to the MongoDB data directory to make physical restores.

    su mongod nohup pbm-agent --mongodb-uri "mongodb://username:password@localhost:27018/" > /data/mdb_node_xyz/pbm-agent.$(hostname -s).27018.log 2>&1 &
    

    Replace username and password with those of your pbm user. /data/mdb_node_xyz/ is the path where pbm-agent log files will be written. Make sure you have created this directory and granted write permissions to it for the mongod user.

    Alternatively, you can run pbm-agent on a shell terminal temporarily if you want to observe and/or debug the startup from the log messages.

    How to see the pbm-agent log¶

    With the packaged systemd service, the log output to stdout is captured by systemd’s default redirection to systemd-journald. You can view it with the command below. See man journalctl for useful options such as --lines, --follow, etc.

    ~journalctl -u pbm-agent.service
    -- Logs begin at Tue 2019-10-22 09:31:34 JST. --
    Jan 22 15:59:14 akira-x1 systemd[1]: Started pbm-agent.
    Jan 22 15:59:14 akira-x1 pbm-agent[3579]: pbm agent is listening for the commands
    ...
    ...
    

    If you started pbm-agent manually, see the file you redirected stdout and stderr to.

    When a message “pbm agent is listening for the commands” is printed to the pbm-agent log file, pbm-agent confirms that it has connected to its mongod node successfully.

    Contact Us

    For free technical help, visit the Percona Community Forum.

    To report bugs or submit feature requests, open a JIRA ticket.

    For paid support and managed or consulting services , contact Percona Sales.


    Last update: February 21, 2023
    Created: February 21, 2023
    Back to top
    Percona LLC and/or its affiliates, © 2023
    Made with Material for MkDocs

    Cookie consent

    We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.