SERVER-5307 New man pages generated from docs by samk@10gen.com

1 files changed, 345 insertions, 74 deletions

diff --git a/debian/mongofiles.1 b/debian/mongofiles.1
index 31b99d73ea1..e6b40b1512d 100644
--- a/debian/mongofiles.1
+++ b/debian/mongofiles.1
@@ -1,94 +1,365 @@
-.TH MONGOFILES "1" "June 2009" "10gen" "Mongo Database"
-.SH "NAME"
-mongofiles \- a simple GridFS interface
-.SH "SYNOPSIS"
-\fBmongofiles [\fIOPTIONS\fR] \fICOMMAND\fR \fIFILENAME\fR\fR
-.SH "DESCRIPTION"
-.PP
-\fBmongofiles\fR
-is used to list, get, and insert files in the database.
+.TH "MONGOFILES" "1" "March 14, 2013" "2.2.3" "mongodb-manual"
+.SH NAME
+mongofiles \- MongoDB
+.
+.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
+..
+.\" Man page generated from reStructuredText.
+.
+.SH SYNOPSIS
+.sp
+The \fI\%mongofiles\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 \fI\%mongofiles\fP commands take arguments in three groups:
+.INDENT 0.0
+.IP 1. 3
+\fI\%Options\fP. You may use one or more of
+these options to control the behavior of \fI\%mongofiles\fP.
+.IP 2. 3
+\fI\%Commands\fP. Use one of these commands to
+determine the action of \fI\%mongofiles\fP.
+.IP 3. 3
+A file name representing either the name of a file on your system\(aqs
+file system, a GridFS object.
+.UNINDENT
+.sp
+\fI\%mongofiles\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.
+.IP Note
+For \fIreplica sets\fP, \fI\%mongofiles\fP can
+only read from the set\(aqs \(aq\fIprimary\fP.
+.RE
+.SH COMMANDS
+.INDENT 0.0
 .TP
-Commands:
+.B mongofiles
+.UNINDENT
+.INDENT 0.0
 .TP
-.B list
-list all files.  FILENAME is an optional prefix which listed filenames
-must begin with.
+.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
-search all files. FILENAME is a substring which listed
-filenames must contain.
+.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
-add a file with filename FILENAME
+.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 \fI\%mongofiles\fP assumes that this reflects the name the
+file has on the local file system. If the local filename is
+different use the \fI\%mongofiles --local\fP option.
+.UNINDENT
+.INDENT 0.0
 .TP
-.B get
-get a file with filename FILENAME
+.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 \fI\%mongofiles\fP assumes that this reflects the name the
+file has on the local file system. If the local filename is
+different use the \fI\%mongofiles --local\fP option.
+.UNINDENT
+.INDENT 0.0
 .TP
-.B delete
-delete all files with filename FILENAME
-
-.SH "EXAMPLES"
+.B delete <filename>
+Delete the specified file from GridFS storage.
+.UNINDENT
+.SH OPTIONS
+.INDENT 0.0
 .TP
-.B mongofiles list
-lists files in test.fs.files
+.B \-\-help
+Returns a basic help and usage text.
+.UNINDENT
+.INDENT 0.0
 .TP
-.B mongofiles put README.txt
-inserts the file README.txt into the collection test.fs.files
+.B \-\-verbose, \-v
+Increases the amount of internal reporting returned on the command
+line. 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 mongofiles get photo.jpg
-retrieves photo.jpg from test.fs.files and saves it locally
-.SH "OPTIONS"
+.B \-\-version
+Returns the version of the \fI\%mongofiles\fP utility.
+.UNINDENT
+.INDENT 0.0
 .TP
-.B \-\-help
-show usage information
+.B \-\-host <hostname><:port>
+Specifies a resolvable hostname for the \fBmongod\fP that
+holds your GridFS system. By default \fI\%mongofiles\fP attempts
+to connect to a MongoDB process ruining 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 \-\-version
-show version information
+.B \-\-port <port>
+Specifies the port number, if the MongoDB instance is not running on
+the standard port. (i.e. \fB27017\fP) You may also specify a port
+number using the \fI\%mongofiles --host\fP command.
+.UNINDENT
+.INDENT 0.0
 .TP
-.B \-v, \-\-verbose
-be more verbose (include multiple times for more verbosity
-e.g. \-vvvvv)
+.B \-\-ipv6
+Enables IPv6 support that allows \fI\%mongofiles\fP to connect
+to the MongoDB instance using an IPv6 network. All MongoDB programs
+and processes, including \fI\%mongofiles\fP, disable IPv6
+support by default.
+.UNINDENT
+.INDENT 0.0
 .TP
-.B \-h, \-\-host HOST
-server to connect to (default HOST=localhost)
+.B \-\-ssl
+New in version 2.4: MongoDB added support for SSL connections to \fBmongod\fP
+instances in mongofiles.
+.IP Note
+SSL support in mongofiles is not compiled into the default
+distribution of MongoDB. See \fB/administration/ssl\fP for more
+information on SSL and MongoDB.
+.sp
+Additionally, mongofiles does not support connections to
+\fBmongod\fP instances that require client certificate
+validation.
+.RE
+.sp
+Allows \fI\%mongofiles\fP to connect to \fBmongod\fP
+instance over an SSL connection.
+.UNINDENT
+.INDENT 0.0
 .TP
-.B\-\-port arg
-server port. Can also use \-\-host hostname:port
+.B \-\-username <username>, \-u <username>
+Specifies a username to authenticate to the MongoDB instance, if your
+database requires authentication. Use in conjunction with the
+\fI\%mongofiles --password\fP option to supply a password.
+.UNINDENT
+.INDENT 0.0
 .TP
-.B \-\-ipv6
-enable IPv6 support (disabled by default)
+.B \-\-password <password>, \-p <password>
+Specifies a password to authenticate to the MongoDB instance. Use
+in conjunction with the \fI\%mongofiles --username\fP option to
+supply a username.
+.sp
+If you specify a \fI\%--username\fP
+without the \fI\%--password\fP option, \fI\%mongofiles\fP
+will prompt for a password interactively.
+.UNINDENT
+.INDENT 0.0
 .TP
-.B \-u|\-\-username USERNAME
-specify user to log in as
+.B \-\-authenticationDatabase <dbname>
+New in version 2.4.
+.sp
+Specifies the database that holds the user\(aqs (e.g
+\fI\%--username\fP) credentials.
+.sp
+By default, \fI\%mongofiles\fP assumes that the database specified to the
+\fI\%--db\fP argument holds the user\(aqs credentials, unless you
+specify \fI\%--authenticationDatabase\fP.
+.sp
+See \fBuserSource\fP,
+\fB/reference/privilege\-documents\fP and
+\fB/reference/user\-privileges\fP for more information about
+delegated authentication in MongoDB.
+.UNINDENT
+.INDENT 0.0
 .TP
-.B \-p|\-\-password PASSWORD
-specify password of user
+.B \-\-authenticationMechanism <name>
+New in version 2.4.
+.sp
+Specifies the authentication mechanism. By default, the
+authentication mechanism is \fBMONGODB\-CR\fP, which is the MongoDB
+challenge/response authentication mechanism. In the MongoDB Subscriber Edition,
+\fI\%mongofiles\fP also includes support for \fBGSSAPI\fP to handle
+Kerberos authentication.
+.sp
+See \fB/tutorial/control\-access\-to\-mongodb\-with\-kerberos\-authentication\fP
+for more information about Kerberos authentication.
+.UNINDENT
+.INDENT 0.0
 .TP
-.B \-\-dbpath PATH
-directly access mongod data files in this path, instead of connecting to a mongod instance
+.B \-\-dbpath <path>
+Specifies the directory of the MongoDB data files. If used, the
+\fI\%--dbpath\fP option enables \fI\%mongofiles\fP to attach directly to
+local data files interact with the GridFS data without the
+\fBmongod\fP. To run with \fI\%--dbpath\fP, \fI\%mongofiles\fP needs to lock
+access to the data directory: as a result, no \fBmongod\fP can access
+the same path while the process runs.
+.UNINDENT
+.INDENT 0.0
 .TP
 .B \-\-directoryperdb
-if dbpath specified, each db is in a separate directory
-.TP
-.B \-d, \-\-db DATABASE
-database to use
-.TP
-.B \-c, \-\-c COLLECTION
-collection to use (some commands, default COLLECTION=fs.files)
-.TP
-.B \-l, \-\-local FILENAME
-local filename for put|get (default is to use the same name as the
-FILENAME)
-.TP
-.B \-t, \-\-type arg
-MIME type for put (default is to omit)
-.TP
-.B \-r, \-\-replace
-Remove other files with the same name after PUT
-.SH "COPYRIGHT"
-.PP
-Copyright 2007\-2011 10gen
-.SH "SEE ALSO"
-For more information, please refer to the mongofiles page in the MongoDB manual, available at http://dochub.mongodb.org/core/mongofilesmanpage
-.SH "AUTHOR"
-Kristina Chodorow
+Use the \fI\%--directoryperdb\fP in conjunction with the corresponding
+option to \fBmongod\fP, which allows \fI\%mongofiles\fP when
+running with the \fI\%--dbpath\fP option and MongoDB uses an
+on\-disk format where every database has a distinct
+directory. This option is only relevant when specifying the
+\fI\%--dbpath\fP option.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-journal
+Allows \fI\%mongofiles\fP operations to use the durability
+\fIjournal\fP when running with \fI\%--dbpath\fP
+to ensure that the database maintains a recoverable state. This
+forces \fI\%mongofiles\fP to record all data on disk regularly.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-db <db>, \-d <db>
+Use the \fI\%--db\fP option to specify the MongoDB database that stores
+or will store the GridFS files.
+.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. \fI\%mongofiles\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>, t <MIME>
+Provides the ability to specify a \fIMIME\fP type to describe the
+file inserted into GridFS storage. \fI\%mongofiles\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
+.SH USE
+.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:
+.sp
+.nf
+.ft C
+mongofiles \-d records list
+.ft P
+.fi
+.sp
+This \fI\%mongofiles\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:
+.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
+.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:
+.sp
+.nf
+.ft C
+mongofiles \-d records put 32\-corinth.lp
+.ft P
+.fi
+.sp
+To delete the \fB32\-corinth.lp\fP file from this GridFS collection in
+the \fBrecords\fP database, you can use the following command:
+.sp
+.nf
+.ft C
+mongofiles \-d records delete 32\-corinth.lp
+.ft P
+.fi
+.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:
+.sp
+.nf
+.ft C
+mongofiles \-d records search corinth
+.ft P
+.fi
+.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:
+.sp
+.nf
+.ft C
+mongofiles \-d records list 32
+.ft P
+.fi
+.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:
+.sp
+.nf
+.ft C
+mongofiles \-d records get 32\-corinth.lp
+.ft P
+.fi
+.SH AUTHOR
+MongoDB Documentation Project
+.SH COPYRIGHT
+2011-2013, 10gen, Inc.
+.\" Generated by docutils manpage writer.
+.