> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polystack.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Replication and Sync

> Configure asynchronous near-real-time replication between Primary DC and Backup sites with TLS 1.3 encryption in transit and integrity verification.

## Overview

Replication mirrors snapshots from one datastore to another over an encrypted
channel. Ironcore Backup Solution (IBS) supports both **push** (Primary site
initiates) and **pull** (Backup site initiates) topologies, with bandwidth
throttling, schedule control, and end-to-end integrity verification. This page
covers configuring sync jobs, choosing the right topology, and validating the
result.

The standard configuration mirrors weekly full backups from the Primary DC to
the Backup site for long-term archival.

<Note>
  **Prerequisites**

  * Administrator role on the Polystack platform
  * At least two datastores — one at the Primary DC site, one at the Backup site
  * Network connectivity between sites on TCP/8007 (TLS 1.3)
  * Identical encryption keys configured on both sites if push-time encryption is enabled
</Note>

***

## Topology

```mermaid theme={null}
graph LR
    subgraph Primary DC Site
        PRIM[Primary Datastore<br/>ibs-primary]
    end
    subgraph Backup Site
        BAKK[Backup Datastore<br/>ibs-archival]
    end
    PRIM -->|Push sync — weekly| BAKK
    BAKK -.->|Pull validation| PRIM
```

| Direction | Use When                                                                                                      |
| --------- | ------------------------------------------------------------------------------------------------------------- |
| **Push**  | Primary site initiates. Best when the Backup site sits behind a firewall and the Primary has outbound access. |
| **Pull**  | Backup site initiates. Best when the Primary site cannot reach the Backup site, or for security separation.   |

***

## Register the Remote Site

Before creating a sync job, register the remote endpoint as a **Remote**.

<Tabs>
  <Tab title="Deployment Console" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Open Remotes" icon="external-link">
        Navigate to **Backup Solution** > **Replication** > **Remotes**.
      </Step>

      <Step title="Add a new remote" icon="plus">
        Click **Add Remote**. Enter:

        * **Name**: `backup-site`
        * **Host**: `ibs.backup.<your-domain>`
        * **Port**: `8007`
        * **Auth-ID**: `sync@polystack!replication`
        * **Fingerprint**: TLS certificate fingerprint from the remote
      </Step>

      <Step title="Test connectivity" icon="signal">
        Click **Test**. The Dashboard probes the remote and reports reachability.
      </Step>

      <Step title="Save" icon="check">
        Click **Save**.

        <Check>The remote is listed under **Replication** and is selectable in sync jobs.</Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Register the backup site" theme={null}
    ironcore-backup remote create \
      --name backup-site \
      --host ibs.backup.<your-domain> \
      --port 8007 \
      --auth-id "sync@polystack!replication" \
      --fingerprint "AB:CD:EF:..."
    ```

    ```bash title="Verify connectivity" theme={null}
    ironcore-backup remote test backup-site
    ```
  </Tab>
</Tabs>

<Warning>
  Always verify the remote's TLS fingerprint out-of-band. A man-in-the-middle
  attack would otherwise be undetectable. The fingerprint is shown on the
  remote's web interface under **Certificates**.
</Warning>

***

## Create a Push Sync Job (Primary → Backup Site)

This is the recommended configuration for weekly archival replication.

<Tabs>
  <Tab title="Deployment Console" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Open Sync Jobs" icon="external-link">
        Navigate to **Backup Solution** > **Replication** > **Sync Jobs**.
      </Step>

      <Step title="Click Create Sync Job" icon="plus">
        Click **Create Sync Job**.
      </Step>

      <Step title="Set source and target" icon="arrow-right">
        Set:

        * **Name**: `primary-to-backup-archival`
        * **Source datastore**: `ibs-primary`
        * **Remote**: `backup-site`
        * **Remote datastore**: `ibs-archival`
        * **Direction**: Push
      </Step>

      <Step title="Filter snapshots" icon="filter">
        Set **Include filter** to `keep-weekly=*` so only weekly snapshots
        replicate, not daily incrementals.
      </Step>

      <Step title="Set schedule" icon="calendar">
        Set the schedule to `Sun 04:30` — runs after the weekly full backup at
        03:00 and after the daily prune at 05:00.
      </Step>

      <Step title="Set bandwidth and encryption" icon="lock">
        Configure:

        * **Bandwidth limit**: based on your inter-site link capacity
        * **Encrypt in transit**: enabled (default)
        * **Encrypt snapshots on the fly**: enabled — encrypts at push time using the project key
      </Step>

      <Step title="Save" icon="check">
        Click **Save**.

        <Check>The sync job appears in the list with the next scheduled run time.</Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Create a push sync job" theme={null}
    ironcore-backup sync create \
      --name primary-to-backup-archival \
      --source ibs-primary \
      --remote backup-site \
      --remote-repository ibs-archival \
      --direction push \
      --schedule "Sun 04:30" \
      --include "keep-weekly=*" \
      --bwlimit 100 \
      --encrypt
    ```
  </Tab>
</Tabs>

***

## Create a Pull Sync Job (Backup Site → Primary)

A pull sync runs on the Backup site, fetching snapshots from the Primary. Used
when the Backup site cannot accept inbound connections from the Primary, or for
security separation.

```bash title="Create a pull sync job" theme={null}
ironcore-backup sync create \
  --name backup-pulls-from-primary \
  --source ibs-archival \
  --remote primary-site \
  --remote-repository ibs-primary \
  --direction pull \
  --schedule "Sun 04:30" \
  --include "keep-weekly=*" \
  --bwlimit 100
```

<Info>
  A pull sync requires the remote registration on the Backup site, with the
  Primary site as the remote.
</Info>

***

## Encryption in Transit

