# Restoring CubeSandbox Configuration from a Backup: Complete Disaster Recovery Guide

> Restore CubeSandbox configuration from backup by extracting archives, copying YAML files, importing MySQL dumps, and restarting services. Follow this complete disaster recovery guide.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: how-to-guide
- Published: 2026-07-13

---

**To restore CubeSandbox from a backup, extract your archive to a temporary directory, copy the YAML files to `configs/single-node/`, import the MySQL dumps into the `ossdb_config` and `instance_db_config` databases, optionally restore the Redis RDB snapshot, and restart the CubeMaster and Cubelet services.**

Restoring CubeSandbox configuration from a backup requires handling three distinct persistence layers: static YAML files in `configs/single-node/`, MySQL databases for runtime metadata, and optional Redis snapshots for metric caches. The TencentCloud/CubeSandbox repository structures its operational state across these components, necessitating a coordinated restoration process to recover from hardware failures or migrate to new infrastructure. This guide provides the exact commands and file paths required to execute a complete disaster recovery based on the source code implementation.

## What Your Backup Archive Must Contain

A complete CubeSandbox backup consists of four critical components. Verify your archive includes these before beginning restoration:

- **Static YAML configurations** – [`cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubemaster.yaml), [`cubelet.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubelet.yaml), and [`network-agent.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent.yaml) from `configs/single-node/`. These define HTTP ports, gRPC timeouts, resource limits, and database connection strings.
- **Environment overrides** – The optional `.env` file containing custom ports, feature toggles (`WEB_UI_ENABLE`), and credentials.
- **MySQL dumps** – SQL exports of the `ossdb_config` database (template snapshots and sandbox metadata) and `instance_db_config` database (runtime state and resource allocation tables).
- **Redis RDB snapshot** – Optional binary dump of the Redis data directory for point-in-time metric recovery.

## Step-by-Step Restoration Process

### 1. Prepare the Restoration Environment

Create a temporary directory and extract your backup archive:

```bash
mkdir -p /restore/cubesandbox
tar -xzf cubesandbox-backup-YYYY-MM-DD.tar.gz -C /restore/cubesandbox

```

Verify the extracted structure contains `config/`, `mysql/`, and optionally `redis/` subdirectories.

### 2. Restore Static Configuration Files

Copy the three core YAML files to their original location in the repository:

```bash
cp /restore/cubesandbox/config/cubemaster.yaml configs/single-node/
cp /restore/cubesandbox/config/cubelet.yaml configs/single-node/
cp /restore/cubesandbox/config/network-agent.yaml configs/single-node/

```

If your backup includes a custom `.env` file, restore it to the repository root to preserve runtime overrides:

```bash
cp /restore/cubesandbox/config/.env .

```

These files reference one another via the `configs/single-node/` path as implemented in the CubeMaster initialization logic.

### 3. Import MySQL Databases

Extract the database credentials from the restored [`cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubemaster.yaml) to avoid manual entry:

```bash
MYSQL_USER=$(grep -A1 'ossdb_config' configs/single-node/cubemaster.yaml | grep 'user' | head -1 | cut -d':' -f2 | tr -d ' "')
MYSQL_PASS=$(grep -A1 'ossdb_config' configs/single-node/cubemaster.yaml | grep 'pwd' | head -1 | cut -d':' -f2 | tr -d ' "')
DB_OSS=$(grep -A1 'ossdb_config' configs/single-node/cubemaster.yaml | grep 'db_name' | head -1 | cut -d':' -f2 | tr -d ' "')
DB_INSTANCE=$(grep -A1 'instance_db_config' configs/single-node/cubemaster.yaml | grep 'db_name' | head -1 | cut -d':' -f2 | tr -d ' "')

```

Import the **ossdb_config** database (stores template snapshots and credential vault data):

```bash
mysql -u"$MYSQL_USER" -p"$MYSQL_PASS" "$DB_OSS" < /restore/cubesandbox/mysql/ossdb.sql

```

Import the **instance_db_config** database (holds per-instance runtime state):

```bash
mysql -u"$MYSQL_USER" -p"$MYSQL_PASS" "$DB_INSTANCE" < /restore/cubesandbox/mysql/instance.sql

```

### 4. Restore Redis State (Optional)

If your backup includes a Redis RDB snapshot, stop the Redis service, replace the data file, and restart:

```bash

# Stop the Redis container or service

sudo systemctl stop cube-sandbox-redis

# Replace the RDB file (adjust path for your installation)

sudo cp /restore/cubesandbox/redis/dump.rdb /var/lib/redis/dump.rdb
sudo chown redis:redis /var/lib/redis/dump.rdb

# Restart Redis

sudo systemctl start cube-sandbox-redis

```

Redis stores node-metric keys and sandbox-proxy routing information. While the system can rebuild these metrics on restart, restoring the RDB preserves historical data and routing tables.

