Skip to content

DOCS-140 review #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 7, 2012
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions source/administration/configuration.rst
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ and settings, this document primarily uses the configuration file
interface. If you run MongoDB using a control script or packaged for
your operating system, you likely already have a configuration file
located at ``/etc/mogondb.conf``. Confirm this by checking the content
of the ``/etc/init.d/mongodb`` or ``/etc/rc.d/mongodb`` script to
insure that the :term:`control scripts <control script>` starts the
of the ``/etc/init.d/mongod`` or ``/etc/rc.d/mongod`` script to
insure that the :term:`control scripts <control script>` start the
:program:`mongod` with the appropriate configuration file (see below.)

To start MongoDB instance using this configuration issue a command in
Expand Down Expand Up @@ -202,6 +202,8 @@ different configurations. The config servers stores the cluster's
metadata, while the cluster distributes data among one or more
shard servers.

TODO: Make a point that the config servers are not a replica set?

To set up one or three "config server" instances as :ref:`normal
<base-config>` :program:`mongod` instances, and then add the following
configuration option:
Expand Down Expand Up @@ -345,3 +347,5 @@ needed:
addition to tools such as :program:`iostat`, :program:`vmstat`, or
:program:`top` to provide insight into the state of the system
in context of the log.

TODO: This setting doesn't actually work as explained. See here: https://jira.mongodb.org/browse/CS-2260?focusedCommentId=86579&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-86579
81 changes: 73 additions & 8 deletions source/reference/configuration-options.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@ Administrators and users can control :program:`mongod` or
configuration file.

While both methods are functionally equivalent and all settings are
similar, The configuration file method is preferable and if you
installed from a package and starting MongoDB using your system's
similar, the configuration file method is preferable. If you
installed from a package and have started MongoDB using your system's
:term:`control script`, you're already using a configuration file.

To start :program:`mongod` or :program:`mongos` using a config file,
Expand All @@ -27,12 +27,16 @@ use one of the following forms:
mongos --config /srv/mongodb/mongos.conf
mongos -f /srv/mongodb/mongos.conf

Declare All settings in this file using the following form:
Declare all settings in this file using the following form:

.. code-block:: sh

<setting> = <value>

TODO: This is not completely accurate. Some settings are <setting>=<value> (no spacing).
Ref here: https://github.com/mongodb/mongo/blob/master/rpm/mongod.conf
This is probably something we should standardize on with no spaces and settings in ALLCAPS being the default.

.. versionadded:: 2.0
*Before* version 2.0, boolean (i.e. "``true|false``") or "flag"
parameters, register as true, if they appear in the configuration
Expand All @@ -50,6 +54,8 @@ Settings
Increases the amount of internal reporting returned on standard
output or in the log file generated by :setting:`logpath`.

TODO: I would figure out a way to collapse these, and try to explain the levels of verbosity. I cannot enumerate them yet.

.. setting:: v

*Default:* false
Expand Down Expand Up @@ -82,6 +88,8 @@ Settings

.. setting:: quiet

TODO: Since we've declared above that configs can be used for mongod and mongos, either state that the config item applies to both, or don't state that at all.

*Default:* false

Runs the :program:`mongod` instance in a quiet mode that attempts to limit
Expand All @@ -99,6 +107,8 @@ Settings

*Default:* 127.0.0.1

TODO: I think this is not true. I think we default to *, and SHOULD default to 127.0.0.1

Set this option to configure the :program:`mongod` process to bind
to and listen for connections from applications on this
address. You may attach :program:`mongod` to any interface;
Expand All @@ -112,6 +122,7 @@ Settings
.. setting:: maxConns

*Default:* depends on system settings.
TODO: Enumerate what system setting this is dependent on.

Specifies a value to set the maximum number of simultaneous
connections that :program:`mongod` or :program:`mongos` will
Expand All @@ -131,6 +142,9 @@ Settings

*Default:* false

TODO: Since this option tells me that invalid BSON data would never get inserted to the DB, we should explain why the default is false.
I believe it has to do with overhead, and we should explain what that is.

