> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Configuration

You can configure [mongosync](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-label-c2c-mongosync) instances at startup by using [command line options](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-label-c2c-cli-options) or a configuration file. The configuration file specifies values for settings that are the equivalent of `mongosync` command line options.

During a migration, you can reconfigure certain `mongosync` settings by following the steps in  [Reconfigure `mongosync` During Synchronization.](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#std-label-c2c-reconfigure-mid-migration)

## Configuration File

You can write most `mongosync` [command line options](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-label-c2c-cli-options) to a YAML file. The configuration file specifies values for each setting using YAML format.

For example:

```yaml
cluster0: "mongodb://192.0.2.10:27017"
cluster1: "mongodb://192.0.2.20:27017"
logPath: "/var/log/mongosync"
verbosity: "WARN"

```

To use a configuration file, start `mongosync` with the [`--config`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--config) option to set the path to the file:

```shell
mongosync --config <configPath>

```

### Settings

You can configure the following `mongosync` settings using a configuration file.

To configure `mongosync` from the command line, see [Command Line Options.](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-label-c2c-cli-options)

**Note:**

The `start` command provides additional options for features like `reversibility`. For more details, see the [start](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start) API documentation.

*Type*: bool

Accepts disclaimers for the [embedded verifier.](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-behavior.md#std-label-c2c-verifier-disclaimer)

When the `mongosync` process starts without this setting, the user is prompted to accept each disclaimer.

This setting allows users who have already read and accepted disclaimers to accept the disclaimer and start the `mongosync` process.

To set the `acceptDisclaimer` setting from the command line, see the [`--acceptDisclaimer`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--acceptDisclaimer) option.

**New in version 1.9**

*Type*: string

Sets the [connection URI](https://www.mongodb.com/docs/manual/reference/connection-string.md#std-label-mongodb-uri) for the first cluster. The first cluster can serve as either the source or the destination in the sync process. Designate the source and destination clusters in the call to the [`start`](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start) API endpoint.

For more information on connecting `mongosync`, see [Connections.](https://www.mongodb.com/docs/mongosync/current/connecting.md#std-label-c2c-connecting)

To set the `cluster0` setting from the command line, see the [`--cluster0`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--cluster0) option.

*Type*: string

Sets the [connection URI](https://www.mongodb.com/docs/manual/reference/connection-string.md#std-label-mongodb-uri) for the second cluster. The second cluster can serve as either the source or the destination in the sync process. Designate the source and destination clusters in the call to the [`start`](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start) API endpoint.

For more information on connecting `mongosync`, see [Connections.](https://www.mongodb.com/docs/mongosync/current/connecting.md#std-label-c2c-connecting)

To set the `cluster1` setting from the command line, see the [`--cluster1`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--cluster1) option.

**New in version 1.19.0**

*Type*: integer

*Minimum*: `1`

*Maximum*: `64`

Explicitly set the batch size for index builds on destination clusters. By default, `mongosync` programmatically optimizes this value on Atlas destination clusters.

**Warning:**

Ensure that you have allocated 100 MB-1 GB of memory per index. Additionally, ensure that the total memory used by concurrent index builds remains under 20% of the destination cluster's RAM. Allocating more than 20% of the destination RAM for index builds can interfere with the filesystem cache, reducing memory available for buffering writes to the destination cluster.

For more information, see [Index Build Optimizations.](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-behavior.md#std-label-mongosync-index-build-optimizations)

To set the `createIndexesBatchSize` setting from the command line, see the [`--createIndexesBatchSize`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--createIndexesBatchSize) option.

*Type*: boolean

**New in version 1.16.0**

Disables metrics logging when you run the Mongosync binary.

**Warning:**

It is strongly recommended to keep metrics logging enabled to facilitate effective troubleshooting and support.

For more information, see [Mongosync Metrics.](https://www.mongodb.com/docs/mongosync/current/reference/metrics.md#std-label-c2c-metrics)

To set the `disableMetricsLogging` setting from the command line, see the [`--disableMetricsLogging`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--disableMetricsLogging) option.

For more information, see [User Data Collection.](https://www.mongodb.com/docs/mongosync/current/reference/telemetry.md#std-label-c2c-telemetry)

*Type*: boolean

**New in version 1.4.0**

Disables the collection of [telemetry data](https://www.mongodb.com/docs/mongosync/current/reference/telemetry.md#std-label-c2c-telemetry) for `mongosync`.

By default, `mongosync` collects anonymous, aggregated usage data to improve MongoDB products. When you run `mongosync` you can disable collection of this telemetry data.

To set the `disableTelemetry` setting from the command line, see the [`--disableTelemetry`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--disableTelemetry) option.

For more information, see [User Data Collection.](https://www.mongodb.com/docs/mongosync/current/reference/telemetry.md#std-label-c2c-telemetry)

*Type*: boolean

Disables the [Embedded Verifier](https://www.mongodb.com/docs/mongosync/current/reference/verification/embedded.md#std-label-c2c-embedded-verifier). When disabled, `mongosync` does not verify the migration. For alternative verification methods, see [Verify Data Transfer.](https://www.mongodb.com/docs/mongosync/current/reference/verification.md#std-label-c2c-verification)

This option provides a workaround for customers who experience OOM kills when running `mongosync` with verification and cannot allocate more resources or tolerate restarting verification. It allows the migration to complete with verification disabled. Verification remains disabled for subsequent restarts and reversals.

This option should not be used when `mongosync` is initially started. Instead, disable verification with the [/start](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start) request parameter `verification.enabled:
  false` since verification is enabled by default.

To disable verification from the command-line, see the [`--disableVerification`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--disableVerification) option.

**New in version 1.10**

*Type*: boolean

`mongosync` requires you to pass this flag to enable creating new capped collections during a migration.

Set to `true` to enable creating new capped collections during a migration. Defaults to `false`.

To set the `enableCappedCollectionHandling` setting from the command line, see the [`--enableCappedCollectionHandling`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--enableCappedCollectionHandling) option.

**New in version 1.20**

*Type*: string

Sets an identifer for hot documents, or documents that update very frequently on source clusters. `mongosync` then copies these documents during the migration commit stage.

Use this setting for migrations that have replication lag due to hot documents when running `mongosync`.

Provide the identifers in the following format:

```text
{
   “db”: <string>, // the name of the database
   "collection" : <string>, // name of the collection
   "ids"    : [ {“_id”:<Object>”}, ...],
}
```

The objects in the `ids` field must be valid [canonical mode extended JSON strings.](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#std-label-mongodb-extended-json-v2)

You can use this setting multiple times to provide hot document identifiers from multiple collections. The following is an example that provides two hot document identifiers from collections `coll1` and `coll2`:

```text
mongosync \
--hotDocIDs '{"db":"db1","collection":"coll1","ids":[{"_id":{"$oid":"doc1"}},{"_id":{"$oid":"6aa23c249cef3cd958e43785"}}]}' \
--hotDocIDs '{"db":"db2","collection":"coll2","ids":[{"_id":{"$oid":"70023c249cef3cd958e43269"}},{"_id":{"$oid":"7aa23c249cef3cd958e43785"}}]}' \
... other CLI arguments ...
```

During an in-progress migration, you can add more hot document identifiers. To add identifiers, stop `mongosync`, update the [`--hotDocIDs`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--hotDocIDs) option or [`hotDocIDs`](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#mongodb-setting-hotDocIDs) setting with the new identifiers, and resume the migration. `mongosync` retains all supplied identifiers across restarts.

You cannot remove supplied hot document identifiers during a migration. To restart the migration from scratch and remove or correct supplied identifiers, see [Restart `mongosync`.](https://www.mongodb.com/docs/mongosync/current/reference/restart-mongosync.md#std-label-mongosync-restart-migration)

**Note:**

`mongosync` does not retain hot documents on a [reverse](https://www.mongodb.com/docs/mongosync/current/reference/api/reverse.md#std-label-c2c-api-reverse) sync. If replication lag occurs due to hot documents during a reverse sync, restart the `mongosync` process and specify the hot document identifiers for the reverse direction. Do not restart the migration from scratch.

To set the `hotDocIDs` from the command line, see the [`--hotDocIDs`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--hotDocIDs) option.

*Type*: string

Sets an identifier for the `mongosync` instance.

Use this setting when running multiple instances of `mongosync` on a sharded cluster, to synchronize the shards individually.

The identifier value for this setting must correspond to the shard ID of the shard it syncs.  To find the shard ID, use the [`listShards`](https://www.mongodb.com/docs/manual/reference/command/listShards.md#mongodb-dbcommand-dbcmd.listShards) command.

To set the `id` setting from the command line, see the [`--id`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--id) option.

*Type*: integer

*Default*: `3`

Sets the cluster workload level for syncing data between the source and destination clusters:

- `4`, the highest setting, maximizes cluster workload and syncs data the fastest.

- `1`, the lowest setting, minimizes cluster workload and syncs data the slowest.

To set the `loadLevel` setting from the command line, see the [`--loadLevel`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--loadLevel) option.

**Warning:**

Setting `loadLevel` higher than the default of `3` may negatively impact the destination cluster performance.

If read bottlenecks exist on the source cluster or if write bottlenecks exist on the destination cluster, decreasing `loadLevel` might improve performance.

**New in version 1.4**

*Type*: string

Sets the path to the log directory. Mongosync writes logs to files in this directory.

For more information, see [Logging.](https://www.mongodb.com/docs/mongosync/current/reference/logging.md#std-label-c2c-logging)

To set the `logPath` setting from the command line, see the [`--logPath`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--logPath) option.

*Type*: string

**New in version 1.16.0**

Sets the path to the metrics log directory. Mongosync writes metrics logs to files in this directory.

For more information, see [Mongosync Metrics.](https://www.mongodb.com/docs/mongosync/current/reference/metrics.md#std-label-c2c-metrics)

To set the `metricsLoggingFilepath` setting from the command line, see the [`--metricsLoggingFilepath`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--metricsLoggingFilepath) option.

*Type*: integer

*Default*: `27182`

Sets the port used by the HTTP server for the Mongosync HTTP API.

To set the `port` setting from the command line, see the [`--port`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--port) option.

*Type*: string

*Default*: `DEBUG`

Sets the verbosity level to use in log messages. Mongosync logs all messages at the specified level and any messages at lower levels.

The `verbosity` setting supports the following values:

- `TRACE`

- `DEBUG`

- `INFO`

- `WARN`

- `ERROR`

- `FATAL`

- `PANIC`

To set the `verbosity` setting from the command line, see the [`--verbosity`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--verbosity) option.

## Reconfigure `mongosync` During Synchronization

**Important:**

Only the following settings can be adjusted during a migration. Other settings **must** remain unchanged between `mongosync` restarts.

While `mongosync` is syncing, you can reconfigure the following options by performing the steps in this section:

- [`--config`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--config)

- [`--createIndexesBatchSize`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--createIndexesBatchSize)

- [`--disableTelemetry`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--disableTelemetry)

- [`--hotDocIDs`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--hotDocIDs)

- [`--loadLevel`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--loadLevel)

- [`--logPath`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--logPath)

- [`--port`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--port)

- [`--verbosity`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--verbosity)

1. (Optional) Pause the `mongosync` processes

   Run [`pause`](https://www.mongodb.com/docs/mongosync/current/reference/api/pause.md#std-label-c2c-api-pause) on each running `mongosync` process.

   You can resume the `mongosync` processes later from the paused state, as shown in the final step.

   **Tip:**

   If you don't want to immediately resume data synchronization operations after reconfiguration, consider pausing the `mongosync` processes. This is useful if you're coordinating operations from multiple `mongosync` processes.

2. Stop the `mongosync` processes

   Use your operating system to stop each running `mongosync` process. For the specific steps, see your operating system documentation.

3. (Optional) Update your configuration file

   If you used the [`--config`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--config) option to set the path to a configuration file when you first initialized `mongosync`, update this configuration file with the new value for each setting.

4. Initialize the `mongosync` processes

   If you updated a configuration file in the last step, initialize the `mongosync` processes with the [`--config`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--config) option set to the path of the updated configuration file:

   ```shell
   mongosync --config <configPath>

   ```

   If you did  *not*  use the [`--config`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--config) option when you first initialized `mongosync`, initialize the `mongosync` processes with the command line options set to their updated values:

   ```shell
   mongosync \
         --cluster0 "<cluster0_connection_string>" \
         --cluster1 "<cluster1_connection_string>" \
         --loadLevel <newLevel> 

   ```

   For more information, see [Initialize mongosync.](https://www.mongodb.com/docs/mongosync/current/quickstart.md#std-label-c2c-initialize)

5. Start or Resume the `mongosync` processes

   If you paused any `mongosync` processes earlier in the optional first step, run [`resume`](https://www.mongodb.com/docs/mongosync/current/reference/api/resume.md#std-label-c2c-api-resume) on the paused `mongosync` processes.

   If you stopped any `mongosync` processes without using [`pause`](https://www.mongodb.com/docs/mongosync/current/reference/api/pause.md#std-label-c2c-api-pause), run [`start`](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start) on the stopped `mongosync` processes. For more detailed instructions, see [Migrate Data Between Clusters.](https://www.mongodb.com/docs/mongosync/current/quickstart.md#std-label-c2c-quickstart-synchronize)

   `mongosync` resumes the sync roughly where it was before you stopped the earlier proceses. Any partitions that were in progress at the time of termination will restart from the beginning.