diff --git a/config/htaccess.yaml b/config/htaccess.yaml index 6737f543188..505e708772e 100644 --- a/config/htaccess.yaml +++ b/config/htaccess.yaml @@ -4713,4 +4713,11 @@ type: 'redirect' code: 301 outputs: - 'before-v3.0' +--- +from: '/core/enable-internal-authentication' +to: '/core/enforce-keyfile-access-control-in-existing-replica-set' +type: 'redirect' +code: 301 +outputs: + - 'after-v3.0' ... diff --git a/source/administration/security-checklist.txt b/source/administration/security-checklist.txt index 3269d643fd1..59ff505aa74 100644 --- a/source/administration/security-checklist.txt +++ b/source/administration/security-checklist.txt @@ -25,6 +25,8 @@ deployments, enable authentication for each MongoDB server. See :doc:`/core/authentication` and :doc:`/tutorial/enable-authentication`. +.. _security-checklist-role-based-access-control: + Configure Role-Based Access Control ----------------------------------- diff --git a/source/core/security-internal-authentication.txt b/source/core/security-internal-authentication.txt index 9d8cb9c57fc..8599504ca26 100644 --- a/source/core/security-internal-authentication.txt +++ b/source/core/security-internal-authentication.txt @@ -90,6 +90,9 @@ see :doc:`/tutorial/upgrade-keyfile-to-x509`. .. toctree:: :titlesonly: - /tutorial/enable-internal-authentication + /tutorial/enforce-keyfile-access-control-in-existing-replica-set + /tutorial/deploy-replica-set-with-keyfile-access-control + /tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster + /tutorial/deploy-sharded-cluster-with-keyfile-access-control /tutorial/configure-x509-member-authentication /tutorial/upgrade-keyfile-to-x509 diff --git a/source/includes/steps-deploy-replica-set-with-auth.yaml b/source/includes/steps-deploy-replica-set-with-auth.yaml index d543bf343da..85a20fd92ea 100644 --- a/source/includes/steps-deploy-replica-set-with-auth.yaml +++ b/source/includes/steps-deploy-replica-set-with-auth.yaml @@ -1,156 +1,265 @@ -title: Start one member of the replica set. stepnum: 1 +title: Create a keyfile. +ref: deploy-repset-generate-keyfile level: 4 -ref: start-first-replica-set-member -content: | - This :program:`mongod` should *not* enable :setting:`auth`. +pre: | + The contents of the keyfile serves as the shared password for the members + of the replica set. The content of the keyfile must be the same for all + :program:`mongod` instances in the replica set. + + You can generate a keyfile using any method you choose. The contents of + the keyfile must be between 6 and 1024 characters long. The keyfile must have + read permission for the file owner, and no group or world permissions. + + The following operation uses ``openssl`` to generate a complex + pseudo-random 1024 character string to use for a keyfile. It then uses + ``chmod`` to apply user read permissions for the file owner only: +action: + language: sh + code: | + openssl rand -base64 755 > + chmod 400 +post: | + See :ref:`internal-auth-keyfile` for additional details and requirements + for using keyfiles. --- -title: Create administrative users. stepnum: 2 +title: Copy the keyfile to each replica set member. +ref: deploy-repset-copy-keyfile level: 4 -ref: create-administrative-users pre: | - The following operations will create two users: a user administrator - that will be able to create and modify users (``myUserAdmin``), - and a :authrole:`root` user (``siteRootAdmin``) that you will use to - complete the remainder of the tutorial: -action: - language: javascript - code: | - use admin - db.createUser( { - user: "myUserAdmin", - pwd: "", - roles: [ { role: "userAdminAnyDatabase", db: "admin" } ] - }); - db.createUser( { - user: "siteRootAdmin", - pwd: "", - roles: [ { role: "root", db: "admin" } ] - }); + Copy the keyfile to each server hosting a replica set member. --- -title: Stop the ``mongod`` instance. stepnum: 3 +title: Enforce access control on each member of the replica set. level: 4 -ref: stop-first-replica-set-member +ref: deploy-repset-start-members +pre: | + Running a :program:`mongod` with the ``keyFile`` parameter enforces both + :doc:`/core/security-internal-authentication` and + :doc:`/core/authorization`. + + For *each* :program:`mongod` in the replica set, start the + :program:`mongod` using either a configuration file or the command line. + + .. important:: + You cannot change the name of a replica set after initiating it. + Choose an appropriate replica set name at this stage to reduce + complications later. + +action: + - pre: | + **Configuration File** + + If using a configuration file, set the :setting:`security.keyFile` option + to the keyfile's path, and the :setting:`replication.replSetName` option + to the replica set name: + language: yaml + code: | + security: + keyFile: + replication: + replSetName: + - pre: | + Start the :program:`mongod` using the configuration file: + language: shell + code: | + mongod --config + post: | + For more information on the configuration file, see + :doc:`configuration options`. + - pre: | + **Command Line** + + If using the command line option, start the :program:`mongod` with the + ``--keyFile`` and ``--replSet`` parameters: + language: sh + code: | + mongod --keyFile --replSet +post: | + For more information on startup parameters, + see the :program:`mongod` reference page. + + Include additional settings as appropriate to your deployment. --- -title: Create the key file to be used by each member of the replica set. stepnum: 4 +title: Connect to a member of the replica set over the localhost interface. level: 4 -ref: generate-keyfile -source: - file: steps-generate-key-file.yaml - ref: generate +ref: deploy-repset-connect-to-member +pre: | + The :ref:`localhost-exception` allows clients connected over the + localhost interface to create users on a :program:`mongod` + enforcing access control. After creating the first user, + the :ref:`localhost-exception` closes. + + Connect to one of the replica set members over the + :ref:`localhost interface`. You must run the + :program:`mongo` shell on the same physical machine as the target + :program:`mongod`. --- -title: Copy the key file to each member of the replica set. stepnum: 5 +title: Initiate the replica set using a configuration document. level: 4 -ref: copy-key-file -content: | - Copy the ``mongodb-keyfile`` to all hosts where components of a - MongoDB deployment run. Set the permissions of these files to - ``600`` so that only the *owner* of the file can read or write this - file to prevent other users on the system from accessing the shared - secret. ---- -title: Start each member of the replica set with the appropriate options. -level: 4 -stepnum: 6 -ref: start-mongod -pre: | - For each member, start a :program:`mongod` and specify the key file and - the name of the replica set. Also specify other parameters as needed for - your deployment. For replication-specific parameters, see - :ref:`cli-mongod-replica-set` required by your deployment. - - .. include:: /includes/fact-unique-replica-set-names.rst +ref: deploy-repset-initiate +pre: | + The :method:`rs.initiate()` method initiates the replica set, and + can take an optional configuration document that describes + each member of the replica set. + + The configuration document requires at minimum the + :rsconf:`_id` and :rsconf:`members` fields. The :rsconf:`members` + field is an array, and requires a document per member of the replica + set containing the :rsconf:`members[n]._id` and + :rsconf:`members[n].host` fields. + + The :rsconf:`_id` *must* match the ``--replSet`` parameter + passed to the :program:`mongod`. + + See :doc:`/reference/replica-configuration` for more information on + replica set configuration documents. action: - pre: | - The following example specifies parameters through the :option:`--keyFile` - and :option:`--replSet` command-line options: - language: javascript - code: | - mongod --keyFile /mysecretdirectory/mongodb-keyfile --replSet "rs0" + The following example initates a three member replica set. + - pre: | - The following example specifies parameters through a configuration file: language: javascript code: | - mongod --config $HOME/.mongodb/config + rs.initiate( + { + _id : , + members: [ + { _id : 0, host : "mongo1.example.net:27017" }, + { _id : 1, host : "mongo2.example.net:27017" }, + { _id : 2, host : "mongo3.example.net:27017" } + ] + } + ) post: | - In production deployments, you can configure a :term:`init script` to - manage this process. Init scripts are beyond the scope of this document. + :method:`rs.initiate()` triggers an :term:`election` and + elects one of the members to be the :term:`primary`. + + Connect to the primary before continuing. Use :method:`rs.status()` to + locate the primary member. --- -title: "Connect to the member of the replica set where you created the administrative users." +stepnum: 6 +title: Create the user administrator. level: 4 -stepnum: 7 -ref: connect-and-auth +ref: deploy-repset-user-admin pre: | - Connect to the replica set member you started and authenticate as - the ``siteRootAdmin`` user. From the :program:`mongo` shell, use the - following operation to authenticate: + .. important:: + After you create the first user, the :ref:`localhost exception + ` is no longer available. + + The first user must have privileges to create other users, such + as a user with the :authrole:`userAdminAnyDatabase`. This ensures + that you can create additional users after the :ref:`localhost-exception` + closes. + + If at least one user does *not* have privileges to create users, + once the localhost exception closes you may be unable to create + or modify users with new privileges, and therefore unable to + access necessary operations. + + Add a user using the :method:`db.createUser()` method. The user should + have at minimum the :authrole:`userAdminAnyDatabase` role on the + ``admin`` database. + + You must be connected to the :term:`primary` to create users. + + The following example creates the user ``userAdmin`` on the + ``admin`` database. Change the ``pwd`` to be a password of your + own choosing: + + .. important:: + Passwords should be random, long, and complex to ensure system security + and to prevent or delay malicious access. + action: + pre: | + language: javascript code: | - use admin - db.auth("siteRootAdmin", ""); + admin = db.getSiblingDB("admin") + admin.createUser( + { + user: "userAdmin", + pwd: "", + roles: [ { role: "userAdminAnyDatabase", db: "admin" } ] + } + ) +post: | + + See :ref:`database-user-roles` for a full list of built-in roles and + related to database administration operations. +--- +stepnum: 7 +title: Authenticate as the user administrator. +ref: deploy-repset-auth-user +level: 4 +pre: | + Authenticate to the ``admin`` database using the ``userAdmin`` user. +action: + - pre: | + Use :method:`db.auth()` to authenticate as the user administrator. + language: javascript + code: | + admin = db.getSiblingDB("admin") + admin.auth("userAdmin", "" ) + - pre: | + Alternatively, connect a new :program:`mongo` shell to the primary + replica set member using the ``-u ``, ``-p ``, and + the ``--authenticationDatabase`` parameters. + language: sh + code: | + mongo -u "userAdmin" -p "" --authenticationDatabase "admin" --- stepnum: 8 +title: Create the cluster administrator. level: 4 -source: - file: steps-deploy-replica-set.yaml - ref: initiate-rs +ref: deploy-repset-add-user-cluster +pre: | + The :authrole:`clusterAdmin` role grants access to + replication operations. +action: + - pre: | + Create a cluster administrator user and assign the + :authrole:`clusterAdmin role to the ``admin`` database: + language: sh + code: | + admin = db.getSiblingDB("admin") + admin.createUser( + { + "user" : "clusterAdmin", + "pwd" : "changeme", + roles: [ { "role" : "clusterAdmin", "db" : "admin" } ] + } + ) +post: | + See :ref:`cluster-admin-roles` for a full list of built-in roles related to + replica set and sharded cluster operations. --- stepnum: 9 +title: Create additional users (Optional). +ref: deploy-repset-add-addtl-users level: 4 -source: - file: steps-deploy-replica-set.yaml - ref: verify-rsconf +pre: | + Create users to allow clients to connect and interact with the replica set. + See :ref:`database-user-roles` for basic built-in roles to use in creating + read-only and read-write users. + + You may also want additional administrative users. + For more information on users, see :doc:`/core/security-users`. --- stepnum: 10 +title: Authenticate as cluster admin (Optional). +ref: deploy-repset-auth-cluster level: 4 -source: - file: steps-deploy-replica-set.yaml - ref: add-remaining-members ---- -stepnum: 11 -level: 4 -source: - file: steps-deploy-replica-set.yaml - ref: check-status ---- -title: Create additional users to address operational requirements. -level: 4 -stepnum: 12 -ref: create-records-db-owner pre: | - You can use :doc:`built-in roles ` to create - common types of database users, such as the :authrole:`dbOwner` role to - create a database administrator, the :authrole:`readWrite` role to - create a user who can update data, or the :authrole:`read` role to - create user who can search data but no more. You also can define - :ref:`custom roles `. -action: - pre: | - For example, the following creates a database administrator for the - ``products`` database: - language: javascript - code: | - use products - db.createUser( - { - user: "productsDBAdmin", - pwd: "password", - roles: - [ - { - role: "dbOwner", - db: "products" - } - ] - } - ) -post: | - For an overview of roles and privileges, see :ref:`authorization`. For - more information on adding users, see - :doc:`/tutorial/manage-users-and-roles`. -... + You cannot perform replica operations such as configuring members + using the ``userAdmin`` user. The underlying :authrole:`userAdminAnyDatabase` + role does not have the required privileges. + + Authenticate to the ``admin`` database as the ``clusterAdmin`` using the + :method:`db.auth()` method or a new :program:`mongo` shell with the + ``username``, ``password``, and ``authenticationDatabase`` parameters. +... \ No newline at end of file diff --git a/source/includes/steps-deploy-sharded-cluster-config-server.yaml b/source/includes/steps-deploy-sharded-cluster-config-server.yaml new file mode 100644 index 00000000000..376555ddb75 --- /dev/null +++ b/source/includes/steps-deploy-sharded-cluster-config-server.yaml @@ -0,0 +1,109 @@ +stepnum: 1 +level: 4 +ref: sharded-cluster-deploy-config-server +pre: | + Running a :program:`mongod` with the ``keyFile`` parameter enforces both + :doc:`/core/security-internal-authentication` and + :doc:`/core/authorization`. + + Start *each* :program:`mongod` in the replica set using either + a configuration file or the command line. +action: + - pre: | + **Configuration File** + + If using a configuration file, set :setting:`security.keyFile` to the + keyfile's path, :setting:`sharding.clusterRole` to ``configsvr``, + and :setting:`replication.replSetName` to the desired name of the + config server replica set. + language: yaml + code: | + security: + keyFile: + sharding: + clusterRole: configsvr + replication: + replSetName: + - pre: | + Start the :program:`mongod` specifying the ``--config`` option and the + path to the configuration file. + language: shell + code: | + mongod --config + post: | + For more information on the configuration file, see + :doc:`configuration options`. + - pre: | + **Command Line** + + If using the command line parameters, start the :program:`mongod` with + the ``-keyFile``, ``--configsvr``, and ``--replSetName`` parameters. + language: sh + code: | + mongod --keyFile --configsvr --replSetName --dbPath + post: | + For more information on startup parameters, + see the :program:`mongod` reference page. +post: | + Include additional settings as appropriate to your deployment. +--- +stepnum: 2 +level: 4 +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-connect-to-member +pre: | + The :ref:`localhost-exception` allows clients connected over the + localhost interface to create users on a :program:`mongod` + enforcing access control. After creating the first user, + the :ref:`localhost-exception` closes. + + Connect a :program:`mongo` shell to one of the config server + :program:`mongod` instances over the + :ref:`localhost interface`. You must run + the :program:`mongo` shell on the same physical machine as the + target :program:`mongod`. +--- +stepnum: 3 +level: 4 +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-initiate +pre: | + The :method:`rs.initiate()` method initiates the replica set, and + can take an optional configuration document that describes + each member of the replica set. + + The configuration document requires at minimum the + :rsconf:`_id` and :rsconf:`members` fields. The :rsconf:`members` + field is an array, and requires a document per member of the replica + set containing the :rsconf:`members[n]._id` and + :rsconf:`members[n].host` fields. + + The :rsconf:`_id` *must* match the ``--replSet`` parameter + passed to the :program:`mongod`. + + See :doc:`/reference/replica-configuration` for more information on + replica set configuration documents. +action: + - pre: | + Pass a configuration document to the :method:`rs.initiate()` method: + language: javascript + code: | + rs.initiate( + { + _id: "", + configsvr: true, + members: [ + { _id : 0, host : "cfg1.example.net:27017" }, + { _id : 1, host : "cfg2.example.net:27017" }, + { _id : 2, host : "cfg3.example.net:27017" } + ] + } + ) +post: | + .. important:: + + You must include the ``configsvr : true`` option for the config server + replica set to start correctly. +... \ No newline at end of file diff --git a/source/includes/steps-deploy-sharded-cluster-connect.yaml b/source/includes/steps-deploy-sharded-cluster-connect.yaml new file mode 100644 index 00000000000..95de5b384ed --- /dev/null +++ b/source/includes/steps-deploy-sharded-cluster-connect.yaml @@ -0,0 +1,200 @@ +stepnum: 1 +title: Connect a :program:`mongos` to the cluster +level: 4 +ref: deploy-cluster-connect-mongos +pre: | + Start a :program:`mongos` specifying + the keyfile using either a configuration file or a command line parameter. +action: + - pre: | + If using a configuration file, set the :setting:`security.keyFile` + to the keyfile`s path and the :setting:`sharding.configDB` to + the replica set name and at least one member of the replica + set in ``/`` format. + language: yaml + code: | + security: + keyFile: + sharding: + configDB: /cfg1.example.net:27017,cfg2.example.net:27017,... + - pre: | + Start the :program:`mongos` specifying the ``--config`` option and the + path to the configuration file. + language: shell + code: | + mongos --config /srv/mongodb/mongos.conf + post: | + For more information on the configuration file, see + :doc:`configuration options`. + - pre: | + If using command line parameters start the :program:`mongos` and specify + the ``--keyFile`` and ``--configDB`` parameters. + language: sh + code: | + mongos --keyFile --configDB /cfg1.example.net:27017,cfg2.example.net:27017,... + post: | + Include any other options as appropriate for your deployment. + - pre: | + **Using mirrored config servers** + + .. versionchanged:: 3.2 MongoDB deprecates mirrored config server configurations + + If using a mirrored configuration, pass all of the config + servers in ``:`` format to the ``configDB`` option. + + If using a configuration file: + language: yaml + code: | + security: + keyFile: + sharding: + configDB: cfg1.example.net:27017,cfg2.example.net:27017,cfg3.example.net:27017 + - pre: | + If using the command line parameters: + language: sh + code: | + mongos --keyFile --configDB cfg1.example.net:27017,cfg2.example.net:27017,cfg3.example.net:27017 +--- +stepnum: 2 +title: Connect to a :program:`mongos` over the localhost interface. +level: 4 +ref: deploy-cluster-connect-mongo +pre: | + The :ref:`localhost-exception` allows clients connected over the + localhost interface to create users on a :program:`mongod` + enforcing access control. After creating the first user, + the :ref:`localhost-exception` closes. + + Connect to one of the replica set members over the + :ref:`localhost interface`. You must run the + :program:`mongo` shell on the same physical machine as the target + :program:`mongos`. +--- +title: Create the user administrator. +stepnum: 3 +level: 4 +ref: add-user +pre: | + .. important:: + After you create the first user, the :ref:`localhost exception + ` is no longer available. + + The first user must have privileges to create other users, such + as a user with the :authrole:`userAdminAnyDatabase`. This ensures + that you can create additional users after the :ref:`localhost-exception` + closes. + + If at least one user does *not* have privileges to create users, + once the localhost exception closes you may be unable to create + or modify users with new privileges, and therefore unable to + access necessary operations. + + Add a user using the :method:`db.createUser()` method. The user should + have at minimum the :authrole:`userAdminAnyDatabase` role on the + ``admin`` database. + + The following example creates the user ``userAdmin`` on the + ``admin`` database. Change the ``pwd`` field to be a password of your + own choosing: + + .. important:: + Passwords should be random, long, and complex to ensure system security + and to prevent or delay malicious access. + +action: + pre: | + + language: javascript + code: | + admin = db.getSiblingDB("admin") + admin.createUser( + { + user: "userAdmin", + pwd: "", + roles: [ { role: "userAdminAnyDatabase", db: "admin" } ] + } + ) +post: | + See :ref:`database-user-roles` for a full list of built-in roles and + related to database administration operations. +--- +title: Authenticate as the user administrator. +stepnum: 4 +level: 4 +ref: auth-as-admin +action: + - pre: | + Use :method:`db.auth()` to authenticate as the user administrator: + language: javascript + code: | + admin = db.getSiblingDB("admin") + admin.auth("userAdmin", "" ) + - pre: | + Alternatively, connect a new :program:`mongo` shell to the target + replica set member using the ``-u ``, ``-p ``, and + the ``--authenticationDatabase admin`` parameters. You must use + the :ref:`localhost-exception` to connect to the :program:`mongos`. + language: sh + code: | + mongo -u "userAdmin" -p "" --authenticationDatabase "admin" +--- +title: Create Administrative User for Cluster Management +stepnum: 5 +level: 4 +ref: add-user-cluster +pre: | + The cluster administrator user has the :authrole:`clusterAdmin` role, + which grants access to replication and sharding operations. + + The following example creates the user ``myUserAdmin`` on the + ``admin`` database. Change the ``pwd`` field to be a password of your + own choosing: + + .. important:: + Passwords should be random, long, and complex to ensure system security + and to prevent or delay malicious access. +action: + - pre: | + Create a :authrole:`clusterAdmin` user in the ``admin`` database: + language: sh + code: | + admin = db.getSiblingDB("admin") + admin.createUser( + { + "user" : "clusterAdmin", + "pwd" : "", + roles: [ { "role" : "clusterAdmin", "db" : "admin" } ] + } + ) +post: | + See :ref:`cluster-admin-roles` for a full list of built-in roles related to + replica set and sharded cluster operations. +--- +stepnum: 6 +title: Authenticate as cluster admin. +ref: auth-user-cluster +level: 4 +pre: | + You cannot perform sharding operations using the ``userAdmin`` user. + The underlying :authrole:`userAdminAnyDatabase` + role does not have the required privileges. + + Authenticate as the ``clusterAdmin`` using either the + :method:`db.auth()` method or a new :program:`mongo` shell with the + ``username``, ``password``, and ``authenticationDatabase`` parameters. +--- +stepnum: 7 +title: Create additional users (Optional). +ref: deploy-cluster-create-users +level: 4 +pre: | + Create users to allow clients to connect and interact with the replica set. + See :ref:`database-user-roles` for basic built-in roles to use in creating + read-only and read-write users. + + You must authenticate as the ``userAdmin`` user, or as a user with + user creation privileges, in order to add additional users. + + You may also want additional administrative users. + See :doc:`/core/security-users`. +... \ No newline at end of file diff --git a/source/includes/steps-deploy-sharded-cluster-mirrored-config.yaml b/source/includes/steps-deploy-sharded-cluster-mirrored-config.yaml new file mode 100644 index 00000000000..598d3bf4133 --- /dev/null +++ b/source/includes/steps-deploy-sharded-cluster-mirrored-config.yaml @@ -0,0 +1,50 @@ +title: Create Data Directories. +stepnum: 1 +level: 4 +ref: deploy-cluster-mirrored-create-data-dir +pre: | + Create data directories for each of the three config server instances. By + default, a config server stores its data files in the + /data/configdb directory. You can choose a different location. + To create a data directory, issue a command similar to the following: +action: + language: sh + code: | + mkdir /data/configdb +--- +title: Start up the Config Server :program:`mongod`. +stepnum: 2 +level: 4 +ref: deploy-cluster-mirrored-start-config +action: + - pre: | + **Configuration File** + + If using a configuration file, set the :setting:`security.keyFile` option + to the keyfile's path and the :setting:`sharding.clusterRole` + option to ``configsvr``. Start the component, as in the following + example: + language: yaml + code: | + security: + keyFile: + sharding: + clusterRole: configsvr + post: | + Include any other settings as appropriate for your deployment. + See :doc:`/reference/configuration-options` for information on + using a configuration file. + - pre: | + **Command Line** + + If using the command line option, when starting the component, specify + the ``--keyFile`` and ``--configsvr`` parameters, as in the + following example: + language: sh + code: | + mongod --keyFile --configsvr --dbpath + post: | + Include any other options as appropriate for your deployment. +post: | + Repeat this step until all three config servers are online. +... \ No newline at end of file diff --git a/source/includes/steps-deploy-sharded-cluster-shard-replica.yaml b/source/includes/steps-deploy-sharded-cluster-shard-replica.yaml new file mode 100644 index 00000000000..03f77cea291 --- /dev/null +++ b/source/includes/steps-deploy-sharded-cluster-shard-replica.yaml @@ -0,0 +1,127 @@ +level: 4 +stepnum: 1 +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-start-members +pre: | + Running a :program:`mongod` with the ``keyFile`` parameter enforces both + :doc:`/core/security-internal-authentication` and + :doc:`/core/authorization`. + + Start *each* :program:`mongod` in the replica set using either + a configuration file or the command line. +action: + - pre: | + **Configuration File** + + If using a configuration file, set the :setting:`security.keyFile` option + to the keyfile's path, the :setting:`replication.replSetName` to the + desired name of the replica set, and the :setting:`sharding.clusterRole` + option to ``shardsvr``. Start the component, as in the following + example: + language: yaml + code: | + security: + keyFile: + sharding: + clusterRole: shardsvr + replication: + replSetName: + post: | + See :doc:`/reference/configuration-options` for information on + using a configuration file. + - pre: | + **Command Line** + + If using the command line option, when starting the component, specify + the ``--keyFile``, ``replSet``, and ``--shardsvr`` parameters, as in the + following example: + language: sh + code: | + mongod --keyFile --shardsvr --replSet + post: | + Include any other options as appropriate for your deployment. +--- +stepnum: 2 +level: 4 +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-connect-to-member +pre: | + The :ref:`localhost-exception` allows clients connected over the + localhost interface to create users on a :program:`mongod` + enforcing access control. After creating the first user, + the :ref:`localhost-exception` closes. + + Connect a :program:`mongo` shell to one of the replica set member + :program:`mongod` instances over the + :ref:`localhost interface`. You + must run the :program:`mongo` shell on the same physical machine as the + target :program:`mongod`. +--- +stepnum: 3 +level: 4 +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-initiate +pre: | + The :method:`rs.initiate()` method initiates the replica set, and + can take an optional configuration document that describes + each member of the replica set. + + The configuration document requires at minimum the + :rsconf:`_id` and :rsconf:`members` fields. The :rsconf:`members` + field is an array, and requires a document per member of the replica + set containing the :rsconf:`members[n]._id` and + :rsconf:`members[n].host` fields. + + The :rsconf:`_id` *must* match the ``--replSet`` parameter + passed to the :program:`mongod`. + + See :doc:`/reference/replica-configuration` for more information on + replica set configuration documents. +action: + - pre: | + The following example initates a three member replica set. + - pre: | + language: javascript + code: | + rs.initiate( + { + _id : , + members: [ + { _id : 0, host : "s1-mongo1.example.net:27017" }, + { _id : 1, host : "s1-mongo2.example.net:27017" }, + { _id : 2, host : "s1-mongo3.example.net:27017" } + ] + } + ) +--- +title: Create the shard-local user administrator (optional). +stepnum: 4 +level: 4 +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-user-admin +--- +title: Authenticate as the shard-local user administrator (optional). +stepnum: 5 +level: 4 +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-auth-user +--- +title: Create the shard-local cluster administrator (optional). +stepnum: 6 +level: 4 +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-add-user-cluster +pre: | + The cluster administrator user has priviledges that allow access to + replication operations. + + This step uses the :authrole:`clusterAdmin` role. For a full list of + roles related to replica set operations see + :ref:`cluster-admin-roles`. +... \ No newline at end of file diff --git a/source/includes/steps-enable-authentication-in-replica-set.yaml b/source/includes/steps-enable-authentication-in-replica-set.yaml new file mode 100644 index 00000000000..ae96ce62cd7 --- /dev/null +++ b/source/includes/steps-enable-authentication-in-replica-set.yaml @@ -0,0 +1,108 @@ +title: Create a keyfile. +stepnum: 1 +ref: generate-keyfile +level: 4 +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-generate-keyfile +--- +stepnum: 2 +ref: copy-keyfile +level: 4 +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-copy-keyfile +--- +stepnum: 3 +title: Shut down all members of the replica set. +ref: shutdown-repset +level: 4 +pre: | + Shut down each :program:`mongod` in the replica set, starting with the + :term:`secondaries`. Continue until *all* members of the + replica set are offline, including any :term:`arbiters`. + The :term:`primary` must be the *last* member shut down to avoid + potential rollbacks. + + To shut down a :program:`mongod`, connect each :program:`mongod` using a + :program:`mongo` shell and issue the :method:`db.shutdownServer()` on the + ``admin`` database: +action: + language: sh + code: | + use admin + db.shutdownServer() +post: | + At the end of this step, *all* members of the replica set should be offline. +--- +stepnum: 4 +title: Restart each member of the replica set with access control enforced. +ref: enable-auth +level: 4 +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-start-members +pre: | + Running a :program:`mongod` with the ``keyFile`` parameter enforces both + :doc:`/core/security-internal-authentication` and + :doc:`/core/authorization`. + + Start *each* :program:`mongod` in the replica set using either + a configuration file or the command line. + + Use the original replica set name for ``replSetName`` when starting each + member. You cannot change the name of a replica set, and attempting to do + so results in errors. +--- +stepnum: 5 +level: 4 +ref: connect-via-localhost +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-connect-to-member +--- +stepnum: 6 +title: Create the user administrator. +level: 4 +ref: add-user +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-user-admin +--- +stepnum: 7 +title: Authenticate as the User Administrator. +ref: enable-replset-auth-user +level: 4 +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-auth-user +--- +stepnum: 8 +title: Create the cluster administrator (Optional). +level: 4 +ref: add-user-cluster +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-add-user-cluster +pre: | + The cluster administrator user has the :authrole:`clusterAdmin` role, + which grants access to replication operations. +post: | + See :ref:`cluster-admin-roles` for a full list of built-in roles related to + replica set operations. +--- +stepnum: 9 +title: Create additional users (Optional). +level: 4 +ref: add-replica-set-users +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-add-addtl-users +--- +stepnum: 10 +level: 4 +ref: auth-as-cluster-admin +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-auth-cluster +... \ No newline at end of file diff --git a/source/includes/steps-enable-authentication-in-sharded-cluster.yaml b/source/includes/steps-enable-authentication-in-sharded-cluster.yaml index 1ebf4101da4..5d579d6c0f7 100644 --- a/source/includes/steps-enable-authentication-in-sharded-cluster.yaml +++ b/source/includes/steps-enable-authentication-in-sharded-cluster.yaml @@ -2,99 +2,458 @@ stepnum: 1 title: Create a keyfile. ref: generate-keyfile level: 4 +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-generate-keyfile +--- +stepnum: 2 +title: Copy the keyfile to each component in the sharded cluster. +ref: copy-keyfile +level: 4 +source: + file: steps-deploy-replica-set-with-auth.yaml + ref: deploy-repset-copy-keyfile pre: | - Create the :ref:`keyfile ` your deployment will - use to authenticate to members to each other. You can generate a - keyfile using any method you choose. Ensure that the password stored - in the keyfile is both long and contains a high amount of randomness. - - For example, the following operation uses ``openssl`` command to - generate pseudo-random data to use for a keyfile: + Every server hosting a :program:`mongod` or :program:`mongos` component + of the sharded cluster must contain a copy of the keyfile. +--- +title: Disable the Balancer. +stepnum: 3 +ref: disable-balancer +level: 4 +pre: | + Connect a :program:`mongo` shell to a :program:`mongos`. +action: + - pre: | + language: sh + code: | + sh.stopBalancer() + post: | + The balancer may not stop immediately if a migration is in progress. + The :method:`sh.stopBalancer()` method blocks the shell until the + balancer stops. + + - pre: | + Use :method:`sh.getBalancerState()` to verify that the balancer has + stopped. + language: sh + code: | + sh.getBalancerState() +post: | + .. important:: Do not proceed until the balancer has stopped running. + + See :doc:`/tutorial/manage-sharded-cluster-balancer` for tutorials on + configuring sharded cluster balancer behavior. +--- +title: Shut down all :program:`mongos` instances for the sharded cluster. +stepnum: 4 +ref: shutdown-mongos +level: 4 +pre: | + Connect a :program:`mongo` shell to each :program:`mongos` and shut + them down. + + Use the :method:`db.shutdownServer()` method on the ``admin`` database + to safely shut down the :program:`mongod`: +action: + language: sh + code: | + admin = db.getSiblingDB("admin") + admin.shutdownServer() +post: | + Repeat until all :program:`mongos` instances in the cluster + are offline. + + Once this step is complete, all :program:`mongos` instances in the cluster + should be offline. +--- +title: Shut down config server :program:`mongod` instances. +stepnum: 5 +ref: shutdown-config-servers +level: 4 +pre: | + Connect a :program:`mongo` shell to each :program:`mongod` in the + config server deployment and shut them down. + + For replica set config server deployments, shut down the :term:`primary` + member last. + + For mirrored config server deployments, there is no required order + for shutting down the individual :program:`mongod` instances. + + Use the :method:`db.shutdownServer()` method on the ``admin`` database + to safely shut down the :program:`mongod`: action: language: sh code: | - openssl rand -base64 741 > /srv/mongodb/mongodb-keyfile - chmod 600 mongodb-keyfile + admin = db.getSiblingDB("admin") + admin.shutdownServer() post: | + Repeat until all config servers are offline. +--- +title: Shut down shard replica set :program:`mongod` instances. +stepnum: 6 +ref: shutdown-shard-servers +level: 4 +pre: | + For each shard replica set, connect a :program:`mongo` shell to each + :program:`mongod` member in the replica set and shut them down. Shut down + the :term:`primary` member last. + + Use the :method:`db.shutdownServer()` method on the ``admin`` database + to safely shut down the :program:`mongod`: +action: + language: sh + code: | + admin = db.getSiblingDB("admin") + admin.shutdownServer() +post: | + Repeat this step for each shard replica set until all :program:`mongod` + instances in all shard replica sets are offline. + + Once this step is complete, the entire sharded cluster should be offline. +--- +title: Enforce Access Control on the Config Servers. +stepnum: 7 +ref: enable-auth-config-serv +level: 4 +pre: | + Running a :program:`mongod` with the ``keyFile`` parameter enforces both + :doc:`/core/security-internal-authentication` and + :doc:`/core/authorization`. + Start *each* :program:`mongod` in the config server deployment using either + a configuration file or the command line. + + .. note:: + MongoDB 3.2 deprecates mirrored config servers. The downtime may be + an ideal time to upgrade mirrored config servers to a replica + set deployment. + + See the :doc:`/tutorial/upgrade-config-servers-to-replica-set` + tutorial for instructions on converting a mirrored config server + deployment to a replica set deployment. +action: + - pre: | + **Configuration File** + + If using a configuration file, set :setting:`security.keyFile` to the + keyfile's path, :setting:`sharding.clusterRole` to ``configsvr``, + and :setting:`replication.replSetName` to the *original* name of the + config server replica set. + + If using a mirrored config server deployment, + omit the :setting:`replication.replSetName` option. + + language: yaml + code: | + security: + keyFile: + sharding: + clusterRole: configsvr + replication: + replSetName: + - pre: | + Start the :program:`mongod` specifying the ``--config`` option and the + path to the configuration file. + language: shell + code: | + mongod --config + post: | + For more information on the configuration file, see + :doc:`configuration options`. + - pre: | + **Command Line** + + If using the command line parameters, start the :program:`mongod` with + the ``-keyFile``, ``--configsvr``, and ``--replSetName`` parameters. + + If using a mirrored config server deployment, omit the ``--replSetName`` + parameter. + language: sh + code: | + mongod --keyFile --configsvr --replSetName --dbPath + post: | + For more information on startup parameters, + see the :program:`mongod` reference page. + + Make sure to use the original replica set name when restarting each + member. You cannot change the name of a replica set. +post: | + Enforcing internal authentication implies and enforces :doc:`user access + control`. --- -title: Enable authentication for each member of the sharded cluster or replica set. -stepnum: 2 +title: Enforce Access Control for each Shard in the Sharded Cluster. +stepnum: 8 ref: enable-auth level: 4 pre: | - For *each* :program:`mongod` in the replica set or for *each* - :program:`mongos` and :program:`mongod` in the sharded cluster, - including all config servers and shards, specify the keyfile using - either a configuration file or a command line option. + Running a :program:`mongod` with the ``keyFile`` parameter enforces both + :doc:`/core/security-internal-authentication` and + :doc:`/core/authorization`. + + Start *each* :program:`mongod` in the replica set using either + a configuration file or the command line. action: - pre: | - In a configuration file, set the :setting:`security.keyFile` option to the - keyfile's path and then start the component, as in the following - example: + **Configuration File** + + If using a configuration file, set the :setting:`security.keyFile` option + to the keyfile's path and the :setting:`replication.replSetName` option + to the *original* name of the replica set. language: yaml code: | security: - keyFile: /srv/mongodb/keyfile + keyFile: + replication: + replSetName: + - pre: | + Start the :program:`mongod` specifying the ``--config`` option and the + path to the configuration file. + language: shell + code: | + mongod --config post: | - Include any other settings as appropriate for your deployment. + For more information on the configuration file, see + :doc:`configuration options`. - pre: | - Or, when starting the component, specify the ``--keyFile`` - option. For example, for a :program:`mongod` + **Command Line** + + If using the command line parameters, start the :program:`mongod` and + specify the ``--keyFile`` and ``--replSetName`` parameters. language: sh code: | - mongod --keyFile /srv/mongodb/mongodb-keyfile --dbpath + mongod --keyfile --replSetName --dbPath post: | - Include any other options as appropriate for your deployment. + For more information on startup parameters, + see the :program:`mongod` reference page. + + Make sure to use the original replica set name when restarting each + member. You cannot change the name of a replica set. post: | - Enabling internal authentication enables :doc:`access control + Enforcing internal authentication implies :doc:`access control `. + + Repeat this step until all shards in the cluster are online. --- -title: Connect to the MongoDB instance via the localhost exception. -stepnum: 3 +title: Create a Shard-Local User Administrator (Optional). +stepnum: 9 +ref: shard-local-adduser level: 4 -ref: connect-via-localhost -content: | - To add the first user using :ref:`localhost-exception`: +pre: | + .. important:: + The :ref:`localhost-exception` allows clients connected over the + localhost interface to create users on a :program:`mongod` + enforcing access control. After creating the first user, + the :ref:`localhost-exception` closes. + + The first user must have privileges to create other users, such + as a user with the :authrole:`userAdminAnyDatabase`. This ensures + that you can create additional users after the :ref:`localhost-exception` + closes. + + If at least one user does *not* have privileges to create users, + once the localhost exception closes you may be unable to create + or modify users with new privileges, and therefore unable to + access certain functions or operations. - - For a replica set, connect a :program:`mongo` shell to the primary. - Run the :program:`mongo` shell from the same host as the primary. + For each shard replica set in the cluster, connect a + :program:`mongo` shell to the :term:`primary` member over the + :ref:`localhost interface`. + + You must run the :program:`mongo` on the same machine as the + target :program:`mongod` to use the localhost interface. + + Create a ``userAdmin`` user with the ``userAdminAnyDatabase`` + role on the ``admin`` database. This user can create + additional users for the shard replica set as necessary. + Creating this user also closes the :ref:`localhost-exception`. + + The following example creates the user ``myUserAdmin`` on the + ``admin`` database. Change the ``pwd`` to be a password of your + own choosing: - - For a sharded cluster, connect a :program:`mongo` shell to the - :program:`mongos`. Run the :program:`mongo` shell from same host as - the :program:`mongos`. + .. important:: + Passwords should be random, long, and complex to ensure system security + and to prevent or delay malicious access. +action: + pre: | + + language: javascript + code: | + admin = db.getSiblingDB("admin") + admin.createUser( + { + user: "userAdmin", + pwd: "", + roles: [ { role: "userAdminAnyDatabase", db: "admin" } ] + } + ) --- -title: Add first user. -stepnum: 4 +title: Enforce Access Control for the :program:`mongos` servers. +stepnum: 10 +ref: enable-auth-mongos level: 4 -ref: add-user -source: - file: steps-create-admin-then-enable-authentication.yaml - ref: create-user-admin -post: | - After you create the user administrator, for a replica set, the - :ref:`localhost exception ` is no longer - available. - - For sharded clusters, you must still prevent unauthorized access to - the individual shards. Follow one of the following steps for each - shard in your cluster: +pre: | + Running a :program:`mongod` with the ``keyFile`` parameter enforces both + :doc:`/core/security-internal-authentication` and + :doc:`/core/authorization`. - - Create an administrative user, or + Start *each* :program:`mongos` in the replica set using either + a configuration file or the command line. +action: + - pre: | + **Configuration File** + + If using a configuration file, set the :setting:`security.keyFile` + to the keyfile`s path and the :setting:`sharding.configDB` to + the replica set name and at least one member of the replica + set in ``/`` format. + language: yaml + code: | + security: + keyFile: + sharding: + configDB: /cfg1.example.net:27017,cfg2.example.net:27017,... + - pre: | + Start the :program:`mongos` specifying the ``--config`` option and the + path to the configuration file. + language: shell + code: | + mongos --config + post: | + For more information on the configuration file, see + :doc:`configuration options`. + - pre: | + **Command Line** + + If using command line parameters start the :program:`mongos` and specify + the ``--keyFile`` and ``--configDB`` parameters. + language: sh + code: | + mongos --keyFile --configDB /cfg1.example.net:27017,cfg2.example.net:27017,... + post: | + Include any other options as appropriate for your deployment. + - pre: | + **Using mirrored config servers** + + .. versionchanged:: 3.2 MongoDB deprecates mirrored config server configurations + + If using a mirrored configuration, pass all of the config + servers in ``:`` format to the ``configDB`` option. + + If using a configuration file: + language: yaml + code: | + security: + keyFile: + sharding: + configDB: cfg1.example.net:27017,cfg2.example.net:27017,cfg3.example.net:27017 + - pre: | + If using the command line parameters: + language: sh + code: | + mongos --keyFile --configDB cfg1.example.net:27017,cfg2.example.net:27017,cfg3.example.net:27017 +post: | + At this point, the entire sharded cluster is back online and can + communicate internally using the keyfile specified. However, external + programs like the :program:`mongo` shell need to use a correctly + provisioned user in order to read or write to the cluster. +--- +title: Connect to the :program:`mongos` instance over the localhost interface. +stepnum: 11 +level: 4 +ref: connect-via-localhost +pre: | + A :program:`mongod` enforcing access control requires clients to + authenticate connections with a :doc:`user`. + If the :program:`mongod` has no users configured, the + :ref:`localhost-exception` allows a client connected over the + localhost interface to create the necessary users. After creating + the first user, the :ref:`localhost-exception` closes. Any new + client connections to the :program:`mongod` must authenticate as a user. - - Disable the :ref:`localhost-exception` at startup. To disable the - localhost exception, set the :parameter:`enableLocalhostAuthBypass` - to 0. + In order to use the :ref:`localhost-exception`, you + *must* run the :program:`mongo` shell from same host as + the :program:`mongos`. --- -stepnum: 5 +title: Create the user administrator. +stepnum: 12 +level: 4 +ref: add-user source: - file: steps-create-admin-then-enable-authentication.yaml + file: steps-deploy-sharded-cluster-connect.yaml + ref: add-user +--- +title: Authenticate as the user administrator. +stepnum: 13 +level: 4 +source: + file: steps-deploy-sharded-cluster-connect.yaml ref: auth-as-admin +ref: auth-as-admin +--- +title: Create Administrative User for Cluster Management +stepnum: 14 level: 4 +source: + file: steps-deploy-sharded-cluster-connect.yaml + ref: add-user-cluster +ref: add-user-cluster +pre: | + The cluster administrator user has the :authrole:`clusterAdmin` role, + which grants access to replication operations. +post: | + See :ref:`cluster-admin-roles` for a full list of built-in roles related to + replica set and sharded cluster operations. --- -stepnum: 6 +stepnum: 15 +title: Authenticate as cluster admin. +source: + file: steps-deploy-sharded-cluster-connect.yaml + ref: auth-user-cluster +ref: auth-user-cluster +level: 4 +pre: | + You cannot perform sharding operations such as sharding collections + using the ``userAdmin`` user. The underlying :authrole:`userAdminAnyDatabase` + role does not have the required privileges. + + Authenticate to the ``admin`` database as the ``clusterAdmin`` using the + :method:`db.auth()` method or a new :program:`mongo` shell with the + ``username``, ``password``, and ``authenticationDatabase`` parameters. +--- +stepnum: 16 +title: Start the load balancer. +ref: shard-start-load-balancer +level: 4 +pre: | + Start the load balancer. +action: + language: javascript + code: | + sh.startBalancer() +post: | + Use the :method:`sh.getBalancerState()` to verify the balancer has started. + + See :doc:`/tutorial/manage-sharded-cluster-balancer` for tutorials on + the sharded cluster balancer. +--- +stepnum: 17 +title: Create additional users (Optional). source: - file: steps-create-admin-then-enable-authentication.yaml - ref: create-additionalusers + file: steps-deploy-sharded-cluster-connect.yaml + ref: deploy-cluster-create-users +ref: deploy-cluster-create-users level: 4 +pre: | + Create users to allow clients to connect and interact with the replica set. + See :ref:`database-user-roles` for basic built-in roles to use in creating + read-only and read-write users. + + You must authenticate as the ``userAdmin`` user, or a user with + similar priviledges, to create new users. + + You may also want additional administrative users. + For more information on users, see :doc:`/core/security-users`. ... diff --git a/source/tutorial/deploy-replica-set-with-keyfile-access-control.txt b/source/tutorial/deploy-replica-set-with-keyfile-access-control.txt new file mode 100644 index 00000000000..a9c43c54ad5 --- /dev/null +++ b/source/tutorial/deploy-replica-set-with-keyfile-access-control.txt @@ -0,0 +1,102 @@ +.. _deploy-repl-set-with-keyfile: +.. _deploy-repl-set-with-auth: + +============================================== +Deploy Replica Set With Keyfile Access Control +============================================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Overview +-------- + +Enforcing access control on a :term:`replica set` requires configuring: + +- Security between members of the replica set using + :doc:`Internal Authentication`, and + +- Security between connecting clients and the replica set using + :doc:`/core/authorization`. + +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 :program:`mongo` shell need to +use a :doc:`user account`. See +:ref:`security-repSetDeploy-access-control`. + +Cloud Manager and Ops Manager +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are currently using or are planning to use Cloud Manager or +Ops Manager, consider using the built-in features for +deploying a replica set with access control enforced. + +See ``Deploy Replica Set`` in the +:mms-docs:`Cloud Manager manual` or in the +:opsmgr:`Ops Manager manual`. + +See ``Access Control for MongoDB Deployments`` in the +:mms-docs:`Cloud Manager manual` or in the +:opsmgr:`Ops manager manual`. + +Considerations +-------------- + +Operating System +~~~~~~~~~~~~~~~~ + +This tutorial primarily refers to the :program:`mongod` process. +Windows users should use the :program:`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 +:doc:`x.509 certificates`. + +.. _security-repSetDeploy-access-control: + +Access Control +~~~~~~~~~~~~~~ + +The users created in this tutorial are best suited for learning or evaluation +environments, and should *not* be used in development or production +environments. See :ref:`security-checklist-role-based-access-control` for best +practices for user creation and management. + +This tutorial covers creating the minimum number of administrative +users on the ``admin`` database *only*. See the +:doc:`/tutorial/manage-users-and-roles` tutorial for instructions on +creating additional users for administrative or client access. + +This tutorial uses the default :doc:`/core/security-scram-sha-1` +authentication mechanism. Challenge-response security mechanisms are +bare-minimum forms of security and are best suited for testing or +development environments. For production environments we recommend using +:doc:`x.509 certificates`. + +.. _security-replica-deploy-with-access-control: + +Deploy New Replica Set with Keyfile Access Control +-------------------------------------------------- + +.. include:: /includes/steps/deploy-replica-set-with-auth.rst + +x.509 Internal Authentication +----------------------------- + +For details on using x.509 for internal authentication, see +:doc:`/tutorial/configure-x509-member-authentication`. + +To upgrade from keyfile internal authentication to x.509 internal +authentication, see +:doc:`/tutorial/upgrade-keyfile-to-x509`. diff --git a/source/tutorial/deploy-sharded-cluster-with-keyfile-access-control.txt b/source/tutorial/deploy-sharded-cluster-with-keyfile-access-control.txt new file mode 100644 index 00000000000..20d77e4dc28 --- /dev/null +++ b/source/tutorial/deploy-sharded-cluster-with-keyfile-access-control.txt @@ -0,0 +1,309 @@ +================================================== +Deploy Sharded Cluster with Keyfile Access Control +================================================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 3 + :class: singlecol + +Overview +-------- + +Enforcing access control on a :term:`sharded cluster` requires configuring: + +- Security between components of the cluster using + :doc:`Internal Authentication`. + +- Security between connecting clients and the cluster using + :doc:`User Access Controls`. + +For this tutorial, each member of the sharded cluster *must* use the same +internal authentication mechanism and settings. This means enforcing internal +authentication on each :program:`mongos` and :program:`mongod` in the cluster. + +The following tutorial uses a :ref:`keyfile ` to +enable internal authentication. + +Enforcing internal authentication also enforces user access control. To +connect to the replica set, clients like the :program:`mongo` shell need to +use a :doc:`user account`. See +:ref:`security-shardClust-deploy-access-control`. + +CloudManager and OpsManager +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are currently using or are planning to use Cloud Manager or +Ops Manager, consider using their built-in features for +deploying a replica set with access control enforced. + +See ``Deploy a Sharded Cluster`` in the +:mms-docs:`Cloud Manager manual` or in the +:opsmgr:`Ops Manager manual`. + +See ``Access Control for MongoDB Deployments`` in the +:mms-docs:`Cloud Manager manual` or in the +:opsmgr:`Ops manager manual`. + +Considerations +-------------- + +Keyfile Security +~~~~~~~~~~~~~~~~ + +Keyfiles are bare-minimum forms of security and are best suited for testing or +development environments. For production environments we recommend using +:doc:`x.509 certificates`. + +.. _security-shardClust-deploy-access-control: + +Access Control +~~~~~~~~~~~~~~ + +The users created in this tutorial are best suited for learning or evaluation +environments, and should *not* be used in development or production +environments. See :ref:`security-checklist-role-based-access-control` for best +practices for user creation and management. + +This tutorial covers creating the minimum number of administrative +users on the ``admin`` database *only*. See the +:doc:`/tutorial/manage-users-and-roles` tutorial for instructions on +creating additional users for administrative or client access. + +This tutorial uses the default :doc:`/core/security-scram-sha-1` +authentication mechanism. Challenge-response security mechanisms are +bare-minimum forms of security and are best suited for testing or +development environments. For production environments we recommend using +:doc:`x.509 certificates`. + + +Users +~~~~~ + +Cluster users exist in the cluster and perform cluster-level operations. You +cannot use a cluster user to connect to an individual shard. + +Shard-local users exist in each individual shard and perform shard-level +operations. You cannot connect to the cluster or perform cluster-level +operations with shard-local users. Shard-local users are primarily for +maintenance operations within the shard. + +This tutorial requires creating cluster users, but includes optional steps for +adding shard-local users. + +See the :doc:`/core/security-users` security documentation for more +information. + +Operating System +~~~~~~~~~~~~~~~~ + +This tutorial primarily refers to the :program:`mongod` process. +Windows users should use the :program:`mongod.exe` program instead. + +.. _security-shard-deploy-sharded-cluster-with-access-control: + +Deploy Sharded Cluster with Keyfile Access Control +-------------------------------------------------- + +The following procedures involve creating a new sharded cluster that consists +of a :program:`mongos`, the config servers, and two shards. + +The exact network layout, infrastructure, or machine hardware that +may be necessary for any given deployment is out of scope of this tutorial. + +Create the Keyfile +~~~~~~~~~~~~~~~~~~ + +The contents of the keyfile serves as the shared password for the members +of the replica set. The content of the keyfile must be the same for all +:program:`mongod` instances in the replica set. + +You can generate a keyfile using any method you choose. The contents of +the keyfile must be between 6 and 1024 characters long. The keyfile must have +read permission for the file owner, and no group or world permissions. + +The following operation uses ``openssl`` to generate a complex +pseudo-random 1024 character string to use for a keyfile. It then uses +``chmod`` to apply user read permissions for the file owner only: + +.. code-block:: shell + + openssl rand -base64 755 > + chmod 400 mongodb-keyfile + +See :ref:`internal-auth-keyfile` for additional details and requirements +for using keyfiles. + +Distribute the Keyfile +~~~~~~~~~~~~~~~~~~~~~~ + +Copy the keyfile to each server hosting a replica set member. Use a +consistent location for each server. + +.. important:: + If a component of the sharded cluster cannot access the keyfile, the + cluster may fail. Do not use shared network locations or storage mediums + such as USB drives for storing the keyfile. + +Ensure the appropriate read/write permissions to the file so that the +user running the :program:`mongod` or :program:`mongos` can access it. + +.. _deploy-auth-cluster-create-config-server-replica-set: + +Create the Config Server Replica Set +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first step to deploying a sharded cluster enforcing access control is +creating the config server replica set. For testing purposes, you can +create a single-member replica set. The recommended minimum number +of replica set members for a production deployment is three_. + +.. include:: /includes/steps/deploy-sharded-cluster-config-server.rst + +Once the Config Server Replica Set is online, you can proceed to creating +the shard replica sets. + +Create Mirrored Config Servers (Deprecated) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionchanged:: 3.2 + + Starting in MongoDB 3.2, config servers for sharded clusters can be + deployed as a :term:`replica set`. MongoDB 3.2 deprecates the use of + mirrored :program:`mongod` instances for config servers. + +In production deployments, if using mirrored config servers, you must deploy +exactly *three* config server instances, each running on different servers to +assure good uptime and data safety. In test environments, you can run all three +instances on a single server. + +.. note:: + + If using MongoDB 3.2, consider using Replica Set Config Server deployments + over mirrored config servers. + +.. include:: /includes/steps/deploy-sharded-cluster-mirrored-config.rst + +Create the Shard Replica Sets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For testing purposes, you can create a single-member replica set. However, +the recommended minimum number of replica set members for a production +deployment is three_. + +These steps include optional procedures for adding shard-local users. +Executing them now ensures that there are users +available for each shard for performing shard-level maintenance. + +.. include:: /includes/steps/deploy-sharded-cluster-shard-replica.rst + + +Connect a to the Sharded Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/steps/deploy-sharded-cluster-connect.rst + +Add Shards to the Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~ + +You must be authenticated as the cluster administrator in order to +proceed. + +Add each shard to the cluster using the :method:`sh.addShard()` method. +Use :method:`sh.addShard()` seperately for each shard. If the shard is a +replica set, specify the name of the replica set and specify a member of the +set. In production deployments, *all* shards should be replica sets. + +The following operation adds a single shard replica set to the cluster: + +.. code-block:: javascript + + sh.addShard( "/s1-mongo1.example.net:27017") + +The following operation is an example of adding a standalone :program:`mongod` +shard to the cluster: + +.. code-block:: javascript + + sh.addShard( "s1-mongo1.example.net:27017") + +Repeat these steps until the cluster includes all shards. At this point the +cluster is online and is enforcing access controls for accessing the cluster +as well as for internal communications between each cluster component. + +Enable Sharding for a Database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You must be authenticated as the cluster administrator in order to +proceed. + +Enabling sharding on a database makes it possible to shard collections +within the database. It does not distribute data across the shards - +only sharding at the collection level results in data distribution. + +Sharding is disabled per database by default. + +Use the :method:`sh.enableSharding()` method to enable sharding on +the target database. + +.. code-block:: javascript + + sh.enableSharding("") + +Enable Sharding for a Collection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You must be authenticated as the cluster administrator in order to +proceed. + +To shard a collection, use the :method:`sh.shardCollection()` method. +You must specify the full namespace of the collection and a document containing +the shard key. + +Your selection of shard key affects the efficiency of sharding, as well as +your ability to take advantage of certain sharding features such as +:doc:`/core/tag-aware-sharding`. See the selection considerations listed +in the :ref:`sharding-shard-key-selection`. + +If the collection already contains data, you must create an index on the +:term:`shard key` using the :method:`db.collection.createIndex()` method before +using :method:`~sh.shardCollection()`. + +If the collection is empty, MongoDB creates the index as part of +:method:`sh.shardCollection()`. + +The following is an example of the :method:`sh.shardCollection()` method: + +.. code-block:: javascript + + sh.shardCollection(".", { : } ) + +Next Steps +---------- + +Create users to allow clients to connect to and interact with +the sharded cluster. + +See :ref:`database-user-roles` for basic built-in roles to use in creating +read-only and read-write users. + +x.509 Internal Authentication +----------------------------- + +For details on using x.509 for internal authentication, see +:doc:`/tutorial/configure-x509-member-authentication`. + +To upgrade from keyfile internal authentication to x.509 internal +authentication, see +:doc:`/tutorial/upgrade-keyfile-to-x509`. + +.. seealso:: + + :doc:`/core/sharded-cluster-architectures-production` + + :doc:`/core/sharded-cluster-requirements` + +.. _three: https://en.wikipedia.org/wiki/Rabbit_of_Caerbannog#Holy_Hand_Grenade_of_Antioch diff --git a/source/tutorial/enable-authentication.txt b/source/tutorial/enable-authentication.txt index c95b0023dc2..6d5ea782172 100644 --- a/source/tutorial/enable-authentication.txt +++ b/source/tutorial/enable-authentication.txt @@ -27,10 +27,9 @@ To enable access control, use either the command line option ``--auth`` or specify a different authentication mechanism, see :doc:`/core/authentication-mechanisms`. -You can also enable client access control by :doc:`enabling internal -authentication ` of replica -sets or sharded clusters. For instructions on enabling internal -authentication, see :doc:`/tutorial/enable-internal-authentication`. +You can also enable client access control by :doc:`enforcing internal +authentication` for replica sets or +sharded clusters. Considerations -------------- @@ -38,10 +37,10 @@ Considerations With access control enabled, ensure you have a user with :authrole:`userAdmin` or :authrole:`userAdminAnyDatabase` role in the ``admin`` database. -This tutorial assumes a :term:`standalone` environment. - -The :doc:`/tutorial/enable-internal-authentication` tutorial has steps -specific to enabling access control on replica sets and sharded clusters. +This tutorial assumes a :term:`standalone` environment. +See :doc:`/core/security-internal-authentication` for replica set +and sharded cluster security tutorials that include steps for creating +users. You can create users before enabling access control or you can create users after enabling access control. If you enable access control before diff --git a/source/tutorial/enable-internal-authentication.txt b/source/tutorial/enable-internal-authentication.txt deleted file mode 100644 index 8d12256139d..00000000000 --- a/source/tutorial/enable-internal-authentication.txt +++ /dev/null @@ -1,80 +0,0 @@ -============================== -Enable Internal Authentication -============================== - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -Overview --------- - -When authentication is enabled on a replica set or a sharded cluster, members -of the replica set or the sharded clusters must provide credentials to -authenticate. - -To enable authentication on a replica set or a sharded cluster, you must -enable authentication individually for each member. For a sharded -cluster, this means enabling authentication on each :program:`mongos` and -each :program:`mongod`, including the config servers and each member of a -shard's replica set. - -The following tutorial uses a :ref:`keyfile ` to -enable internal authentication. You can also use x.509 certificate for -internal authentication. For details on using x.509, see -:doc:`/tutorial/configure-x509-member-authentication`. - -Considerations --------------- - -Access Control -~~~~~~~~~~~~~~ - -Enabling internal authentication enables :doc:`access control -`. The following tutorial assumes *no* users have -been created in the system before enabling internal authentication, and -uses :ref:`localhost-exception` to add a user administrator after access -control has been enabled. - -If you prefer, you can create the users before enabling internal -authentication. - -Sharded Cluster -~~~~~~~~~~~~~~~ - -It is not possible to convert an existing sharded cluster that does -not enforce access control to require authentication without taking -all components of the cluster offline for a short period of time. - -For sharded clusters, the :ref:`localhost-exception` will apply to the -individual shards unless you either create an administrative user or -disable the localhost exception on each shard. - -Procedures ----------- - -Update Existing Deployment -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/steps/enable-authentication-in-sharded-cluster.rst - -.. _deploy-repl-set-with-auth: - -Deploy New Replica Set with Access Control -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/steps/deploy-replica-set-with-auth.rst - -x.509 Internal Authentication ------------------------------ - -For details on using x.509 for internal authentication, see -:doc:`/tutorial/configure-x509-member-authentication`. - -To upgrade from keyfile internal authentication to x.509 internal -authentication, see -:doc:`/tutorial/upgrade-keyfile-to-x509`. diff --git a/source/tutorial/enforce-keyfile-access-control-in-existing-replica-set.txt b/source/tutorial/enforce-keyfile-access-control-in-existing-replica-set.txt new file mode 100644 index 00000000000..d826decf152 --- /dev/null +++ b/source/tutorial/enforce-keyfile-access-control-in-existing-replica-set.txt @@ -0,0 +1,99 @@ +=============================================== +Enforce Keyfile Access Control in a Replica Set +=============================================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Overview +-------- + +Enforcing access control on a :term:`replica set` requires configuring: + +- Security between members of the replica set using + :doc:`Internal Authentication`, and + +- Security between connecting clients and the replica set using + :doc:`User Access Controls`. + +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 :program:`mongo` shell need to +use a :doc:`user account`. See +:ref:`security-replSet-auth-access-control`. + +Cloud Manager and Ops Manager +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If Cloud Manager or Ops Manager is managing your deployment, +see: ``Configure Access Control for MongoDB Deployments`` +in the :mms-docs:`Cloud Manager manual +` +or in the :opsmgr:`Ops Manager manual +` for enforcing access control. + +Considerations +-------------- + +Operating System +~~~~~~~~~~~~~~~~ + +This tutorial primarily refers to the :program:`mongod` process. +Windows users should use the :program:`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 +:doc:`x.509 certificates`. + +.. _security-replSet-auth-access-control: + +Access Control +~~~~~~~~~~~~~~ + +The users created in this tutorial are best suited for learning or evaluation +environments, and should *not* be used in development or production +environments. See :ref:`security-checklist-role-based-access-control` for best +practices for user creation and management. + +This tutorial covers creating the minimum number of administrative +users on the ``admin`` database *only*. See the +:doc:`/tutorial/manage-users-and-roles` tutorial for instructions on +creating additional users for administrative or client access. + +This tutorial uses the default :doc:`/core/security-scram-sha-1` +authentication mechanism. Challenge-response security mechanisms are +bare-minimum forms of security and are best suited for testing or +development environments. For production environments we recommend using +:doc:`x.509 certificates`. + +Downtime +~~~~~~~~ + +Enforcing access control on an existing replica set requires downtime. + +.. _security-enable-access-control-replica-set: + +Enforce Keyfile Access Control on Existing Replica Set +------------------------------------------------------ + +.. include:: /includes/steps/enable-authentication-in-replica-set.rst + +x.509 Internal Authentication +----------------------------- + +For details on using x.509 for internal authentication, see +:doc:`/tutorial/configure-x509-member-authentication`. + +To upgrade from keyfile internal authentication to x.509 internal +authentication, see +:doc:`/tutorial/upgrade-keyfile-to-x509`. diff --git a/source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster.txt b/source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster.txt new file mode 100644 index 00000000000..7ebef873d03 --- /dev/null +++ b/source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster.txt @@ -0,0 +1,130 @@ +================================================= +Enforce Keyfile Access Control in Sharded Cluster +================================================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 3 + :class: singlecol + +Overview +-------- + +Enforcing access control on a :term:`sharded cluster` requires configuring: + +- Security between components of the cluster using + :doc:`Internal Authentication`. + +- Security between connecting clients and the cluster using + :doc:`/core/authorization`. + +For this tutorial, each member of the sharded cluster *must* use the same +internal authentication mechanism and settings. This means enforcing internal +authentication on each :program:`mongos` and :program:`mongod` in the cluster. + +The following tutorial uses a :ref:`keyfile ` to +enable internal authentication. + +Enforcing internal authentication also enforces user access control. To +connect to the replica set, clients like the :program:`mongo` shell need to +use a :doc:`user account`. See +:ref:`security-shardClust-enforce-access-control`. + +CloudManager and OpsManager +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If Cloud Manager or Ops Manager is managing your deployment, internal +authentication is automatically enforced. + +To configure Access Control on a +managed deployment, see: ``Configure Access Control for MongoDB Deployments`` +in the :mms-docs:`Cloud Manager manual +` +or in the :opsmgr:`Ops Manager manual +`. + +Considerations +-------------- + +Operating System +~~~~~~~~~~~~~~~~ + +This tutorial primarily refers to the :program:`mongod` process. +Windows users should use the :program:`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 +:doc:`x.509 certificates`. + +.. _security-shardClust-enforce-access-control: + +Access Control +~~~~~~~~~~~~~~ + +The users created in this tutorial are best suited for learning or evaluation +environments, and should *not* be used in development or production +environments. See :ref:`security-checklist-role-based-access-control` for best +practices for user creation and management. + +This tutorial covers creating the minimum number of administrative +users on the ``admin`` database *only*. See the +:doc:`/tutorial/manage-users-and-roles` tutorial for instructions on +creating additional users for administrative or client access. + +This tutorial uses the default :doc:`/core/security-scram-sha-1` +authentication mechanism. Challenge-response security mechanisms are +bare-minimum forms of security and are best suited for testing or +development environments. For production environments we recommend using +:doc:`x.509 certificates`. + +Users +~~~~~ + +Cluster users exist in the cluster and perform cluster-level operations. You +cannot use a cluster user to connect to an individual shard. + +Shard-local users exist in each individual shard and perform shard-level +operations. You cannot connect to the cluster or perform cluster-level +operations with shard-local users. Shard-local users are primarily for +maintenance operations within the shard. + +See the :doc:`/core/security-users` security documentation for more +information. + +Downtime +~~~~~~~~ + +Upgrading a sharded cluster to enforce access control requires downtime. + +Procedures +---------- + +.. _security-update-existing-sharded-deployment-with-auth: + +Enforce Keyfile Internal Authentication on Existing Sharded Cluster Deployment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/steps/enable-authentication-in-sharded-cluster.rst + + +x.509 Internal Authentication +----------------------------- + +For details on using x.509 for internal authentication, see +:doc:`/tutorial/configure-x509-member-authentication`. + +To upgrade from keyfile internal authentication to x.509 internal +authentication, see +:doc:`/tutorial/upgrade-keyfile-to-x509`. + +.. seealso:: + + :doc:`/core/sharded-cluster-architectures-production` + + :doc:`/core/sharded-cluster-requirements`