Set to ``true`` to force :program:`mongod` to validate all requests
from clients upon receipt to ensure that invalid objects are never
inserted into the database.
Expand All @@ -139,19 +153,25 @@ Settings

*Default:* None. (i.e. ``/dev/stdout``)

TODO: Explain that this setting to to a filename, _not_ a directory.

Specify a path for the log file that will hold all diagnostic
logging information.

Unless specified, :program:`mongod` will output all log information
to the standard output. Unless :setting:`logappend` is ``true``,
the logfile will be overwritten when the process restarts.

TODO: Follow this ticket for behavioral change on this topic: https://jira.mongodb.org/browse/SERVER-4499

.. setting:: logappend

*Default:* false

Set to ``true`` to add new entries to the end of the logfile rather
than overwriting the content of the log when the process restarts.

TODO: same as above

.. setting:: syslog

Expand Down Expand Up @@ -205,6 +225,8 @@ Settings

Set to ``true`` to enable a :term:`daemon` mode for :program:`mongod`
which forces the process to the background.

TODO: "forces" vs "forks"?

.. setting:: auth

Expand Down Expand Up @@ -232,11 +254,13 @@ Settings

Set this value to designate a directory for the :program:`mongod`
instance to store its data. Typical locations include:
"``/srv/mognodb``", "``/var/lib/mongodb``" or "``/opt/mongodb``"
"``/srv/mongodb``", "``/var/lib/mongodb``" or "``/opt/mongodb``"

Unless specified, :program:`mongod` creates data files in the
default ``/data/db`` directory. (Windows systems use the
``\data\db`` directory.)

TODO: Inaccurate. While we expect this dir by default, if it does not exist on first run, mongod will error out and exit. Also, packages have distinct locations for db storage that are created upon install and the conf for those has it applied.

.. setting:: diaglog

Expand All @@ -246,6 +270,8 @@ Settings
:program:`mongod` instance. Possible values, and their impact are
as follows.

TODO: Explain which diaglog this is, since we call the "logpath" for diagnostic logging, and this logging may be in another log file.

========= ===================================
**Value** **Setting**
--------- -----------------------------------
Expand All @@ -264,10 +290,15 @@ Settings
to store each database's files in a distinct folder. Use this option to
configure MongoDB to store data on a number of distinct disk
devices to increase write throughput or disk capacity.

TODO: Explain the distinct folder naming scheme

Unless specified, :program:`mongod` saves all database files in the
directory specified by :setting:`dbpath`.

TODO: Since all files will be in dpath anyways, and just branch off the root of that dir, maybe this statement should be explained better.


.. setting:: journal

*Default:* (on 64-bit systems) true
Expand Down Expand Up @@ -316,11 +347,15 @@ Settings

For consistency use the :setting:`auth` option.

TODO: I didn't see a refernce here for the auth setting - is it missing? Should we have both auth and noauth?

.. setting:: nohttpinterface

*Default:* false

Set to ``true`` to disable the HTTP interface.

TODO: Does disabling with nohttp override jsonp and rest commands? Do they reenable http? Don't know.

.. setting:: nojournal

Expand All @@ -332,6 +367,8 @@ Settings
default, :program:`mongod` enables journaling in 64-bit versions
after v2.0.

TODO: Same as auth/noauth - what do we do with journal/nojournal?

.. setting:: noprealloc

*Default:* false
Expand Down Expand Up @@ -360,7 +397,7 @@ Settings
Specify this value in megabytes.

Use this setting to control the default size for all newly created
namespace files (i.e ``.NS``). This option has no impact on the
namespace files (i.e ``.ns``). This option has no impact on the
size of existing namespace files.

The default value is 16 megabytes, this provides for effectively
Expand All @@ -374,6 +411,8 @@ Settings
inserts information about operation performance into output of
:program:`mongod` or the log file. The following levels are
available:

TODO: "or the log file" - maybe explain why it would go to the logfile? If `logpath is specified`?

========= ==================================
**Level** **Setting**
Expand All @@ -383,7 +422,7 @@ Settings
2 On. Includes all operations.
========= ==================================

