Deploy Sharded Cluster with Keyfile Authentication

Start each mongod in the config server replica set. Include the keyFile setting. The keyFile setting enforces both Internal/Membership Authentication and Role-Based Access Control.

You can specify the mongod settings either via a configuration file or the command line.

Configuration File

If using a configuration file, set security.keyFile to the keyfile's path, sharding.clusterRole to configsvr, and replication.replSetName to the desired name of the config server replica set.

security:
  keyFile: <path-to-keyfile>
sharding:
  clusterRole: configsvr
replication:
  replSetName: <setname>

Include additional options as required for your configuration. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the net.bindIp setting. For more information, see Localhost Binding Compatibility Changes.

Start the mongod specifying the --config option and the path to the configuration file.

mongod --config <path-to-config-file>

Command Line

If using the command line parameters, start the mongod with the --keyFile, --configsvr, and --replSet parameters.

mongod --keyFile <path-to-keyfile> --configsvr --replSet <setname> --dbpath <path>

Include additional options as required for your configuration. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the --bind_ip. For more information, see Localhost Binding Compatibility Changes.

Connect to a member of the replica set over the localhost interface.

Connect mongosh to one of the mongod instances over the localhost interface. You must run mongosh on the same physical machine as the mongod instance.

The localhost interface is only available since no users have been created for the deployment. The localhost interface closes after the creation of the first user.

The rs.initiate() method initiates the replica set and can take an optional replica set configuration document. In the replica set configuration document, include:

• The _id. The _id must match the --replSet parameter passed to the mongod.

• The members field. The members field is an array and requires a document per each member of the replica set.

• The configsvr field. The configsvr field must be set to true for the config server replica set.

See Replica Set Configuration for more information on replica set configuration documents.

Initiate the replica set using the rs.initiate() method and a configuration document:

rs.initiate(
  {
    _id: "myReplSet",
    configsvr: true,
    members: [
      { _id : 0, host : "cfg1.example.net:27019" },
      { _id : 1, host : "cfg2.example.net:27019" },
      { _id : 2, host : "cfg3.example.net:27019" }
    ]
  }
)

Start each member of the replica set with access control enabled.

Running a mongod with the keyFile parameter enforces both Internal/Membership Authentication and Role-Based Access Control.

Start each mongod in the replica set using either a configuration file or the command line.

Configuration File

If using a configuration file, set the security.keyFile option to the keyfile's path, the replication.replSetName to the desired name of the replica set, and the sharding.clusterRole option to shardsvr.

security:
  keyFile: <path-to-keyfile>
sharding:
  clusterRole: shardsvr
replication:
  replSetName: <replSetName>
storage:
   dbPath: <path>

Include additional options as required for your configuration. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the net.bindIp setting. For more information, see Localhost Binding Compatibility Changes.

Start the mongod specifying the --config option and the path to the configuration file.

mongod --config <path-to-config-file>

Command Line

If using the command line option, when starting the component, specify the --keyFile, replSet, and --shardsvr parameters, as in the following example:

mongod --keyFile <path-to-keyfile> --shardsvr --replSet <replSetName>  --dbpath <path>

Include additional options as required for your configuration. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the --bind_ip. For more information, see Localhost Binding Compatibility Changes.

Connect to a member of the replica set over the localhost interface.

Connect mongosh to one of the mongod instances over the localhost interface. You must run mongosh on the same physical machine as the mongod instance.

The localhost interface is only available since no users have been created for the deployment. The localhost interface closes after the creation of the first user.

Initiate the replica set.

From mongosh, run the rs.initiate() method.

rs.initiate() can take an optional replica set configuration document. In the replica set configuration document, include:

• The _id field set to the replica set name specified in either the replication.replSetName or the --replSet option.

• The members array with a document per each member of the replica set.

The following example initates a three member replica set.

rs.initiate(
  {
    _id : "myReplSet",
    members: [
      { _id : 0, host : "s1-mongo1.example.net:27018" },
      { _id : 1, host : "s1-mongo2.example.net:27018" },
      { _id : 2, host : "s1-mongo3.example.net:27018" }
    ]
  }
)

rs.initiate() triggers an election and elects one of the members to be the primary.

Connect to the primary before continuing. Use rs.status() to locate the primary member.

Create the shard-local user administrator (optional).

Add a user using the db.createUser() method. The user should have at minimum the userAdminAnyDatabase role on the admin database.

You must be connected to the primary to create users.

The following example creates the user fred with the userAdminAnyDatabase role on the admin database.