### 5. Restart CubeSandbox Services

With configurations and databases restored, restart the services using the systemd units defined in `CubeMaster/scripts/`:

```bash
sudo systemctl restart cube-sandbox-cubemaster
sudo systemctl restart cube-sandbox-cubelet
sudo systemctl restart cube-sandbox-network-agent

```

For Docker-based deployments, restart the composition:

```bash
docker-compose down
docker-compose up -d

```

## Automated Restoration Script

Below is a complete bash script that automates the restoration process assuming your backup is extracted to `/restore/cubesandbox`:

```bash
#!/usr/bin/env bash
set -euo pipefail

RESTORE_DIR=/restore/cubesandbox
CONFIG_DIR=configs/single-node

# 1. Restore YAML configs

cp "$RESTORE_DIR"/config/*.yaml "$CONFIG_DIR/"

# 2. Restore .env if present

[[ -f "$RESTORE_DIR"/config/.env ]] && cp "$RESTORE_DIR"/config/.env .

# 3. Extract credentials and restore MySQL

MYSQL_USER=$(grep -A1 'ossdb_config' "$CONFIG_DIR"/cubemaster.yaml | grep 'user' | head -1 | cut -d':' -f2 | tr -d ' "')
MYSQL_PASS=$(grep -A1 'ossdb_config' "$CONFIG_DIR"/cubemaster.yaml | grep 'pwd' | head -1 | cut -d':' -f2 | tr -d ' "')
DB_OSS=$(grep -A1 'ossdb_config' "$CONFIG_DIR"/cubemaster.yaml | grep 'db_name' | head -1 | cut -d':' -f2 | tr -d ' "')
DB_INSTANCE=$(grep -A1 'instance_db_config' "$CONFIG_DIR"/cubemaster.yaml | grep 'db_name' | head -1 | cut -d':' -f2 | tr -d ' "')

mysql -u"$MYSQL_USER" -p"$MYSQL_PASS" "$DB_OSS" < "$RESTORE_DIR"/mysql/ossdb.sql
mysql -u"$MYSQL_USER" -p"$MYSQL_PASS" "$DB_INSTANCE" < "$RESTORE_DIR"/mysql/instance.sql

# 4. Restore Redis (optional)

if [[ -f "$RESTORE_DIR"/redis/dump.rdb ]]; then
    REDIS_DATA_DIR=$(grep -A1 'redis:' "$CONFIG_DIR"/cubemaster.yaml | grep 'data_dir' | head -1 | cut -d':' -f2 | tr -d ' "' || echo "/var/lib/redis")
    sudo cp "$RESTORE_DIR"/redis/dump.rdb "$REDIS_DATA_DIR/"
fi

# 5. Restart services

sudo systemctl restart cube-sandbox-cubemaster cube-sandbox-cubelet

```

## Summary

Restoring CubeSandbox configuration from a backup involves coordinated recovery across multiple persistence layers:

- **Static configuration** is restored by copying [`cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubemaster.yaml), [`cubelet.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubelet.yaml), and [`network-agent.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent.yaml) to `configs/single-node/`.
- **Runtime state** is recovered by importing MySQL dumps into `ossdb_config` and `instance_db_config` using credentials extracted from the restored YAML files.
- **Environment overrides** are preserved by restoring the `.env` file to the repository root.
- **Metric data** can be optionally recovered by replacing the Redis `dump.rdb` file before restarting services.

## Frequently Asked Questions

### How do I restore CubeSandbox to a new host?

Restoring to a new host requires installing the CubeSandbox binaries or Docker images first, then extracting your backup to a temporary directory. Copy the YAML files to the same relative path (`configs/single-node/`), ensure the MySQL and Redis endpoints are accessible from the new host, and execute the import commands. Update the `.env` file if the new host uses different service endpoints or credentials.

### Can I restore only the YAML configuration without the databases?

You can restore only the static YAML files, but the system will fail to start or will initialize with empty state if the MySQL databases are missing. The `ossdb_config` database contains essential template definitions and authentication data referenced by CubeMaster at startup. Without it, the service will lose all sandbox definitions and user credentials.

### What happens if I skip the Redis snapshot restoration?

Skipping Redis restoration is safe for functional recovery. The Redis cache stores node-metric keys and sandbox-proxy routing information as implemented in the storage layer. If omitted, CubeSandbox will rebuild these entries automatically as nodes re-register and new metrics are collected, though historical metric data will be lost.

### How do I verify the restoration was successful?

Verify restoration by checking the MySQL database tables contain expected row counts, ensuring the CubeMaster service responds on its configured HTTP port (default defined in [`cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubemaster.yaml)), and confirming the Web UI loads if `WEB_UI_ENABLE` is set. Check the Cubelet logs to verify reconnection to the restored CubeMaster instance.