iSCSI Target cmdlet reference

First published on TECHNET on Jun 08, 2012

Windows Server 2012 comes with a complete set of PowerShell cmdlets for iSCSI. By combining the iSCSI target, iSCSI initiator, and storage cmdlets, you can automate pretty much all management tasks. This blog post will provide you with some examples. If you want more information about iSCSI Target and its basic configuration cmdlet, please see Introduction to iSCSI Target in Windows Server 2012 .

Cmdlet Basics

Modules

The Cmdlets are grouped into modules. To get all the cmdlets in a module, type “ get-command –module <name> ”. For example:

iSCSI Target cmdlets:

Get-command -module iSCSITarget

iSCSI Initiator cmdlets:

Get-command -module iSCSI

Volume, partition, disk, storage pool and related cmdlets:

Get-command -module storage

General Windows PowerShell guidelines were followed in the development of these cmdlets, using the standard Windows PowerShell cmdlet verbs to manage the objects. If you are familiar with powershell, it is quite easy to pick up these modules.

To learn more about iSCSI Initiator cmdlets, see iSCSI Cmdlets in Windows PowerShell

To learn more about iSCSI Target cmdlets, see iSCSI Target Cmdlets in Windows PowerShell

To learn more about storage cmdlets, see Storage Cmdlets in Windows PowerShell

Another very good reference for cmdlet management for file and storage-related scenarios: Windows PowerShell Reference Sheet for File and Storage Services in Windows Server 2012

Requirements

The iSCSI initiator cmdlets require the msiscsi service . By default, this service is stopped and not set to start automatically. The first time you configure the iSCSI initiator, you should start this service as well as change the service startup type to Automatic:

Start-Service msiscsi
Set-Service msiscsi –startuptype “automatic”

Note : if you open the iSCSI initiator control panel applet, it will prompt you to start this service and change the service startup type to Automatic.

iSCSI Target Server module is loaded by default in Windows Server 2012. However, the cmdlets cannot be run successfully without the iSCSI Target Server role service installed. To install it, run:

Add-WindowsFeature FS-iSCSTarget-Server

Specific cluster-related cmdlet to create the “iSCSI Target Server Clustered role” requires the Failover Clustering feature. You can enable this feature and its management tool using the following:

Add-WindowsFeature Failover-Clustering

Add-WindowsFeature RSAT-Clustering

Add-WindowsFeature RSAT-Clustering-Mgmt

Add-WindowsFeature RSAT-Clustering-PowerShell

Cmdlet Nouns

The iSCSI Initiator and iSCSI Target modules are both loaded by default on Server,. The nouns managed by both modules are prefixed with Iscsi . This section explains these nouns.

To better understand iSCSI initiator, see Understanding Microsoft iSCSI Initiator Features and Components . Although the article specially mentions Windows 7 and Windows Server 2008 R2, the concepts still apply to Windows 8 and Windows Server 2012. For additional reference on terminology, see Introduction to iSCSI Target in Windows Server 2012 .

The diagram below illustrates the relationship of the cmdlet nouns in a simplified view:

The following nouns are managed, accessed, and hosted on the iSCSI initiator computer :

• IscsiTarget: This object is used to identify the iSCSI target on the server from the initiator side. It is the object which the iSCI initiator can connect to. The initiator can only see those targets which allow it access.


• IscsiConnection: the TCP connection between the iSCSI initiator and target.


• IscsiSession: the session established between the initiator and target. For each session, there could be one or more connections. In Windows Server 2012, iSCSI Target Server supports one connection per session. You can register a session such that the initiator will automatically reconnect to the target after reboot. If the initiator connects the target multiple times, there will be multiple sessions, you will need to enable MPIO feature on the initiator to view the iSCSI LUNs.


• IscsiTargetPortal: specifies the iSCSI Target Server name or IP address.


• IscsiChapSecret: specifies the iSCSI target CHAP secret be used during login.

The following cmdlet nouns are hosted on and managed by the iSCSI Target Server computer :

• IscsiServerTarget: the target object on the iSCSI Target Server computer. By default, iSCSI targets are not accessible by any initiators. You will need to configure the initiatorIDs to specify the initiators that can access it. There are four ways to identify an iSCSI initiator: IQN, DNS, IP (or IPv6) or MAC address. The preferred assignment is to use IQN because the iSCSI target can compare the IQN from the incoming connection and determine if it is allowed for access. With DNSName assignment, the iSCSI target will need to resolve the name with a DNS server, which takes longer for login. If you have a static IP environment, IP address can be used for the assignment. To keep the management simple, it is better to use the same assignment method for the initiatorID. For example, if you use IP address for assignment, always use it, so that you can easily identify the initiators in the cmdlet queries. In later examples, you will see how the initiatorIDs can be used in the cmdlets.


• IscsiVirtualDisk: represents the iSCSI virtual disk objects. The iSCSI virtual disk objects are mapped to a VHD file. Removing the IscsiVirtualDisk object will not automatically delete the VHD files. If you want to load a VHD file, you will need to import it first.

