Windows Server 2008 iscsicli.exe CommandLine Interface

The easiest way to connect to you iSCSI storage LUNs from Windows Server 2008 is by using the iSCSI initiator GUI. With the GUI you can easily make a connection with your iSCSI Storage by giving the ip-address and dynamically discover the LUNs (or Volumes) it has to offer. With the Windows Server 2008 R2 Core edition, you can start the GUI with iSCSICPL.exe.
In case you do not have the option to use the GUI (Core Server or when scripting the configuration), you can use the CommandLine Interface (CLI) Windows Server 2008 has to offer by default.

The iscsicli.exe command of Windows Server 2008 allows you to use the Microsoft iSCSI initiator without the GUI. Making it the perfect tool for scripting the iSCSI connections (Hyper-V Server shared storage). If you know the ip-address of your iSCSI storage and the IQN of the LUN you want to use (though it can be found with the command), you are all set to set up the connection and use your shared storage.

This post offers step-by-step instructions for the iscsicli.exe command.

Enable the iSCSI Initiator

The Microsoft (software) iSCSI initiator uses the Microsoft iSCSI Service to communicate with you iSCSI storage. This Service is set to manual startup by default, which must be changed (and started) to be able to use the initiator.

* Change the startup type for the Microsoft iSCSI Service (iSCSI initiator):

C:\>sc [server-name] config msiscsi start= auto

 
Which uses the following additional syntax:

• server-name: NetBIOS name of the server (\\localhost); optional value if the command is run locally.

Notice the space between start= and auto, this space is mandatory for the sc.exe command.

* Start the Microsoft iSCSI Service:

C:\>sc [server-name] start msiscsi

 
Which uses the following additional syntax:

• server-name: NetBIOS name of the server (\\localhost); optional value if the command is run locally.

* Check the status of the Service (if you want to be sure):

C:\>sc [server-name] query msiscsi

 
Which uses the following additional syntax:

• server-name: NetBIOS name of the server (\\localhost); optional value if the command is run locally.

Configuring the iSCSI initiator (using iscsicli.exe)

After the Service settings are made, the CLI can be used to connect to the iSCSI Target and right LUN. Thus creating a new local disk to be used by the Operating System.

 

* Add iSCSI Targets:

C:\>iscsicli.exe QAddTargetPortal [tartget-portal-address] [chap-username] [chap-password]

 
Which uses the following additional syntax:

• target-portal-address: IP-address of the iSCSI storage.
• chap-username: Username for CHAP authentication; optional.
• chap-password: Password for CHAP authentication; optional.

* Get the iSCSI Target IQN:

C:\>iscsicli.exe ListTargets

Microsoft iSCSI Initiator Version 6.0 Build 6000

Target List:
     iqn.2001-05.com.example:x-xxxxxx-xxxxxxxxx-xxxxxxxxxxx

The operation completed successfully.

* Login to Target:

C:\>iscsicli.exe QLoginTarget [target-iqn]

 
Which uses the following additional syntax:

• target-iqn: unique identifier of the LUN/Volume (IQN) you want to connect to on the iSCSI Storage.

* Set up a persistent connection (reconnects after reboot Server):

C:\>iscsicli.exe PersistentLoginTarget [target-iqn] T * * * * * * * * * * * * * * * 0

 
Which uses the following additional syntax:

• target-iqn: unique identifier of the LUN/Volume (IQN) you want to connect to on the iSCSI Storage.

* List the persistent connections to target LUNs:

C:\>iscsicli.exe ListPersistentTargets

Microsoft iSCSI Initiator Version 6.0 Build 6000
Total of 1 persistent targets
Target Name: [target-iqn]
Address and Socket : [ip-address-storage] [port-number]
Session Type : Data
Initiator Name : Root\ISCSIPRTY\0000_0
Port Number : <Any Port>
++Security Flags : 0x0
++Version : 0
++Information Specified: 0x20
++Login Flags: 0x8
++Username : 

The operation completed successfully.

 
Which uses the following additional syntax:

• target-iqn: unique identifier of the LUN/Volume (IQN) you want to connect to on the iSCSI Storage.
• ip-address-storage: ip-address of the iSCSI storage device.
• port-number: port number (socket) used for the connection; default port 3260 is used.

* Check active connections:

C:\>iscsicli.exe ReportTargetMappings

After the connection is set up, the LUN will be shown as a local disk (offline and with the readonly attribute set) of the Windows Server. The disk needs to be activated and configured before you are able to use it. A commandline tool like diskpart can be used if you want to automate this process as well or are not abel to use the Storage Manager GUI.

My next post will show how diskpart.exe can be used to script disk configurations.

Esther Barthel

Solutions Architect at cognition IT

Esther has been working in different roles and functions as an IT consultant ever since she finished her Masters degree in Computer Science in 1997. She has worked as a web developer, database administrator, and server administrator until she discovered how Server-Based Computing ( SBC ) combined servers, desktops, and user experience in one solution. Esther has been specializing in virtualization solutions such as SBC, VDI, application, and server virtualization for over eight years now and is currently working as a Senior Consultant at PepperByte, where she designs and implements Citrix® solutions for both small-business and large-enterprise infrastructures scaling from 100 to 15,000 users.
In january 2014 her first book Citrix XenApp 6.5 Expert Cookbook was published by Packt Publishing.

Esther is awarded as a Citrix Technology Professional (CTP) from 2015 - 2017.
Esther is awarded as a Microsoft Most Valuable Professional (MVP) in 2017.

Esther is a Citrix Certified Expert – Virtualization (CCE-V), Citrix Certified Professional – Mobility (CCP-M), Citrix Certified Professional – Networking (CCP-N) and RES Software Certified Professional (RCP).