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

# `mongosync` Binary

## Definition

The `mongosync` binary is the primary process used in Mongosync. `mongosync` migrates data from a source cluster to a destination cluster until you [finalize](https://www.mongodb.com/docs/mongosync/current/about-mongosync.md#std-label-c2c-about-finalizing) the sync.

For an overview of the `mongosync` process, see [About `mongosync`.](https://www.mongodb.com/docs/mongosync/current/about-mongosync.md#std-label-about-mongosync)

To get started with `mongosync`, refer to the [Quick Start Guide.](https://www.mongodb.com/docs/mongosync/current/quickstart.md#std-label-c2c-quickstart)

The [Frequently Asked Questions (FAQ)](https://www.mongodb.com/docs/mongosync/current/faq.md#std-label-c2c-faq) page addresses questions users have asked about `mongosync`.

## Compatibility

- For details on version compatibility requirements, see [MongoDB Server Version Compatibility.](https://www.mongodb.com/docs/mongosync/current/reference/supported-server-version.md#std-label-c2c-server-version-compatibility)

- `mongosync` supports replica sets and sharded clusters.

- Standalone MongoDB instances are not supported. [Convert the standalone instance](https://www.mongodb.com/docs/manual/tutorial/convert-standalone-to-replica-set.md#std-label-server-replica-set-deploy-convert) to a replica set before using Mongosync.

- `mongosync` does not support Atlas shared clusters or serverless instances.

- For a full list of limitations, see [Mongosync Limitations.](https://www.mongodb.com/docs/mongosync/current/reference/limitations.md#std-label-c2c-limitations)

## Syntax

The `mongosync` command layout below is modified for display. To connect `cluster0` to `cluster1` with `mongosync`, enter the following command on one line:

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

```

For more information about connection strings, see the connection documentation for your cluster architecture:

- [Atlas to Atlas](https://www.mongodb.com/docs/mongosync/current/connecting/atlas-to-atlas.md#std-label-c2c-conn-atlas2atlas)

- [Self-Managed to Self-Managed](https://www.mongodb.com/docs/mongosync/current/connecting/onprem-to-onprem.md#std-label-c2c-conn-oprem2onprem)

- [Self-Managed to Atlas](https://www.mongodb.com/docs/mongosync/current/connecting/onprem-to-atlas.md#std-label-c2c-conn-onprem2atlas)

## Command Line Options

You can configure the following `mongosync` options using the command line.

To configure `mongosync` from a configuration file, see [Configuration File.](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#std-label-c2c-configuration-file)

### Global Options

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 option, the user is prompted to accept each disclaimer.

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

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

**New in version 1.9**

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 [Atlas to Atlas](https://www.mongodb.com/docs/mongosync/current/connecting/atlas-to-atlas.md#std-label-c2c-conn-atlas2atlas), [Self-Managed to Self-Managed](https://www.mongodb.com/docs/mongosync/current/connecting/onprem-to-onprem.md#std-label-c2c-conn-oprem2onprem), or [Self-Managed to Atlas.](https://www.mongodb.com/docs/mongosync/current/connecting/onprem-to-atlas.md#std-label-c2c-conn-onprem2atlas)

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

**Warning:**

On some systems, providing a password in a connection string with the `--cluster0` or `--cluster1` options may make the password visible to system status programs, such as `ps`, that may be invoked by other users.

Consider using the [`--config`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--config) option to specify a configuration file containing the password instead.

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 [Atlas to Atlas](https://www.mongodb.com/docs/mongosync/current/connecting/atlas-to-atlas.md#std-label-c2c-conn-atlas2atlas), [Self-Managed to Self-Managed](https://www.mongodb.com/docs/mongosync/current/connecting/onprem-to-onprem.md#std-label-c2c-conn-oprem2onprem), or [Self-Managed to Atlas.](https://www.mongodb.com/docs/mongosync/current/connecting/onprem-to-atlas.md#std-label-c2c-conn-onprem2atlas)

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

**Warning:**

On some systems, providing a password in a connection string with the `--cluster0` or `--cluster1` options may make the password visible to system status programs, such as `ps`, that may be invoked by other users.

Consider using the [`--config`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--config) option to specify a configuration file containing the password instead.

Sets the path to the configuration file.

To set the configuration file path during a migration, see [Reconfigure `mongosync` During Synchronization.](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#std-label-c2c-reconfigure-mid-migration)

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

**New in version 1.19.0**

*Type*: integer

*Minimum*: `1`

*Maximum*: `64`

Set the batch size for index builds on destination clusters. By default, `mongosync` programmatically optimizes this value on Atlas destination clusters. On non-Atlas destination clusters, the default batch size is `2`.

`mongosync` groups indexes into batches and issues one `createIndexes` command per batch. Each batch contains indexes for a single collection, so a collection with more indexes than the batch size requires multiple batches.

**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` option from a configuration file, see the [`createIndexesBatchSize`](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#mongodb-setting-createIndexesBatchSize) setting.

**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` option from a configuration file, see the [`disableMetricsLogging`](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#mongodb-setting-disableMetricsLogging) setting.

**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` option from a configuration file, see the [`disableTelemetry`](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#mongodb-setting-disableTelemetry) setting.

To disable telemetry data collection during a migration, see [Reconfigure `mongosync` During Synchronization.](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#std-label-c2c-reconfigure-mid-migration)

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

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 configuration file, see the [`disableVerification`](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#mongodb-setting-disableVerification) setting.

**New in version 1.10**

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

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

**New in version 1.20**

Prints usage information to stdout.

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 option 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 option 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` option from a configuration file, see the [`hotDocIDs`](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#mongodb-setting-hotDocIDs) setting.

**New in version 1.18**

Sets an identifier for the `mongosync` instance.

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

The identifier value for this option 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` option from a configuration file, see the [`id`](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#mongodb-setting-id) setting.

*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` option from a configuration file, see the [`loadLevel`](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#mongodb-setting-loadLevel) setting.

To change the load level during a migration, see [Reconfigure `mongosync` During Synchronization.](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#std-label-c2c-reconfigure-mid-migration)

**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**

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` option from a configuration file, see the [`logPath`](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#mongodb-setting-logPath) setting.

To change the path to the log directory during a migration, see [Reconfigure `mongosync` During Synchronization.](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#std-label-c2c-reconfigure-mid-migration)

**Note:**

If you start `mongosync` with the `--logPath` option, you can send a `USR1` signal to the `mongosync` process to rotate its log file:

```javascript
kill -s USR1 $mongosync_pid

```

`$mongosync_pid` is the `mongosync` process ID.

**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` option from a configuration file, see the [`metricsLoggingFilepath`](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#mongodb-setting-metricsLoggingFilepath) setting.

*Default*: `27182`

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

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

To change the port during a migration, see [Reconfigure `mongosync` During Synchronization.](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#std-label-c2c-reconfigure-mid-migration)

*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` option supports the following values:

- `TRACE`

- `DEBUG`

- `INFO`

- `WARN`

- `ERROR`

- `FATAL`

- `PANIC`

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

To change the verbosity level during a migration, see [Reconfigure `mongosync` During Synchronization.](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#std-label-c2c-reconfigure-mid-migration)

Prints `mongosync` version information to stdout.

## Behavior

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

## Learn More

- [Atlas to Atlas](https://www.mongodb.com/docs/mongosync/current/connecting/atlas-to-atlas.md#std-label-c2c-conn-atlas2atlas)

- [Self-Managed to Self-Managed](https://www.mongodb.com/docs/mongosync/current/connecting/onprem-to-onprem.md#std-label-c2c-conn-oprem2onprem)

- [Self-Managed to Atlas](https://www.mongodb.com/docs/mongosync/current/connecting/onprem-to-atlas.md#std-label-c2c-conn-onprem2atlas)

- [`mongosync` States](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-states.md#std-label-c2c-states)

- [`start`](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api)

- [Finalize Cutover Process](https://www.mongodb.com/docs/mongosync/current/reference/cutover-process.md#std-label-c2c-cutover-process)