Importing VHD files to iSCSI Target Server on Windows Server 2012 is supported as follows:

Note:

1. For differencing VHDs, you will need to run Convert-IscsiVirtualDisk before importing them.

2. iSCSI Target Server doesn’t support dynamic virtual disks and you cannot create dynamic VHDs using iSCSI Target.

3. iSCSI Target Server doesn’t support dynamic virtual disks and you cannot import dynamic disks created by Hyper-V.

4. iSCSI Target Server doesn’t support VHDX and you cannot create VHDX using iSCSI Target Server.

5. iSCSI Target Server doesn’t support VHDX and you cannot import VHDX created by Hyper-V.

• IscsiVirtualDiskSnapshot: represents the snapshots for the virtual disk objects. iSCSI Target Server supports taking snapshot of the virtual disks for backup.


• IscsiVirtualDiskTargetMapping: represents the assignment between the iSCSI target and the iSCSI virtual disks


• IscsiTargetServerSetting: allows you to specify common settings for iSCSI Target Server.

Cmdlet Help

Cmdlet help has a new mechanism to allow dynamic update of the content from the Internet. Before using the help, you need to run “ Update-help –module <name> ” to get the latest help content. This implies the computer has Internet connectivity. To get help for all modules, type “ Update-help ”.

To use the help, type <cmdlet name> -?

For example:

Get-IscsiServerTarget -?

If you search for the cmdlets that can manage iSCSIVirtualdisk, you can type:

Get-Command *IscsiVirtualDisk*

This is a great way to find all the cmdlets that can manage the iSCSIVirtual disks.

Management and Maintenance Tasks

To learn more about iSCSI Target configuration cmdlets, see Introduction to iSCSI Target in Windows Server 2012 . This blog post will focus on the following iSCSI management and maintenance tasks to:

1. Get all iSCSi targets associated with a virtual disk


2. Get all virtual disks associated with an iSCSI target


3. Get all iSCSI initiators accessing a virtual disk


4. Get all virtual disks used by an iSCSI initiator


5. Replace an iSCSI initiator assignment


6. Add aniSCI initiator to an iSCSI target


7. Remove all virtual disks from an iSCSI Target


8. Delete all iSCSI initiators from an iSCSI target


9. Delete all virtual disks that are not assigned to any iSCSI target


10. Get all iSCSI Targets that have not been used or connected for seven days


11. Manage iSNS Server registration

The following diagram illustrates these tasks. To setup this scenario, use the iSCSI cmdlets listed in Introduction to iSCSI Target in Windows Server 2012 .

On the iSCSI Target server, there are five iSCSI target objects and five virtual disk objects. Target1 is assigned to Init1, which can access two virtual disks. Target2 is assigned to Init2, and Target3 is assigned to Init3. Both Init2 and Init3 have access to iSCSI Virtual Disk 3. Target4 is not assigned to any initiators. Target5 has no association to any initiators or virtual disks. iSCSI Virtual Disk 5 has no association to any iSCI target.

1. Get all iSCSI targets associated with a virtual disk

Using the above example, let’s say something went wrong with iSCSI Virtual Disk 3 and you want to find all the iSCSI targets associated with this virtual disk. You can run the following:

Get-IscsiServerTarget –path C:\iSCSIVirtualDisks\LUN3.VHD

For the example above, the output shows all the iSCSI targets (Target2 and Target3) associated with the virtual disk (c:\Iscsivirtualdisks\LUN3.vhd).

2. Get all virtual disks associated with an iSCSI target

In this example, the Target1 got disconnected for some reason, you want to find all the iSCSI virtual disks which are associated with this Target:

Get-IscsiVirtualDisk –TargetName <name>

The output shows all the Virtual disks (LUN1.VHD and LUN2.VHD) which are associated with Target1.

3. Get all the iSCSI initiators accessing a virtual disk

Suppose one of the virtual disks (C:\IscsiVirtualDisks\LUN3.VHD) is having issues, and you want to disable it. Before doing that, you want to find all the initiators which will be affected:

(Get-IscsiServerTarget -Path C:\IscsiVirtualDisks\LUN3.VHD).InitiatorIds

The cmdlet shows the initiators that are accessible by the virtual disk (C:\IscsiVirtualDisks\LUN3.VHD)

4. Get all virtual disks used by an iSCSI initiator

Say one of the initiators (init1) is going offline and; you want to determine all the virtual disks which can be accessed by Init1 using its IQN:

(Get-IscsiServerTarget -InitiatorId "IQN:iqn.1991-05.com.microsoft:init1.contoso.com").
LunMappings.Path

Note:

• The virtual disks (c:\iscsivirtualdisks\LUN1.vhd and c:\ iscsivirtualdisks\LUN 2.vhd) may not be exclusively assigned to Init1. You can use the cmdlets in the previous task to find all the initiators for each virtual disk.


• Make sure you use the right ID to identify the initiator. If you used DNSName during the initiator assignment, you will need to use the same DNSName in the cmdlet.

5. Replace an iSCSI initiator assignment

