atlas/docs/BACKUP_RESTORE.md

Configuration Backup & Restore

Overview

AtlasOS provides comprehensive configuration backup and restore functionality, allowing you to save and restore all system configurations including users, storage services (SMB/NFS/iSCSI), and snapshot policies.

Features

• Full Configuration Backup: Backs up all system configurations
• Compressed Archives: Backups are stored as gzipped tar archives
• Metadata Tracking: Each backup includes metadata (ID, timestamp, description, size)
• Verification: Verify backup integrity before restore
• Dry Run: Test restore operations without making changes
• Selective Restore: Restore specific components or full system

Configuration

Set the backup directory using the ATLAS_BACKUP_DIR environment variable:

export ATLAS_BACKUP_DIR=/var/lib/atlas/backups
./atlas-api

If not set, defaults to data/backups in the current directory.

Backup Contents

A backup includes:

• Users: All user accounts (passwords cannot be restored - users must reset)
• SMB Shares: All SMB/CIFS share configurations
• NFS Exports: All NFS export configurations
• iSCSI Targets: All iSCSI targets and LUN mappings
• Snapshot Policies: All automated snapshot policies
• System Config: Database path and other system settings

API Endpoints

Create Backup

POST /api/v1/backups

Creates a new backup of all system configurations.

Request Body:

{
  "description": "Backup before major changes"
}

Response:

{
  "id": "backup-1703123456",
  "created_at": "2024-12-20T10:30:56Z",
  "version": "1.0",
  "description": "Backup before major changes",
  "size": 24576
}

Example:

curl -X POST http://localhost:8080/api/v1/backups \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"description": "Weekly backup"}'

List Backups

GET /api/v1/backups

Lists all available backups.

Response:

[
  {
    "id": "backup-1703123456",
    "created_at": "2024-12-20T10:30:56Z",
    "version": "1.0",
    "description": "Weekly backup",
    "size": 24576
  },
  {
    "id": "backup-1703037056",
    "created_at": "2024-12-19T10:30:56Z",
    "version": "1.0",
    "description": "",
    "size": 18432
  }
]

Example:

curl -X GET http://localhost:8080/api/v1/backups \
  -H "Authorization: Bearer <token>"

Get Backup Details

GET /api/v1/backups/{id}

Retrieves metadata for a specific backup.

Response:

{
  "id": "backup-1703123456",
  "created_at": "2024-12-20T10:30:56Z",
  "version": "1.0",
  "description": "Weekly backup",
  "size": 24576
}

Example:

curl -X GET http://localhost:8080/api/v1/backups/backup-1703123456 \
  -H "Authorization: Bearer <token>"

Verify Backup

GET /api/v1/backups/{id}?verify=true

Verifies that a backup file is valid and can be restored.

Response:

{
  "message": "backup is valid",
  "backup_id": "backup-1703123456",
  "metadata": {
    "id": "backup-1703123456",
    "created_at": "2024-12-20T10:30:56Z",
    "version": "1.0",
    "description": "Weekly backup",
    "size": 24576
  }
}

Example:

curl -X GET "http://localhost:8080/api/v1/backups/backup-1703123456?verify=true" \
  -H "Authorization: Bearer <token>"

Restore Backup

POST /api/v1/backups/{id}/restore

Restores configuration from a backup.

Request Body:

{
  "dry_run": false
}

Parameters:

• dry_run (optional): If true, shows what would be restored without making changes

Response:

{
  "message": "backup restored successfully",
  "backup_id": "backup-1703123456"
}

Example:

# Dry run (test restore)
curl -X POST http://localhost:8080/api/v1/backups/backup-1703123456/restore \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'

# Actual restore
curl -X POST http://localhost:8080/api/v1/backups/backup-1703123456/restore \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": false}'

Delete Backup

DELETE /api/v1/backups/{id}

Deletes a backup file and its metadata.

Response:

{
  "message": "backup deleted",
  "backup_id": "backup-1703123456"
}

Example:

curl -X DELETE http://localhost:8080/api/v1/backups/backup-1703123456 \
  -H "Authorization: Bearer <token>"

Restore Process

When restoring a backup:

1. Verification: Backup is verified before restore
2. User Restoration:
   • Users are restored with temporary passwords
   • Default admin user (user-1) is skipped
   • Users must reset their passwords after restore
3. Storage Services:
   • SMB shares, NFS exports, and iSCSI targets are restored
   • Existing configurations are skipped (not overwritten)
   • Service configurations are automatically applied
4. Snapshot Policies:
   • Policies are restored by dataset
   • Existing policies are skipped
5. Service Application:
   • Samba, NFS, and iSCSI services are reconfigured
   • Errors are logged but don't fail the restore

Backup File Format

Backups are stored as gzipped tar archives containing:

• metadata.json: Backup metadata (ID, timestamp, description, etc.)
• config.json: All configuration data (users, shares, exports, targets, policies)

Best Practices

1. Regular Backups: Create backups before major configuration changes
2. Verify Before Restore: Always verify backups before restoring
3. Test Restores: Use dry run to test restore operations
4. Backup Retention: Keep multiple backups for different time periods
5. Offsite Storage: Copy backups to external storage for disaster recovery
6. Password Management: Users must reset passwords after restore

Limitations

• Passwords: User passwords cannot be restored (security feature)
• ZFS Data: Backups only include configuration, not ZFS pool/dataset data
• Audit Logs: Audit logs are not included in backups
• Jobs: Background jobs are not included in backups

Error Handling

• Invalid Backup: Verification fails if backup is corrupted
• Missing Resources: Restore skips resources that already exist
• Service Errors: Service configuration errors are logged but don't fail restore
• Partial Restore: Restore continues even if some components fail

Security Considerations

1. Backup Storage: Store backups in secure locations
2. Access Control: Backup endpoints require authentication
3. Password Security: Passwords are never included in backups
4. Encryption: Consider encrypting backups for sensitive environments

Example Workflow

# 1. Create backup before changes
BACKUP_ID=$(curl -X POST http://localhost:8080/api/v1/backups \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"description": "Before major changes"}' \
  | jq -r '.id')

# 2. Verify backup
curl -X GET "http://localhost:8080/api/v1/backups/$BACKUP_ID?verify=true" \
  -H "Authorization: Bearer <token>"

# 3. Make configuration changes
# ... make changes ...

# 4. Test restore (dry run)
curl -X POST "http://localhost:8080/api/v1/backups/$BACKUP_ID/restore" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'

# 5. Restore if needed
curl -X POST "http://localhost:8080/api/v1/backups/$BACKUP_ID/restore" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": false}'

Future Enhancements

• Scheduled Backups: Automatic backup scheduling
• Incremental Backups: Only backup changes since last backup
• Backup Encryption: Encrypt backup files
• Remote Storage: Support for S3, FTP, etc.
• Backup Compression: Additional compression options
• Selective Restore: Restore specific components only