By default, :program:`mongod` disables profiling Database profiling
By default, :program:`mongod` disables profiling. Database profiling
can impact database performance because the profiler must record
and process all database operations. Enable this option only after
careful consideration.
Expand Down Expand Up @@ -459,12 +498,14 @@ Settings
file size for data files and limits the maximum file size to 512
megabytes. Use :setting:`smallfiles` if you have a large number of
databases that each holds a small quaint of data.

TODO: I think "quaint" in the last line is quaint, but probably meant amount or something else.

.. setting:: syncdelay

*Default:* 60

This setting contrils the maximum number of seconds between disk
This setting controls the maximum number of seconds between disk
syncs. While :program:`mongod` is always writing data to disk, this
setting controls the maximum guaranteed interval between a
successful write operation and the next time the database flushes
Expand All @@ -489,6 +530,15 @@ Settings

More typically, run this operation by way of the :option:`mongod
--sysinfo` command.

TODO: What kind of system info is returned? Is it helpful, used in any way?
Here's an output from a production server:
Tue Mar 6 13:48:57 sysinfo:
Tue Mar 6 13:48:57 page size: 4096
Tue Mar 6 13:48:57 _SC_PHYS_PAGES: 4116145
Tue Mar 6 13:48:57 _SC_AVPHYS_PAGES: 30950

I don't know what these values mean, nor what units they are measured in.

.. setting:: upgrade

Expand All @@ -503,6 +553,8 @@ Settings

When specified for a :program:`mongos` instance, this option updates
the meta data format used by the :term:`config database`.

TODO: Is this still a thing? When/where do we tell someone to run this command?

Replica Set Options
```````````````````
Expand All @@ -523,6 +575,11 @@ Replica Set Options
secondary or slave will be permanently out of sync with the
primary, which may cause significant consistency problems.

TODO: Since we recommend a resync as a recommended method of bringing up a new member of a replica set, is this part of replsets, or master/slave?
I found this:
--fastsync If the node has a completely up-to-date copy of the data, use this option to let it know it can skip the resync. Be careful – the server will assume it is caught up completely and if not so the data will be out of sync permanently.
here: http://www.mongodb.org/display/DOCS/Command+Line+Parameters

.. setting:: oplogSize

o Specifies a maximum size in megabytes for the replication operation
Expand Down Expand Up @@ -563,6 +620,8 @@ Master/Slave Replication

Used with the :setting:`slave` option, the ``only`` setting
specifies only a single :term:`database` to replicate.

TODO: I don't think this is a true/false, rather a db name

.. setting:: slavedelay

Expand Down Expand Up @@ -591,6 +650,8 @@ Master/Slave Replication
Replica Set Options
```````````````````

TODO: Is it me, or are there two replica set options sections?

.. setting:: replSet

*Default:* <none>
Expand All @@ -602,13 +663,15 @@ Replica Set Options
Use this setting to configure replication with replica
sets. Specify a replica set name as an argument to this set. All
hosts must have the same set name. You can add one or more "seed"
hosts to one or more host in the set to initiate the cluster. Use
hosts to one or more hosts in the set to initiate the cluster. Use
the following form: ::

replSet = <setname>/<host1>,<host2>:<port>

When you add or reconfigure the replica set on one host, these
changes propagate throughout the cluster.

TODO: Do they? If they are set in a config file, then probably not. Maybe "When you add or reconfig.. should be propagated"?

Sharding Cluster Options
````````````````````````
Expand Down Expand Up @@ -648,6 +711,8 @@ Sharding Cluster Options
(i.e. :term:`config database`) for the :term:`shard cluster`. You may
specify either 1 configuration server or 3 configuration servers,
in a comma separated list.

TODO: May vs must?

This setting only affects :program:`mongos` processes.

Expand Down
2 changes: 1 addition & 1 deletion source/reference/mongod.rst
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,7 @@ Options
.. option:: --cpu

Forces :program:`mongod` to report the percentage of CPU time in
write lock. :program:`mongod` generates output ever four
write lock. :program:`mongod` generates output every four
seconds. MongoDB writes this data to standard output or the logfile
if using the :setting:`logpath` option.

Expand Down