Percona Backup for MongoDB has no authentication and authorization subsystem of its own - it uses MongoDB’s, i.e. pbm and pbm-agent only require a valid MongoDB connection URI string for the PBM user.

For the S3-compatible remote storage authentication config, see Percona Backup for MongoDB config in a Cluster (or Non-sharded Replicaset).

Create the PBM user

To run Percona Backup for MongoDB a user must be created in the admin db that has the role grants as shown below.

db.getSiblingDB("admin").createRole({ "role": "pbmAnyAction",
      "privileges": [
         { "resource": { "anyResource": true },
           "actions": [ "anyAction" ]
      "roles": []
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" }

User name and password values and other options of the createUser command can be set as you require so long as the roles shown above are granted.

This user must be created on every replicaset, i.e. it must be created on the shard replicasets as well as the config server replicaset.


In a cluster run db.getSiblingDB(“config”).shards.find({}, {“host”: true, “_id”: false}) to list all the host+port lists for the shard replicasets. The replicaset 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).

MongoDB connection strings - A Reminder (or Primer)

Percona Backup for MongoDB uses MongoDB Connection URI strings to open MongoDB connections. Neither pbm or pbm-agent accept legacy-style command-line arguments for --host, --port, --user, --password, etc. as the mongo shell or mongodump command does.

$ pbm-agent --mongodb-uri "mongodb://pbmuser:secretpwd@localhost:27018/"
$ #Alternatively:
$ export PBM_MONGODB_URI="mongodb://pbmuser:secretpwd@localhost:27018/"
$ pbm-agent
$ pbm list --mongodb-uri "mongodb://pbmuser:secretpwd@mongocsvr1:27018,mongocsvr2:27018,mongocsvr3:27018/?replicaSet=configrs"
$ #Alternatively:
$ export PBM_MONGODB_URI="mongodb://pbmuser:secretpwd@mongocsvr1:27018,mongocsvr2:27018,mongocsvr3:27018/?replicaSet=configrs"
$ pbm list

The connection URI above is the format that MongoDB drivers accept universally since approximately the release time of MongoDB server v3.6. The mongo shell accepts it too since v4.0. Using a v4.0+ mongo shell is a recommended way to debug connection URI validity from the command line.

The MongoDB Connection URI specification includes several non-default options you may need to use. For example the TLS certificates/keys needed to connect to a cluster or non-sharded replicaset with network encryption enabled are “tls=true” plus “tlsCAFile” and/or “tlsCertificateKeyFile” (see tls options).

Technical note

As of v1.0 the driver used by Percona Backup for MongoDB is the official v1.1 mongo-go-driver.

The pbm-agent connection string

pbm-agent processes should connect to their localhost mongod with a standalone type of connection.

The pbm connection string

The pbm CLI will ultimately connect to the replica set with the PBM control collections.

  • In a non-sharded replica set it is simply that replica set.
  • In a cluster it is the config server replica set.

You do not necessarily have to provide that connection string. If you provide a connection to any live node (shard, configsvr, or non-sharded replicaset member), it will automatically determine the right hosts and establish a new connection to those instead.


When running pbm from an unsupervised script, we recommend using a replica set connection string. A standalone-style connection string will fail if that mongod host happens to be down temporarily.