Windows Server 2008 Server Core : Working with iSCSI Using the iSCSICli Utility (part 1) - Working with the iSCSI Client (iSCSICli) Utility

1. Starting the iSCSI Initiator

Before you can use an iSCSI drive, you must start the iSCSI initiator service by typing SC Start MSiSCSI and pressing Enter. To ensure that the iSCSI initiator service starts in the future, type SC Config MSiSCSI Start= Auto and press Enter (remember the space between the = and the word Auto). In addition, you must allow the iSCSI initiator through the firewall. Unfortunately, you can't use the NetSH utility to perform this task because Windows Server 2008 uses a new technique to set some features. You must use the Registry Editor (RegEdit.EXE) to perform this task. The following steps tell you how to perform the configuration change.

2. Working with the iSCSI Client (iSCSICli) Utility

The iSCSICli utility supports an interactive mode. Type iSCSICli and press Enter to access this mode. You can use any of the commands that you can use at command line in interactive mode without typing iSCSICli first. For example, if you want to obtain a list of initiators, type ListInitiators and press Enter. This utility uses the following syntax for each supported command:

Manually Configured Targets:

iSCSICli AddTarget TargetName TargetAlias TargetPortalAddress
   TargetPortalSocket TargetFlags Persist LoginFlags HeaderDigest
   DataDigest MaxConnections DefaultTime2Wait DefaultTime2Retain
   Username Password AuthType MappingCount MappingEntries
iSCSICli QAddTarget TargetName TargetPortalAddress
iSCSICli RemoveTarget TargetName
iSCSICli ListTargets [ForceUpdate]

Target Portals:

iSCSICli AddTargetPortal TargetPortalAddress TargetPortalSocket
   [HBAName] [PortNumber] SecurityFlags LoginFlags HeaderDigest
   DataDigest MaxConnections DefaultTime2Wait DefaultTime2Retain
   Username Password AuthType
iSCSICli QAddTargetPortal TargetPortalAddress [CHAPUsername]
   [CHAPPassword]
iSCSICli RemoveTargetPortal TargetPortalAddress TargetPortalSocket
   [HBAName] [PortNumber]
iSCSICli RefreshTargetPortal TargetPortalAddress TargetPortalSocket
   [HBAName] [PortNumber]
iSCSICli ListTargetPortals

iSNS Commands:

iSCSICli AddiSNSServer iSNSServerAddress
iSCSICli RemoveiSNSServer iSNSServerAddress
iSCSICli RefreshiSNSServer iSNSServerAddress
iSCSICli ListiSNSServers

Target Operations:

iSCSICli TargetInfo TargetName [DiscoveryMechanism]
iSCSICli LoginTarget TargetName ReportToPNP TargetPortalAddress
   TargetPortalSocket InitiatorInstance PortNumber SecurityFlags
   LoginFlags HeaderDigest DataDigest MaxConnections DefaultTime2Wait
   DefaultTime2Retain Username Password AuthType Key MappingCount
   MappingEntries
iSCSICli QLoginTarget TargetName [CHAPUsername] [CHAPPassword]
iSCSICli LogoutTarget SessionId
iSCSICli PersistentLoginTarget TargetName ReportToPNP
   TargetPortalAddress TargetPortalSocket InitiatorInstance PortNumber
   SecurityFlags LoginFlags HeaderDigest DataDigest MaxConnections
   DefaultTime2Wait DefaultTime2Retain Username Password AuthType Key
   MappingCount MappingEntries
iSCSICli ListPersistentTargets
iSCSICli RemovePersistentTarget InitiatorName TargetName PortNumber
   TargetPortalAddress TargetPortalSocket
iSCSICli AddConnection SessionId InitiatorInstance PortNumber
   TargetPortalAddress TargetPortalSocket SecurityFlags LoginFlags
   HeaderDigest DataDigest MaxConnections DefaultTime2Wait
   DefaultTime2Retain Username Password AuthType Key
iSCSICli QAddConnection SessionId InitiatorInstance TargetPortalAddress
   [CHAPUsername] [CHAPPassword]
iSCSICli RemoveConnection SessionId ConnectionId

					  

SCSI Commands:

iSCSICli ScsiInquiry SessionId LUN EvpdCmddt PageCode [Length]
iSCSICli ReadCapacity SessionId LUN
iSCSICli ReportLUNs SessionId
iSCSICli ReportTargetMappings

