164 lines
4.8 KiB
Markdown
164 lines
4.8 KiB
Markdown
# Service Daemon Integration
|
|
|
|
## Overview
|
|
|
|
AtlasOS integrates with system storage daemons (Samba, NFS, iSCSI) to automatically apply configuration changes. When storage services are created, updated, or deleted via the API, the system daemons are automatically reconfigured.
|
|
|
|
## Architecture
|
|
|
|
The service integration layer (`internal/services/`) provides:
|
|
|
|
- **Configuration Generation**: Converts API models to daemon-specific configuration formats
|
|
- **Atomic Updates**: Writes to temporary files, then atomically replaces configuration
|
|
- **Safe Reloads**: Reloads services without interrupting active connections
|
|
- **Error Recovery**: Automatically restores backups on configuration failures
|
|
|
|
## SMB/Samba Integration
|
|
|
|
### Configuration
|
|
- **Config File**: `/etc/samba/smb.conf`
|
|
- **Service**: `smbd` (Samba daemon)
|
|
- **Reload Method**: `smbcontrol all reload-config` or `systemctl reload smbd`
|
|
|
|
### Features
|
|
- Generates Samba configuration from SMB share definitions
|
|
- Supports read-only, guest access, and user restrictions
|
|
- Automatically reloads Samba after configuration changes
|
|
- Validates configuration syntax using `testparm`
|
|
|
|
### Example
|
|
When an SMB share is created via API:
|
|
1. Share is stored in the store
|
|
2. All shares are retrieved
|
|
3. Samba configuration is generated
|
|
4. Configuration is written to `/etc/samba/smb.conf`
|
|
5. Samba service is reloaded
|
|
|
|
## NFS Integration
|
|
|
|
### Configuration
|
|
- **Config File**: `/etc/exports`
|
|
- **Service**: `nfs-server`
|
|
- **Reload Method**: `exportfs -ra`
|
|
|
|
### Features
|
|
- Generates `/etc/exports` format from NFS export definitions
|
|
- Supports read-only, client restrictions, and root squash
|
|
- Automatically reloads NFS exports after configuration changes
|
|
- Handles multiple clients per export
|
|
|
|
### Example
|
|
When an NFS export is created via API:
|
|
1. Export is stored in the store
|
|
2. All exports are retrieved
|
|
3. `/etc/exports` is generated
|
|
4. Exports file is written atomically
|
|
5. NFS exports are reloaded using `exportfs -ra`
|
|
|
|
## iSCSI Integration
|
|
|
|
### Configuration
|
|
- **Tool**: `targetcli` (LIO target framework)
|
|
- **Service**: `target` (systemd service)
|
|
- **Method**: Direct targetcli commands
|
|
|
|
### Features
|
|
- Creates iSCSI targets with IQN
|
|
- Configures initiator ACLs
|
|
- Maps ZVOLs as LUNs
|
|
- Manages target enable/disable state
|
|
|
|
### Example
|
|
When an iSCSI target is created via API:
|
|
1. Target is stored in the store
|
|
2. All targets are retrieved
|
|
3. For each target:
|
|
- Target is created via `targetcli`
|
|
- Initiator ACLs are configured
|
|
- LUNs are mapped to ZVOLs
|
|
4. Configuration is applied atomically
|
|
|
|
## Safety Features
|
|
|
|
### Atomic Configuration Updates
|
|
1. Write configuration to temporary file (`*.atlas.tmp`)
|
|
2. Backup existing configuration (`.backup`)
|
|
3. Atomically replace configuration file
|
|
4. Reload service
|
|
5. On failure, restore backup
|
|
|
|
### Error Handling
|
|
- Configuration errors are logged but don't fail API requests
|
|
- Service reload failures trigger automatic backup restoration
|
|
- Validation is performed before applying changes (where supported)
|
|
|
|
## Service Status
|
|
|
|
Each service provides a `GetStatus()` method to check if the daemon is running:
|
|
|
|
```go
|
|
// Check Samba status
|
|
running, err := smbService.GetStatus()
|
|
|
|
// Check NFS status
|
|
running, err := nfsService.GetStatus()
|
|
|
|
// Check iSCSI status
|
|
running, err := iscsiService.GetStatus()
|
|
```
|
|
|
|
## Requirements
|
|
|
|
### Samba
|
|
- `samba` package installed
|
|
- `smbcontrol` command available
|
|
- Write access to `/etc/samba/smb.conf`
|
|
- Root/sudo privileges for service reload
|
|
|
|
### NFS
|
|
- `nfs-kernel-server` package installed
|
|
- `exportfs` command available
|
|
- Write access to `/etc/exports`
|
|
- Root/sudo privileges for export reload
|
|
|
|
### iSCSI
|
|
- `targetcli` package installed
|
|
- LIO target framework enabled
|
|
- Root/sudo privileges for targetcli operations
|
|
- ZVOL backend support
|
|
|
|
## Configuration Flow
|
|
|
|
```
|
|
API Request → Store Update → Service Integration → Daemon Configuration
|
|
↓ ↓ ↓ ↓
|
|
Create/ Store in Generate Config Write & Reload
|
|
Update/ Memory/DB from Models Service
|
|
Delete
|
|
```
|
|
|
|
## Future Enhancements
|
|
|
|
1. **Async Configuration**: Queue configuration changes for background processing
|
|
2. **Validation API**: Pre-validate configurations before applying
|
|
3. **Rollback Support**: Automatic rollback on service failures
|
|
4. **Status Monitoring**: Real-time service health monitoring
|
|
5. **Configuration Diff**: Show what will change before applying
|
|
|
|
## Troubleshooting
|
|
|
|
### Samba Configuration Not Applied
|
|
- Check Samba service status: `systemctl status smbd`
|
|
- Validate configuration: `testparm -s`
|
|
- Check logs: `journalctl -u smbd`
|
|
|
|
### NFS Exports Not Working
|
|
- Check NFS service status: `systemctl status nfs-server`
|
|
- Verify exports: `exportfs -v`
|
|
- Check permissions on exported paths
|
|
|
|
### iSCSI Targets Not Created
|
|
- Verify targetcli is installed: `which targetcli`
|
|
- Check LIO service: `systemctl status target`
|
|
- Review targetcli output for errors
|