admin = db.getSiblingDB("admin")
admin.createUser(
  {
    user: "fred",
    pwd: passwordPrompt(), // or cleartext password
    roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
  }
)

Enter the password when prompted. See Database User Roles for a full list of built-in roles and related to database administration operations.

Authenticate as the shard-local user administrator (optional).

Authenticate to the admin database.

In mongosh, use db.auth() to authenticate. For example, the following authenticate as the user administrator fred:

db.getSiblingDB("admin").auth("fred", passwordPrompt()) // or cleartext password

Alternatively, connect a new mongosh instance to the primary replica set member using the -u <username>, -p <password>, and the --authenticationDatabase parameters.

mongosh -u "fred" -p  --authenticationDatabase "admin"

If you do not specify the password to the -p command-line option, mongosh prompts for the password.

Create the shard-local cluster administrator (optional).

The shard-local cluster administrator user has the clusterAdmin role, which provides privileges that allow access to replication operations.

For a full list of roles related to replica set operations see Cluster Administration Roles.

Create a cluster administrator user and assign the clusterAdmin role in the admin database:

db.getSiblingDB("admin").createUser(
  {
    "user" : "ravi",
    "pwd" : passwordPrompt(),     // or cleartext password
    roles: [ { "role" : "clusterAdmin", "db" : "admin" } ]
  }
)

Enter the password when prompted.

See Cluster Administration Roles for a full list of built-in roles related to replica set and sharded cluster operations.

Connect a mongos to the cluster

Start a mongos specifying the keyfile using either a configuration file or a command line parameter.

Configuration File

If using a configuration file, set the security.keyFile to the keyfile's path and the sharding.configDB to the replica set name and at least one member of the replica set in <replSetName>/<host:port> format.

security:
  keyFile: <path-to-keyfile>
sharding:
  configDB: <configReplSetName>/cfg1.example.net:27019,cfg2.example.net:27019,...

Include additional options as required for your configuration. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the net.bindIp setting. For more information, see Localhost Binding Compatibility Changes.

Start the mongos specifying the --config option and the path to the configuration file.

mongos --config <path-to-config>

Command Line

If using command line parameters start the mongos and specify the --keyFile and --configdb parameters.

mongos --keyFile <path-to-keyfile> --configdb <configReplSetName>/cfg1.example.net:27019,cfg2.example.net:27019,...

Include additional options as required for your configuration. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the --bind_ip. For more information, see Localhost Binding Compatibility Changes.

Connect to a mongos over the localhost interface.

Connect mongosh to one of the mongos instances over the localhost interface. You must run mongosh on the same physical machine as the mongos instance.

The localhost interface is only available since no users have been created for the deployment. The localhost interface closes after the creation of the first user.

Create the user administrator.

Add a user using the db.createUser() method. The user should have at minimum the userAdminAnyDatabase role on the admin database.

The following example creates the user fred on the admin database:

admin = db.getSiblingDB("admin")
admin.createUser(
  {
    user: "fred",
    pwd:  passwordPrompt(),     // or cleartext password
    roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
  }
)

See Database User Roles for a full list of built-in roles and related to database administration operations.

Authenticate as the user administrator.

Use db.auth() to authenticate as the user administrator to create additional users:

db.getSiblingDB("admin").auth("fred", passwordPrompt()) // or cleartext password

Enter the password when prompted.

Alternatively, connect a new mongosh session to the target replica set member using the -u <username>, -p <password>, and the --authenticationDatabase "admin" parameters. You must use the Localhost Exception to connect to the mongos.

mongosh -u "fred" -p  --authenticationDatabase "admin"

If you do not specify the password to the -p command-line option, mongosh prompts for the password.

Create Administrative User for Cluster Management

The cluster administrator user has the clusterAdmin role, which grants access to replication and sharding operations.

Create a clusterAdmin user in the admin database.

The following example creates the user ravi on the admin database.

db.getSiblingDB("admin").createUser(
  {
    "user" : "ravi",
    "pwd" : passwordPrompt(),     // or cleartext password
    roles: [ { "role" : "clusterAdmin", "db" : "admin" } ]
  }
)

See Cluster Administration Roles for a full list of built-in roles related to replica set and sharded cluster operations.

Create additional users (Optional).

Create users to allow clients to connect and access the sharded cluster. See Database User Roles for available built-in roles, such as read and readWrite. You may also want additional administrative users. For more information on users, see Users.

To create additional users, you must authenticate as a user with userAdminAnyDatabase or userAdmin roles.