Suppose there has been a change to iSCSI initiator computer Init1 and a new computer Init5 that is replacing it. You want to assign to Init5 all the iSCSI targets which were associated with Init1.

Get-IscsiServerTarget -InitiatorId "IQN:iqn.1991-05.com.microsoft:Init1.Contoso.com" |
foreach {Set-IscsiServerTarget $_.TargetName –InitiatorIds
"IQN: iqn.1991-05.com.microsoft:Init5.Contoso.com "}

Note: This cmdlet will remove all existing initiator assignments for the given targets, and replace it with the new initiator ID. To add initiators, use the cmdlet in the next section.

6. Add an iSCSI initiator to an iSCSI target

You want to add a new computer Init4 and build a two- node cluster with Init1. To do so, you need to add Init4 to the Target1 InitiatorID so that Init4 can also logon to Target1 to access the shared storage:

$c = new-object Microsoft.Iscsi.Target.Commands.InitiatorId
("iqn:iqn.1991-05.com.microsoft:init4.contoso.com")

Set-Iscsiservertarget Target1 -initiatorids {$_.initiatorids + $c}

Note: $c is to remember the existing initiators assigned to the Target.

If you don’t remember which iSCSI target Init1 was associated with, use the following:

Get-IscsiServerTarget –InitiatorId “iqn:iqn.1991-05.com.microsoft:init1.contoso.com” |
Set-Iscsiservertarget -initiatorids {$_.initiatorids + $c}

The Target now has both Init1 and Init4 added to allow access.

Note: You can also get the IQN of the initiator on the local computer by running:

Get-InitiatorPort | fl –property NodeAddress

7. Remove all virtual disks from an iSCSI target

While doing maintenance on the iSCSI target, you find Init3 is accessing the same iSCSI virtual disk as Init2. You want to reassign Init3 to Target4 and remove Target3. You cannot delete the iSCSI target if there are any virtual disks associated with it, so you will need to remove all the iSCSI Virtual disks from Target3 first.

(Get-IscsiServerTarget Target3).LunMappings|Remove-IscsiVirtualDiskTargetMapping

Check that Target3 has no iSCSI virtual disks associated with it. Now you can proceed with the next task to remove Iinit3 from Target3 before deleting the iSCSI target.

8. Delete all iSCSI initiators from a given iSCSI target

Let’s remove the initiators associated with Target3. Deleting the initiators is equivalent to set the initiator assignment to “null”:

Set-IscsiServerTarget Target3 -InitiatorIds @()

You can safely remove the iSCSI target by running:

Remove-IscsiServerTarget Target3
9. Delete all virtual disks which are not assigned to any iSCSI target

n our example, you may notice iSCSI Virtual Disk 5 is not assigned to any iSCSI target. It is easy to delete a specific virtual disk if you know what it is. The script below illustrates a more generic approach to find and delete all the disks which are not assigned to any iSCSI target.

It’s a little tricky, so we list two different approaches:

• You can find the virtual disks which do not have any iSCSI target by running:

Get-iscsivirtualdisk | where { $targets = get-iscsiservertarget -path $_.path;
$targets.count -eq 0} | Remove-Iscsivirutaldisk

• Or you can get all the virtual disks and pick out the ones that are assigned - the ones remaining are the “unassigned” virtual disks:

$AllDisks = (Get-IscsiVirtualDisk).Path

$AssignedDisks = (Get-IscsiServerTarget).LunMappings.Path

$AllDisks | where {$AssignedDisks -notcontains $_} |
foreach {Remove-IscsiVirtualDisk $_ }

In the last removal of the iSCSI virtual disk, you can also delete the VHD file by adding:

$AllDisks | where {$AssignedDisks -notcontains $_} |
foreach {Remove-IscsiVirtualDisk $_ ; rm $_ }
10.Get all iSCSI targets that have not been used for seven days

To see which iSCSI targets are not being used or connected to, we introduced a new parameter “IdleDuration” on the iSCSI Target object. This records the time since the last session was disconnected from an iSCSI target. In conjunction of the “LastLogin” parameter, you can get an idea of how long this target was in use versus not being used. In this example, I want to find all the targets which have been sitting idle for the past week:

Get-IscsiServerTarget | where { $_.IdleDuration –ge [timespan]”7.00:00:00” }

Note that both “IdleDuration” and “LastLogin” are not persistent, so they will be reset if the iSCSI Target service was restarted.

11.Manage iSNS server registration

The iSNS server registration can be done using the following cmdlets, which manages the WMI objects.

To add an iSNS server:

Set-WmiInstance -Namespace root\wmi -Class WT_iSNSServer –Arguments
@{ServerName="ISNSservername"}

To view iSNS server settings:

Get-WmiObject -Namespace root\wmi -Class WT_ iSNSServer

To delete an iSNS server:

Get-WmiObject -Namespace root\wmi -Class wt_isnsserver –Filter
“ServerName =’iSNSServerName’” | Remove-WmiInstance

Conclusion

I hope these examples give you some ideas on how piping can be used with iSCSI Target cmdlets. If you have questions not covered, please raise it in the comments, so I can address it with upcoming postings.