atlas/docs/SERVICE_INTEGRATION.md

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:

// 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