307 lines
6.1 KiB
Markdown
307 lines
6.1 KiB
Markdown
# ZFS Operations
|
|
|
|
## Overview
|
|
|
|
AtlasOS provides comprehensive ZFS pool management including pool creation, import, export, scrubbing with progress monitoring, and health status reporting.
|
|
|
|
## Pool Operations
|
|
|
|
### List Pools
|
|
|
|
**GET** `/api/v1/pools`
|
|
|
|
Returns all ZFS pools.
|
|
|
|
**Response:**
|
|
```json
|
|
[
|
|
{
|
|
"name": "tank",
|
|
"status": "ONLINE",
|
|
"size": 1099511627776,
|
|
"allocated": 536870912000,
|
|
"free": 562641027776,
|
|
"health": "ONLINE",
|
|
"created_at": "2024-01-15T10:30:00Z"
|
|
}
|
|
]
|
|
```
|
|
|
|
### Get Pool
|
|
|
|
**GET** `/api/v1/pools/{name}`
|
|
|
|
Returns details for a specific pool.
|
|
|
|
### Create Pool
|
|
|
|
**POST** `/api/v1/pools`
|
|
|
|
Creates a new ZFS pool.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"name": "tank",
|
|
"vdevs": ["sda", "sdb"],
|
|
"options": {
|
|
"ashift": "12"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Destroy Pool
|
|
|
|
**DELETE** `/api/v1/pools/{name}`
|
|
|
|
Destroys a ZFS pool. **Warning**: This is a destructive operation.
|
|
|
|
## Pool Import/Export
|
|
|
|
### List Available Pools
|
|
|
|
**GET** `/api/v1/pools/available`
|
|
|
|
Lists pools that can be imported (pools that exist but are not currently imported).
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"pools": ["tank", "backup"]
|
|
}
|
|
```
|
|
|
|
### Import Pool
|
|
|
|
**POST** `/api/v1/pools/import`
|
|
|
|
Imports a ZFS pool.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"name": "tank",
|
|
"options": {
|
|
"readonly": "on"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Options:**
|
|
- `readonly`: Set pool to read-only mode (`on`/`off`)
|
|
- Other ZFS pool properties
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"message": "pool imported",
|
|
"name": "tank"
|
|
}
|
|
```
|
|
|
|
### Export Pool
|
|
|
|
**POST** `/api/v1/pools/{name}/export`
|
|
|
|
Exports a ZFS pool (makes it unavailable but preserves data).
|
|
|
|
**Request Body (optional):**
|
|
```json
|
|
{
|
|
"force": false
|
|
}
|
|
```
|
|
|
|
**Parameters:**
|
|
- `force` (boolean): Force export even if pool is in use
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"message": "pool exported",
|
|
"name": "tank"
|
|
}
|
|
```
|
|
|
|
## Scrub Operations
|
|
|
|
### Start Scrub
|
|
|
|
**POST** `/api/v1/pools/{name}/scrub`
|
|
|
|
Starts a scrub operation on a pool. Scrub verifies data integrity and repairs any errors found.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"message": "scrub started",
|
|
"pool": "tank"
|
|
}
|
|
```
|
|
|
|
### Get Scrub Status
|
|
|
|
**GET** `/api/v1/pools/{name}/scrub`
|
|
|
|
Returns detailed scrub status with progress information.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"status": "in_progress",
|
|
"progress": 45.2,
|
|
"time_elapsed": "2h15m",
|
|
"time_remain": "30m",
|
|
"speed": "100M/s",
|
|
"errors": 0,
|
|
"repaired": 0,
|
|
"last_scrub": "2024-12-15T10:30:00Z"
|
|
}
|
|
```
|
|
|
|
**Status Values:**
|
|
- `idle`: No scrub in progress
|
|
- `in_progress`: Scrub is currently running
|
|
- `completed`: Scrub completed successfully
|
|
- `error`: Scrub encountered errors
|
|
|
|
**Progress Fields:**
|
|
- `progress`: Percentage complete (0-100)
|
|
- `time_elapsed`: Time since scrub started
|
|
- `time_remain`: Estimated time remaining
|
|
- `speed`: Current scrub speed
|
|
- `errors`: Number of errors found
|
|
- `repaired`: Number of errors repaired
|
|
- `last_scrub`: Timestamp of last completed scrub
|
|
|
|
## Usage Examples
|
|
|
|
### Import a Pool
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8080/api/v1/pools/import \
|
|
-H "Authorization: Bearer $TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"name": "tank"
|
|
}'
|
|
```
|
|
|
|
### Start Scrub and Monitor Progress
|
|
|
|
```bash
|
|
# Start scrub
|
|
curl -X POST http://localhost:8080/api/v1/pools/tank/scrub \
|
|
-H "Authorization: Bearer $TOKEN"
|
|
|
|
# Check progress
|
|
curl http://localhost:8080/api/v1/pools/tank/scrub \
|
|
-H "Authorization: Bearer $TOKEN"
|
|
```
|
|
|
|
### Export Pool
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8080/api/v1/pools/tank/export \
|
|
-H "Authorization: Bearer $TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"force": false
|
|
}'
|
|
```
|
|
|
|
## Scrub Best Practices
|
|
|
|
### When to Scrub
|
|
|
|
- **Regular Schedule**: Monthly or quarterly
|
|
- **After Disk Failures**: After replacing failed disks
|
|
- **Before Major Operations**: Before pool upgrades or migrations
|
|
- **After Data Corruption**: If data integrity issues are suspected
|
|
|
|
### Monitoring Scrub Progress
|
|
|
|
1. **Start Scrub**: Use POST endpoint to start
|
|
2. **Monitor Progress**: Poll GET endpoint every few minutes
|
|
3. **Check Errors**: Monitor `errors` and `repaired` fields
|
|
4. **Wait for Completion**: Wait until `status` is `completed`
|
|
|
|
### Scrub Performance
|
|
|
|
- **Impact**: Scrub operations can impact pool performance
|
|
- **Scheduling**: Schedule during low-usage periods
|
|
- **Duration**: Large pools may take hours or days
|
|
- **I/O**: Scrub generates significant I/O load
|
|
|
|
## Pool Import/Export Use Cases
|
|
|
|
### Import Use Cases
|
|
|
|
1. **System Reboot**: Pools are automatically imported on boot
|
|
2. **Manual Import**: Import pools that were exported
|
|
3. **Read-Only Import**: Import pool in read-only mode for inspection
|
|
4. **Recovery**: Import pools from backup systems
|
|
|
|
### Export Use Cases
|
|
|
|
1. **System Shutdown**: Export pools before shutdown
|
|
2. **Maintenance**: Export pools for maintenance operations
|
|
3. **Migration**: Export pools before moving to another system
|
|
4. **Backup**: Export pools before creating full backups
|
|
|
|
## Error Handling
|
|
|
|
### Pool Not Found
|
|
|
|
```json
|
|
{
|
|
"code": "NOT_FOUND",
|
|
"message": "pool not found"
|
|
}
|
|
```
|
|
|
|
### Scrub Already Running
|
|
|
|
```json
|
|
{
|
|
"code": "CONFLICT",
|
|
"message": "scrub already in progress"
|
|
}
|
|
```
|
|
|
|
### Pool in Use (Export)
|
|
|
|
```json
|
|
{
|
|
"code": "CONFLICT",
|
|
"message": "pool is in use, cannot export"
|
|
}
|
|
```
|
|
|
|
Use `force: true` to force export (use with caution).
|
|
|
|
## Compliance with SRS
|
|
|
|
Per SRS section 4.2 ZFS Management:
|
|
|
|
- ✅ **List available disks**: Implemented
|
|
- ✅ **Create pools**: Implemented
|
|
- ✅ **Import pools**: Implemented (Priority 20)
|
|
- ✅ **Export pools**: Implemented (Priority 20)
|
|
- ✅ **Report pool health**: Implemented
|
|
- ✅ **Create and manage datasets**: Implemented
|
|
- ✅ **Create ZVOLs**: Implemented
|
|
- ✅ **Scrub operations**: Implemented
|
|
- ✅ **Progress monitoring**: Implemented (Priority 19)
|
|
|
|
## Future Enhancements
|
|
|
|
1. **Scrub Scheduling**: Automatic scheduled scrubs
|
|
2. **Scrub Notifications**: Alerts when scrub completes or finds errors
|
|
3. **Pool Health Alerts**: Automatic alerts for pool health issues
|
|
4. **Import History**: Track pool import/export history
|
|
5. **Pool Properties**: Manage pool properties via API
|
|
6. **VDEV Management**: Add/remove vdevs from pools
|
|
7. **Pool Upgrade**: Upgrade pool version
|
|
8. **Resilver Operations**: Monitor and manage resilver operations
|