Managing iSCSI Initiator connections with Windows PowerShell on Windows Server 2012

Article
07/31/2012

Managing iSCSI Initiator Connections

Updated: 9/18/2012

This post covers iSCSI Initiator connection management using the Iscsi module for Windows PowerShell available with Windows Server 2012 and Windows 8.

Note: For additional details on management of Windows Disk, Partition, and Volume objects, please refer to the following article:

Managing Storage with Windows PowerShell on Windows Server 2012
https://blogs.msdn.com/b/san/archive/2012/07/03/managing-storage-with-windows-powershell-on-windows-server-2012.aspx

Background:

Prior to Windows Server 2012, iSCSI Initiator connection management via the command line was performed using the iSCSICLI.exe tool from a CMD prompt. The legacy tool iSCSICLI.exe is superseded by the iSCSI module for Windows PowerShell available on Windows Server 2012 and Windows 8 (only).

Prerequisites

The iSCSI module requires that the iSCSI Service and its associated firewall rule be enabled in order to report information back. This can be accomplished via either of the following methods:

Open the iSCSI control panel: The first time that the iSCSI Initiator control panel is opened, you are prompted and asked if you would like to start the service automatically.

- Use the following commands in PowerShell;
  - Set-Service -Name msiscsi -StartupType Automatic

- Start-Service msiscsi

Note: at a minimum, the Windows Firewall rule for the iSCSI Initiator Service must also be enabled for outgoing traffic.

PS C:\WINDOWS\system32> Get-NetFirewallServiceFilter -Service msiscsi | Get-NetFirewallRule | Select DisplayGroup,DisplayName,Enabled

Connecting to a new iSCSI Target

Connecting to a new iSCSI Target is a two-step process. First an iSCSI Target Portal is established using the New-iSCSITargetPortal cmdlet, and then a connection is established using the Connect-iSCSITarget cmdlet.

Creating a new iSCSI Target Portal

For example, I have a new iSCSI target named DeepSpace that I need to establish a connection with. I would complete the connection using the following command:

New-IscsiTargetPortal –TargetPortalAddress DeepSpace

Viewing available iSCSI Targets

After a new target portal is created, the iSCSI target, and its connection status are displayed via the Get-IscsiTarget cmdlet as shown below:

Connecting to available iSCSI Targets

To connect to all available iSCSI Targets, use the following command:

Get-IscsiTarget | Connect-IscsiTarget

Listing iSCSI Connections and sessions:

View currently connected iSCSI Sessions and connections using the following commands;

To view iSCSI Connections:

Get-iSCSIConnection

To View iSCSI Sessions:

Get-iSCSISession

To list all Windows disks for a specific iSCSI session:

Get-iSCSISession | Get-Disk

Listing the iSCSI IQN for the iSCSI Initiator

You can list the current iSCSI Qualified Name (IQN) by using the following command: The iSCSI IQN for the initiator is typically used when configuring masking sets with an iSCSI Target device to allow access by a specific initiator to an iSCSI Target device.

(Get-InitiatorPort).NodeAddress

Configuring sessions to persist across reboots:

An iSCSI Session that has a property of IsPersistent = $True will automatically attempt reconnection on a system reboot. For example, the connection below is not persistent:

PS C:\WINDOWS\system32> Get-IscsiSession

AuthenticationType : NONE
InitiatorInstanceName : ROOT\ISCSIPRT\0000_0
InitiatorNodeAddress : iqn.1991-05.com.microsoft:deepcore.contoso.com
InitiatorPortalAddress : 0.0.0.0
InitiatorSideIdentifier : 400001370000
IsConnected : True
IsDataDigest : False
IsDiscovered : False
IsHeaderDigest : False
IsPersistent : False
NumberOfConnections : 1
SessionIdentifier : fffffa80144f8430-4000013700000003
TargetNodeAddress : iqn.1991-05.com.microsoft:deepspace-deepcore-target
TargetSideIdentifier : 0300
PSComputerName :

When connecting to a new iSCSI Target using the Connect-iSCSITarget cmdlet, persistence is managed via the –IsPersistent Boolean value.