Internet Protocol Secure (IPSec) Commands:

iSCSICli TunnelAddr InitiatorName InitiatorPort DestinationAddress
   TunnelAddress Persist
iSCSICli GroupKey Key Persist
iSCSICli PSKey InitiatorName InitiatorPort SecurityFlags IdType Id Key
   Persist
iSCSICli GetPSKey InitiatorName InitiatorPort IdType Id

Volume Binding Commands:

iSCSICli BindPersistentVolumes
iSCSICli BindPersistentDevices
iSCSICli ReportPersistentDevices
iSCSICli AddPersistentDevice VolumeOrDevicePath
iSCSICli RemovePersistentDevice VolumeOrDevicePath
iSCSICli ClearPersistentDevices

Miscellaneous Commands:

iSCSICli CHAPSecret CHAPSecret
iSCSICli ListInitiators
iSCSICli NodeName NodeName
iSCSICli Ping InitiatorName Address [RequestCount] [RequestSize]
   [RequestTimeout]
iSCSICli SessionList [ShowSessionInfo]
iSCSICli VersionInfo

					  

The following list describes each of the command line arguments.

Address

Specifies the address of the iSNS server to ping.

AuthType

Determines the kind of authentication used to verify the caller's identity. 

CHAPPassword

Contains the Challenge-Handshake Authentication Protocol (CHAP) password used to authenticate the caller. This password forms the CHAP secret that the initiator uses to create a hash value that identifies the caller. The hash value provides identification during subsequent calls.

CHAPSecret

Contains the initiator CHAP secret used for mutual CHAP authentication. If the input value is an asterisk (*), then the system sets an empty initiator CHAP secret.

CHAPUsername

Contains the username used for CHAP authentication. If the input value is an asterisk (*), then the initiator uses the node name as the CHAP username.

ConnectionId

Represents a particular connection to the iSNS server. You use this value to define which connection to manage.

DataDigest

Determines the data digest setting used when logging into the target portal. A value of 0 indicates that the client won't use a data digest, while a non-zero value indicates the use of a data digest. Use an asterisk (*) to indicate that you want to set the data digest value to the value used by the initiator kernel mode driver.

DefaultTime2Retain

Specifies the time that the iSCSI initiator negotiates for retaining a connection when logging into the target. When this time expires without caller activity, the server automatically terminates the session. Use an asterisk (*) to indicate that you want to set the default retention time value to the value used by the initiator kernel mode driver.

DefaultTime2Wait

Specifies the time that the iSCSI initiator waits when logging into the target. When this time expires without a login, the iSCSI initiator registers an error. Use an asterisk (*) to indicate that you want to set the default waiting time value to the value used by the initiator kernel mode driver.

DestinationAddress

Specifies the Internet Protocol (IP) address to associate with the tunnel address for IPSec communication.

DiscoveryMechanism

Defines the method used to discover targets on the iSNS server. If you don't specify this option, then iSCSICli lists all of the discovery mechanisms without any target data. Providing a discovery mechanism value displays targets associated with that discovery mechanism.

EvpdCmddt

Defines the parameter to use for the inquiry.

ForceUpdate

Forces an update of the target list when set to T or t.

HBAName

Defines the name of the Host Bus Adapter (HBA) used to route the SendTargets calls. If you don't specify this value, then the iSCSI initiator service chooses an HBA. Some sources call this value the InitiatorInstanceName.

HeaderDigest

Specifies whether the iSCSI initiator should enable the header digest when logging into the target portal. Use a non-zero value to enable the header digest. Use an asterisk (*) to indicate that you want to set the header digest value to the value used by the initiator kernel mode driver.

Id

Represents the Internet Key Exchange (IKE) ID payload.

IdType

Defines the IKE ID payload type. This value can include a fully qualified domain name or an Internet Protocol version 4 (IPv4) address.

InitiatorInstance

Defines the name of the iSCSI initiator used to perform the login operation. The iSCSI initiator service chooses an iSCSI initiator when you don't provide this value.

InitiatorName

Specifies the name of the iSCSI initiator normally used to login to the target (the tunnel mode outer address when used for IPSec). You must configure the iSCSI initiator for this purpose. When working with IPSec, providing a value of asterisk (*) configures all iSCSI initiators to use the caller's address.

