diff --git a/source/includes/access-mongodump-collections.rst b/source/includes/access-mongodump-collections.rst index fe58514c4dd..e106a125a3a 100644 --- a/source/includes/access-mongodump-collections.rst +++ b/source/includes/access-mongodump-collections.rst @@ -1,9 +1,9 @@ -To backup all the databases in a cluster via :program:`mongodump`, you +To back up all the databases in a cluster via :program:`mongodump`, you should have the :authrole:`backup` role. The :authrole:`backup` role provides the required privileges for backing up all databases. The role confers no additional access, in keeping with the policy of :term:`least privilege`. -To backup a given database, you must have ``read`` access on the database. +To back up a given database, you must have ``read`` access on the database. Several roles provide this access, including the :authrole:`backup` role. .. include:: /includes/fact-required-access-for-backup-profiling.rst diff --git a/source/includes/access-mongodump-users.rst b/source/includes/access-mongodump-users.rst index 6c370eae502..d88fe259e3c 100644 --- a/source/includes/access-mongodump-users.rst +++ b/source/includes/access-mongodump-users.rst @@ -1,16 +1,16 @@ .. versionchanged:: 2.6 -To backup users and :ref:`user-defined roles ` for a +To back up users and :ref:`user-defined roles ` for a given database, you must have access to the ``admin`` database. MongoDB stores the user data and role definitions for all databases in the ``admin`` database. -Specifically, to backup a given database's users, you must have the +Specifically, to back up a given database's users, you must have the :authaction:`find` :ref:`action ` on the ``admin`` database's :data:`admin.system.users` collection. The :authrole:`backup` and :authrole:`userAdminAnyDatabase` roles both provide this privilege. -To backup the user-defined roles on a database, you must have the +To back up the user-defined roles on a database, you must have the :authaction:`find` action on the ``admin`` database's :data:`admin.system.roles` collection. Both the :authrole:`backup` and :authrole:`userAdminAnyDatabase` roles provide this privilege. diff --git a/source/includes/access-mongorestore-collections.rst b/source/includes/access-mongorestore-collections.rst new file mode 100644 index 00000000000..b2b96bc3bd3 --- /dev/null +++ b/source/includes/access-mongorestore-collections.rst @@ -0,0 +1,7 @@ +To restore collection data to a database with authentication enabled, +the connecting user must possess the appropriate user roles. + +To restore a single database, the connecting user must possess the :authrole:`readWrite` +role for that database. Alternatively, the +:authrole:`readWriteAnyDatabase` provides access to restore any database. +The :authrole:`restore` role also provides the requisite permissions. diff --git a/source/includes/access-mongorestore.rst b/source/includes/access-mongorestore-users.rst similarity index 69% rename from source/includes/access-mongorestore.rst rename to source/includes/access-mongorestore-users.rst index c639d82abaf..8daee402891 100644 --- a/source/includes/access-mongorestore.rst +++ b/source/includes/access-mongorestore-users.rst @@ -14,3 +14,9 @@ To restore user-defined roles to a database, you must have the :authaction:`insert` action on the ``admin`` database's :data:`admin.system.roles` collection. The :authrole:`restore` role provides this privilege. + +If your database is running with authentication enabled, you must +possess the :authrole:`userAdmin` role on the database you are +restoring, or the :authrole:`userAdminAnyDatabase` role, which allows +you to restore user data to any database. The :authrole:`restore` role +also provides the requisite privileges. diff --git a/source/includes/fact-required-access-for-backup-profiling.rst b/source/includes/fact-required-access-for-backup-profiling.rst index ef9542eaa6c..eece41d34f9 100644 --- a/source/includes/fact-required-access-for-backup-profiling.rst +++ b/source/includes/fact-required-access-for-backup-profiling.rst @@ -1,4 +1,4 @@ -To backup the :data:`system.profile <.system.profile>` +To back up the :data:`system.profile <.system.profile>` collection, which is created when you activate :ref:`database profiling `, you must have **additional** ``read`` access on this collection. Several diff --git a/source/reference/program/mongodump.txt b/source/reference/program/mongodump.txt index bbf5b06b857..7dc931b1162 100644 --- a/source/reference/program/mongodump.txt +++ b/source/reference/program/mongodump.txt @@ -44,13 +44,13 @@ from :term:`secondary` members of the set. Required Access --------------- -Backup Collections -~~~~~~~~~~~~~~~~~~ +Back Up Collections +~~~~~~~~~~~~~~~~~~~ .. include:: /includes/access-mongodump-collections.rst -Backup Users -~~~~~~~~~~~~ +Back Up Users +~~~~~~~~~~~~~ .. include:: /includes/access-mongodump-users.rst diff --git a/source/reference/program/mongoexport.txt b/source/reference/program/mongoexport.txt index 85d7092316f..59c1dabdf4d 100644 --- a/source/reference/program/mongoexport.txt +++ b/source/reference/program/mongoexport.txt @@ -26,6 +26,15 @@ data type information. Use :program:`mongodump` and :program:`mongorestore` as described in :doc:`/core/backups` for this kind of functionality. +Required Access +--------------- + +In order to connect to a :program:`mongod` that enforces authorization +with the :option:`--auth ` option, you must use the +:option:`--username ` and :option:`--password +` options. The connecting user must possess at a +minimum, the :authrole:`read` role on the database that they are exporting. + Options ------- @@ -192,7 +201,7 @@ shell uses the :doc:`mongoShell mode representation .. code-block:: javascript use test - db.traffic.insert( { _id: 1, volume: NumberLong(2980000), date: new Date() } ) + db.traffic.insert( { _id: 1, volume: NumberLong("2980000"), date: new Date() } ) Use :program:`mongoexport` to export the data: diff --git a/source/reference/program/mongofiles.txt b/source/reference/program/mongofiles.txt index 6734ec8bbbe..4c3539e1db5 100644 --- a/source/reference/program/mongofiles.txt +++ b/source/reference/program/mongofiles.txt @@ -42,7 +42,22 @@ stored in a MongoDB data directory without requiring a running .. important:: For :term:`replica sets `, :program:`mongofiles` can only read from the set's - ':term:`primary`. + :term:`primary`. + +Required Access +--------------- + +In order to connect to a :program:`mongod` that enforces authorization +with the :option:`--auth ` option, you must use the +:option:`--username ` and :option:`--password +` options. The connecting user must possess, at a +minimum: + +- the :authrole:`read` role for the accessed database when using the + ``list``, ``search`` or ``get`` commands, + +- the :authrole:`readWrite` role for the accessed database when using + the ``put`` or ``delete`` commands. .. _mongofiles-options: @@ -109,7 +124,6 @@ Options .. include:: /includes/option/option-mongofiles-writeConcern.rst - .. _mongofiles-commands: Commands diff --git a/source/reference/program/mongoimport.txt b/source/reference/program/mongoimport.txt index 581d662f892..d1038426d10 100644 --- a/source/reference/program/mongoimport.txt +++ b/source/reference/program/mongoimport.txt @@ -31,6 +31,16 @@ functionality. a time into MongoDB. Custom import tools for data ingestion may have better performance for specific workloads. +Required Access +--------------- + +In order to connect to a :program:`mongod` that enforces authorization +with the :option:`--auth ` option, you must use the +:option:`--username ` and :option:`--password +` options. The connecting user must +possess, at a minimum, the :authrole:`readWrite` role on the database +into which they are importing data. + Options ------- diff --git a/source/reference/program/mongorestore.txt b/source/reference/program/mongorestore.txt index b64e51ceecc..7c8c9b9e8fb 100644 --- a/source/reference/program/mongorestore.txt +++ b/source/reference/program/mongorestore.txt @@ -48,10 +48,18 @@ Remember the following properties of :program:`mongorestore` behavior: .. versionadded:: 3.0.0 :program:`mongorestore` also accepts input via standard input. -Required Access to Restore User Data ------------------------------------- +Required Access +--------------- -.. include:: /includes/access-mongorestore.rst +Restore Collection Data +~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/access-mongorestore-collections.rst + +Restore Users and User Data +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/access-mongorestore-users.rst Options ------- diff --git a/source/reference/program/mongosniff.txt b/source/reference/program/mongosniff.txt index f56dc4a339b..bec13a4528b 100644 --- a/source/reference/program/mongosniff.txt +++ b/source/reference/program/mongosniff.txt @@ -12,7 +12,7 @@ Synopsis :program:`mongosniff` provides a low-level operation tracing/sniffing view into database activity in real time. Think of :program:`mongosniff` as a MongoDB-specific analogue of ``tcpdump`` for TCP/IP network -traffic. Typically, :program:`mongosniff` is most frequently used in driver +traffic. :program:`mongosniff` is most frequently used in driver development. .. _mongosniff-libcap: @@ -64,34 +64,6 @@ interface and port 27018, for driver development and troubleshooting: mongosniff --objcheck --source NET lo 27018 -Build ``mongosniff`` --------------------- - -To build ``mongosniff`` yourself, Linux users can use the following -procedure: - -1. Obtain prerequisites using your operating - systems package management software. Dependencies include: - - - ``libpcap`` - to capture network packets. - - ``git`` - to download the MongoDB source code. - - ``scons`` and a C++ compiler - to build :program:`mongosniff`. - -2. Download a copy of the MongoDB source code using ``git``: - - .. code-block:: sh - - git clone git://github.com/mongodb/mongo.git - -3. Issue the following sequence of commands to change to the - ``mongo/`` directory and build :program:`mongosniff`: - - .. code-block:: sh - - cd mongo - scons mongosniff - -.. note:: - - If you run ``scons mongosniff`` before installing ``libpcap`` you - must run ``scons clean`` before you can build :program:`mongosniff`. +.. seealso:: + To build :program:`mongosniff` yourself, see: :about:`Build MongoDB + Tools From Source `. \ No newline at end of file diff --git a/source/reference/program/mongostat.txt b/source/reference/program/mongostat.txt index 3fbb20bbaa5..afe4263a4d1 100644 --- a/source/reference/program/mongostat.txt +++ b/source/reference/program/mongostat.txt @@ -32,13 +32,13 @@ UNIX/Linux file system utility ``vmstat``, but provides data regarding For an additional utility that provides MongoDB metrics see :doc:`mongotop `. -Access Control Requirements ---------------------------- +Required Access +--------------- In order to connect to a :program:`mongod` that enforces authorization with the :option:`--auth ` option, specify the :option:`--username ` and :option:`--password -` options, and the user specified must have the +` options, and the connecting user must have the :authaction:`serverStatus` privilege action on the cluster resources. The built-in role :authrole:`clusterMonitor` provides this privilege as diff --git a/source/reference/program/mongotop.txt b/source/reference/program/mongotop.txt index 9b7fafad7d6..968b5ee200d 100644 --- a/source/reference/program/mongotop.txt +++ b/source/reference/program/mongotop.txt @@ -16,16 +16,6 @@ MongoDB instance spends reading and writing data. :program:`mongotop` provides statistics on a per-collection level. By default, :program:`mongotop` returns values every second. -.. important:: In order to connect to a :program:`mongod` that enforces - authorization with the :option:`--auth ` option, the - :option:`--username ` and - :option:`--password ` options must be used, and the - user specified must have the :authaction:`serverStatus` and - :authaction:`top` privileges. - - The most appropriate built-in role that has these privileges is - :authrole:`clusterMonitor`. - .. seealso:: For more information about monitoring MongoDB, see @@ -42,6 +32,18 @@ provides statistics on a per-collection level. By default, For an additional utility that provides MongoDB metrics see :doc:`mongostat `. +Required Access +--------------- + +In order to connect to a :program:`mongod` that enforces authorization +with the :option:`--auth ` option, you must use the +:option:`--username ` and :option:`--password +` options, and the connecting user must +have the :authaction:`serverStatus` and :authaction:`top` privileges. + +The most appropriate built-in role that has these privileges is +:authrole:`clusterMonitor`. + .. _mongotop-options: Options diff --git a/source/release-notes/3.0-compatibility.txt b/source/release-notes/3.0-compatibility.txt index b3ec6cfc959..90743c6d43a 100644 --- a/source/release-notes/3.0-compatibility.txt +++ b/source/release-notes/3.0-compatibility.txt @@ -249,8 +249,8 @@ instance(s) before using these tools. Removed Options ~~~~~~~~~~~~~~~ -- Removed ``--dbpath`` and ``--filter`` options for - :program:`mongorestore`, :program:`mongoimport`, +- Removed ``--dbpath``, ``--journal``, and ``--filter`` options for + :program:`mongodump`, :program:`mongorestore`, :program:`mongoimport`, :program:`mongoexport`, and :program:`bsondump`. - Removed ``--locks`` option for :program:`mongotop`. diff --git a/source/tutorial/backup-with-mongodump.txt b/source/tutorial/backup-with-mongodump.txt index c8fd1d5d51b..abac6d069b2 100644 --- a/source/tutorial/backup-with-mongodump.txt +++ b/source/tutorial/backup-with-mongodump.txt @@ -122,7 +122,9 @@ and password credentials to specify database authentication. Restore a Database with ``mongorestore`` ---------------------------------------- -.. include:: /includes/access-mongorestore.rst +.. include:: /includes/access-mongorestore-collections.rst + +.. include:: /includes/access-mongorestore-users.rst Basic ``mongorestore`` Operations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~