> ## 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.

# Backup Datastores

> Provision local, replicated, and S3-backed datastores for Ironcore Backup Solution. Organise data into namespaces with per-project access policies.

## Overview

A **datastore** is the storage location where Ironcore Backup Solution (IBS) writes
chunks and snapshots. Each datastore has its own deduplication pool, retention
policy, access control, and verification schedule. This page describes the
supported backends, how to provision a new datastore, and how to organise data
with namespaces.

<Note>
  **Prerequisites**

  * Administrator role on the Polystack platform
  * At least one of: local mount, networked filesystem, S3-compatible bucket,
    or LTO tape library
  * Network reachability from the backup server to the backend
</Note>

***

## Backend Types

<CardGroup cols={2}>
  <Card title="Local Filesystem" icon="hard-drive" color="#bf9667">
    XFS, ext4, or ZFS on directly-attached storage. Highest write throughput
    and lowest latency for the Primary DC site.
  </Card>

  <Card title="Replicated Filesystem" icon="layers" color="#bf9667">
    ZFS send/receive, GlusterFS, or a clustered POSIX filesystem. Survives
    single-disk or single-node failure within the same site.
  </Card>

  <Card title="S3-Compatible Object Storage" icon="cloud" color="#bf9667">
    Native S3 API. Use on-premises object stores or cloud providers for
    elastic capacity and geographic redundancy.
  </Card>

  <Card title="LTO Tape Library" icon="archive" color="#bf9667">
    LTO-5 and newer for offline, compliance-grade archival. Managed by the
    Tape Worker — see [Tape and Object Storage](/services/ironcore-backup/admin-guide/tape-and-object).
  </Card>
</CardGroup>

***

## Create a Local Datastore

<Tabs>
  <Tab title="Deployment Console" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Open Backup Solution Configuration" icon="settings">
        Navigate to **Backup Solution** > **Datastores** > **Add Datastore**.
      </Step>

      <Step title="Enter datastore details" icon="database">
        Set:

        * **Name**: `ibs-primary`
        * **Type**: Local Filesystem
        * **Path**: `/mnt/backup/ibs-primary` (must be empty)
      </Step>

      <Step title="Configure scheduled tasks" icon="calendar">
        Define schedules for:

        * **Garbage Collection**: weekly
        * **Verification**: weekly
        * **Prune**: daily
      </Step>

      <Step title="Set notification group" icon="bell">
        Attach the operational notification group so alerts dispatch to the
        right channel.
      </Step>

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

        <Check>The datastore is created. Initial chunks directory and atime tracking are set up automatically.</Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Provision the underlying filesystem" theme={null}
    # ZFS dataset example
    zfs create -o atime=off -o xattr=sa -o compression=off rpool/ibs-primary
    mkdir -p /mnt/backup/ibs-primary
    mount /dev/zvol/rpool/ibs-primary /mnt/backup/ibs-primary
    ```

    ```bash title="Register the datastore with IBS" theme={null}
    ironcore-backup datastore create \
      --name ibs-primary \
      --type local \
      --path /mnt/backup/ibs-primary \
      --gc-schedule "Sun 05:00" \
      --verify-schedule "Sun 06:00" \
      --prune-schedule "daily 05:00"
    ```

    <Check>`ironcore-backup datastore list` shows the new datastore with status `online`.</Check>
  </Tab>
</Tabs>

<Warning>
  Do not host two datastores on the same filesystem. Each datastore is the
  authoritative owner of chunks under its path. Sharing a path leads to chunk
  collision and silent data loss during garbage collection.
</Warning>

***

## Create an S3-Backed Datastore

S3-compatible datastores are ideal for the Backup site or for elastic archival.

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

      <Step title="Choose S3 type" icon="cloud">
        Set:

        * **Name**: `ibs-archival`
        * **Type**: S3-compatible
        * **Endpoint**: `https://s3.<your-domain>` (or your provider's endpoint)
        * **Bucket**: `polystack-backup-archival`
        * **Region**: `default`
      </Step>

      <Step title="Provide credentials" icon="key">
        Enter the access key and secret key. The credentials are stored
        encrypted in the backup server configuration.
      </Step>

      <Step title="Set throughput and request monitoring" icon="activity">
        Optionally set:

        * **Request count threshold** — alert if requests exceed N per minute
        * **Bandwidth limit** — cap egress in MiB/s
      </Step>

      <Step title="Configure schedules" icon="calendar">
        Set garbage collection, verification, and prune schedules. S3 datastores
        typically verify less often than local datastores due to cost considerations.
      </Step>

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

        <Check>The datastore status transitions to `online` once a probe write/read succeeds.</Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Create an S3 datastore" theme={null}
    ironcore-backup datastore create \
      --name ibs-archival \
      --type s3 \
      --endpoint https://s3.<your-domain> \
      --bucket polystack-backup-archival \
      --region default \
      --access-key "AKIA..." \
      --secret-key "..." \
      --gc-schedule "monthly" \
      --verify-schedule "monthly" \
      --request-rate-threshold 500
    ```
  </Tab>
</Tabs>

<Tip>
  For very large archival datasets, enable the S3 datastore's
  **request-rate-threshold** with a notification destination. This alerts you
  to runaway sync jobs that could incur unexpected egress costs.
</Tip>

***

## Namespaces

Namespaces partition a datastore into logical scopes while preserving cross-namespace
deduplication. Use namespaces to separate environments, teams, or compliance scopes.

<Tabs>
  <Tab title="Deployment Console" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Open the datastore" icon="database">
        Open **Backup Solution** > **Datastores** > *(select datastore)*
        \> **Namespaces**.
      </Step>

      <Step title="Create a namespace" icon="plus">
        Click **Add Namespace** and enter a name (for example, `production`).
      </Step>

      <Step title="Assign access" icon="users">
        From the namespace detail panel, click **Permissions** and grant the
        appropriate roles to users and tokens.
      </Step>

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

        <Check>The namespace appears in the datastore detail view and is selectable in backup creation dialogs.</Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Create a namespace" theme={null}
    ironcore-backup namespace create ibs-primary production
    ironcore-backup namespace create ibs-primary staging
    ironcore-backup namespace create ibs-primary security
    ```

    ```bash title="Grant per-namespace permissions" theme={null}
    ironcore-backup acl update \
      --path /datastore/ibs-primary/production \
      --auth-id security-team@polystack \
      --role Datastore.Reader
    ```
  </Tab>
