This commit is contained in:
307
docs/BACKUP_RESTORE.md
Normal file
307
docs/BACKUP_RESTORE.md
Normal file
@@ -0,0 +1,307 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user