InitiatorPort

Specifies the physical port number of the iSCSI initiator for the specified tunnel mode outer address. When working with IPSec, providing a value of asterisk (*) configures all ports to use the caller's address.

iSNSServerAddress

Represents a particular iSNS server. You may provide either an IP address or a Domain Name System (DNS) name as input. The iSCSI initiator queries the specified server to discover targets. It also registers the iSNS for State Change Notification (SCN) so that it can detect changes in server functionality, such as a change in availability. Any value you provide is persisted and the iSCSI initiator queries the server during each restart of the service or whenever an SCN occurs.

Key

Contains the IPSec pre-shared key used to establish the Transaction Control Protocol (TCP) connection when the iSCSI initiator relies on IPSec to connect with the target.

Length

Defines the allocation length to specify for an inquiry. This argument doesn't appear with some forms for the iSCSICli command. It's always optional. The default value is 0xFF (255 bytes). The maximum value is 8 KB (0x2000).

LoginFlags

Determines how the client logs into the target portal. 

LUN

Specifies the Logical Unit Number (LUN) that receives an inquiry.

MappingCount

Specifies the number of target mappings that the iSCSI initiator should use to login to the target. 

MappingEntries

Contains one or more TargetLun, OSBus, OSTarget, or OSLun entries. The MappingCount argument determines the number of entries. 

MaxConnections

Determines the number of connections that the system uses during the discovery session to perform tasks such as the SendTargets operation. Use an asterisk (*) to indicate that you want to set the maximum connections value to the value used by the initiator kernel mode driver.

NodeName

Changes the default iSCSI node name for the iSCSI initiator. This argument specifies the new node name. The system won't validate the name you provide as a valid iSCSI Qualified Name (IQN) or Institute of Electrical and Electronics Engineers (IEEE) EUI-64 format.

PageCode

Contains the page code to use for an inquiry.

Password

Contains the password used to authenticate the caller. This password forms the CHAP secret that the initiator uses to create a hash value that identifies the caller. The hash value provides identification during subsequent calls.

Persist

Determines when the iSCSI initiator persists the specified object, such as a target or tunnel mode outer address. The iSCSI initiator re-creates persisted object each time you restart the service. Use a value of T or t to specify that you want to persist the target.

PortNumber

Determines which port the iSCSI initiator uses to route SendTargets calls. If you don't specify this value, then the iSCSI initiator uses the port value provided by the initiator kernel mode drive. Some texts call this value the InitiatorPortNumber.

ReportToPNP

Determines whether the iSCSI initiator exposes the LUN to a port driver so that the operating system can display it as a storage device using Plug and Play (PNP). When the target is exposed through PNP, the client can perform standard device operations such as mounting the drive, assigning it a drive letter, and formatting it. You must set this argument to T or t to obtain the PNP functionality. If you set this argument to any other value, then the operating system only allows you to perform iSCSI discovery on the target.

RequestCount

Specifies the number of Ping requests to perform.

RequestSize

Specifies the size of the Ping request.

RequestTimeout

Determines the time that the Ping command will wait until it signifies an error condition after making a request and not receiving a response.

SecurityFlags

Specifies the type of IPSec to use when creating a TCP connection to the target portal.

SessionId

Represents a particular iSNS server session. You use this value to define which session (and by extension, connection) to manage.

ShowSessionInfo

Determines whether the SessionList command displays full session information. This is an optional argument that displays the full information when set to T or t. Older versions of iSCSICli don't support this argument.

TargetAlias

Specifies the alias of the target. Use a value of asterisk (*) when the target doesn't have an alias defined.

TargetFlags

Determines how the iSCSI initiator service manages the target. 

TargetName

Specifies the name of the target.

TargetPortalAddress

Defines the IP or DNS address of the target portal.

TargetPortalSocket

Defines the TCP port number of the target portal. The default port setting is 3260. However, the administrator can set the TCP port number to any value.

TunnelAddress

Specifies the IP address to associate with the destination address for IPSec communications.

Username

Contains the username used for authentication. If the input value is an asterisk (*), then the initiator uses the node name as the username.

VolumeOrDevicePath

Specifies the drive letter or mount point for the volume that you want to bind persistently or the device interface name for a device. If you specify a drive letter, mount point, or device interface name that the iSCSI initiator has already bound, the system returns an error.