</Tabs>

***

## Move Backup Groups Between Namespaces

Backup groups can be relocated between namespaces in the same datastore without
re-uploading chunks. The move is atomic with per-group locking for data consistency.

<Tabs>
  <Tab title="Deployment Console" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Find the group" icon="search">
        Open the group in **Backup Solution** > **Snapshots**.
      </Step>

      <Step title="Click Move" icon="arrow-right">
        Click **Move** and pick the target namespace.
      </Step>

      <Step title="Confirm" icon="check">
        Confirm the move. The operation is online — chunks are not transferred.

        <Check>The group appears under the destination namespace.</Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash theme={null}
    ironcore-backup snapshot move \
      --source ibs-primary:production/vm/12345 \
      --destination ibs-primary:security/vm/12345
    ```
  </Tab>
</Tabs>

***

## Datastore Lifecycle Tasks

| Task                   | Default Frequency | Purpose                                              |
| ---------------------- | ----------------- | ---------------------------------------------------- |
| **Garbage Collection** | Weekly            | Reclaims chunks no snapshot references               |
| **Verification**       | Weekly            | Re-reads chunks and validates SHA-256                |
| **Prune**              | Daily             | Applies retention policy, removes outdated snapshots |
| **Sync**               | Per-job schedule  | Replicates to remote datastores                      |

<Info>
  Garbage collection runs in two phases: mark and sweep. The mark phase
  enumerates referenced chunks; the sweep phase removes unreferenced chunks
  older than a grace period (default 24 hours) to allow concurrent backup
  jobs to complete without race conditions.
</Info>

***

## Capacity Monitoring

<CardGroup cols={2}>
  <Card title="Usage Telemetry" icon="activity" color="#bf9667">
    The Dashboard exposes used bytes, deduplication ratio, projected fill date,
    and write throughput per datastore.
  </Card>

  <Card title="Threshold Alerts" icon="bell" color="#bf9667">
    Configure free-space alerts at 80%, 90%, and 95% utilisation. Alerts
    dispatch via the configured notification group.
  </Card>

  <Card title="S3 Cost Telemetry" icon="dollar-sign" color="#bf9667">
    For S3 datastores, request count and egress bandwidth are exposed for
    cost monitoring.
  </Card>

  <Card title="Capacity Forecasting" icon="chart-line" color="#bf9667">
    The Statistics panel projects fill date based on a rolling 14-day growth
    rate. Use this to plan expansion.
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Datastore status is `offline`" icon="alert-triangle">
    The backup server cannot reach the backend. For local datastores, check
    the mount status. For S3 datastores, check credentials and endpoint
    reachability.

    ```bash title="Force a re-probe" theme={null}
    ironcore-backup datastore probe ibs-primary
    ```
  </Accordion>

  <Accordion title="Garbage collection is taking many hours" icon="clock">
    Large datastores with many snapshots can take significant time to GC. Run
    GC during off-hours. If unacceptable, partition the datastore by creating
    a second datastore for new data.
  </Accordion>

  <Accordion title="Free space alerts firing unexpectedly" icon="hard-drive">
    Confirm the underlying filesystem reports correct free space. A failed
    prune job may have left expired manifests in place — check **Tasks** for
    prune failures.
  </Accordion>

  <Accordion title="S3 datastore high request count" icon="dollar-sign">
    Sync jobs that re-upload existing chunks generate excess S3 requests. Check
    the deduplication hit rate on sync tasks. Consider increasing the chunk
    cache size on the source datastore.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Retention Policies" icon="calendar-days" href="/services/ironcore-backup/admin-guide/retention-policies" color="#bf9667">
    Define retention windows applied to each datastore
  </Card>

  <Card title="Replication and Sync" icon="arrow-left-right" href="/services/ironcore-backup/admin-guide/replication-sync" color="#bf9667">
    Mirror datastores between Primary and Backup sites
  </Card>

  <Card title="Access Control" icon="key" href="/services/ironcore-backup/admin-guide/access-control" color="#bf9667">
    Grant per-datastore and per-namespace permissions
  </Card>

  <Card title="Infrastructure Sizing" icon="ruler" href="/services/ironcore-backup/admin-guide/infrastructure-sizing" color="#bf9667">
    Plan datastore capacity for incremental, full, and archival retention
  </Card>
</CardGroup>