From b322c3a89c9a3f5eebd86fc551c8207c8a263e05 Mon Sep 17 00:00:00 2001 From: Kay Kim Date: Tue, 1 Oct 2019 22:50:04 -0400 Subject: [PATCH] DOCS-12989: add = to the options for mongodb command line tools (mongofiles) --- source/reference/program/mongofiles.txt | 434 +++++++++++++++++++++--- 1 file changed, 396 insertions(+), 38 deletions(-) diff --git a/source/reference/program/mongofiles.txt b/source/reference/program/mongofiles.txt index 04e45ae79f9..30f2ce73f56 100644 --- a/source/reference/program/mongofiles.txt +++ b/source/reference/program/mongofiles.txt @@ -112,61 +112,419 @@ Options .. program:: mongofiles -.. include:: /includes/option/option-mongofiles-help.rst +.. option:: --help -.. include:: /includes/option/option-mongofiles-verbose.rst + Returns information on the options and use of :program:`mongofiles`. -.. include:: /includes/option/option-mongofiles-quiet.rst -.. include:: /includes/option/option-mongofiles-version.rst +.. option:: --verbose, -v -.. include:: /includes/option/option-mongofiles-uri.rst + Increases the amount of internal reporting returned on standard output + or in log files. Increase the verbosity with the ``-v`` form by + including the option multiple times, (e.g. ``-vvvvv``.) + + + +.. option:: --quiet + + Runs :program:`mongofiles` in a quiet mode that attempts to limit the amount + of output. + + This option suppresses: + + - output from :term:`database commands ` + + - replication activity + + - connection accepted events + + - connection closed events + + +.. option:: --version + + Returns the :program:`mongofiles` release number. + + +.. option:: --uri= + + .. versionadded:: 3.4.6 + + Specify a resolvable :doc:`URI ` + connection string (enclose in quotes) to connect to the MongoDB deployment. + + .. code-block:: none + + --uri="mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]" + + For information on the components of the connection string, see + the :doc:`Connection String URI Format + ` documentation. + + .. note:: + + For TLS/SSL options, use the command-line options instead of the + :ref:`URI options for TLS/SSL (Available starting in + 4.2)`. + + + .. important:: + + The following command-line options cannot be used in conjunction + with :option:`--uri` option: + + - :option:`--host` + - :option:`--port` + - :option:`--db` + - :option:`--username` + - :option:`--password` (if the + :doc:`URI ` connection string also includes the password) + - :option:`--authenticationDatabase` + - :option:`--authenticationMechanism` + + Instead, specify these options as part of your :option:`--uri` + connection string. + + +.. 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 + to a MongoDB process running on the localhost port number ``27017``. + + Optionally, specify a port number to connect a MongoDB instance running + on a port other than 27017. + + .. note:: + + You cannot specify both :option:`--host` and :option:`--uri`. + + + +.. option:: --port= + + *Default*: 27017 + + Specifies the TCP port on which the MongoDB instance listens for + client connections. + + .. note:: + + You cannot specify both :option:`--port` and :option:`--uri`. + + +.. option:: --ipv6 + + *Removed in version 3.0.* + + Enables IPv6 support and allows :program:`mongofiles` to connect to the + MongoDB instance using an IPv6 network. Prior to MongoDB 3.0, you + had to specify :option:`--ipv6` to use IPv6. In MongoDB 3.0 and later, IPv6 + is always enabled. + + +.. option:: --ssl + + .. versionadded:: 2.6 + + Enables connection to a :binary:`~bin.mongod` or :binary:`~bin.mongos` that has + TLS/SSL support enabled. + + .. include:: /includes/extracts/ssl-facts-see-more.rst + + + +.. option:: --sslCAFile= + + .. versionadded:: 2.6 + + Specifies the :file:`.pem` file that contains the root certificate chain + from the Certificate Authority. Specify the file name of the + :file:`.pem` file using relative or absolute paths. + + .. include:: /includes/extracts/ssl-facts-ca-file.rst + + .. warning:: + + **Version 3.2 and earlier:** For TLS/SSL connections (``--ssl``) to + :binary:`~bin.mongod` and :binary:`~bin.mongos`, if the :program:`mongofiles` runs without the + :option:`--sslCAFile`, :program:`mongofiles` will not attempt + to validate the server certificates. This creates a vulnerability + to expired :binary:`~bin.mongod` and :binary:`~bin.mongos` certificates as + well as to foreign processes posing as valid :binary:`~bin.mongod` or + :binary:`~bin.mongos` instances. Ensure that you *always* specify the + CA file to validate the server certificates in cases where + intrusion is a possibility. + + .. include:: /includes/extracts/ssl-facts-see-more.rst + + +.. option:: --sslPEMKeyFile= + + .. versionadded:: 2.6 + + Specifies the :file:`.pem` file that contains both the TLS/SSL certificate + and key. Specify the file name of the :file:`.pem` file using relative + or absolute paths. + + This option is required when using the :option:`--ssl` option to connect + to a :binary:`~bin.mongod` or :binary:`~bin.mongos` that has + :setting:`~net.ssl.CAFile` enabled *without* + :setting:`~net.ssl.allowConnectionsWithoutCertificates`. + + .. include:: /includes/extracts/ssl-facts-see-more.rst + + + +.. option:: --sslPEMKeyPassword= + + .. versionadded:: 2.6 + + 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 + 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 + :ref:`ssl-certificate-password`. + + .. include:: /includes/extracts/ssl-facts-see-more.rst + + +.. option:: --sslCRLFile= + + .. versionadded:: 2.6 + + Specifies the :file:`.pem` file that contains the Certificate Revocation + List. Specify the file name of the :file:`.pem` file using relative or + absolute paths. + + .. include:: /includes/extracts/ssl-facts-see-more.rst + -.. include:: /includes/option/option-mongofiles-host.rst -.. include:: /includes/option/option-mongofiles-port.rst +.. option:: --sslAllowInvalidCertificates + + .. versionadded:: 2.6 + + Bypasses the validation checks for server certificates and allows + the use of invalid certificates. When using the + :setting:`~net.ssl.allowInvalidCertificates` setting, MongoDB logs as a + warning the use of the invalid certificate. + + .. include:: /includes/extracts/ssl-facts-x509-invalid-certificate.rst + + .. include:: /includes/extracts/ssl-facts-invalid-cert-warning-clients.rst + + .. include:: /includes/extracts/ssl-facts-see-more.rst + + + +.. option:: --sslAllowInvalidHostnames + + .. versionadded:: 3.0 + + Disables the validation of the hostnames in TLS/SSL certificates. Allows + :program:`mongofiles` to connect to MongoDB instances even if the hostname in their + certificates do not match the specified hostname. + + .. include:: /includes/extracts/ssl-facts-see-more.rst + + +.. option:: --username=, -u= + + Specifies a username with which to authenticate to a MongoDB database + that uses authentication. Use in conjunction with the :option:`--password` and + :option:`--authenticationDatabase` options. + + .. note:: + + You cannot specify both :option:`--username` and :option:`--uri`. + + +.. option:: --password=, -p= + + Specifies a password with which to authenticate to a MongoDB database + that uses authentication. Use in conjunction with the :option:`--username` and + :option:`--authenticationDatabase` options. + + .. versionchanged:: 3.0.2 + + To prompt the user + for the password, pass the :option:`--username` option without + :option:`--password` or specify an empty string as the :option:`--password` value, + as in ``--password ""`` . + + .. note:: + + You cannot specify both :option:`--password` and :option:`--uri`. + + +.. option:: --authenticationDatabase= + + Specifies the authentication database where the specified :option:`--username` has been created. + See :ref:`user-authentication-database`. + + .. note:: + + You cannot specify both :option:`--authenticationDatabase` and :option:`--uri`. + + +.. option:: --authenticationMechanism= + + *Default*: SCRAM-SHA-1 + + Specifies the authentication mechanism the :program:`mongofiles` instance uses to + authenticate to the :binary:`~bin.mongod` or :binary:`~bin.mongos`. + + .. versionchanged:: 4.0 + + MongoDB removes support for the deprecated MongoDB + Challenge-Response (``MONGODB-CR``) authentication mechanism. + + MongoDB adds support for SCRAM mechanism using the SHA-256 hash + function (``SCRAM-SHA-256``). + + .. include:: /includes/list-table-auth-mechanisms.rst + + .. note:: + + You cannot specify both :option:`--authenticationMechanism` and :option:`--uri`. -.. include:: /includes/option/option-mongofiles-ipv6.rst -.. include:: /includes/option/option-mongofiles-ssl.rst +.. option:: --gssapiServiceName= + + .. versionadded:: 2.6 + + Specify the name of the service using :doc:`GSSAPI/Kerberos + `. Only required if the service does not use the + default name of ``mongodb``. + + This option is available only in MongoDB Enterprise. + + + +.. option:: --gssapiHostName= + + .. versionadded:: 2.6 + + Specify the hostname of a service using :doc:`GSSAPI/Kerberos + `. *Only* required if the hostname of a machine does + not match the hostname resolved by DNS. + + This option is available only in MongoDB Enterprise. + + + +.. option:: --db=, -d= + + Specifies the name of the database on which to run the :program:`mongofiles`. + + .. note:: + + You cannot specify both :option:`--db` and :option:`--uri`. + + +.. option:: --local=, -l= + + Specifies the local filesystem name of a file for get and put + operations. + + 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 + file's name on the local file system. This setting overrides this + default. + -.. include:: /includes/option/option-mongofiles-sslCAFile.rst -.. include:: /includes/option/option-mongofiles-sslPEMKeyFile.rst +.. 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 + the default operation. + + Use only with :command:`mongofiles put` operations. + -.. include:: /includes/option/option-mongofiles-sslPEMKeyPassword.rst -.. include:: /includes/option/option-mongofiles-sslCRLFile.rst +.. option:: --replace, -r -.. include:: /includes/option/option-mongofiles-sslAllowInvalidCertificates.rst + Alters the behavior of :command:`mongofiles put` to replace existing + GridFS objects with the specified local file, rather than adding an + additional object with the same name. + + In the default operation, files will not be overwritten by a + :command:`mongofiles put` option. + -.. include:: /includes/option/option-mongofiles-sslAllowInvalidHostnames.rst -.. include:: /includes/option/option-mongofiles-username.rst +.. option:: --prefix= -.. include:: /includes/option/option-mongofiles-password.rst + *Default*: fs -.. include:: /includes/option/option-mongofiles-authenticationDatabase.rst + GridFS prefix to use. + -.. include:: /includes/option/option-mongofiles-authenticationMechanism.rst -.. include:: /includes/option/option-mongofiles-gssapiServiceName.rst +.. option:: --writeConcern= -.. include:: /includes/option/option-mongofiles-gssapiHostName.rst + *Default*: majority -.. include:: /includes/option/option-mongofiles-db.rst + Specifies the :term:`write concern` for each write operation that :program:`mongofiles` + performs. + + Specify the write concern as a document with :ref:`w options `: + + .. code-block:: sh + + --writeConcern="{w:'majority'}" -.. include:: /includes/option/option-mongofiles-local.rst + + If the write concern is also included in the :option:`--uri + connection string <--uri>`, the command-line + :option:`--writeConcern` overrides the write concern specified in + the URI string. -.. include:: /includes/option/option-mongofiles-type.rst -.. include:: /includes/option/option-mongofiles-replace.rst +.. option:: --readPreference= -.. include:: /includes/option/option-mongofiles-prefix.rst + *Default*: :readmode:`primary` -.. include:: /includes/option/option-mongofiles-writeConcern.rst + Specifies the :ref:`read preference` for + :program:`mongofiles`. The :option:`--readPreference` option can take: + + - A string if specifying only the read preference mode: + + .. code-block:: sh + + --readPreference=secondary + + - A quote-enclosed document to specify the mode, the optional + :ref:`read preference tag sets `, and the + optional :ref:`maxStalenessSeconds + `: + + .. code-block:: sh + + --readPreference='{mode: "secondary", tagSets: [ { "region": "east" } ], maxStalenessSeconds: 120}' + + If specifying the :ref:`maxStalenessSeconds + `, the value must be greater than or equal to 90. + + .. versionadded:: 4.2 + + :program:`mongofiles` defaults to :readmode:`primary` + :ref:`read preference `. + + Starting in version 4.2, if the read + preference is also included in the :option:`--uri connection string + <--uri>`, the command-line :option:`--readPreference` overrides the read preference + specified in the URI string. + + .. include:: /includes/warning-read-preference-mongos.rst -.. include:: /includes/option/option-mongofiles-readPreference.rst .. _mongofiles-commands: @@ -250,7 +608,7 @@ To return a list of all files in a :term:`GridFS` collection in the .. code-block:: sh - mongofiles -d records list + mongofiles -d=records list This :binary:`~bin.mongofiles` instance will connect to the :binary:`~bin.mongod` instance running on the ``27017`` localhost @@ -259,9 +617,9 @@ 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 + 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. @@ -271,14 +629,14 @@ the ``records`` database, you can use the following command: .. code-block:: sh - mongofiles -d records put 32-corinth.lp + 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 + 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 @@ -286,21 +644,21 @@ following command: .. code-block:: sh - mongofiles -d records search corinth + mongofiles -d=records search corinth To list all files in the GridFS collection in the ``records`` database that begin with the string ``32``, you can use the following command: .. code-block:: sh - mongofiles -d records list 32 + 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 + mongofiles -d=records get 32-corinth.lp To fetch the file from the GridFS collection in the ``records`` database with ``_id: ObjectId("56feac751f417d0357e7140f")``, you can use @@ -308,6 +666,6 @@ the following command: .. code-block:: sh - mongofiles -d records get_id 'ObjectId("56feac751f417d0357e7140f")' + mongofiles -d=records get_id 'ObjectId("56feac751f417d0357e7140f")' You must include quotation marks around the ``_id``.