587 lines
15 KiB
Groff
587 lines
15 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.TH "MONGOFILES" "1" "January 30, 2015" "3.0" "mongodb-manual"
|
|
.SH NAME
|
|
mongofiles \- MongoDB GridFS Utility
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.SH SYNOPSIS
|
|
.sp
|
|
The \fBmongofiles\fP utility makes it possible to manipulate files
|
|
stored in your MongoDB instance in \fIGridFS\fP objects from the
|
|
command line. It is particularly useful as it provides an interface
|
|
between objects stored in your file system and GridFS.
|
|
.sp
|
|
All \fBmongofiles\fP commands have the following form:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
mongofiles <options> <commands> <filename>
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
The components of the \fBmongofiles\fP command are:
|
|
.INDENT 0.0
|
|
.IP 1. 3
|
|
\fI\%Options\fP\&. You may use one or more of
|
|
these options to control the behavior of \fBmongofiles\fP\&.
|
|
.IP 2. 3
|
|
\fI\%Commands\fP\&. Use one of these commands to
|
|
determine the action of \fBmongofiles\fP\&.
|
|
.IP 3. 3
|
|
A filename which is either: the name of a file on your local\(aqs file
|
|
system, or a GridFS object.
|
|
.UNINDENT
|
|
.sp
|
|
\fBmongofiles\fP, like \fBmongodump\fP, \fBmongoexport\fP,
|
|
\fBmongoimport\fP, and \fBmongorestore\fP, can access data
|
|
stored in a MongoDB data directory without requiring a running
|
|
\fBmongod\fP instance, if no other \fBmongod\fP is running.
|
|
.sp
|
|
\fBIMPORTANT:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
For \fIreplica sets\fP,
|
|
\fBmongofiles\fP can only read from the set\(aqs
|
|
\(aq\fIprimary\fP\&.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH OPTIONS
|
|
.sp
|
|
Changed in version 3.0.0: \fBmongofiles\fP removed the \fB\-\-dbpath\fP as well as related
|
|
\fB\-\-directoryperdb\fP and \fB\-\-journal\fP options. You must use
|
|
\fBmongofiles\fP while connected to a \fBmongod\fP instance.
|
|
|
|
.INDENT 0.0
|
|
.TP
|
|
.B mongofiles
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-help
|
|
Returns information on the options and use of \fBmongofiles\fP\&.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-verbose, \-v
|
|
Increases the amount of internal reporting returned on standard output
|
|
or in log files. Increase the verbosity with the \fB\-v\fP form by
|
|
including the option multiple times, (e.g. \fB\-vvvvv\fP\&.)
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-quiet
|
|
Runs the \fBmongofiles\fP in a quiet mode that attempts to limit the amount
|
|
of output.
|
|
.sp
|
|
This option suppresses:
|
|
.INDENT 7.0
|
|
.IP \(bu 2
|
|
output from \fIdatabase commands\fP
|
|
.IP \(bu 2
|
|
replication activity
|
|
.IP \(bu 2
|
|
connection accepted events
|
|
.IP \(bu 2
|
|
connection closed events
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-version
|
|
Returns the \fBmongofiles\fP release number.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-host <hostname><:port>
|
|
Specifies a resolvable hostname for the \fBmongod\fP that holds
|
|
your GridFS system. By default \fBmongofiles\fP attempts to connect
|
|
to a MongoDB process running on the localhost port number \fB27017\fP\&.
|
|
.sp
|
|
Optionally, specify a port number to connect a MongoDB instance running
|
|
on a port other than 27017.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-port <port>
|
|
\fIDefault\fP: 27017
|
|
.sp
|
|
Specifies the TCP port on which the MongoDB instance listens for
|
|
client connections.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-ipv6
|
|
Enables IPv6 support and allows the \fBmongofiles\fP to connect to the
|
|
MongoDB instance using an IPv6 network. All MongoDB programs and
|
|
processes disable IPv6 support by default.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-ssl
|
|
New in version 2.6.
|
|
|
|
.sp
|
|
Enables connection to a \fBmongod\fP or \fBmongos\fP that has
|
|
SSL support enabled.
|
|
.sp
|
|
The default distribution of MongoDB does not contain support for SSL.
|
|
For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure\-ssl\&.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-sslCAFile <filename>
|
|
New in version 2.6.
|
|
|
|
.sp
|
|
Specifies the \fB\&.pem\fP file that contains the root certificate chain
|
|
from the Certificate Authority. Specify the file name of the
|
|
\fB\&.pem\fP file using relative or absolute paths.
|
|
.sp
|
|
The default distribution of MongoDB does not contain support for SSL.
|
|
For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure\-ssl\&.
|
|
.sp
|
|
\fBWARNING:\fP
|
|
.INDENT 7.0
|
|
.INDENT 3.5
|
|
If the \fBmongo\fP shell or any other tool that connects to
|
|
\fBmongos\fP or \fBmongod\fP is run without
|
|
\fI\-\-sslCAFile\fP, it will not attempt to validate
|
|
server certificates. This results in vulnerability to expired
|
|
\fBmongod\fP and \fBmongos\fP certificates as well as to foreign
|
|
processes posing as valid \fBmongod\fP or \fBmongos\fP
|
|
instances. Ensure that you \fIalways\fP specify the CA file against which
|
|
server certificates should be validated in cases where intrusion is a
|
|
possibility.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-sslPEMKeyFile <filename>
|
|
New in version 2.6.
|
|
|
|
.sp
|
|
Specifies the \fB\&.pem\fP file that contains both the SSL certificate
|
|
and key. Specify the file name of the \fB\&.pem\fP file using relative
|
|
or absolute paths.
|
|
.sp
|
|
This option is required when using the \fI\-\-ssl\fP option to connect
|
|
to a \fBmongod\fP or \fBmongos\fP that has
|
|
\fBCAFile\fP enabled \fIwithout\fP
|
|
\fBallowConnectionsWithoutCertificates\fP\&.
|
|
.sp
|
|
The default distribution of MongoDB does not contain support for SSL.
|
|
For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure\-ssl\&.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-sslPEMKeyPassword <value>
|
|
New in version 2.6.
|
|
|
|
.sp
|
|
Specifies the password to de\-crypt the certificate\-key file (i.e.
|
|
\fI\-\-sslPEMKeyFile\fP). Use the \fI\-\-sslPEMKeyPassword\fP option only if the
|
|
certificate\-key file is encrypted. In all cases, the \fBmongofiles\fP will
|
|
redact the password from all logging and reporting output.
|
|
.sp
|
|
If the private key in the PEM file is encrypted and you do not specify
|
|
the \fI\-\-sslPEMKeyPassword\fP option, the \fBmongofiles\fP will prompt for a passphrase. See
|
|
\fIssl\-certificate\-password\fP\&.
|
|
.sp
|
|
The default distribution of MongoDB does not contain support for SSL.
|
|
For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure\-ssl\&.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-sslCRLFile <filename>
|
|
New in version 2.6.
|
|
|
|
.sp
|
|
Specifies the \fB\&.pem\fP file that contains the Certificate Revocation
|
|
List. Specify the file name of the \fB\&.pem\fP file using relative or
|
|
absolute paths.
|
|
.sp
|
|
The default distribution of MongoDB does not contain support for SSL.
|
|
For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure\-ssl\&.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-sslAllowInvalidCertificates
|
|
New in version 2.6.
|
|
|
|
.sp
|
|
Bypasses the validation checks for server certificates and allows
|
|
the use of invalid certificates. When using the
|
|
\fBallowInvalidCertificates\fP setting, MongoDB logs as a
|
|
warning the use of the invalid certificate.
|
|
.sp
|
|
The default distribution of MongoDB does not contain support for SSL.
|
|
For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure\-ssl\&.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-sslAllowInvalidHostnames
|
|
New in version 3.0.
|
|
|
|
.sp
|
|
Disables the validation of the hostnames in SSL certificates. Allows
|
|
\fBmongofiles\fP to connect to MongoDB instances if the hostname their
|
|
certificates do not match the specified hostname.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-sslFIPSMode
|
|
New in version 2.6.
|
|
|
|
.sp
|
|
Directs the \fBmongofiles\fP to use the FIPS mode of the installed OpenSSL
|
|
library. Your system must have a FIPS compliant OpenSSL library to use
|
|
the \fI\-\-sslFIPSMode\fP option.
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 7.0
|
|
.INDENT 3.5
|
|
FIPS Compatible SSL is
|
|
available only in \fI\%MongoDB Enterprise\fP\&. See
|
|
http://docs.mongodb.org/manual/tutorial/configure\-fips for more information.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-username <username>, \-u <username>
|
|
Specifies a username with which to authenticate to a MongoDB database
|
|
that uses authentication. Use in conjunction with the \fB\-\-password\fP and
|
|
\fB\-\-authenticationDatabase\fP options.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-password <password>, \-p <password>
|
|
Specifies a password with which to authenticate to a MongoDB database
|
|
that uses authentication. Use in conjunction with the \fB\-\-username\fP and
|
|
\fB\-\-authenticationDatabase\fP options.
|
|
.sp
|
|
If you do not specify an argument for \fI\-\-password\fP, \fBmongofiles\fP will
|
|
prompt interactively for a password on the console.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-authenticationDatabase <dbname>
|
|
New in version 2.4.
|
|
|
|
.sp
|
|
Specifies the database that holds the user\(aqs credentials.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-authenticationMechanism <name>
|
|
\fIDefault\fP: MONGODB\-CR
|
|
.sp
|
|
New in version 2.4.
|
|
|
|
.sp
|
|
Changed in version 2.6: Added support for the \fBPLAIN\fP and \fBMONGODB\-X509\fP authentication
|
|
mechanisms.
|
|
|
|
.sp
|
|
Specifies the authentication mechanism the \fBmongofiles\fP instance uses to
|
|
authenticate to the \fBmongod\fP or \fBmongos\fP\&.
|
|
.TS
|
|
center;
|
|
|l|l|.
|
|
_
|
|
T{
|
|
Value
|
|
T} T{
|
|
Description
|
|
T}
|
|
_
|
|
T{
|
|
MONGODB\-CR
|
|
T} T{
|
|
MongoDB challenge/response authentication.
|
|
T}
|
|
_
|
|
T{
|
|
MONGODB\-X509
|
|
T} T{
|
|
MongoDB SSL certificate authentication.
|
|
T}
|
|
_
|
|
T{
|
|
PLAIN
|
|
T} T{
|
|
External authentication using LDAP. You can also use \fBPLAIN\fP
|
|
for authenticating in\-database users. \fBPLAIN\fP transmits
|
|
passwords in plain text. This mechanism is available only in
|
|
\fI\%MongoDB Enterprise\fP\&.
|
|
T}
|
|
_
|
|
T{
|
|
GSSAPI
|
|
T} T{
|
|
External authentication using Kerberos. This mechanism is
|
|
available only in \fI\%MongoDB Enterprise\fP\&.
|
|
T}
|
|
_
|
|
.TE
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-gssapiServiceName
|
|
New in version 2.6.
|
|
|
|
.sp
|
|
Specify the name of the service using \fBGSSAPI/Kerberos\fP\&. Only required if the service does not use the
|
|
default name of \fBmongodb\fP\&.
|
|
.sp
|
|
This option is available only in MongoDB Enterprise.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-gssapiHostName
|
|
New in version 2.6.
|
|
|
|
.sp
|
|
Specify the hostname of a service using \fBGSSAPI/Kerberos\fP\&. \fIOnly\fP required if the hostname of a machine does
|
|
not match the hostname resolved by DNS.
|
|
.sp
|
|
This option is available only in MongoDB Enterprise.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-db <database>, \-d <database>
|
|
Specifies the name of the database on which to run the \fBmongofiles\fP\&.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-collection <collection>, \-c <collection>
|
|
This option has no use in this context and a future release may
|
|
remove it. See \fI\%SERVER\-4931\fP for more information.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-local <filename>, \-l <filename>
|
|
Specifies the local filesystem name of a file for get and put
|
|
operations.
|
|
.sp
|
|
In the \fBmongofiles put\fP and \fBmongofiles get\fP commands,
|
|
the required \fB<filename>\fP modifier refers to the name the object will
|
|
have in GridFS. \fBmongofiles\fP assumes that this reflects the
|
|
file\(aqs name on the local file system. This setting overrides this
|
|
default.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-type <MIME>
|
|
Provides the ability to specify a \fIMIME\fP type to describe the file
|
|
inserted into GridFS storage. \fBmongofiles\fP omits this option in
|
|
the default operation.
|
|
.sp
|
|
Use only with \fBmongofiles put\fP operations.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-replace, \-r
|
|
Alters the behavior of \fBmongofiles put\fP to replace existing
|
|
GridFS objects with the specified local file, rather than adding an
|
|
additional object with the same name.
|
|
.sp
|
|
In the default operation, files will not be overwritten by a
|
|
\fBmongofiles put\fP option.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-prefix string
|
|
\fIDefault\fP: fs
|
|
.sp
|
|
GridFS prefix to use.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-writeConcern <document>
|
|
\fIDefault\fP: majority
|
|
.sp
|
|
Specifies the \fIwrite concern\fP for each write operation that \fBmongofiles\fP
|
|
writes to the target database.
|
|
.sp
|
|
Specify the write concern as a document with \fIw options\fP\&.
|
|
.UNINDENT
|
|
.SH COMMANDS
|
|
.INDENT 0.0
|
|
.TP
|
|
.B list <prefix>
|
|
Lists the files in the GridFS store. The characters specified after
|
|
\fBlist\fP (e.g. \fB<prefix>\fP) optionally limit the list of
|
|
returned items to files that begin with that string of characters.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B search <string>
|
|
Lists the files in the GridFS store with names that match any
|
|
portion of \fB<string>\fP\&.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B put <filename>
|
|
Copy the specified file from the local file system into GridFS
|
|
storage.
|
|
.sp
|
|
Here, \fB<filename>\fP refers to the name the object will have in
|
|
GridFS, and \fBmongofiles\fP assumes that this reflects the name the
|
|
file has on the local file system. If the local filename is
|
|
different use the \fImongofiles \-\-local\fP option.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B get <filename>
|
|
Copy the specified file from GridFS storage to the local file
|
|
system.
|
|
.sp
|
|
Here, \fB<filename>\fP refers to the name the object will have in
|
|
GridFS, and \fBmongofiles\fP assumes that this reflects the name the
|
|
file has on the local file system. If the local filename is
|
|
different use the \fImongofiles \-\-local\fP option.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B delete <filename>
|
|
Delete the specified file from GridFS storage.
|
|
.UNINDENT
|
|
.SH EXAMPLES
|
|
.sp
|
|
To return a list of all files in a \fIGridFS\fP collection in the
|
|
\fBrecords\fP database, use the following invocation at the system shell:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
mongofiles \-d records list
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
This \fBmongofiles\fP instance will connect to the
|
|
\fBmongod\fP instance running on the \fB27017\fP localhost
|
|
interface to specify the same operation on a different port or
|
|
hostname, and issue a command that resembles one of the following:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
mongofiles \-\-port 37017 \-d records list
|
|
mongofiles \-\-hostname db1.example.net \-d records list
|
|
mongofiles \-\-hostname db1.example.net \-\-port 37017 \-d records list
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Modify any of the following commands as needed if you\(aqre connecting
|
|
the \fBmongod\fP instances on different ports or hosts.
|
|
.sp
|
|
To upload a file named \fB32\-corinth.lp\fP to the GridFS collection in
|
|
the \fBrecords\fP database, you can use the following command:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
mongofiles \-d records put 32\-corinth.lp
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
To delete the \fB32\-corinth.lp\fP file from this GridFS collection in
|
|
the \fBrecords\fP database, you can use the following command:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
mongofiles \-d records delete 32\-corinth.lp
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
To search for files in the GridFS collection in the \fBrecords\fP
|
|
database that have the string \fBcorinth\fP in their names, you can use
|
|
following command:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
mongofiles \-d records search corinth
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
To list all files in the GridFS collection in the \fBrecords\fP database
|
|
that begin with the string \fB32\fP, you can use the following command:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
mongofiles \-d records list 32
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
To fetch the file from the GridFS collection in the \fBrecords\fP
|
|
database named \fB32\-corinth.lp\fP, you can use the following command:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
mongofiles \-d records get 32\-corinth.lp
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH AUTHOR
|
|
MongoDB Documentation Project
|
|
.SH COPYRIGHT
|
|
2011-2015
|
|
.\" Generated by docutils manpage writer.
|
|
.
|