Walrus storage nodes provide backup and restore functionality for the primary database containing blob data. This guide covers configuration requirements, operational procedures, and best practices for automated and manual backup processes and restore operations.

> **Info**
>
> The current backup implementation creates full copies of the database files. Backups require substantial disk space, approximately the same size as your active database. A checkpoint-based solution is planned for a future release.

- [x] Storage node running with appropriate permissions to create backups
- [x] Sufficient disk space for backup storage (a separate physical volume is recommended)
- [x] Unix or Linux operating system with support for Unix domain sockets
- [x] `walrus` [user account](/docs/operator-guide/storage-nodes/storage-node-setup) with appropriate permissions
- [x] Configure the local administration socket

    The backup system communicates with running storage nodes through a Unix domain socket. To enable this functionality:

    ##### Step 1: Configure the administration socket path in your node configuration file.

    ```yaml
        admin_socket_path: /opt/walrus/admin.socket
    ```

    ##### Step 2: Restart the storage node to initialize the socket.

    ```sh
        $ sudo systemctl restart walrus-node.service
    ```

    ##### Step 3: Verify socket creation.

    ```sh
        $ ls -la /opt/walrus/admin.socket
    ```

    :::caution

    The storage node creates the socket with permissions `srw------- 1 walrus walrus`, ensuring that only the `walrus` user can send operations to it. This is critical for security because operations sent to this socket execute directly on the running storage node.

    Currently supported operations include:
    - **local-admin checkpoint**
    - **local-admin log-level**

    :::

## Set up automated periodic backups

Storage nodes support scheduled automatic backups through checkpoint configuration. Add the following to your node configuration:

```yaml
checkpoint_config:
  # Directory where backups are stored
  db_checkpoint_dir: /opt/walrus/checkpoints

  # Number of backups to retain (oldest are deleted)
  max_db_checkpoints: 2

  # Backup frequency (example: 4-hour interval)
  db_checkpoint_interval:
    secs: 14400  # 4 hours in seconds
    nanos: 0

  # Sync in-memory data to disk before creating a backup
  sync: true

  # Maximum concurrent backup operations
  max_background_operations: 1

  # Enable/disable automated backups
  periodic_db_checkpoints: true
```

To disable automated backups, set `periodic_db_checkpoints: false` in your configuration.

## Create manual backups

Create on-demand backups using the `local-admin` command.

The following commands assume `walrus-node` is in your system PATH. If it is not, replace `walrus-node` with the full path to the binary, for example `/opt/walrus/bin/walrus-node`.

```sh
$ sudo -u walrus walrus-node local-admin \
    --socket-path /opt/walrus/admin.socket \
    checkpoint create \
    --path /opt/walrus/backups/manual-backup-name
```

The backup operation runs in the background within the storage node. After backup creation initializes, the process continues independently even if you terminate the command-line interface.

## List available backups

Run the following command to list available backups:

```sh
$ sudo -u walrus walrus-node list-db-checkpoint /opt/walrus/checkpoints
```

Sample output:

```sh
Backups:
Backup ID: 1, Size: 85.9 GiB, Files: 1055, Created: 2025-07-02T00:25:48Z
Backup ID: 2, Size: 86.2 GiB, Files: 1058, Created: 2025-07-02T04:25:52Z
```

## Restore from a backup

> **Danger**
>
> Do not copy backup directories directly to the storage node data path. You must use the restore tool to properly reconstruct the database from checkpoint files. The storage engine cannot recognize directly copied content.
To restore from a backup:

##### Step 1: Stop the storage node service.

```sh
$ sudo systemctl stop walrus-node.service
```

Verify the service is stopped:

```sh
$ sudo systemctl status walrus-node.service
```

##### Step 2: Back up the current database (optional).

Assuming the Walrus storage path is `storage_path: /opt/walrus/db`:

```sh
$ sudo -u walrus cp -r /opt/walrus/db /opt/walrus/db.backup.$(date +%Y%m%d-%H%M%S)
```

This command saves the main database files, the events database (`/opt/walrus/db/events/`), and event blob data (`/opt/walrus/db/event_blob_writer/`).

##### Step 3: Clear existing data (if performing a clean restore).

Remove all existing database files to ensure a clean restore. Assuming the Walrus storage path is `storage_path: /opt/walrus/db`:

```sh
$ sudo -u walrus rm -rf /opt/walrus/db/*
```

This command removes the main database files, the events database (`/opt/walrus/db/events/`), and event blob data (`/opt/walrus/db/event_blob_writer/`).

##### Step 4: Restore the main database.

The restore process can take significant time depending on database size. Run the restore command in a persistent session using `tmux` or `screen` to prevent interruption if your connection drops.

If `walrus-node` is not in your PATH, use the full path to the binary.

Restore from a specific checkpoint:

```sh
$ sudo -u walrus walrus-node \
    restore \
    --db-checkpoint-path /opt/walrus/checkpoints \
    --db-path /opt/walrus/db \
    --checkpoint-id 2
```

Or restore from the latest checkpoint by omitting `--checkpoint-id`:

```sh
$ sudo -u walrus walrus-node \
    restore \
    --db-checkpoint-path /opt/walrus/checkpoints \
    --db-path /opt/walrus/db
```

##### Step 5: Start the storage node.

```sh
$ sudo systemctl start walrus-node.service
```

Monitor startup logs:

```sh
$ sudo journalctl -u walrus-node.service -f
```

The storage node begins downloading and replaying events. This process can take some time before the node transitions to `Active` state.