Upgrade User Authorization Data to 2.6 Format
On this page
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, after upgrading all MongoDB process to 2.6 you must also upgrade the authorization model.
Considerations
Complete all other Upgrade Requirements
Before upgrading the authorization model, you should first upgrade
MongoDB binaries to 2.6. For sharded clusters, ensure that all
cluster components are 2.6. If there are users in any database, be sure
you have at least one user in the admin database with the role
userAdminAnyDatabase before upgrading the MongoDB
binaries.
Timing
Because downgrades are more difficult after you upgrade the user authorization model, once you upgrade the MongoDB binaries to version 2.6, allow your MongoDB deployment to run a day or two without upgrading the user authorization model.
This allows 2.6 some time to "burn in" and decreases the likelihood of downgrades occurring after the user privilege model upgrade. The user authentication and access control will continue to work as it did in 2.4, but it will be impossible to create or modify users or to use user-defined roles until you run the authorization upgrade.
If you decide to upgrade the user authorization model immediately instead of waiting the recommended "burn in" period, then for sharded clusters, you must wait at least 10 seconds after upgrading the sharded clusters to run the authorization upgrade script.
Replica Sets
For a replica set, it is only necessary to run the upgrade process on the primary as the changes will automatically replicate to the secondaries.
Sharded Clusters
For a sharded cluster, connect to a mongos and run the
upgrade procedure to upgrade the cluster's authorization data. By
default, the procedure will upgrade the authorization data of the
shards as well.
To override this behavior, run the upgrade command with the
additional parameter upgradeShards: false. If you choose to
override, you must run the upgrade procedure on the mongos
first, and then run the procedure on the primary members of
each shard.
For a sharded cluster, do not run the upgrade process directly
against the config servers. Instead, perform the upgrade
process using one mongos instance to interact with the
config database.
Requirements
To upgrade the authorization model, you must have a user in the
admin database with the role userAdminAnyDatabase.
Procedure
Connect to MongoDB instance.
Connect and authenticate to the mongod instance for a
single deployment or a mongos for a sharded cluster as an
admin database user with the role
userAdminAnyDatabase.
Upgrade authorization schema.
Use the authSchemaUpgrade command in the admin
database to update the user data using the mongo shell.
Run authSchemaUpgrade command.
db.adminCommand({authSchemaUpgrade: 1 });
In case of error, you may safely rerun the
authSchemaUpgrade command.
Sharded cluster authSchemaUpgrade consideration.
For a sharded cluster, authSchemaUpgrade will
upgrade the authorization data of the shards as well and the
upgrade is complete. You can, however, override this behavior by
including upgradeShards: false in the command, as in the
following example:
db.adminCommand({authSchemaUpgrade: 1, upgradeShards: false });
If you override the behavior, after running
authSchemaUpgrade on a mongos instance,
you will need to connect to the primary for each shard and
repeat the upgrade process after upgrading on the
mongos.
Result
All users in a 2.6 system are stored in the admin.system.users
collection. To manipulate these users, use the user management
methods.
The upgrade procedure copies the version 2.4 admin.system.users
collection to admin.system.backup_users.
The upgrade procedure leaves the version 2.4
<database>.system.users collection(s) intact.