Docs4dev
Docs
mongodb / v3.6 / reference / tutorial-deploy-replica-set-with-keyfile-access-control.html

Deploy New Replica Set With Keyfile Access Control

On this page

Overview

Enforcing access control on a replica set requires configuring:

For this tutorial, each member of the replica set uses the same internal authentication mechanism and settings.

Enforcing internal authentication also enforces user access control. To connect to the replica set, clients like the mongo shell need to use a user account. See Users and Authentication Mechanisms.

Cloud Manager and Ops Manager

If you are currently using or are planning to use Cloud Manager or Ops Manager, see the Cloud Manager manual or the Ops Manager manual for enforcing access control.

Considerations

IP Binding

Changed in version 3.6.

Starting in MongoDB 3.6, mongod and mongos bind to localhost by default. If the members of your deployment are run on different hosts or if you wish remote clients to connect to your deployment, you must specify --bind_ip or net.bindIp. For more information, see Localhost Binding Compatibility Changes.

Operating System

This tutorial primarily refers to the mongod process. Windows users should use the mongod.exe program instead.

Keyfile Security

Keyfiles are bare-minimum forms of security and are best suited for testing or development environments. For production environments we recommend using x.509 certificates.

Users and Authentication Mechanisms

This tutorial covers creating the minimum number of administrative users on the admin database only. For the user authentication, the tutorial uses the default SCRAM authentication mechanism. Challenge-response security mechanisms are best suited for testing or development environments. For production environments, we recommend using x.509 certificates or LDAP Proxy Authentication (available for MongoDB Enterprise only) or Kerberos Authentication (available for MongoDB Enterprise only).

For details on creating users for specific authentication mechanism, refer to the specific authentication mechanism pages.

See ➤ Configure Role-Based Access Control for best practices for user creation and management.

Deploy New Replica Set with Keyfile Access Control

1

Create a keyfile.

With keyfile authentication, each mongod instances in the replica set uses the contents of the keyfile as the shared password for authenticating other members in the deployment. Only mongod instances with the correct keyfile can join the replica set.

The content of the keyfile must be between 6 and 1024 characters long and must be the same for all members of the replica set.

Note

On UNIX systems, the keyfile must not have group or world permissions. On Windows systems, keyfile permissions are not checked.

You can generate a keyfile using any method you choose. For example, the following operation uses openssl to generate a complex pseudo-random 1024 character string to use for a keyfile. It then uses chmod to change file permissions to provide read permissions for the file owner only:

openssl rand -base64 756 > <path-to-keyfile>
chmod 400 <path-to-keyfile>

See Keyfiles for additional details and requirements for using keyfiles.

2

Copy the keyfile to each replica set member.

Copy the keyfile to each server hosting the replica set members. Ensure that the user running the mongod instances is the owner of the file and can access the keyfile.

Avoid storing the keyfile on storage mediums that can be easily disconnected from the hardware hosting the mongod instances, such as a USB drive or a network attached storage device.

3

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

For each member in the replica set, start the mongod with either the security.keyFile configuration file setting or the --keyFile command-line option. Running mongod with the --keyFile command-line option or the security.keyFile configuration file setting enforces both Internal Authentication and Role-Based Access Control.

Configuration File

If using a configuration file, set

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.

security:
  keyFile: <path-to-keyfile>
replication:
  replSetName: <replicaSetName>
net:
   bindIp: localhost,<ip address>

Start the mongod using the configuration file:

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

For more information on the configuration file, see configuration options.

Command Line

If using the command line options, start the mongod with the following options:

  • --keyFile set to the keyfile’s path, and
  • --replSet set to the replica set name.

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.

mongod --keyFile <path-to-keyfile> --replSet <replicaSetName> --bind_ip localhost,<ip address of the mongod host>

For more information on command-line options, see the mongod reference page.

4

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

Connect a mongo shell to one of the mongod instances over the localhost interface. You must run the mongo shell 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.

5

Initiate the replica set.

From the mongo shell, 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.

Important

Run rs.initiate() on just one and only one mongod instance for the replica set.

rs.initiate(
  {
    _id : <replicaSetName>,
    members: [
      { _id : 0, host : "mongo1.example.net:27017" },
      { _id : 1, host : "mongo2.example.net:27017" },
      { _id : 2, host : "mongo3.example.net:27017" }
    ]
  }
)

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

Connect to the primary before continuing. Use