For example,

Get-iSCSITarget | Connect-IscsiTarget –IsPersistent $False would prevent the new connection from persisting across reboots.

Note: Connections are persistent by default unless overridden by specifying –IsPersistent $False

For an existing session, if the session is not persistent, it can be made persistent by piping the session to the Register-iSCSISession cmdlet. For example:

PS C:\WINDOWS\system32> Get-IscsiSession | Where-Object IsPersistent -eq $False

In this case, since I have an iSCSI Session which is not persistent, I could pipe this object to Register-IscsiSession to make it persistent.

Get-IscsiSession | Register-IscsiSession

Connecting to an iSCSI Target when using CHAP Secrets

To connect to an iSCSI Target which requires the use of a CHAP secret, you can use the following cmdlet options, and select the appropriate type of CHAP secret to use in the –AuthenticationType parameter.

Get-iScsiTarget | Connect-iScsitarget –AuthenticationType ONEWAYCHAP –ChapUserName <username> -ChapSecret <secret>

Advanced Configuration Management: Using MPIO with iSCSI Connections.

Connecting multiple network adapters in conjunction with iSCSI and MPIO:

Note: MPIO is available on Windows Server versions only.

Tip: List your IPv4 addresses using the Get-NetIPAddress cmdlet

Get-NetIPAddress –AddressFamily IPv4 –PrefixOrigin DHCP

For example, if I stored the output of the above command in the variable $Nics on a machine with 2 network adapters, then $Nics[0].IpAddress returns the IP address for my first NIC, and $Nics[1].Ipaddress returns the IP address for my second NIC.

For the rest of this example, I have used the above to populate two variables;

$Nic1 = $Nics[0]

$Nic2 = $Nics[1]

Configuring MPIO to automatically claim devices:

Tip: By configuring MPIO to automatically claim iSCSI devices (for example) before any are connected, you may be able to avoid an extra reboot when the disks are claimed.

In the example below, I am installing the MPIO feature, enabling automatic claiming of all iSCSI disks, and setting the default load balance policy in MPIO to Round Robin:

# Enable the MPIO Feature
Enable-WindowsOptionalFeature -Online -FeatureName MultipathIO

# Enable automatic claiming of iSCSI devices for MPIO
Enable-MSDSMAutomaticClaim -BusType iSCSI

# Set the default load balance policy of all newly claimed devices to Round Robin
Set-MSDSMGlobalDefaultLoadBalancePolicy -Policy RR

Connecting with MPIO and iSCSI using multiple Network adapters

First we will need to define the targetportal to point to the iSCSI Target. In my example below, the target portal is named DeepSpace

New-IscsiTargetPortal –TargetPortalAddress DeepSpace

Lastly, we would create one MPIO-enabled iSCSI connection per network adapter using the following commands:

Get-IscsiTarget | Connect-IscsiTarget -IsPersistent $True –IsMultipathEnabled $True –InitiatorPortalAddress $Nic1.IPAddress

Get-IscsiTarget | Connect-IscsiTarget -IsPersistent $True –IsMultipathEnabled $True –InitiatorPortalAddress $Nic2.IPAddress

Viewing connections to determine which Network Adapter is used

Get-iSCSIConnection displays the IP address for the network adapter used with this connection(s). For example;

Viewing advanced properties for a disk which is connected via iSCSI:

The following example shows listing all disks associated with the active iSCSI Connection(s) in the system.

This process can also be reversed to determine the iSCSI connections for a specific Disk object such as by passing the output of Get-Disk 1 to Get-iSCSIConnection.

Additional References:

Complete list of cmdlets in the iSCSI module:

For a complete listing of the cmdlets contained in the iSCSI module for Windows PowerShell, please refer to the following document on TechNet:
https://technet.microsoft.com/library/hh826099.aspx

iSCSI Initiator WMI V2 Classes for Windows Server 2012 and Windows 8
https://msdn.microsoft.com/en-us/library/windows/desktop/hh968118(v=vs.85).aspx

Thanks,

Bruce

Managing iSCSI Initiator connections with Windows PowerShell on Windows Server 2012