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 required a unique target id (tid), header and data digest is 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): addupdate, delete

Default mode (LUNs): add

Sample JSON

   {

      "accounts":    [{

            "account":    {

                "username":    "Sam",

                "password":    "Sams password",

                "mode":    "add"

            }

        }, {

            "account":    {

                "username":    "glen",

                "password":    "the new password",

                "mode":    "change"

            }

        }, {

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

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"

                        }]

                }

            }]

}