318
docs/ISCSI_CONNECTION.md
Normal file
318
docs/ISCSI_CONNECTION.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# iSCSI Connection Instructions
|
||||
|
||||
## Overview
|
||||
|
||||
AtlasOS provides iSCSI connection instructions to help users connect initiators to iSCSI targets. The system automatically generates platform-specific commands for Linux, Windows, and macOS.
|
||||
|
||||
## API Endpoint
|
||||
|
||||
### Get Connection Instructions
|
||||
|
||||
**GET** `/api/v1/iscsi/targets/{id}/connection`
|
||||
|
||||
Returns connection instructions for an iSCSI target, including platform-specific commands.
|
||||
|
||||
**Query Parameters:**
|
||||
- `port` (optional): Portal port number (default: 3260)
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"iqn": "iqn.2024-12.com.atlas:target1",
|
||||
"portal": "192.168.1.100:3260",
|
||||
"portal_ip": "192.168.1.100",
|
||||
"portal_port": 3260,
|
||||
"luns": [
|
||||
{
|
||||
"id": 0,
|
||||
"zvol": "tank/iscsi/lun1",
|
||||
"size": 10737418240
|
||||
}
|
||||
],
|
||||
"commands": {
|
||||
"linux": [
|
||||
"# Discover target",
|
||||
"iscsiadm -m discovery -t sendtargets -p 192.168.1.100:3260",
|
||||
"",
|
||||
"# Login to target",
|
||||
"iscsiadm -m node -T iqn.2024-12.com.atlas:target1 -p 192.168.1.100:3260 --login",
|
||||
"",
|
||||
"# Verify connection",
|
||||
"iscsiadm -m session",
|
||||
"",
|
||||
"# Logout (when done)",
|
||||
"iscsiadm -m node -T iqn.2024-12.com.atlas:target1 -p 192.168.1.100:3260 --logout"
|
||||
],
|
||||
"windows": [
|
||||
"# Open PowerShell as Administrator",
|
||||
"",
|
||||
"# Add iSCSI target portal",
|
||||
"New-IscsiTargetPortal -TargetPortalAddress 192.168.1.100 -TargetPortalPortNumber 3260",
|
||||
"",
|
||||
"# Connect to target",
|
||||
"Connect-IscsiTarget -NodeAddress iqn.2024-12.com.atlas:target1",
|
||||
"",
|
||||
"# Verify connection",
|
||||
"Get-IscsiSession",
|
||||
"",
|
||||
"# Disconnect (when done)",
|
||||
"Disconnect-IscsiTarget -NodeAddress iqn.2024-12.com.atlas:target1"
|
||||
],
|
||||
"macos": [
|
||||
"# macOS uses built-in iSCSI support",
|
||||
"# Use System Preferences > Network > iSCSI",
|
||||
"",
|
||||
"# Or use command line (if iscsiutil is available)",
|
||||
"iscsiutil -a -t iqn.2024-12.com.atlas:target1 -p 192.168.1.100:3260",
|
||||
"",
|
||||
"# Portal: 192.168.1.100:3260",
|
||||
"# Target IQN: iqn.2024-12.com.atlas:target1"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Get Connection Instructions
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/api/v1/iscsi/targets/iscsi-1/connection \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
### With Custom Port
|
||||
|
||||
```bash
|
||||
curl "http://localhost:8080/api/v1/iscsi/targets/iscsi-1/connection?port=3261" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
## Platform-Specific Instructions
|
||||
|
||||
### Linux
|
||||
|
||||
**Prerequisites:**
|
||||
- `open-iscsi` package installed
|
||||
- `iscsid` service running
|
||||
|
||||
**Steps:**
|
||||
1. Discover the target
|
||||
2. Login to the target
|
||||
3. Verify connection
|
||||
4. Use the device (appears as `/dev/sdX` or `/dev/disk/by-id/...`)
|
||||
5. Logout when done
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Discover target
|
||||
iscsiadm -m discovery -t sendtargets -p 192.168.1.100:3260
|
||||
|
||||
# Login to target
|
||||
iscsiadm -m node -T iqn.2024-12.com.atlas:target1 -p 192.168.1.100:3260 --login
|
||||
|
||||
# Verify connection
|
||||
iscsiadm -m session
|
||||
|
||||
# Find device
|
||||
lsblk
|
||||
# or
|
||||
ls -l /dev/disk/by-id/ | grep iqn
|
||||
|
||||
# Logout when done
|
||||
iscsiadm -m node -T iqn.2024-12.com.atlas:target1 -p 192.168.1.100:3260 --logout
|
||||
```
|
||||
|
||||
### Windows
|
||||
|
||||
**Prerequisites:**
|
||||
- Windows 8+ or Windows Server 2012+
|
||||
- PowerShell (run as Administrator)
|
||||
|
||||
**Steps:**
|
||||
1. Add iSCSI target portal
|
||||
2. Connect to target
|
||||
3. Verify connection
|
||||
4. Initialize disk in Disk Management
|
||||
5. Disconnect when done
|
||||
|
||||
**Example (PowerShell as Administrator):**
|
||||
```powershell
|
||||
# Add portal
|
||||
New-IscsiTargetPortal -TargetPortalAddress 192.168.1.100 -TargetPortalPortNumber 3260
|
||||
|
||||
# Connect to target
|
||||
Connect-IscsiTarget -NodeAddress iqn.2024-12.com.atlas:target1
|
||||
|
||||
# Verify connection
|
||||
Get-IscsiSession
|
||||
|
||||
# Initialize disk in Disk Management
|
||||
# (Open Disk Management, find new disk, initialize and format)
|
||||
|
||||
# Disconnect when done
|
||||
Disconnect-IscsiTarget -NodeAddress iqn.2024-12.com.atlas:target1
|
||||
```
|
||||
|
||||
### macOS
|
||||
|
||||
**Prerequisites:**
|
||||
- macOS 10.13+ (High Sierra or later)
|
||||
- iSCSI initiator software (third-party)
|
||||
|
||||
**Steps:**
|
||||
1. Use GUI iSCSI initiator (if available)
|
||||
2. Or use command line tools
|
||||
3. Configure connection settings
|
||||
4. Connect to target
|
||||
|
||||
**Note:** macOS doesn't have built-in iSCSI support. Use third-party software like:
|
||||
- GlobalSAN iSCSI Initiator
|
||||
- ATTO Xtend SAN iSCSI
|
||||
|
||||
## Portal IP Detection
|
||||
|
||||
The system automatically detects the portal IP address using:
|
||||
|
||||
1. **Primary Method**: Parse `targetcli` output to find configured portal IP
|
||||
2. **Fallback Method**: Use system IP from `hostname -I`
|
||||
3. **Default**: `127.0.0.1` if detection fails
|
||||
|
||||
**Custom Portal IP:**
|
||||
|
||||
If the detected IP is incorrect, you can manually specify it by:
|
||||
- Setting environment variable `ATLAS_ISCSI_PORTAL_IP`
|
||||
- Or modifying the connection instructions after retrieval
|
||||
|
||||
## LUN Information
|
||||
|
||||
The connection instructions include LUN information:
|
||||
|
||||
- **ID**: LUN number (typically 0, 1, 2, ...)
|
||||
- **ZVOL**: ZFS volume backing the LUN
|
||||
- **Size**: LUN size in bytes
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
"luns": [
|
||||
{
|
||||
"id": 0,
|
||||
"zvol": "tank/iscsi/lun1",
|
||||
"size": 10737418240
|
||||
},
|
||||
{
|
||||
"id": 1,
|
||||
"zvol": "tank/iscsi/lun2",
|
||||
"size": 21474836480
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Initiator ACLs
|
||||
|
||||
iSCSI targets can be configured with initiator ACLs to restrict access:
|
||||
|
||||
```json
|
||||
{
|
||||
"iqn": "iqn.2024-12.com.atlas:target1",
|
||||
"initiators": [
|
||||
"iqn.2024-12.com.client:initiator1"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Only initiators in the ACL list can connect to the target.
|
||||
|
||||
### CHAP Authentication
|
||||
|
||||
For production deployments, configure CHAP authentication:
|
||||
|
||||
1. Set up CHAP credentials in target configuration
|
||||
2. Configure initiator with matching credentials
|
||||
3. Use authentication in connection commands
|
||||
|
||||
**Note:** CHAP configuration is not yet exposed via API (future enhancement).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Fails
|
||||
|
||||
1. **Check Target Status**: Verify target is enabled
|
||||
2. **Check Portal**: Verify portal IP and port are correct
|
||||
3. **Check Network**: Ensure network connectivity
|
||||
4. **Check ACLs**: Verify initiator IQN is in ACL list
|
||||
5. **Check Firewall**: Ensure port 3260 (or custom port) is open
|
||||
|
||||
### Portal IP Incorrect
|
||||
|
||||
If the detected portal IP is wrong:
|
||||
|
||||
1. Check `targetcli` configuration
|
||||
2. Verify network interfaces
|
||||
3. Manually override in connection commands
|
||||
|
||||
### LUN Not Visible
|
||||
|
||||
1. **Check LUN Mapping**: Verify LUN is mapped to target
|
||||
2. **Check ZVOL**: Verify ZVOL exists and is accessible
|
||||
3. **Rescan**: Rescan iSCSI session on initiator
|
||||
4. **Check Permissions**: Verify initiator has access
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Use ACLs
|
||||
|
||||
Always configure initiator ACLs to restrict access:
|
||||
- Only allow known initiators
|
||||
- Use descriptive initiator IQNs
|
||||
- Regularly review ACL lists
|
||||
|
||||
### 2. Use CHAP Authentication
|
||||
|
||||
For production:
|
||||
- Enable CHAP authentication
|
||||
- Use strong credentials
|
||||
- Rotate credentials regularly
|
||||
|
||||
### 3. Monitor Connections
|
||||
|
||||
- Monitor active iSCSI sessions
|
||||
- Track connection/disconnection events
|
||||
- Set up alerts for connection failures
|
||||
|
||||
### 4. Test Connections
|
||||
|
||||
Before production use:
|
||||
- Test connection from initiator
|
||||
- Verify LUN visibility
|
||||
- Test read/write operations
|
||||
- Test disconnection/reconnection
|
||||
|
||||
### 5. Document Configuration
|
||||
|
||||
- Document portal IPs and ports
|
||||
- Document initiator IQNs
|
||||
- Document LUN mappings
|
||||
- Keep connection instructions accessible
|
||||
|
||||
## Compliance with SRS
|
||||
|
||||
Per SRS section 4.6 iSCSI Block Storage:
|
||||
|
||||
- ✅ **Provision ZVOL-backed LUNs**: Implemented
|
||||
- ✅ **Create iSCSI targets with IQN**: Implemented
|
||||
- ✅ **Map LUNs to targets**: Implemented
|
||||
- ✅ **Configure initiator ACLs**: Implemented
|
||||
- ✅ **Expose connection instructions**: Implemented (Priority 21)
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
1. **CHAP Authentication**: API support for CHAP configuration
|
||||
2. **Portal Management**: Manage multiple portals per target
|
||||
3. **Connection Monitoring**: Real-time connection status
|
||||
4. **Auto-Discovery**: Automatic initiator discovery
|
||||
5. **Connection Templates**: Pre-configured connection templates
|
||||
6. **Connection History**: Track connection/disconnection events
|
||||
7. **Multi-Path Support**: Instructions for multi-path configurations
|
||||
Reference in New Issue
Block a user