--- title: influxd-ctl backup description: The influxd-ctl backup command backs up an InfluxDB Enterprise v1 cluster’s metastore and shard data at that point in time and stores the copy in the specified directory. url: https://docs.influxdata.com/enterprise_influxdb/v1/tools/influxd-ctl/backup/ estimated_tokens: 2498 publisher: InfluxData canonical: https://docs.influxdata.com/enterprise_influxdb/v1/tools/influxd-ctl/backup/ date: '2026-05-08T12:11:51-05:00' lastmod: '2026-05-08T12:11:51-05:00' --- The `influxd-ctl backup` command backs up an InfluxDB Enterprise cluster’s[metastore](/enterprise_influxdb/v1/concepts/glossary/#metastore) and[shard](/enterprise_influxdb/v1/concepts/glossary/#shard) data at that point in time and stores the copy in the specified directory. To back up only the cluster metastore, use the `-strategy only-meta` flag. Backups are incremental by default, meaning they create a copy of the metastore and shard data that have changed since the previous incremental backup. If there are no existing incremental backups, the system automatically performs a complete backup. #### Backup strategies InfluxDB Enterprise supports the following backup strategies: * **only-meta**: Back up metastore data only, including users, roles, databases, continuous queries, and retention policies. This strategy does not back up shards. * **full**: Back up metastore and all shard data. * **incremental**: *(Default)* Back up metastore and shard data that has changed since the last incremental backup. If there are no existing incremental backups, the system automatically performs a full backup. ## Usage ```sh influxd-ctl backup [flags] ``` ## Arguments * **backup-dir**: Directory to store backup files in ## Flags | Flag | Description | |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-bufsize` | Buffer size (in bytes) for writing gzip files. Default is `1048576` (1 MB). *v1.12.3+* | | `-cpuprofile` | Write CPU profile to the specified file path. For debugging backup performance. *v1.12.3+* | | `-db` | Database to backup | | `-end` | End date for backup *(RFC3339 timestamp)* | | `-estimate` | Estimate the size of the requested backup | | `-from` |Data node TCP address to prefer when backing up. In v1.12.3+, the node must exist in the cluster or the command returns an error. When the preferred node doesn’t own a shard, the command falls back to other owners sorted by most recent write. See [Node selection](#node-selection).| | `-full` | Perform a full backup *(deprecated in favor of `-strategy full`)* | | `-gzipBlockCount` | Number of concurrent blocks for gzip compression. Default is the number of CPU cores. Recommended: 1-2x CPU cores. *v1.12.3+* | | `-gzipBlockSize` | Block size (in bytes) for pgzip compression. Default is `1048576` (1 MB). Recommended \>1 MB for performance. *v1.12.3+* | |`-gzipCompressionLevel`| Gzip compression level: `default`, `full`, `speedy`, or `none`. Default is `default`. *v1.12.3+* | | `-rp` | Retention policy to backup | | `-shard` | Shard ID to backup | |`-staleness-threshold` | For incremental backups, skip shards modified within this duration of the existing backup. Default is `10m` (matches [`cache-snapshot-write-cold-duration`](/enterprise_influxdb/v1/administration/configure/config-data-nodes/#cache-snapshot-write-cold-duration)). *v1.12.3+* | | `-start` | Start date for backup *(RFC3339 timestamp)* | | `-strategy` | Backup strategy to use (`only-meta`, `full`, or `incremental`) | *Also see [`influxd-ctl` global flags](/enterprise_influxdb/v1/tools/influxd-ctl/#influxd-ctl-global-flags).* ## Backup behavior ### Node selection When backing up a shard, the command selects the best data node to read from: 1. Shard copies with zero bytes are skipped. 2. Copies are sorted by most recent write time — the most recently written copy is tried first. 3. If you specify `-from`, that node is preferred. If the preferred node doesn’t own the shard, the command falls back to other owners. 4. If the `-from` node doesn’t exist in the cluster, the command fails with: `data node "" does not exist`. ### Staleness threshold During incremental backups, the `-staleness-threshold` flag controls when a shard is considered current and can be skipped. A shard is skipped when the existing backup timestamp plus the staleness threshold is after the shard’s last modification time. ## Examples * [Perform an incremental backup](#perform-an-incremental-backup) * [Perform a full backup](#perform-a-full-backup) * [Estimate the size of a backup](#estimate-the-size-of-a-backup) * [Backup data from a specific time range](#backup-data-from-a-specific-time-range) * [Backup a specific shard](#backup-a-specific-shard) ### Perform an incremental backup ```sh influxd-ctl backup /path/to/backup-dir ``` ### Perform a full backup ```sh influxd-ctl backup -strategy full /path/to/backup-dir ``` ### Estimate the size of a backup ```sh influxd-ctl backup -estimate ``` ### Backup data from a specific time range ```sh influxd-ctl backup \ -start 2023-01-01T00:00:00Z \ -end 2023-06-01T00:00:00Z \ /path/to/backup-dir ``` ### Backup a specific shard ```sh influxd-ctl backup -shard 00 /path/to/backup-dir ``` #### Related * [Back up and restore](/enterprise_influxdb/v1/administration/backup-and-restore/) * [influxd-ctl backup](/enterprise_influxdb/v1/tools/influxd-ctl/backup/) | Flag | Description | | --- | --- | | Flag | Description | | -bufsize | Buffer size (in bytes) for writing gzip files. Default is 1048576 (1 MB). v1.12.3+ | | -cpuprofile | Write CPU profile to the specified file path. For debugging backup performance. v1.12.3+ | | -db | Database to backup | | -end | End date for backup (RFC3339 timestamp) | | -estimate | Estimate the size of the requested backup | | -from | Data node TCP address to prefer when backing up. In v1.12.3+, the node must exist in the cluster or the command returns an error. When the preferred node doesn’t own a shard, the command falls back to other owners sorted by most recent write. See Node selection . | | -full | Perform a full backup (deprecated in favor of -strategy full ) | | -gzipBlockCount | Number of concurrent blocks for gzip compression. Default is the number of CPU cores. Recommended: 1-2x CPU cores. v1.12.3+ | | -gzipBlockSize | Block size (in bytes) for pgzip compression. Default is 1048576 (1 MB). Recommended >1 MB for performance. v1.12.3+ | | -gzipCompressionLevel | Gzip compression level: default , full , speedy , or none . Default is default . v1.12.3+ | | -rp | Retention policy to backup | | -shard | Shard ID to backup | | -staleness-threshold | For incremental backups, skip shards modified within this duration of the existing backup. Default is 10m (matches cache-snapshot-write-cold-duration ). v1.12.3+ | | -start | Start date for backup (RFC3339 timestamp) | | -strategy | Backup strategy to use ( only-meta , full , or incremental ) |