diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index 8db70382a2d..81e41a8cd61 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -21,13 +21,13 @@ suggestions for administers of replica sets. The following tutorials provide task-oriented instructions for specific administrative tasks related to replica set operation. - - :doc:`/tutorial/change-hostnames-in-a-replica-set` + - :doc:`/tutorial/deploy-replica-set` + - :doc:`/tutorial/expand-replica-set` + - :doc:`/tutorial/deploy-geographically-distributed-replica-set` - :doc:`/tutorial/change-oplog-size` - :doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster` + - :doc:`/tutorial/change-hostnames-in-a-replica-set` - :doc:`/tutorial/convert-secondary-into-arbiter` - - :doc:`/tutorial/deploy-geographically-distributed-replica-set` - - :doc:`/tutorial/deploy-replica-set` - - :doc:`/tutorial/expand-replica-set` .. _replica-set-node-configurations: .. _replica-set-member-configurations: @@ -335,6 +335,10 @@ Procedures .. _replica-set-admin-procedure-add-member: +.. note:: For procedures on deploying replica sets, see + :doc:`/administration/replication-architectures` document + and see the :ref:`list of replica set tutorials `. + Adding Members ~~~~~~~~~~~~~~ @@ -493,12 +497,12 @@ of the member with the highest :data:`members[n].priority` setting. Changing Oplog Size ~~~~~~~~~~~~~~~~~~~ -The following is an overview of the procedure for changing the size of the oplog: +The following is an overview of the procedure for changing the size of +the oplog. For a detailed procedure, see +:doc:`/tutorial/change-oplog-size`. .. include:: /includes/procedure-change-oplog-size.rst -For a detailed procedure, see :doc:`/tutorial/change-oplog-size`. - .. _replica-set-security: Security diff --git a/source/tutorial/deploy-replica-set.txt b/source/tutorial/deploy-replica-set.txt index 567c0f98642..167cdf18993 100644 --- a/source/tutorial/deploy-replica-set.txt +++ b/source/tutorial/deploy-replica-set.txt @@ -4,135 +4,138 @@ Deploy a Replica Set .. default-domain:: mongodb -This tutorial describes the process for deploying a three member -:term:`replica set` , with specific instructions for development and -test as well as for production systems. +This tutorial describes how to deploy a three member +:term:`replica set`, with specific instructions for development +and test systems and for production systems. -.. seealso:: ":doc:`/core/replication`" and - ":doc:`/administration/replication-architectures`" for appropriate - background. +.. seealso:: For appropriate background, see :doc:`/core/replication` + and :doc:`/administration/replication-architectures`. Overview -------- -Three member replica sets provide enough redundancy to survive most +Three member :term:`replica sets ` provide enough redundancy to survive most network partitions and other system failures. Additionally, these sets have sufficient capacity for many distributed read operations. Most -deployments require no additional nodes or configuration. +deployments require no additional members or configuration. Requirements ------------ -Three distinct systems, so that each system can run its own instance -of :program:`mongod`. For development systems you may run all three +A replica set requires three distinct systems so that each system can run its own instance +of :program:`mongod`. For development systems you can run all three instances of the :program:`mongod` process on a local system. (e.g. a laptop) or within a virtual instance. For production environments, you -should endeavor to maintain as much separation between the nodes. For -example, when using VMs in Production, each node should live on +should endeavor to maintain as much separation between the members as possible. For +example, when using VMs in Production, each member should live on separate host servers, served by redundant power circuits, and with redundant network paths. Procedure --------- -This procedure assumes that you already have instances of MongoDB -installed on all systems that you hope to have as members of your -replica set. If you have not already installed MongoDB, see the +These procedures assume you already have instances of MongoDB +installed on the systems you will add as members of your +:term:`replica set`. If you have not already installed MongoDB, see the :ref:`installation tutorials `. -Development and Test Replica Set -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Deploy a Development or Testing Replica Set +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Begin by starting three instances of :program:`mongod`. For ephemeral -tests and the purposes of this guide, you may run the :program:`mongod` -instances in separate windows of GNU Screen. OS X and most Linux -distributions come with screen installed by default [#screen]_ -systems. +The examples in this procedure create a new replica set named ``rs0``. -Issue the following command to create the necessary data directories: +1. Start three instances of :program:`mongod` as members of a replica + set named ``rs0``, as described in this step. For ephemeral tests and + the purposes of this guide, you may run the :program:`mongod` + instances in separate windows of GNU Screen. OS X and most Linux + distributions come with screen installed by default [#screen]_ + systems. -.. code-block:: sh + a. Create the necessary data directories by issuing a command + similiar to the following: - mkdir -p /srv/mongodb/rs0-0 /srv/mongodb/rs0-1 /srv/mongodb/rs0-2 + .. code-block:: sh -Issue the following commands, each in a distinct screen window: + mkdir -p /srv/mongodb/rs0-0 /srv/mongodb/rs0-1 /srv/mongodb/rs0-2 -.. code-block:: sh + #. Issue the following commands, each in a distinct screen window: - mongod --port 27017 --dbpath /srv/mongodb/rs0-0 --replSet rs0 - mongod --port 27018 --dbpath /srv/mongodb/rs0-1 --replSet rs0 - mongod --port 27019 --dbpath /srv/mongodb/rs0-2 --replSet rs0 + .. code-block:: sh -These command start members of a replica set named ``rs0``, each -running on a distinct port. Alternatively, if you are already using these -ports, you can select different ports. See the documentation of the -following options for more information: :option:`--port `, -:option:`--dbpath `, and :option:`--replSet `. + mongod --port 27017 --dbpath /srv/mongodb/rs0-0 --replSet rs0 + mongod --port 27018 --dbpath /srv/mongodb/rs0-1 --replSet rs0 + mongod --port 27019 --dbpath /srv/mongodb/rs0-2 --replSet rs0 -Connect to the :program:`mongod` instance with the :program:`mongo` -shell to the first host. If you're running this command remotely, -replace "localhost" with the appropriate hostname. In a new shell -session, enter the following: + This starts each instance as a member of a replica set named + ``rs0``, each running on a distinct port. If you are already using + these ports, you can select different ports. See the documentation + of the following options for more information: :option:`--port + `, :option:`--dbpath `, and + :option:`--replSet `. -.. code-block:: sh +#. Open a :program:`mongo` shell and connect to the first + :program:`mongod` instance. If you're running this command remotely, + replace "localhost" with the appropriate hostname. In a new shell + session, enter the following: - mongo localhost:27017 + .. code-block:: sh -Issue the following shell function to initiate a replica set -consisting of the current node, using the default configuration: + mongo localhost:27017 -.. code-block:: javascript +#. Use :method:`rs.initiate()` to initiate a replica set consisting of + the current member and using the default configuration: - rs.initiate() + .. code-block:: javascript -Use the following shell function to display the current :doc:`replica -configuration `: + rs.initiate() -.. code-block:: javascript +#. Display the current :doc:`replica configuration `: - rs.conf() + .. code-block:: javascript -Now, issue the following sequence of commands to add two nodes to the -replica set. + rs.conf() -.. code-block:: javascript +#. Add two members to the replica set by issuing a sequence of commands + similar to the following. - rs.add("localhost:27018") - rs.add("localhost:27019") + .. code-block:: javascript -Congratulations, after these commands return you will have a fully -functional replica set. The new replica set should successfully elect -a :term:`primary` node within a few seconds. + rs.add("localhost:27018") + rs.add("localhost:27019") -Check the status of your replica set at any time with the -:method:`rs.status()` operation. + After these commands return you have a fully functional replica set. + New replica sets elect a :term:`primary` within a seconds. -See the documentation of the following shell functions for more -information: :method:`rs.initiate()`, :method:`rs.conf()`, -:method:`rs.reconfig()` and :method:`rs.add()`. +#. Check the status of your replica set at any time with the + :method:`rs.status()` operation. -.. [#screen] `GNU Screen `_ is packaged as - ``screen`` on Debian-based, Fedora/Red Hat-based, and Arch Linux. -.. seealso:: You may also consider the "`simple setup script - `_" +.. seealso:: The documentation of the following shell functions for + more information: + + - :method:`rs.initiate()` + - :method:`rs.conf()` + - :method:`rs.reconfig()` + - :method:`rs.add()` + + You may also consider the `simple setup script + `_ as an example of a basic automatically configured replica set. -Production Replica Set -~~~~~~~~~~~~~~~~~~~~~~ +.. [#screen] `GNU Screen `_ is packaged as + ``screen`` on Debian-based, Fedora/Red Hat-based, and Arch Linux. + +Deploy a Production Replica Set +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Production replica sets are very similar to the development or testing deployment described above, with the following differences: -- Each member of the replica set will reside on it's own machine, and - the MongoDB processes will all bind to port ``27017``, which is the +- Each member of the replica set resides on it's own machine, and + the MongoDB processes all bind to port ``27017``, which is the standard MongoDB port. -- Specify all run-time configuration in :doc:`configuration files - ` rather than as :doc:`command - line options `. - -- Each member of the replica set needs to be accessible by way of +- Each member of the replica set must be accessible by way of resolvable DNS or hostnames in the following scheme: - ``mongodb0.example.net`` @@ -142,89 +145,92 @@ deployment described above, with the following differences: Configure DNS names appropriately, *or* set up your systems' ``/etc/host`` file to reflect this configuration. -Use the following configuration for each MongoDB instance. +- You specify run-time configuration on each system in a + :doc:`configuration file ` stored in + ``/etc/mongodb.conf`` or in a related location. You *do not* specify + run-time configuration through command line options. + + For each MongoDB instance, use the following configuration. Set + configuration values appropriate to your systems: + + .. code-block:: cfg -.. code-block:: cfg + port = 27017 - port = 27017 + bind_ip = 10.8.0.10 - bind_ip = 10.8.0.10 + dbpath = /srv/mongodb/ - dbpath = /srv/mongodb/ + fork = true - fork = true + replSet = rs0 - replSet = rs0 + You do not need to specify an interface with :setting:`bind_ip`. + However, if you do not specify an interface, MongoDB listens for + connections on all available IPv4 interfaces. Modify + :setting:`bind_ip` to reflect a secure interface on your system that + is able to access all other members of the set *and* on which all + other members of the replica set can access the current member. The + DNS or host names must point and resolve to this IP address. + Configure network rules or a virtual private network (i.e. "VPN") to + permit this access. -You do not need to specify an interface with -:setting:`bind_ip`. However, if you do not specify an interface, -MongoDB will listen for connections on all available IPv4 -interfaces. Modify :setting:`bind_ip` to reflect a secure interface on -your system that will be able to access all other members of the set -*and* on which all other members of the replica set can access the -current node. The DNS or host names need to point and resolve to this -IP address. Configure network rules or a virtual private network -(i.e. "VPN") to permit this access. + For more documentation on run time options used above and on + additional configuration options, see + :doc:`/reference/configuration-options`. -For more documentation of the run time options used above, see: -:setting:`dbpath`, :setting:`port`, :setting:`replSet`, -:setting:`bind_ip`, and :setting:`fork`. Also consider any additional -:doc:`configuration options ` that -your deployment may require. +To deploy a production replica set: -Store the configuration file on each system, at ``/etc/mongodb.conf`` -or a related location on the file system. +1. On each system start the :program:`mongod` process by issuing a + command similar to following: -On each system issue the following command to start the -:program:`mongod` process: + .. code-block:: sh -.. code-block:: sh + mongod --config /etc/mongodb.conf - mongod --config /etc/mongodb.conf + .. note:: -.. note:: + In production deployments you likely want to use and configure a + :term:`control script` to manage this process based on this + command. Control scripts are beyond the scope of this document. - In production deployments you likely want to use and configure a - :term:`control script` to manage this process based on this - command. Control scripts are beyond the scope of this document. +#. Open a :program:`mongo` shell connected to this host: -Log in with the :program:`mongo` shell to this host using the following -command: + .. code-block:: sh -.. code-block:: sh + mongo - mongo +#. Use :method:`rs.initiate()` to initiate a replica set consisting of + the current member and using the default configuration: -Issue the following shell function to initiate a replica set -consisting of the current node, using the default configuration: + .. code-block:: javascript -.. code-block:: javascript + rs.initiate() - rs.initiate() +#. Display the current :doc:`replica configuration `: -Use the following shell function to display the current :doc:`replica -configuration `: + .. code-block:: javascript -.. code-block:: javascript + rs.conf() - rs.config() +#. Add two members to the replica set by issuing a sequence of commands + similar to the following. -Now, issue the following sequence of commands to add two nodes to the -replica set. + .. code-block:: javascript -.. code-block:: javascript + rs.add("mongodb1.example.net") + rs.add("mongodb2.example.net") - rs.add("mongodb1.example.net") - rs.add("mongodb2.example.net") + After these commands return you have a fully functional replica set. + New replica sets elect a :term:`primary` within a seconds. -Congratulations, after these commands return you will have a fully -functional replica set. New replica sets will elect a :term:`primary` -within a few moments. +#. Check the status of your replica set at any time with the + :method:`rs.status()` operation. .. seealso:: The documentation of the following shell functions for more information: - - :method:`rs.initiate()`, - - :method:`rs.conf()`, - - :method:`rs.reconfig()`, and - - :method:`rs.add()`. + - :method:`rs.initiate()` + - :method:`rs.conf()` + - :method:`rs.reconfig()` + - :method:`rs.add()`