Docs Menu

Docs HomeMongoDB Manual

Config Servers

On this page

  • Replica Set Config Servers
  • Read and Write Operations on Config Servers
  • Config Server Availability
  • Sharded Cluster Metadata
  • Sharded Cluster Security
  • Config Shards


Starting in 3.4, the use of the deprecated mirrored mongod instances as config servers (SCCC) is no longer supported. Before you can upgrade your sharded clusters to 3.4, you must convert your config servers from SCCC to CSRS.

To convert your config servers from SCCC to CSRS, see the MongoDB 3.4 manual Upgrade Config Servers to Replica Set.

Config servers store the metadata for a sharded cluster. The metadata reflects state and organization for all data and components within the sharded cluster. The metadata includes the list of chunks on every shard and the ranges that define the chunks.

The mongos instances cache this data and use it to route read and write operations to the correct shards. mongos updates the cache when there are metadata changes for the cluster, such as adding a shard. Shards also read chunk metadata from the config servers.

The config servers also store Authentication configuration information such as Role-Based Access Control or internal authentication settings for the cluster.

MongoDB also uses the config servers to manage distributed locks.

Each sharded cluster must have its own config servers. Do not use the same config servers for different sharded clusters.


Administrative operations conducted on config servers may have significant impact on sharded cluster performance and availability. Depending on the number of config servers impacted, the cluster may be read-only or offline for a period of time.

Starting in MongoDB 7.0, you can configure a config server to store application data in addition to the usual sharded cluster metadata. The config server is then known as a config shard. You'll learn more later on this page in the Config Shards section.

Changed in version 3.4.

Config servers for sharded clusters can be deployed as a replica set (CSRS). Using a replica set for the config servers improves consistency across the config servers, since MongoDB can take advantage of the standard replica set read and write protocols for the config data. In addition, using a replica set for config servers allows a sharded cluster to have more than 3 config servers since a replica set can have up to 50 members. To deploy config servers as a replica set, the config servers must run the WiredTiger Storage Engine.

The following restrictions apply to a replica set configuration when used for config servers:

The admin database and the config database exist on the config servers.

The admin database contains the collections related to the authentication and authorization as well as the other system.* collections for internal use.

The config database contains the collections that contain the sharded cluster metadata. MongoDB writes data to the config database when the metadata changes, such as after a chunk migration or a chunk split.

Users should avoid writing directly to the config database in the course of normal operation or maintenance.

When writing to the config servers, MongoDB uses a write concern of "majority".

MongoDB reads from the admin database for authentication and authorization data and other internal uses.

MongoDB reads from the config database when a mongos starts or after a change in the metadata, such as after a chunk migration. Shards also read chunk metadata from the config servers.

When reading from the replica set config servers, MongoDB uses a Read Concern level of "majority".

If the config server replica set loses its primary and cannot elect a primary, the cluster's metadata becomes read only. You can still read and write data from the shards, but no chunk migration or chunk splits will occur until the replica set can elect a primary.

In a sharded cluster, mongod and mongos instances monitor the replica sets in the sharded cluster (e.g. shard replica sets, config server replica set).

If all config servers become unavailable, the cluster can become inoperable. To ensure that the config servers remain available and intact, backups of config servers are critical. The data on the config server is small compared to the data stored in a cluster, and the config server has a relatively low activity load.

See A Config Server Replica Set Member Become Unavailable for more information.

Config servers store metadata in the Config Database.


Always back up the config database before doing any maintenance on the config server.

To access the config database, issue the following command in mongosh:

use config

In general, you should never edit the content of the config database directly. The config database contains the following collections:

For more information on these collections and their role in sharded clusters, see Config Database. See Read and Write Operations on Config Servers for more information about reads and updates to the metadata.

Use Internal/Membership Authentication to enforce intra-cluster security and prevent unauthorized cluster components from accessing the cluster. You must start each mongod in the cluster with the appropriate security settings in order to enforce internal authentication.

Starting in MongoDB 5.3, SCRAM-SHA-1 cannot be used for intra-cluster authentication. Only SCRAM-SHA-256 is supported.

In previous MongoDB versions, SCRAM-SHA-1 and SCRAM-SHA-256 can both be used for intra-cluster authentication, even if SCRAM is not explicitly enabled.

See Deploy Sharded Cluster with Keyfile Authentication for a tutorial on deploying a secured sharded cluster.

New in version 7.0.

Starting in MongoDB 7.0, you can:

  • Configure a config server to store your application data in addition to the usual sharded cluster metadata. A config server that stores application data is called a config shard.

  • Transition a config server between being a config shard and a dedicated config server.

A cluster requires a config server, but the server can be a config shard instead of a dedicated config server. Using a config shard reduces the number of nodes required and can simplify your deployment.

You cannot use the same config shard for multiple sharded clusters.

To configure a dedicated config server to run as a config shard, run the transitionFromDedicatedConfigServer command.

To configure a config shard to run as a dedicated config server, run the transitionToDedicatedConfigServer command.

A user created on a config shard has the same behavior as a user created on a dedicated config server.

A config shard has a document in the admin.system.version collection to identify the config server as a config shard:

_id: 'shardIdentity',
shardName: 'config',
clusterId: ObjectId("<objectID>"),
configsvrConnectionString: '<config server replica set connection string>',

The following example retrieves a shard identity document from admin.system.version in the admin database:

use admin

Output extract:

_id: 'shardIdentity',
shardName: 'config',
clusterId: ObjectId("6441bdd6779584849dcac095"),
configsvrConnectionString: 'configRepl/localhost:27007'

If your cluster has a config shard and you need to downgrade the feature compatibility version to earlier than 7.0, connect to mongos and use the admin database and then perform this procedure:



db.adminCommand( {
transitionToDedicatedConfigServer: 1
} )

Syntax for movePrimary command:

db.adminCommand( { movePrimary: <databaseName>, to: <newPrimaryShard> } )

Replace databaseName and newPrimaryShard with your database name and new primary shard name.

The following example moves the primary shard in the test database to the shard01 primary shard:

db.adminCommand( { movePrimary: "test", to: "shard01" } )

Run transitionToDedicatedConfigServer command again:


db.adminCommand( {
transitionToDedicatedConfigServer: 1
} )

The response after a successful data move contains state: "completed". For full response details, see removeShard.


The following example sets the feature compatibility version to 6.0:

db.adminCommand( { setFeatureCompatibilityVersion: "6.0" } )
←  Shardsmongos →
Share Feedback
© 2023 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.