-
Notifications
You must be signed in to change notification settings - Fork 1.7k
/
replica-configuration.txt
603 lines (389 loc) · 17.8 KB
/
replica-configuration.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
=========================
Replica Set Configuration
=========================
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
You can access the configuration of a :term:`replica set` using the
:method:`rs.conf()` method or the :dbcommand:`replSetGetConfig` command.
To modify the configuration for a replica set, use the
:method:`rs.reconfig()` method, passing a configuration document to the
method. See :method:`rs.reconfig()` for more information.
.. warning::
.. include:: /includes/warning-mixed-version-rs-config.rst
.. _replica-set-configuration-settings:
.. _replica-set-configuration-document:
Replica Set Configuration Document Example
------------------------------------------
.. include:: /includes/replica-set-conf-document-output.rst
.. _replSetGetConfig-output:
Replica Set Configuration Fields
--------------------------------
.. rsconf:: _id
*Type*: string
The name of the replica set.
:rsconf:`_id` *must* be identical to the
:setting:`replication.replSetName` or the value of `--replSet`
specified to :binary:`~bin.mongod` on the command line.
.. see::
:setting:`~replication.replSetName` or :option:`--replSet <mongod --replSet>`
for information on setting the replica set name.
.. rsconf:: version
*Type*: int
An incrementing number used to distinguish revisions of the replica
set configuration object from previous iterations of the
configuration.
.. rsconf:: configsvr
.. versionadded:: 3.2
*Type*: boolean
*Default*: false
Indicates whether the replica set is used for a sharded cluster's
config servers. Set to ``true`` if the replica set is for a sharded
cluster's config servers.
.. seealso:: :ref:`3.2-rel-notes-sharded-cluster`
.. rsconf:: protocolVersion
.. versionadded:: 3.2
*Type*: number
*Default*: 1
Starting in 4.0, MongoDB only supports ``protocolVersion: 1`` and no
longer supports ``protocolVersion: 0``.
.. seealso:: :doc:`/reference/replica-set-protocol-versions`
.. rsconf:: writeConcernMajorityJournalDefault
.. versionadded:: 3.2.6
*Type*: boolean
*Default*: true
Determines the behavior of :writeconcern:`{ w: "majority" }
<"majority">` write concern if the write concern does not explicitly
specify the journal option :ref:`j <wc-j>`.
The following table lists the ``writeConcernMajorityJournalDefault``
values and the associated :writeconcern:`{ w: "majority" }
<"majority">` behavior:
.. list-table::
:header-rows: 1
:widths: 15 85
* - Value
- ``{ w: "majority" }`` Behavior
* - true
- MongoDB acknowledges the write operation after a majority of
the voting members have written to the on-disk journal.
.. important::
All voting members of the replica set must run with
journaling when ``writeConcernMajorityJournalDefault``
is ``true``.
.. include:: /includes/extracts/no-journaling-writeConcernMajorityJournalDefault-true.rst
* - false
- MongoDB acknowledges the write operation after a majority of
the voting members have applied the operation in
memory.
.. warning::
.. include:: /includes/extracts/no-journaling-writeConcernMajorityJournalDefault-false.rst
.. include:: /includes/changes-inmem-startup-warning.rst
.. seealso:: :ref:`wc-ack-behavior`, :doc:`/reference/replica-set-protocol-versions`
``members``
~~~~~~~~~~~
.. rsconf:: members
*Type*: array
An array of member configuration documents, one for each member
of the replica set. The :rsconf:`members` array
is a zero-indexed array.
Each member-specific configuration document can contain the following
fields:
.. rsconf:: members[n]._id
*Type*: integer
An integer identifier of every member in the replica set.
Values must be between 0 and 255 inclusive. Each replica set member
must have a unique :rsconf:`_id<members[n]._id>`.
Once set, you cannot change the :rsconf:`_id<members[n]._id>` of a member.
.. note::
.. include:: /includes/fact-rs-conf-array-index.rst
.. rsconf:: members[n].host
*Type*: string
The hostname and, if specified, the port number, of the set
member.
The hostname name must be resolvable for every host in the
replica set.
.. warning::
:rsconf:`members[n].host` cannot hold a
value that resolves to ``localhost`` or the local interface
unless *all* members of the set are on hosts that resolve to
``localhost``.
.. rsconf:: members[n].arbiterOnly
*Optional*.
*Type*: boolean
*Default*: false
A boolean that identifies an arbiter. A value of ``true``
indicates that the member is an arbiter.
When using the :method:`rs.addArb()` method to add an arbiter,
the method automatically sets
:rsconf:`members[n].arbiterOnly` to ``true``
for the added member.
.. include:: /includes/extracts/arbiters-and-pvs-with-reference.rst
.. rsconf:: members[n].buildIndexes
*Optional*.
*Type*: boolean
*Default*: true
A boolean that indicates whether the :binary:`~bin.mongod` builds
:term:`indexes <index>` on this member. You can only set this
value when adding a member to a replica set. You cannot change
:rsconf:`members[n].buildIndexes` field after
the member has been added to the set. To add a member, see
:method:`rs.add()` and :method:`rs.reconfig()`.
Do not set to ``false`` for :binary:`~bin.mongod` instances that receive
queries from clients.
Setting ``buildIndexes`` to ``false`` may be useful if **all**
the following conditions are true:
- you are only using this instance to perform backups using
:binary:`~bin.mongodump`, *and*
- this member will receive no queries, *and*
- index creation and maintenance overburdens the host
system.
Even if set to ``false``, secondaries *will* build indexes on the
``_id`` field in order to facilitate operations required for
replication.
.. warning::
If you set
:rsconf:`members[n].buildIndexes` to
``false``, you must also set
:rsconf:`members[n].priority` to ``0``. If
:rsconf:`members[n].priority` is not
``0``, MongoDB will return an error when attempting to add a
member with
:rsconf:`members[n].buildIndexes` equal to
``false``.
To ensure the member receives no queries, you should make all
instances that do not build indexes hidden.
Other secondaries cannot replicate from a member where
:rsconf:`members[n].buildIndexes` is
false.
.. rsconf:: members[n].hidden
*Optional*.
*Type*: boolean
*Default*: false
When this value is ``true``, the replica set hides this instance
and does not include the member in the output of
:method:`db.hello()` or :dbcommand:`hello`. This prevents
read operations (i.e. queries) from ever reaching this host by
way of secondary :term:`read preference`.
Hidden members can acknowledge write operations
issued with :ref:`write-concern`. For write operations issued
with :writeconcern:`"majority"` write concern, the member must
also be a voting member (i.e. :rsconf:`~members[n].votes` is
greater than ``0``).
.. seealso::
:ref:`Hidden Replica Set Members <replica-set-hidden-members>`
.. rsconf:: members[n].priority
.. versionchanged:: 3.6
Starting in MongoDB 3.6, arbiters have the priority ``0``. If an
arbiter has a priority of ``1``, MongoDB 3.6 reconfigures the
arbiter to have a priority of ``0``.
*Optional*.
*Type*: Number between 0 and 1000 for primary/secondary; 0 or 1 for arbiters.
*Default*: 1.0 for primary/secondary; 0 for arbiters.
A number that indicates the relative eligibility of a member to
become a :term:`primary`.
Specify higher values to make a member *more* eligible to become
:term:`primary`, and lower values to make the member *less*
eligible. A member with a :rsconf:`members[n].priority` of ``0`` is
ineligible to become primary.
.. include:: /includes/fact-rs-nonzero-priority-vote-restriction.rst
Changing the balance of priority in a replica set will trigger
one or more elections. If a lower priority secondary is elected
over a higher priority secondary, replica set members will
continue to call elections until the highest priority available
member becomes primary.
Members with :rsconf:`~members[n].priority` of ``0`` can
acknowledge write operations issued with :ref:`write-concern`.
For write operations issued with :writeconcern:`"majority"` write
concern, the member must also be a voting member (i.e.
:rsconf:`~members[n].votes` is greater than ``0``).
.. seealso::
:ref:`Replica Set Elections <replica-set-elections>`.
.. rsconf:: members[n].tags
*Optional*.
*Type*: document
*Default*: none
.. include:: /includes/fact-tags-field.rst
.. rsconf:: members[n].slaveDelay
*Optional*.
*Type*: integer
*Default*: 0
The number of seconds "behind" the primary that this
replica set member should "lag".
Use this option to create :ref:`delayed members
<replica-set-delayed-members>`. Delayed members maintain a copy
of the data that reflects the state of the data at some time in
the past.
Delayed members can contribute to acknowledging write
operations issued with :ref:`write-concern`. However,
they return write acknowledgment no earlier than the configured
delay value. For write operations issued with
:writeconcern:`"majority"` write concern, the member must also be
a voting member (i.e. :rsconf:`~members[n].votes` is greater than
``0``).
.. seealso::
:doc:`/core/replica-set-delayed-member`
.. rsconf:: members[n].votes
*Optional*.
*Type*: integer
*Default*: 1
The number of votes a server will cast in a :ref:`replica set
election <replica-set-elections>`. The number of votes each
member has is either ``1`` or ``0``, and :ref:`arbiters
<replica-set-arbiters>` always have exactly ``1`` vote.
.. include:: /includes/fact-rs-nonzero-priority-vote-restriction.rst
A replica set can have up to :limit:`50 members
<Number of Members of a Replica Set>` but only 7 voting members.
If you need more than 7 members in one replica set, set
:rsconf:`members[n].votes` to ``0`` for the
additional non-voting members.
.. versionchanged:: 3.2
.. include:: /includes/fact-rs-non-voting-priority-restriction.rst
.. include:: /includes/members-used-to-allow-multiple-votes.rst
Members with ``0`` votes cannot acknowledge write operations
issued with a :ref:`write-concern` of :writeconcern:`majority`.
``settings``
~~~~~~~~~~~~
.. rsconf:: settings
*Optional*.
*Type*: document
A document that contains configuration options that apply to the
whole replica set.
The :rsconf:`settings` document contain the
following fields:
.. rsconf:: settings.chainingAllowed
*Optional*.
*Type*: boolean
*Default*: true
When :rsconf:`settings.chainingAllowed` is
``true``, the replica set allows :term:`secondary` members to
replicate from other secondary members. When
:rsconf:`settings.chainingAllowed` is
``false``, secondaries can replicate only from the :term:`primary`.
.. seealso:: :doc:`/tutorial/manage-chained-replication`
.. rsconf:: settings.getLastErrorDefaults
*Optional*.
*Type*: document
A document that specifies the :doc:`write concern
</core/replica-set-write-concern>` for the replica set. The
replica set will use this write concern only when :ref:`write
operations <write-methods-incompatibility>` or
:dbcommand:`getLastError` specify no other write concern.
If :rsconf:`settings.getLastErrorDefaults` is
not set, the default write concern for the replica set only
requires confirmation from the primary.
.. rsconf:: settings.getLastErrorModes
*Optional*.
*Type*: document
A document used to define a custom :ref:`write concern
<write-concern>` through the use of :rsconf:`members[n].tags`.
The custom write concern can provide :term:`data-center
awareness`.
.. code-block:: none
{ getLastErrorModes: {
<name of write concern> : { <tag1>: <number>, .... },
...
} }
The ``<number>`` refers to the number of different tag values
required to satisfy the write concern. For example, the following
:rsconf:`settings.getLastErrorModes` defines a write concern
named ``datacenter`` that requires the write to propagate to two
members whose ``dc`` tag values differ.
.. code-block:: none
{ getLastErrorModes: { datacenter: { "dc": 2 } } }
To use the custom write concern, pass in the write concern name
to the :ref:`wc-w`, e.g.
.. code-block:: none
{ w: "datacenter" }
See :doc:`/tutorial/configure-replica-set-tag-sets` for more
information and example.
.. rsconf:: settings.heartbeatTimeoutSecs
*Optional*.
*Type*: int
*Default*: 10
Number of seconds that the replica set members wait for a
successful heartbeat from each other. If a member does not
respond in time, other members mark the delinquent member as
inaccessible.
.. note::
For :rsconf:`pv1 <protocolVersion>`,
:rsconf:`settings.electionTimeoutMillis` has a greater
influence on whether the secondary members call for an
election than the :rsconf:`settings.heartbeatTimeoutSecs`.
.. rsconf:: settings.electionTimeoutMillis
.. versionadded:: 3.2
*Optional*.
*Type*: int
*Default*: 10000 (10 seconds)
The time limit in milliseconds for detecting when a replica set's
primary is unreachable:
- Higher values result in slower failovers but decreased
sensitivity to primary node or network slowness or spottiness.
- Lower values result in faster failover, but increased
sensitivity to primary node or network slowness or spottiness.
The setting only applies when using :rsconf:`protocolVersion: 1`.
.. note::
.. include:: /includes/extracts/rs-stepdown-election-handoff.rst
.. rsconf:: settings.catchUpTimeoutMillis
.. versionadded:: 3.4
*Optional*.
*Type*: int
.. versionchanged:: 3.6
\
*Default*: -1, infinite catchup time.
Time limit in milliseconds for a newly elected primary to sync
(catch up) with the other replica set members that may have more
recent writes. Infinite or high time limits may reduce the
amount of data that the other members would need to roll back
after an election but may increase the failover time.
The newly elected primary ends the catchup period early once it
is fully caught up with other members of the set. During the
catchup period, the newly elected primary is unavailable for
writes from clients. Use :dbcommand:`replSetAbortPrimaryCatchUp`
to abort the catchup then complete the transition to primary.
The setting only applies when using :rsconf:`protocolVersion: 1`.
.. note::
To downgrade a replica set initiated in version 3.6 to 3.4,
change ``catchUpTimeoutMillis`` from ``-1`` to a
positive number. Failure to change this value to a positive
number causes nodes running version 3.4 to neither restart nor
join the replica set.
.. _repl-conf-catchup-takeover-delay:
.. rsconf:: settings.catchUpTakeoverDelayMillis
.. versionadded:: 3.6
*Optional*.
*Type*: int
*Default*: 30000 (30 seconds)
Time in milliseconds a node waits to initiate a
*catchup takeover* after determining it is ahead of the current
:term:`primary`. During a catchup takeover, the node ahead of the
current primary initiates an :term:`election` to become the new
primary of the :term:`replica set`.
After the node initiating the takeover determines that it is
ahead of the current :term:`primary`, it waits the specified
number of milliseconds and then verifies the following:
1. It is still ahead of the current primary,
#. It is the most up-to-date node among all available nodes,
#. The current primary is currently catching up to it.
Once determining that all of these conditions are met, the node
initiating the takeover immediately runs for election.
For more information on Replica
Set Elections, see :doc:`/core/replica-set-elections/`.
.. note::
Setting ``catchUpTakeoverDelayMillis`` to ``-1`` disables
catchup takeover. Setting :rsconf:`catchUpTimeoutMillis` to
``0`` disables *primary catchup* and consequently also catchup
takeover.
.. rsconf:: settings.heartbeatIntervalMillis
.. versionadded:: 3.2
*Internal use only*.
The frequency in milliseconds of the heartbeats.
.. rsconf:: settings.replicaSetId
.. versionadded:: 3.2
*Type*: ObjectId
The ObjectId associated with the replica set and automatically
created during :method:`rs.initiate()` or
:dbcommand:`replSetInitate`. You cannot change the
:setting:`~settings.replicaSetId`.