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:

```bash
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:**
```json
{
  "description": "Backup before major changes"
}
```

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

**Example:**
```bash
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:**
```json
[
  {
    "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:**
```bash
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:**
```json
{
  "id": "backup-1703123456",
  "created_at": "2024-12-20T10:30:56Z",
  "version": "1.0",
  "description": "Weekly backup",
  "size": 24576
}
```

**Example:**
```bash
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:**
```json
{
  "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:**
```bash
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:**
```json
{
  "dry_run": false
}
```

**Parameters:**
- `dry_run` (optional): If `true`, shows what would be restored without making changes

**Response:**
```json
{
  "message": "backup restored successfully",
  "backup_id": "backup-1703123456"
}
```

**Example:**
```bash
# 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:**
```json
{
  "message": "backup deleted",
  "backup_id": "backup-1703123456"
}
```

**Example:**
```bash
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

```bash
# 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