Quick Page Index
iSCSI Service Configuration
Interface and CHAP Binding JSON Example
Complete Configuration JSON Example
Also see iSCSI Configuration Troubleshooting
Integrated iSCSI Service Configuration
The Nexfs integrated iSCSI service is configured using JSON formatted change requests, the simplest method to view or to load JSON iSCSI configuration changes is using the Nexfs admin command nexfscli (see using nexfscli to manage iSCSI)
iSCSI Configuration Sections
The iSCSI configuration is split into four sections, each section can be configured separately and only the configuration parts that are to be changed need to be included in an iSCSI JSON change request.
When issuing a change request you need to specify the change mode, the mode is one of:
add - Add a new configuration
update - Change an existing configuration
delete - Delete a configuration
online - Bring a LUN online
offline - Take a LUN offline
offline:delete - Take a LUN offline and then delete that LUN
Not all modes are available for each configuration section, those that are supported are in the relative section documented below
iSCSI Interface Configuration
An iSCSI Interface specifies a local network IP address and port number that the iSCSI service should service clients over.
If no interfaces are manually created then Nexfs will automatically serve clients on all system network interfaces on the default iSCSI port 3260. There is no need to manually remove the default all interface, it will be automatically removed when the first manually interface has been created.
Note: Interfaces must be bound to Targets
Supported modes: add, delete
Default mode: add
Sample JSON
{
"interfaces": [{
"interface": {
"address": "192.168.178.70:3260",
"mode": "add"
}
}, {
"interface": {
"address": "127.0.0.1:3260"
}
}, {
"interface": {
"address": "172.16.43.17:6100",
"mode": "delete"
}]
}
The above example will create two interfaces and delete one, the new interfaces are both listening on port 3260, the first interface attached to the network interface with the IP address 192.168.178.70, the second to the local loop-back IP address 127.0.0.1. The third interface with the IP address 172.16.43.17 and port 6100 will be deleted.
Notice that when adding a new interface specifying the mode is optional.
iSCSI Target and LUN Configuration
LUNs are attached to iSCSI Targets, iSCSI Targets are created automatically when a LUN is attached to a Target that does not already exist. Targets cannot be created without at least one LUN, Targets cannot be manually deleted.
Note: Targets must be bound to interfaces before they can be accessed by iSCSI clients.
A target requires a unique target id (tid). Header and data digest are configured at the target level.
Headerdigest and datadigest can both be enabled at the target level, to enabled either set the corresponding value in the JSON request to "on",or to "off" to disable (the default)
Supported modes (LUNs): online, offline, delete, offline:delete
Default mode (LUNs): online
A LUN must be offline before it can be deleted, it is possible to take a LUN offline and deleted it in a single request using the special "offline:delete" mode.
For lun file path, the prefix directory that the Nexfs file system is mounted to is excluded, for example, if Nexfs is mounted to /mnt/nexfs and the intention is create a LUN using the file /mnt/nexfs/virtalservers/lun01, then the path in the JSON is only "/virtalservers/lun01". This allows the Nexfs mount point location to be changed without the need to update existing iSCSI LUNs.
Sample JSON
{
"itargets": [{
"itarget": {
"tid": 1,
"headerdigest": "on",
"datadigest": "on",
"luns": [{
"lun": 1,
"path": "/iscsi/lun01",
"mode": "delete"
}, {
"lun": 2,
"path": "/virtualservers/windowsserver.img",
"mode": "online"
}, {
"lun": 3,
"path": "/virtualservers/linuxserver.img"
}]
}
},
{
"itarget": {
"tid": 2,
"luns": [{
"lun": 1,
"path": "/old/lunA",
"mode": "offline"
}, {
"lun": 2,
"path": "/LunB.img",
"mode": "delete"
}, {
"lun": 3,
"path": "/ntfs.img",
"mode": "offline:delete"
}]
}
},
{
"itarget": {
"tid": 3,
"headerdigest": "on",
"datadigest": "off"
}
}]
}
The above JSON enables both header digest and data digest on target id 1(tid 1), next it deletes LUN 1 which has been exported using the path /iscsi/lun01 attached to target 1, and then created two new LUNs also attached to Target id 1, notice that no mode has been included when creating LUN 3 with path /virtualservers/linuxserver.img, online (create) is the default mode.
For Target 2, LUN 1 is taken offline, and LUN 2 is deleted (note that LUN 2 must already be offline for the delete to succeed), LUN3 which is active is first taken offline and then deleted.
Finally for existing Target 3, headerdigest is enabled and datadigest is disabled, note that as no LUN configuration is changed there is no requirement to include existing LUNs with that request.
iSCSI CHAP Accounts
iSCSI accounts are optional, when created they must be bound (see Bindings Below) to Targets to become active. iSCSI accounts can be enabled for one or more Target, there is no requirement for each Target to have its own set of accounts.
Note: CHAP Accounts must be bound to Targets to become active
Supported modes (LUNs): add, update, delete
Default mode (LUNs): add
Sample JSON
{
"accounts": [{
"account": {
"username": "Sam",
"password": "Sams password",
"mode": "add"
}
}, {
"account": {
"username": "glen",
"password": "the new password",
"mode": "update"
}
}, {
"account": {
"username": "Joey",
"mode": "delete"
}
}]
}
In the above example from a new account with the username "Sam" and Password "Sams password" is created, then the password for the existing account "glen" is changed to"the new password", and finally the existing account for the username "Joey" is deleted.
iSCSI Target interface and CHAP account Bindings
Target Interface Bindings
Targets must be bound to one or more Interfaces before they and their attached LUNs can be accessed. To bind a Target to all interfaces in a single operation the "ALL" keyword is used.
Supported modes (LUNs): add, delete
Default mode (LUNs): add
Sample JSON
{
"bindings": [{
"binding": {
"tid": 1,
"bindto": [{
"address": "192.168.178.70:3260",
"mode": "add"
},
{
"address": "127.0.0.1:3260",
"mode": "delete"
}]
}
},
{
"binding": {
"tid": 2,
"bindto": [{
"address": "ALL"
}]
}
}]
}
In the above example bindings are configured for two Targets, first a binding to interface 192.168.178.70:3260 is created for Target 1, next, the existing binding to interface 127.0.0.1:3260 is removed from Target 1, finally, Target 2 is bound to all interfaces using the special "ALL" interface keyword.
Target CHAP Security Account Bindings
iSCSI accounts can be enabled for inbound authentication or outbound authentication, inbound requires the iSCSI client must authenticate to the iSCSI server, outbound requires the iSCSI server to authenticate back to the client.
Note: inbound authentication must be enabled before outbound authentication can be activated.
Supported modes (LUNs): add,inbound, delete, deleteinbound, addtarget ,outbound, deletetarget, deleteoutbound
Default mode (LUNs): add
The following mode aliases are also valid and may optionally also be used:
add = inbound
delete = deleteinbound
addtarget = outbound
deletetarget = deleteoutbound
Sample JSON
{
"bindings": [{
"binding": {
"tid": 1,
"accounts": [{
"username": "Joey",
"mode": "inbound"
},
{
"username": "Sam",
"mode": "deleteoutbound"
}]
}
}]
}
In the example shown above first the CHAP username "Joey" is enabled for the client to the iSCSI service authentication on Target 1, then the username "Sam" is removed from Target 1 for outbound iSCSI server to client authentication.
Sample Combined iSCSI Interface and Accounts Binding JSON
Interface and account bindings can be included in a single request, the below provide a sample JSON for combining the examples shown above
{
"bindings": [{
"binding": {
"tid": 1,
"bindto": [{
"address": "192.168.178.70:3260",
"mode": "add"
},
{
"address": "127.0.0.1:3260",
"mode": "delete"
}],
"accounts": [{
"username": "Joey",
"mode": "inbound"
},
{
"username": "Sam",
"mode": "deleteoutbound"
}]
}
},
{
"binding": {
"tid": 2,
"bindto": [{
"address": "ALL"
}]
}
}]
}
iSCSI JSON Configuration all sections example
You may include one or more sections in a single JSON request, the following example shows a correctly formatted configuration contains all iSCSI sections
{
"interfaces": [{
"interface": {
"address": "192.168.178.70:3260",
"mode": "add"
}
}, {
"interface": {
"address": "127.0.0.1:3260"
}
}, {
"interface": {
"address": "172.16.43.17:6100",
"mode": "delete"
}
}],
"itargets": [{
"itarget": {
"tid": 1,
"headerdigest": "on",
"datadigest": "on",
"luns": [{
"lun": 1,
"path": "/iscsi/lun01",
"mode": "delete"
}, {
"lun": 2,
"path": "/virtualservers/windowsserver.img",
"mode": "online"
}, {
"lun": 3,
"path": "/virtualservers/linuxserver.img"
}]
}
},
{
"itarget": {
"tid": 2,
"luns": [{
"lun": 1,
"path": "/old/lunA",
"mode": "offline"
}, {
"lun": 2,
"path": "/LunB.img",
"mode": "delete"
}, {
"lun": 3,
"path": "/ntfs.img",
"mode": "offline:delete"
}]
}
},
{
"itarget": {
"tid": 3,
"headerdigest": "on",
"datadigest": "off"
}
}],
"accounts": [{
"account": {
"username": "Sam",
"password": "Sams password",
"mode": "delete"
}
}, {
"account": {
"username": "glen",
"password": "the new password",
"mode": "change"
}
}, {
"account": {
"username": "Joey",
"mode": "add"
}
}],
"bindings": [{
"binding": {
"tid": 1,
"bindto": [{
"address": "192.168.178.70:3260",
"mode": "add"
},
{
"address": "127.0.0.1:3260",
"mode": "delete"
}],
"accounts": [{
"username": "Joey",
"mode": "inbound"
},
{
"username": "Sam",
"mode": "deleteoutbound"
}]
}
},
{
"binding": {
"tid": 2,
"bindto": [{
"address": "ALL"
}]
}
}]
}