diff --git a/snooty.toml b/snooty.toml index 4dadd543..b7646c4e 100644 --- a/snooty.toml +++ b/snooty.toml @@ -9,6 +9,7 @@ toc_landing_pages = [ "/bsondump", "/mongodump", "/mongoexport", + "/mongofiles", "/mongoimport", "/mongorestore", "/mongostat", diff --git a/source/bsondump.txt b/source/bsondump.txt index 516a8e06..ecf5bce5 100644 --- a/source/bsondump.txt +++ b/source/bsondump.txt @@ -1,8 +1,8 @@ .. _bsondump: -======== -bsondump -======== +============ +``bsondump`` +============ .. default-domain:: mongodb diff --git a/source/includes/extracts-run-from-cmd.yaml b/source/includes/extracts-run-from-cmd.yaml index c4352c2b..fbbf8135 100644 --- a/source/includes/extracts-run-from-cmd.yaml +++ b/source/includes/extracts-run-from-cmd.yaml @@ -10,6 +10,7 @@ replacement: command: :binary:`~bin.mongodump` --- ref: require-cmd-line-bsondump + inherit: file: extracts-run-from-cmd.yaml ref: _require-cmd-line @@ -22,11 +23,4 @@ inherit: ref: _require-cmd-line replacement: command: :binary:`~bin.mongoexport` ---- -ref: require-cmd-line-mongofiles -inherit: - file: extracts-run-from-cmd.yaml - ref: _require-cmd-line -replacement: - command: :binary:`~bin.mongofiles` ... \ No newline at end of file diff --git a/source/mongodump.txt b/source/mongodump.txt index 2c04d097..4f3c146a 100644 --- a/source/mongodump.txt +++ b/source/mongodump.txt @@ -1,8 +1,8 @@ .. _mongodump: -========= -mongodump -========= +============= +``mongodump`` +============= .. default-domain:: mongodb @@ -723,7 +723,7 @@ Learn More For more information about ``mongodump``, see: - :ref:`mongodump-compatibility-and-installation` -- :ref:`mongodump-behavior` +- :ref:`mongodump Behavior ` - :ref:`mongodump-examples` .. include:: /includes/extracts/ssl-facts-see-more.rst diff --git a/source/mongodump/mongodump-compatibility-and-installation.txt b/source/mongodump/mongodump-compatibility-and-installation.txt index 864766f4..94cfd1fa 100644 --- a/source/mongodump/mongodump-compatibility-and-installation.txt +++ b/source/mongodump/mongodump-compatibility-and-installation.txt @@ -61,5 +61,5 @@ Learn More ---------- - :ref:`mongodump` -- :ref:`mongodump-behavior` +- :ref:`mongodump Behavior ` - :ref:`mongodump-examples` diff --git a/source/mongodump/mongodump-examples.txt b/source/mongodump/mongodump-examples.txt index 287f680f..bf5d1b14 100644 --- a/source/mongodump/mongodump-examples.txt +++ b/source/mongodump/mongodump-examples.txt @@ -250,4 +250,4 @@ Learn More - :ref:`mongodump` - :ref:`mongodump-compatibility-and-installation` -- :ref:`mongodump-behavior` +- :ref:`mongodump Behavior ` diff --git a/source/mongoexport.txt b/source/mongoexport.txt index bd640938..d79944f4 100644 --- a/source/mongoexport.txt +++ b/source/mongoexport.txt @@ -753,7 +753,7 @@ Learn More ---------- - :ref:`mongoexport-compatibility-and-installation` -- :ref:`mongoexport Behavior ` +- :ref:`mongoexport Behavior ` - :ref:`mongoexport-examples` .. toctree:: diff --git a/source/mongoexport/mongoexport-behavior.txt b/source/mongoexport/mongoexport-behavior.txt index cae65cc6..d18de39b 100644 --- a/source/mongoexport/mongoexport-behavior.txt +++ b/source/mongoexport/mongoexport-behavior.txt @@ -1,4 +1,4 @@ -.. _mongoexport-behavior-access-usage: +.. _mongoexport-behavior: ============================================ mongoexport Behavior, Access, and Usage diff --git a/source/mongoexport/mongoexport-compatibility-and-installation.txt b/source/mongoexport/mongoexport-compatibility-and-installation.txt index 6888aef1..d1fb8359 100644 --- a/source/mongoexport/mongoexport-compatibility-and-installation.txt +++ b/source/mongoexport/mongoexport-compatibility-and-installation.txt @@ -57,5 +57,5 @@ Learn More ---------- - :ref:`mongoexport` -- :ref:`mongoexport Behavior ` +- :ref:`mongoexport Behavior ` - :ref:`mongoexport-examples` \ No newline at end of file diff --git a/source/mongoexport/mongoexport-examples.txt b/source/mongoexport/mongoexport-examples.txt index 722d7bc9..72eea872 100644 --- a/source/mongoexport/mongoexport-examples.txt +++ b/source/mongoexport/mongoexport-examples.txt @@ -278,4 +278,4 @@ Learn More - :ref:`mongoexport` - :ref:`mongoexport-compatibility-and-installation` -- :ref:`mongoexport Behavior ` \ No newline at end of file +- :ref:`mongoexport Behavior ` \ No newline at end of file diff --git a/source/mongofiles.txt b/source/mongofiles.txt index f5e35ad3..fa1284db 100644 --- a/source/mongofiles.txt +++ b/source/mongofiles.txt @@ -1,90 +1,62 @@ +.. _mongofiles: + +=============== +``mongofiles`` +=============== + .. default-domain:: mongodb .. binary:: mongofiles .. program:: mongofiles -.. _mongofiles: - -============== -``mongofiles`` -============== - .. contents:: On this page :local: :backlinks: none :depth: 1 :class: singlecol +.. facet:: + :name: genre + :values: reference + .. |arrow| unicode:: U+27A4 -.. |tool-binary| replace:: :binary:`~bin.mongofiles` -.. |mongodb-aws-example| replace:: :ref:`mongofiles-example-connect-using-aws-iam` +.. |tool-binary| replace:: ``mongofiles`` + +.. |mongodb-aws-example| replace:: :ref:`mongofiles-example-connect-using-aws-iam` + +This documentation is for version ``{+release+}`` of |tool-binary|. Synopsis -------- -The :binary:`~bin.mongofiles` utility makes it possible to manipulate files +``mongofiles`` makes it possible to manipulate files stored in your MongoDB instance in :term:`GridFS` objects from the command line. It is particularly useful as it provides an interface between objects stored in your file system and GridFS. -.. include:: /includes/extracts/require-cmd-line-mongofiles.rst - -Versioning -~~~~~~~~~~ - -.. include:: /includes/extracts/dbtools-version-single.rst - -.. note:: Quick links to older documentation - - - :v4.2:`MongoDB 4.2 mongofiles ` - - :v4.0:`MongoDB 4.0 mongofiles ` - -This documentation is for version ``{+release+}`` of |tool-binary|. - -Compatibility -------------- - -MongoDB Server Compatibility -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/extracts/dbtools-compatibility-single.rst - -Platform Support -~~~~~~~~~~~~~~~~ - -|tool-binary| version ``{+release+}`` is supported on the following -platforms: - -.. include:: /includes/fact-platform-support.rst - -Installation ------------- - -.. include:: /includes/fact-see-install-guide.rst Syntax ------ -The :binary:`~bin.mongofiles` command has the following form: +``mongofiles`` syntax: .. code-block:: sh mongofiles -.. include:: /includes/extracts/require-cmd-line-mongofiles.rst -The components of the :binary:`~bin.mongofiles` command are: +The components of the ``mongofiles`` command are: 1. :ref:`Options `. You may use one or more of - these options to control the behavior of :binary:`~bin.mongofiles`. + these options to control the behavior of ``mongofiles``. 2. :option:`Connection String `. The connection string of the :binary:`~bin.mongod` / :binary:`~bin.mongos` to connect to - with :binary:`~bin.mongofiles`. + with ``mongofiles``. 3. :ref:`Command `. Use one of these commands to - determine the action of :binary:`~bin.mongofiles`. + determine the action of ``mongofiles``. 4. An identifier which is either: the name of a file on your local file system, or a GridFS object. @@ -92,57 +64,9 @@ The components of the :binary:`~bin.mongofiles` command are: .. important:: For :term:`replica sets `, - :binary:`~bin.mongofiles` can only read from the set's + ``mongofiles`` can only read from the set's :term:`primary`. -Required Access ---------------- - -In order to connect to a :binary:`~bin.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. - -Behavior --------- - -FIPS -~~~~ - -:binary:`~bin.mongofiles` automatically creates FIPS-compliant -connections to a :binary:`~bin.mongod`/:binary:`~bin.mongos` that is -:manual:`configured to use FIPS mode `. - -Read Preference -~~~~~~~~~~~~~~~ - -By default, :binary:`~bin.mongofiles` uses read preference -:readmode:`primary`. To override the default, you can specify the -:ref:`read preference ` in the -:option:`--readPreference ` command line -option or in the :option:`--uri connection string `. - -If you specify read preference in the URI -string and the :option:`--readPreference `, -the :option:`--readPreference ` value -overrides the read preference specified in the URI string. - -Write Concern -~~~~~~~~~~~~~ - -You can specify both the -:option:`--writeConcern ` and the -:option:`--uri connection string ` option. If write -concern is specified using both options, the -:option:`--writeConcern ` value overrides -the write concern specified in the URI string. .. _mongofiles-options: @@ -151,7 +75,7 @@ Options .. option:: --help - Returns information on the options and use of :program:`mongofiles`. + Returns information on the options and use of ``mongofiles``. .. option:: --verbose, -v @@ -164,7 +88,7 @@ Options .. option:: --quiet - Runs :program:`mongofiles` in a quiet mode that attempts to limit the amount + Runs ``mongofiles`` in a quiet mode that attempts to limit the amount of output. This option suppresses: @@ -180,7 +104,7 @@ Options .. option:: --version - Returns the :program:`mongofiles` release number. + Returns the ``mongofiles`` release number. .. option:: --config= @@ -217,7 +141,7 @@ Options .. option:: --host=<:port> Specifies a resolvable hostname for the :binary:`~bin.mongod` that holds - your GridFS system. By default :binary:`~bin.mongofiles` attempts to connect + your GridFS system. By default ``mongofiles`` attempts to connect to a MongoDB process running on the localhost port number ``27017``. Optionally, specify a port number to connect a MongoDB instance running @@ -281,11 +205,11 @@ Options Specifies the password to de-crypt the certificate-key file (i.e. :option:`--sslPEMKeyFile`). Use the :option:`--sslPEMKeyPassword` option only if the - certificate-key file is encrypted. In all cases, the :program:`mongofiles` will + certificate-key file is encrypted. In all cases, the ``mongofiles`` will redact the password from all logging and reporting output. If the private key in the PEM file is encrypted and you do not specify - the :option:`--sslPEMKeyPassword` option, the :program:`mongofiles` will prompt for a passphrase. See + the :option:`--sslPEMKeyPassword` option, the ``mongofiles`` will prompt for a passphrase. See :ref:`ssl-certificate-password`. .. include:: /includes/extracts/uri-used-with-sslpemkeypassword.rst @@ -323,7 +247,7 @@ Options .. option:: --sslAllowInvalidHostnames Disables the validation of the hostnames in TLS/SSL certificates. Allows - :program:`mongofiles` to connect to MongoDB instances even if the hostname in their + ``mongofiles`` to connect to MongoDB instances even if the hostname in their certificates do not match the specified hostname. .. include:: /includes/extracts/uri-used-with-sslallowinvalidhostnames.rst @@ -378,12 +302,12 @@ Options *Default*: SCRAM-SHA-1 - Specifies the authentication mechanism the :program:`mongofiles` instance uses to + Specifies the authentication mechanism the ``mongofiles`` instance uses to authenticate to the :binary:`~bin.mongod` or :binary:`~bin.mongos`. .. versionchanged:: 100.1.0 - Starting in version ``100.1.0``, :program:`mongofiles` adds support + Starting in version ``100.1.0``, ``mongofiles`` adds support for the ``MONGODB-AWS`` authentication mechanism when connecting to a :atlas:`MongoDB Atlas ` cluster. @@ -414,7 +338,7 @@ Options .. option:: --db=, -d= - Specifies the name of the database on which to run the :program:`mongofiles`. + Specifies the name of the database on which to run the ``mongofiles``. .. include:: /includes/extracts/uri-used-with-db.rst @@ -426,7 +350,7 @@ Options In the :command:`mongofiles put` and :command:`mongofiles get` commands, the required ```` modifier refers to the name the object will - have in GridFS. :binary:`~bin.mongofiles` assumes that this reflects the + have in GridFS. ``mongofiles`` assumes that this reflects the file's name on the local file system. This setting overrides this default. @@ -435,7 +359,7 @@ Options .. option:: --type= Provides the ability to specify a :term:`MIME` type to describe the file - inserted into GridFS storage. :binary:`~bin.mongofiles` omits this option in + inserted into GridFS storage. ``mongofiles`` omits this option in the default operation. Use only with :command:`mongofiles put` operations. @@ -465,7 +389,7 @@ Options *Default*: majority - Specifies the :term:`write concern` for each write operation that :program:`mongofiles` + Specifies the :term:`write concern` for each write operation that ``mongofiles`` performs. Specify the write concern as a document with :ref:`w options `: @@ -486,7 +410,7 @@ Options *Default*: :readmode:`primary` Specifies the :ref:`read preference` for - :program:`mongofiles`. The :option:`--readPreference` option can take: + ``mongofiles``. The :option:`--readPreference` option can take: - A string if specifying only the read preference mode: @@ -506,7 +430,7 @@ Options If specifying the :ref:`maxStalenessSeconds `, the value must be greater than or equal to 90. - :program:`mongofiles` defaults to :readmode:`primary` + ``mongofiles`` defaults to :readmode:`primary` :ref:`read preference `. If the read preference is also included in the @@ -514,6 +438,7 @@ Options :option:`--readPreference` overrides the read preference specified in the URI string. + .. _mongofiles-commands: Commands @@ -537,7 +462,7 @@ Commands list. Each specified filename refers to the name the object will have in - GridFS, and :binary:`~bin.mongofiles` assumes that this reflects the + GridFS, and ``mongofiles`` assumes that this reflects the name the file has on the local file system. If the local filename is different, use the :option:`mongofiles --local` option. @@ -547,7 +472,7 @@ Commands file system. Each specified filename refers to the name the object has in - GridFS, and :binary:`~bin.mongofiles` will use this filename when + GridFS, and ``mongofiles`` will use this filename when writing to the local file system. If specifying *only one* ``filename`` to the ``get`` command, you can @@ -568,7 +493,7 @@ Commands the object in GridFS. ``get_id`` can accept either ObjectId values or non-ObjectId values for ``<_id>``. - :binary:`~bin.mongofiles` writes the file to the local + ``mongofiles`` writes the file to the local file system using the file's filename in GridFS. To choose a different location for the file on the local file system, use the :option:`--local ` option. @@ -587,7 +512,7 @@ Commands case-insensitivity. Multiple options should be provided together without separators, e.g. ``--regexOptions si`` - :binary:`~bin.mongofiles` writes the file or files to the local + ``mongofiles`` writes the file or files to the local file system using each file's matched filename in GridFS. You **cannot** use the :option:`--local ` option with the ``get_regex`` command. @@ -602,177 +527,18 @@ Commands ``delete_id`` can accept either ObjectId values or non-ObjectId values for ``<_id>``. -Examples --------- - -.. include:: /includes/extracts/require-cmd-line-mongofiles.rst - -To return a list of all files in a :term:`GridFS` collection in the -``records`` database, use the following invocation at the system shell: - -.. code-block:: sh - - mongofiles -d=records list - -This :binary:`~bin.mongofiles` instance will connect to the -:binary:`~bin.mongod` instance running on the ``27017`` localhost -interface to specify the same operation on a different port or -hostname, and issue a command that resembles one of the following: - -.. code-block:: sh - - mongofiles --port=37017 -d=records list - mongofiles --host=db1.example.net -d=records list - mongofiles --host=db1.example.net --port=37017 -d=records list - -Modify any of the following commands as needed if you're connecting -the :binary:`~bin.mongod` instances on different ports or hosts. - -To upload a file named ``32-corinth.lp`` to the GridFS collection in -the ``records`` database, you can use the following command: - -.. code-block:: sh - - mongofiles -d=records put 32-corinth.lp - -To delete the ``32-corinth.lp`` file from this GridFS collection in -the ``records`` database, you can use the following command: - -.. code-block:: sh - - mongofiles -d=records delete 32-corinth.lp - -To search for files in the GridFS collection in the ``records`` -database that have the string ``corinth`` in their names, you can use -following command: - -.. code-block:: sh - - mongofiles -d=records search corinth - -To list all files in the GridFS collection in the ``records`` database -with names that begin with the string ``32``, you can use the following -command: - -.. code-block:: sh - - mongofiles -d=records list 32 - -To fetch the file from the GridFS collection in the ``records`` -database named ``32-corinth.lp``, you can use the following command: - -.. code-block:: sh - - mongofiles -d=records get 32-corinth.lp - -To fetch all files from the GridFS collection in the ``records`` -database with names beginning with the string ``32`` and ending with the -string ``.lp``, you can use the following command: - -.. code-block:: sh - - mongofiles -d=records get_regex 32*.lp - -To fetch the file from the GridFS collection in the ``records`` database -with ``_id: ObjectId("56feac751f417d0357e7140f")``, you can use the -following command: - -.. code-block:: sh - - mongofiles -d=records get_id '{"$oid": "56feac751f417d0357e7140f"}' - -You must include quotation marks around the ``_id``. - -.. _mongofiles-example-connect-using-aws-iam: - -Connect to a MongoDB Atlas Cluster using AWS IAM Credentials -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 100.1.0 - -To connect to a :atlas:`MongoDB Atlas ` cluster which -has been configured to support authentication via `AWS IAM credentials -`__, -provide a :option:`connection string ` to -|tool-binary| similar to the following: - -.. code-block:: none - - mongofiles 'mongodb+srv://:@cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS' - -Connecting to Atlas using AWS IAM credentials in this manner uses the -``MONGODB-AWS`` :urioption:`authentication mechanism ` -and the ``$external`` :urioption:`authSource`, as shown in this example. - -If using an `AWS session token -`__, -as well, provide it with the ``AWS_SESSION_TOKEN`` -:urioption:`authMechanismProperties` value, as follows: - -.. code-block:: none - - mongofiles 'mongodb+srv://:@cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:' - -.. include:: /includes/fact-pct-encode-uri.rst - -Alternatively, the AWS access key ID, secret access key, and optionally -session token can each be provided outside of the connection string -using the :option:`--username `, :option:`--password `, and -:option:`--awsSessionToken` options instead, like so: - -.. code-block:: none - - mongofiles 'mongodb+srv://cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS' --username --password --awsSessionToken - -When provided as command line parameters, these three options do not -require percent encoding. - -You may also set these credentials on your platform using standard -`AWS IAM environment variables -`__. -|tool-binary| checks for the following environment variables when you -use the ``MONGODB-AWS`` -:urioption:`authentication mechanism `: - -- ``AWS_ACCESS_KEY_ID`` -- ``AWS_SECRET_ACCESS_KEY`` -- ``AWS_SESSION_TOKEN`` - -If set, these credentials do not need to be specified in the connection -string or via their explicit options. - -.. note:: - - If you chose to use the AWS environment variables to specify these - values, you cannot mix and match with the corresponding explicit or - connection string options for these credentials. Either use the - environment variables for access key ID *and* secret access key - (*and* session token if used), **or** specify each of these using the - explicit or connection string options instead. - -The following example sets these environment variables in the ``bash`` -shell: - -.. code-block:: none - - export AWS_ACCESS_KEY_ID='' - export AWS_SECRET_ACCESS_KEY='' - export AWS_SESSION_TOKEN='' - -Syntax for setting environment variables in other shells will be -different. Consult the documentation for your platform for more -information. - -You can verify that these environment variables have been set with the -following command: - -.. code-block:: none - env | grep AWS +Learn More +---------- -Once set, the following example connects to a MongoDB Atlas cluster -using these environment variables: +- :ref:`mongofiles-compatibility-and-installation` +- :ref:`mongofiles Behavior ` +- :ref:`mongofiles-examples` -.. code-block:: none +.. toctree:: + :maxdepth: 1 + :hidden: - mongofiles 'mongodb+srv://cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS' + Compatibility and Installation + Behavior + Examples \ No newline at end of file diff --git a/source/mongofiles/mongofiles-behavior.txt b/source/mongofiles/mongofiles-behavior.txt new file mode 100644 index 00000000..48466285 --- /dev/null +++ b/source/mongofiles/mongofiles-behavior.txt @@ -0,0 +1,78 @@ +.. _mongofiles-behavior: + +============================================ +mongofiles Behavior, Access, and Usage +============================================ + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. |arrow| unicode:: U+27A4 +.. |tool-binary| replace:: ``mongofiles`` + +Behavior +-------- + +FIPS +~~~~ + +``mongofiles`` automatically creates FIPS-compliant +connections to a :binary:`~bin.mongod`/:binary:`~bin.mongos` that is +:manual:`configured to use FIPS mode `. + +Read Preference +~~~~~~~~~~~~~~~ + +By default, ``mongofiles`` uses read preference +:readmode:`primary`. To override the default, you can specify the +:ref:`read preference ` in the +:option:`--readPreference ` command line +option or in the :option:`--uri connection string `. + +If you specify read preference in the URI +string and the :option:`--readPreference `, +the :option:`--readPreference ` value +overrides the read preference specified in the URI string. + +Write Concern +~~~~~~~~~~~~~ + +You can specify both the +:option:`--writeConcern ` and the +:option:`--uri connection string ` option. If write +concern is specified using both options, the +:option:`--writeConcern ` value overrides +the write concern specified in the URI string. + + +Required Access +--------------- + +In order to connect to a :binary:`~bin.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. + + +Learn More +---------- + +- :ref:`mongofiles` +- :ref:`mongofiles-compatibility-and-installation` +- :ref:`mongofiles-examples` \ No newline at end of file diff --git a/source/mongofiles/mongofiles-compatibility-and-installation.txt b/source/mongofiles/mongofiles-compatibility-and-installation.txt new file mode 100644 index 00000000..fcfa4cf8 --- /dev/null +++ b/source/mongofiles/mongofiles-compatibility-and-installation.txt @@ -0,0 +1,61 @@ +.. _mongofiles-compatibility-and-installation: + +================================================ +mongofiles Compatibility and Installation +================================================ + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: shell + +.. |arrow| unicode:: U+27A4 +.. |tool-binary| replace:: ``mongofiles`` +.. |app-name| replace:: ``mongofiles`` + +This page describes software compatibility and installation for version +``{+release+}`` of |tool-binary|. + +Starting in MongoDB 4.4, the {+dbtools+} are released separately from +the MongoDB Server. The {+dbtools+} use their own versioning, with an +initial version of ``100.0.0``. + +Compatibility +------------- + +MongoDB Server Compatibility +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/extracts/dbtools-compatibility-single.rst + +Platform Support +~~~~~~~~~~~~~~~~ + +|tool-binary| version ``{+release+}`` is supported on the following +platforms: + +.. include:: /includes/fact-platform-support.rst + +Installation +------------ + +.. include:: /includes/fact-see-install-guide.rst + + +Learn More +---------- + +- :ref:`mongofiles` +- :ref:`mongofiles Behavior ` +- :ref:`mongofiles-examples` \ No newline at end of file diff --git a/source/mongofiles/mongofiles-examples.txt b/source/mongofiles/mongofiles-examples.txt new file mode 100644 index 00000000..4560ecfa --- /dev/null +++ b/source/mongofiles/mongofiles-examples.txt @@ -0,0 +1,209 @@ +.. _mongofiles-examples: + +===================== +mongofiles Examples +===================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: shell + +.. |arrow| unicode:: U+27A4 +.. |tool-binary| replace:: ``mongofiles`` + +This page shows examples for |tool-binary|. + +Run |tool-binary| from the system command line, not the +:binary:`~bin.mongo` shell. + +Return all Files in a GridFS Collection +------------------------------------------------------------------------------- + +To return a list of all files in a :term:`GridFS` collection in the +``records`` database, use the following invocation at the system shell: + +.. code-block:: sh + + mongofiles -d=records list + +This ``mongofiles`` instance will connect to the +:binary:`~bin.mongod` instance running on the ``27017`` localhost +interface to specify the same operation on a different port or +hostname, and issue a command that resembles one of the following: + +.. code-block:: sh + + mongofiles --port=37017 -d=records list + mongofiles --host=db1.example.net -d=records list + mongofiles --host=db1.example.net --port=37017 -d=records list + +Modify any of the following commands as needed if you're connecting +the :binary:`~bin.mongod` instances on different ports or hosts. + +To upload a file named ``32-corinth.lp`` to the GridFS collection in +the ``records`` database, you can use the following command: + +.. code-block:: sh + + mongofiles -d=records put 32-corinth.lp + +To delete the ``32-corinth.lp`` file from this GridFS collection in +the ``records`` database, you can use the following command: + +.. code-block:: sh + + mongofiles -d=records delete 32-corinth.lp + +To search for files in the GridFS collection in the ``records`` +database that have the string ``corinth`` in their names, you can use +following command: + +.. code-block:: sh + + mongofiles -d=records search corinth + +To list all files in the GridFS collection in the ``records`` database +with names that begin with the string ``32``, you can use the following +command: + +.. code-block:: sh + + mongofiles -d=records list 32 + +To fetch the file from the GridFS collection in the ``records`` +database named ``32-corinth.lp``, you can use the following command: + +.. code-block:: sh + + mongofiles -d=records get 32-corinth.lp + +To fetch all files from the GridFS collection in the ``records`` +database with names beginning with the string ``32`` and ending with the +string ``.lp``, you can use the following command: + +.. code-block:: sh + + mongofiles -d=records get_regex 32*.lp + +To fetch the file from the GridFS collection in the ``records`` database +with ``_id: ObjectId("56feac751f417d0357e7140f")``, you can use the +following command: + +.. code-block:: sh + + mongofiles -d=records get_id '{"$oid": "56feac751f417d0357e7140f"}' + +You must include quotation marks around the ``_id``. + +.. _mongofiles-example-connect-using-aws-iam: + +Connect to a MongoDB Atlas Cluster using AWS IAM Credentials +------------------------------------------------------------------------------- + +.. versionadded:: 100.1.0 + +To connect to a :atlas:`MongoDB Atlas ` cluster which +has been configured to support authentication via `AWS IAM credentials +`__, +provide a :option:`connection string ` to +|tool-binary| similar to the following: + +.. code-block:: none + + mongofiles 'mongodb+srv://:@cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS' + +Connecting to Atlas using AWS IAM credentials in this manner uses the +``MONGODB-AWS`` :urioption:`authentication mechanism ` +and the ``$external`` :urioption:`authSource`, as shown in this example. + +If using an `AWS session token +`__, +as well, provide it with the ``AWS_SESSION_TOKEN`` +:urioption:`authMechanismProperties` value, as follows: + +.. code-block:: none + + mongofiles 'mongodb+srv://:@cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:' + +.. include:: /includes/fact-pct-encode-uri.rst + +Alternatively, the AWS access key ID, secret access key, and optionally +session token can each be provided outside of the connection string +using the :option:`--username `, :option:`--password `, and +:option:`--awsSessionToken ` options instead, like so: + +.. code-block:: none + + mongofiles 'mongodb+srv://cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS' --username --password --awsSessionToken + +When provided as command line parameters, these three options do not +require percent encoding. + +You may also set these credentials on your platform using standard +`AWS IAM environment variables +`__. +|tool-binary| checks for the following environment variables when you +use the ``MONGODB-AWS`` +:urioption:`authentication mechanism `: + +- ``AWS_ACCESS_KEY_ID`` +- ``AWS_SECRET_ACCESS_KEY`` +- ``AWS_SESSION_TOKEN`` + +If set, these credentials do not need to be specified in the connection +string or via their explicit options. + +.. note:: + + If you chose to use the AWS environment variables to specify these + values, you cannot mix and match with the corresponding explicit or + connection string options for these credentials. Either use the + environment variables for access key ID *and* secret access key + (*and* session token if used), **or** specify each of these using the + explicit or connection string options instead. + +The following example sets these environment variables in the ``bash`` +shell: + +.. code-block:: none + + export AWS_ACCESS_KEY_ID='' + export AWS_SECRET_ACCESS_KEY='' + export AWS_SESSION_TOKEN='' + +Syntax for setting environment variables in other shells will be +different. Consult the documentation for your platform for more +information. + +You can verify that these environment variables have been set with the +following command: + +.. code-block:: none + + env | grep AWS + +Once set, the following example connects to a MongoDB Atlas cluster +using these environment variables: + +.. code-block:: none + + mongofiles 'mongodb+srv://cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS' + +Learn More +---------- + +- :ref:`mongofiles` +- :ref:`mongofiles-compatibility-and-installation` +- :ref:`mongofiles Behavior ` \ No newline at end of file diff --git a/source/mongoimport.txt b/source/mongoimport.txt index 392e6a51..d4839946 100644 --- a/source/mongoimport.txt +++ b/source/mongoimport.txt @@ -789,7 +789,7 @@ Learn More ---------- - :ref:`mongoimport-compatibility-and-installation` -- :ref:`mongoimport Behavior ` +- :ref:`mongoimport Behavior ` - :ref:`mongoimport-examples` .. toctree:: diff --git a/source/mongoimport/mongoimport-behavior.txt b/source/mongoimport/mongoimport-behavior.txt index 1fad8bb6..47af7b32 100644 --- a/source/mongoimport/mongoimport-behavior.txt +++ b/source/mongoimport/mongoimport-behavior.txt @@ -1,4 +1,4 @@ -.. _mongoimport-behavior-access-usage: +.. _mongoimport-behavior: ============================================ mongoimport Behavior, Access, and Usage diff --git a/source/mongoimport/mongoimport-compatibility-and-installation.txt b/source/mongoimport/mongoimport-compatibility-and-installation.txt index c7888cc6..e5c8d8a0 100644 --- a/source/mongoimport/mongoimport-compatibility-and-installation.txt +++ b/source/mongoimport/mongoimport-compatibility-and-installation.txt @@ -59,5 +59,5 @@ Learn More ---------- - :ref:`mongoimport` -- :ref:`mongoimport Behavior ` +- :ref:`mongoimport Behavior ` - :ref:`mongoimport-examples` \ No newline at end of file diff --git a/source/mongoimport/mongoimport-examples.txt b/source/mongoimport/mongoimport-examples.txt index 4c7eb0b2..2e3cc7b1 100644 --- a/source/mongoimport/mongoimport-examples.txt +++ b/source/mongoimport/mongoimport-examples.txt @@ -423,4 +423,4 @@ Learn More - :ref:`mongoimport` - :ref:`mongoimport-compatibility-and-installation` -- :ref:`mongoimport Behavior ` \ No newline at end of file +- :ref:`mongoimport Behavior ` \ No newline at end of file diff --git a/source/mongorestore.txt b/source/mongorestore.txt index b3bf8417..23673338 100644 --- a/source/mongorestore.txt +++ b/source/mongorestore.txt @@ -852,7 +852,7 @@ Learn More ---------- - :ref:`mongorestore-compatibility-and-installation` -- :ref:`Behavior ` +- :ref:`Behavior ` - :ref:`mongorestore-examples` .. toctree:: @@ -860,5 +860,5 @@ Learn More :hidden: Compatibility and Installation - Behavior + Behavior Examples \ No newline at end of file diff --git a/source/mongorestore/mongorestore-behavior-access-usage.txt b/source/mongorestore/mongorestore-behavior.txt similarity index 99% rename from source/mongorestore/mongorestore-behavior-access-usage.txt rename to source/mongorestore/mongorestore-behavior.txt index b5daeb9e..99319848 100644 --- a/source/mongorestore/mongorestore-behavior-access-usage.txt +++ b/source/mongorestore/mongorestore-behavior.txt @@ -1,4 +1,4 @@ -.. _mongorestore-behavior-access-usage: +.. _mongorestore-behavior: ============================================ mongorestore Behavior, Access, and Usage diff --git a/source/mongorestore/mongorestore-compatibility-and-installation.txt b/source/mongorestore/mongorestore-compatibility-and-installation.txt index 06c0f885..e3e343f4 100644 --- a/source/mongorestore/mongorestore-compatibility-and-installation.txt +++ b/source/mongorestore/mongorestore-compatibility-and-installation.txt @@ -62,5 +62,5 @@ Learn More ---------- - :ref:`mongorestore` -- :ref:`Behavior ` +- :ref:`Behavior ` - :ref:`mongorestore-examples` \ No newline at end of file diff --git a/source/mongorestore/mongorestore-examples.txt b/source/mongorestore/mongorestore-examples.txt index 9969864d..f9dc2b1a 100644 --- a/source/mongorestore/mongorestore-examples.txt +++ b/source/mongorestore/mongorestore-examples.txt @@ -444,4 +444,4 @@ Learn More - :ref:`mongorestore` - :ref:`mongorestore-compatibility-and-installation` -- :ref:`Behavior ` \ No newline at end of file +- :ref:`Behavior ` \ No newline at end of file diff --git a/source/mongostat.txt b/source/mongostat.txt index 730c09d1..da2d1604 100644 --- a/source/mongostat.txt +++ b/source/mongostat.txt @@ -649,7 +649,7 @@ Learn More ---------- - :ref:`mongostat-compatibility-and-installation` -- :ref:`mongostat Behavior ` +- :ref:`mongostat Behavior ` - :ref:`mongostat-examples` .. toctree:: diff --git a/source/mongostat/mongostat-behavior.txt b/source/mongostat/mongostat-behavior.txt index 3110d33d..65e7bfcf 100644 --- a/source/mongostat/mongostat-behavior.txt +++ b/source/mongostat/mongostat-behavior.txt @@ -1,4 +1,4 @@ -.. _mongostat-behavior-access-usage: +.. _mongostat-behavior: ============================================ mongostat Behavior, Access, and Usage diff --git a/source/mongostat/mongostat-compatibility-and-installation.txt b/source/mongostat/mongostat-compatibility-and-installation.txt index 172107e3..1d569dac 100644 --- a/source/mongostat/mongostat-compatibility-and-installation.txt +++ b/source/mongostat/mongostat-compatibility-and-installation.txt @@ -57,5 +57,5 @@ Learn More ---------- - :ref:`mongostat` -- :ref:`mongostat Behavior ` +- :ref:`mongostat Behavior ` - :ref:`mongostat-examples` \ No newline at end of file diff --git a/source/mongostat/mongostat-examples.txt b/source/mongostat/mongostat-examples.txt index 9b269aa1..ebd71f74 100644 --- a/source/mongostat/mongostat-examples.txt +++ b/source/mongostat/mongostat-examples.txt @@ -356,4 +356,4 @@ Learn More - :ref:`mongostat` - :ref:`mongostat-compatibility-and-installation` -- :ref:`mongostat Behavior ` \ No newline at end of file +- :ref:`mongostat Behavior ` \ No newline at end of file