Upgrade User Authorization Data to 2.6 Format

MongoDB 2.6 includes significant changes to the authorization model,which requires changes to the way that MongoDB stores users’credentials. As a result, in addition to upgrading MongoDB processes,if your deployment uses authentication and authorization, afterupgrading all MongoDB process to 2.6 you must also upgrade theauthorization model.

Considerations

Complete all other Upgrade Requirements

Before upgrading the authorization model, you should first upgradeMongoDB binaries to 2.6. For sharded clusters, ensure that allcluster components are 2.6. If there are users in any database, be sureyou have at least one user in the admin database with the roleuserAdminAnyDatabasebefore upgrading the MongoDBbinaries.

Timing

Because downgrades are more difficult after you upgrade the userauthorization model, once you upgrade the MongoDB binaries toversion 2.6, allow your MongoDB deployment to run a day or twowithout upgrading the user authorization model.

This allows 2.6 some time to “burn in” and decreases the likelihoodof downgrades occurring after the user privilege model upgrade. Theuser authentication and access control will continue to work asit did in 2.4, but it will be impossible to create or modifyusers or to use user-defined roles until you run the authorizationupgrade.

If you decide to upgrade the user authorizationmodel immediately instead of waiting the recommended “burn in”period, then for sharded clusters, you must wait at least 10 secondsafter upgrading the sharded clusters to run the authorizationupgrade script.

Replica Sets

For a replica set, it is only necessary to run the upgrade process onthe primary as the changes will automatically replicate tothe secondaries.

Sharded Clusters

For a sharded cluster, connect to a mongos and run theupgrade procedure to upgrade the cluster’s authorization data. Bydefault, the procedure will upgrade the authorization data of theshards as well.

To override this behavior, run the upgrade command with theadditional parameter upgradeShards: false. If you choose tooverride, you must run the upgrade procedure on the mongosfirst, and then run the procedure on the primary members ofeach shard.

For a sharded cluster, do not run the upgrade process directlyagainst the config servers. Instead, perform the upgradeprocess using one mongos instance to interact with theconfig database.

Requirements

To upgrade the authorization model, you must have a user in theadmin database with the role userAdminAnyDatabase.

Procedure

Connect to MongoDB instance.

Connect and authenticate to the mongod instance for asingle deployment or a mongos for a sharded cluster as anadmin database user with the roleuserAdminAnyDatabase.

Upgrade authorization schema.

Use the authSchemaUpgrade command in the admindatabase to update the user data using the mongo shell.

Run authSchemaUpgrade command.

db.adminCommand({authSchemaUpgrade: 1 });

In case of error, you may safely rerun theauthSchemaUpgrade command.

Sharded cluster authSchemaUpgrade consideration.

For a sharded cluster, authSchemaUpgrade willupgrade the authorization data of the shards as well and theupgrade is complete. You can, however, override this behavior byincluding upgradeShards: false in the command, as in thefollowing example:

db.adminCommand({authSchemaUpgrade: 1,
upgradeShards: false });

If you override the behavior, after runningauthSchemaUpgrade on a mongos instance,you will need to connect to the primary for each shard andrepeat the upgrade process after upgrading on themongos.

Result

All users in a 2.6 system are stored in the admin.system.userscollection. To manipulate these users, use the user managementmethods.

The upgrade procedure copies the version 2.4 admin.system.userscollection to admin.system.backup_users.

The upgrade procedure leaves the version 2.4<database>.system.users collection(s) intact.