DOCS-1960: updates mongoexport, mongoimport, mongofiles with auth reqs

- updates mongoexport, mongoimport, mongorestore, mongodump,
  and mongofiles to include the
  permissions required to run them against a mongodb database
  with auth enabled
- pulls out-of-date 'building the tools' section from mongosniff
- adds item to compatibility notes about deprecation of --journal
  for tools
- updates backup with mongodump tutorial to not use deprecated option

Author: schmalliso

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

source/includes/access-mongodump-users.rst

@@ -1,16 +1,16 @@
 .. versionchanged:: 2.6
 
-To backup users and :ref:`user-defined roles <user-defined-roles>` for a
+To back up users and :ref:`user-defined roles <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 <security-user-actions>` 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.

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.

source/includes/access-mongorestore.rst renamed to 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.

source/includes/fact-required-access-for-backup-profiling.rst

@@ -1,4 +1,4 @@
-To backup the :data:`system.profile <<database>.system.profile>`
+To back up the :data:`system.profile <<database>.system.profile>`
 collection, which is created when you activate :ref:`database profiling
 <database-profiling>`, you must have **additional**
 ``read`` access on this collection. Several

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
 

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 <mongod --auth>` option, you must use the
+:option:`--username <mongoexport --username>` and :option:`--password
+<mongoexport --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:
 

source/reference/program/mongofiles.txt

@@ -42,7 +42,22 @@ stored in a MongoDB data directory without requiring a running
 
 .. important:: For :term:`replica sets <replica set>`,
    :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 <mongod --auth>` option, you must use the
+:option:`--username <mongofiles --username>` and :option:`--password
+<mongofiles --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

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 <mongod --auth>` option, you must use the
+:option:`--username <mongoexport --username>` and :option:`--password
+<mongoexport --password>` options. The connecting user must
+possess, at a minimum, the :authrole:`readWrite` role on the database
+into which they are importing data.
+
 Options
 -------
 

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
 -------