| Layer                      | Mechanism                                          | Notes                                          |
| -------------------------- | -------------------------------------------------- | ---------------------------------------------- |
| Transport                  | TLS 1.3                                            | Mandatory between sites                        |
| Chunk                      | Already encrypted on the client side (AES-256-GCM) | No additional encryption needed                |
| Sync-time chunk encryption | Optional opt-in                                    | Encrypts unencrypted source chunks before push |

<Tip>
  If the source datastore holds **unencrypted** snapshots (legacy or
  unencrypted-by-policy workloads), enable **Encrypt on push** so the
  destination receives encrypted chunks. The destination must hold the matching
  decryption key for any restore from the Backup site.
</Tip>

***

## Bandwidth Management

Sync jobs typically run during off-hours, but inter-site link capacity may be
shared with production traffic. Use bandwidth limits to coexist.

| Setting                      | Effect                                               |
| ---------------------------- | ---------------------------------------------------- |
| `--bwlimit 100`              | Cap at 100 MiB/s                                     |
| `--bwlimit 0`                | Unlimited (default)                                  |
| Schedule with `JobIO` weight | Lower-priority IO scheduling on the source datastore |

***

## Filter Expressions

| Filter                 | Matches                                          |
| ---------------------- | ------------------------------------------------ |
| `keep-weekly=*`        | Any snapshot retained by a `keep-weekly` window  |
| `keep-monthly=*`       | Any snapshot retained by a `keep-monthly` window |
| `backup-id:vm/12345`   | A specific source group                          |
| `namespace:production` | An entire namespace                              |
| Combined               | Filters are OR-combined: any match passes        |

***

## Integrity Verification

After every sync, the destination runs a SHA-256 verification on the newly
received chunks. The result is recorded in the destination snapshot's
verification report.

```mermaid theme={null}
sequenceDiagram
    participant SRC as Primary Datastore
    participant DST as Backup Datastore
    SRC->>DST: Manifest + chunk list
    SRC->>DST: Encrypted chunks (TLS 1.3)
    DST->>DST: Compute SHA-256 per chunk
    DST->>DST: Validate against manifest hashes
    alt All chunks OK
        DST-->>SRC: ACK (sync OK)
    else Mismatch detected
        DST-->>SRC: Failure (retry chunk)
        SRC->>DST: Re-transmit chunk
    end
```

If a chunk fails verification, IBS automatically retries up to 3 times before
marking the sync as failed and emitting a notification.

***

## Replication Monitoring

| Metric                          | Where                                                  |
| ------------------------------- | ------------------------------------------------------ |
| Sync task progress              | **Tasks** panel — live progress and bytes transferred  |
| Last sync result per source     | Datastore detail panel — **Last sync** column          |
| Verification status per replica | Snapshot detail — **Verification** tab                 |
| Inter-site bandwidth            | Datastore statistics — **Replication bandwidth** chart |

***

## Recover From a Failed Sync

<AccordionGroup>
  <Accordion title="Sync failed mid-transfer" icon="alert-triangle">
    Failed syncs do not leave the destination in an inconsistent state — chunks
    are committed only after the full manifest is signed. Re-run the sync; only
    chunks that did not complete are retransmitted.

    ```bash theme={null}
    ironcore-backup sync run --name primary-to-backup-archival
    ```
  </Accordion>

  <Accordion title="Destination drifted from source" icon="arrow-left-right">
    Compare datastores with `ironcore-backup sync diff`. The diff lists
    snapshots present on only one side. Re-run the sync to align.

    ```bash theme={null}
    ironcore-backup sync diff \
      --source ibs-primary \
      --remote backup-site \
      --remote-repository ibs-archival
    ```
  </Accordion>

  <Accordion title="TLS fingerprint mismatch after certificate renewal" icon="lock">
    The remote's TLS certificate was renewed. Update the registered fingerprint
    after verifying the new certificate out-of-band.

    ```bash theme={null}
    ironcore-backup remote update \
      --name backup-site \
      --fingerprint "<new-fingerprint>"
    ```
  </Accordion>
</AccordionGroup>

***

## Disaster Recovery Workflow

When the Primary site is unavailable and you need to restore from the Backup site:

<Steps titleSize="h3">
  <Step title="Designate the Backup site as the new restore source" icon="server">
    Operators connect their backup CLI or Dashboard to the Backup site directly.
  </Step>

  <Step title="Restore the workload" icon="rotate-ccw">
    Use the standard restore procedures from the Backup site datastore. Choose
    the most recent weekly archival snapshot.
  </Step>

  <Step title="Reverse the sync" icon="arrow-left-right">
    After the Primary site is recovered, configure a temporary reverse sync to
    re-seed the Primary datastore with any snapshots created in the meantime.
  </Step>

  <Step title="Restore normal direction" icon="check">
    Once the Primary is fully re-seeded, restore the original sync direction.
  </Step>
</Steps>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Verification and Validation" icon="check" href="/services/ironcore-backup/admin-guide/verification-validation" color="#bf9667">
    Schedule SHA-256 verification on both sites
  </Card>

  <Card title="Tape and Object Storage" icon="archive" href="/services/ironcore-backup/admin-guide/tape-and-object" color="#bf9667">
    Layer on long-term tape archival from the Backup site
  </Card>

  <Card title="Security and Encryption" icon="lock" href="/services/ironcore-backup/admin-guide/security-encryption" color="#bf9667">
    Key handling for snapshots that replicate between sites
  </Card>

  <Card title="Infrastructure Sizing" icon="ruler" href="/services/ironcore-backup/admin-guide/infrastructure-sizing" color="#bf9667">
    Capacity planning across both Primary and Backup sites
  </Card>
</CardGroup>