atlas/docs/ISCSI_CONNECTION.md

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:

{
  "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

curl http://localhost:8080/api/v1/iscsi/targets/iscsi-1/connection \
  -H "Authorization: Bearer $TOKEN"

With Custom Port

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:

# 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):

# 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:

"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:

{
  "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