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,
+you must possess the appropriate user roles.
+
+To restore a single database, you 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
 -------

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 </contributors/tutorial/build-tools-from-source>`.

source/reference/program/mongostat.txt

@@ -32,8 +32,8 @@ UNIX/Linux file system utility ``vmstat``, but provides data regarding
    For an additional utility that provides MongoDB metrics see
    :doc:`mongotop </reference/program/mongotop>`.
 
-Access Control Requirements
----------------------------
+Required Access
+---------------
 
 In order to connect to a :program:`mongod` that enforces authorization
 with the :option:`--auth <mongod --auth>` option, specify the

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 <mongod --auth>` option, the
-   :option:`--username <mongotop --username>` and
-   :option:`--password <mongotop --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 </reference/program/mongostat>`.
 
+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 <mongotop --username>` and :option:`--password
+<mongotop --password>` options, 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`.
+
 .. _mongotop-options:
 
 Options

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

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