# 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