Jaa

PowerShell cmdlets for the Microsoft iSCSI Target 3.3 (included in Windows Storage Server 2008 R2)

  • Artikkeli

1. Overview

One of the new features in the Microsoft iSCSI Software Target 3.3 (included in Windows Storage Server 2008 R2) is the inclusion of PowerShell cmdlets for management.

In this blog post, we will examine the details of the cmdlets available to manage targets and their associated virtual disks.

2. Modules, Cmdlets and Classes

The iSCSI Target PowerShell is provided in a single module called MicrosoftIscsiTarget, which includes 10 cmdlets, as listed in the example below:

PS C:\> Import-Module MicrosoftIscsiTarget
PS C:\> Get-Command -module MicrosoftIscsiTarget | Sort Noun

CommandType Name Definition
----------- ---- ----------
Cmdlet Remove-IscsiServerTarget Remove-IscsiServerTarget [-TargetName] <String> ...
Cmdlet New-IscsiServerTarget New-IscsiServerTarget [-TargetName] <String> [-I...
Cmdlet Set-IscsiServerTarget Set-IscsiServerTarget [-TargetName] <String> [-T...
Cmdlet Get-IscsiServerTarget Get-IscsiServerTarget [[-TargetName] <String>] [...
Cmdlet Remove-IscsiVirtualDisk Remove-IscsiVirtualDisk [-DevicePath] <WindowsPa...
Cmdlet New-IscsiVirtualDisk New-IscsiVirtualDisk [-DevicePath] <WindowsPath>...
Cmdlet Get-IscsiVirtualDisk Get-IscsiVirtualDisk [[-DevicePath] <WindowsPath...
Cmdlet Set-IscsiVirtualDisk Set-IscsiVirtualDisk [-DevicePath] <WindowsPath>...
Cmdlet Add-VirtualDiskTargetMapping Add-VirtualDiskTargetMapping [-TargetName] <Stri...
Cmdlet Remove-VirtualDiskTargetMapping Remove-VirtualDiskTargetMapping [-TargetName] <S...

As you can see, these cmdlets relate to three different nouns: IscsiServerTarget (Target), IscsiVirtualDisk (Virtual Disks) and VirtualDiskTargetMapping (LUN Mapping).

Next, we will examine these three main classes (or types) used to manage a Microsoft iSCSI Software Target, looking at their specific cmdlets and properties.

2.1. IscsiServerTarget

TypeName:

  • Microsoft.Iscsi.Target.Commands.IscsiServerTarget

Associated Cmdlets:

  • New-IscsiServerTarget (Creates a new iSCSI target object with the specified name)
  • Get-IscsiServerTarget (Obtains the iSCSI targets and their associated properties)
  • Set-IscsiServerTarget (Modifies settings for the iSCSi target)
  • Remove-IscsiServerTarget (Deletes an iSCSI target object)

Properties:

  • Id (Microsoft.Iscsi.Target.Commands.IscsiServerTargetIdentity)
  • TargetName (System.String)
  • TargetIqn (Microsoft.Iscsi.Target.Commands.Iqn)
  • ComputerName (System.String)
  • ServerInfo (Microsoft.Iscsi.Server.ServerInfo)
  • Description (System.String)
  • InitiatorIds (Collection of Microsoft.Iscsi.Target.Command.InitiatorId)
  • LunMappings (Collection of Microsoft.Iscsi.Target.Command.LunMapping)
  • Enable (System.Boolean)
  • Status (Microsoft.Iscsi.Target.Commands.IscsiServerTargetStatus)
  • LastLogin (System.DateTime)
  • EnableChap (System.Boolean)
  • EnableReverseChap (System.Boolean)
  • EnforceIdleTimeoutDetection (System.Boolean)
  • FirstBurstLength (System.Int32)
  • MaxBurstLength (System.Int32)
  • MaxReceiveDataSegmentLength (System.Int32)
  • ReceiveBufferCount (System.Int32)
  • Version (System.Version)

2.2. IscsiVirtualDisk

TypeName

  • Microsoft.Iscsi.Target.Commands.IscsiVirtualDisk

Associated Cmdlets

  • New-IscsiVirtualDisk (Creates an iSCSI virtual disk with the specified file path and size, or imports the VHD file if it already exists)
  • Get-IscsiVirtualDisk (Obtains the iSCSI virtual disks and their associated properties)
  • Set-IscsiVirtualDisk (Modifies the settings for the specified iSCSI virtual disk)
  • Remove-IscsiVirtualDisk (Deletes the specified iSCSI virtual disk)

Properties

  • Id (Microsoft.Iscsi.Target.Commands.IscsiVirtualDiskIdentity)
  • DevicePath (Microsoft.Iscsi.Server.WindowsPath)
  • VirtualDiskIndex (System.Int32)
  • Size  (Microsoft.Iscsi.Server.StorageSize)
  • SnapshotStorageSize (Microsoft.Iscsi.Server.StorageSize)
  • ComputerName (System.String)
  • ServerInfo (Microsoft.Iscsi.Server.ServerInfo)
  • Description (System.String)
  • Enabled (System.Boolean)
  • Status (Microsoft.Iscsi.Target.Commands.IscsiVirtualDiskStatus)
  • LastLocalMountTime (System.DateTime)
  • Flags (Microsoft.Iscsi.Target.Commands.IscsiVirtualDiskFlags)
  • SerialNumber (System.String)
  • LocalMountDeviceId (System.String)
  • LocalMountPaths (Collection of System.String)
  • LocalMountStatus (Microsoft.Iscsi.Target.Commands.LocalMountStatus)
  • Version (System.Version)

2.3. VirtualDiskTargetMapping or LunMapping

Typename

  • Microsoft.Iscsi.Target.Command.LunMapping

Associated Cmdlets

  • Add-VirtualDiskTargetMapping (Assigns a virtual disk to an iSCSI target)
  • Remove-VirtualDiskTargetMapping (Removes the assignment between the specified iSCSI virtual disk and iSCSI target)

Note: To obtains a list of Lun mappings, use the cmdlet: “(Get-IscsiServerTarget <name>).LunMappings”

Properties

  • TargetName (System.String)
  • VirtualDiskIndex (System.Int32)
  • LUN (System.Int32)

3. Class Diagram

Here’s a simplified class diagram showing the related classes, their properties and methods.

image

Note 1: The Initiator is implemented as the InitiatorIds collection, which is a property of iSCSIServerTarget
Note 2: The LUN Mapping is implemented as the LunMappings collection, which is a property of iSCSIServerTarget

4. Cmdlet Details

Here is a list of the 10 cmdlets in the MicrosoftIscsiTarget module, with a description, syntax and examples.

Note: The optional –ComputerName parameter, available for all cmdlets, is used to execute the task on a remote computer running the Microsoft iSCSI Target. In order to use the cmdlets remotely you need to use another computer running Windows Storage Server 2008 R2 or Windows Server 2008 R2 with the Microsoft iSCSI Target installed. You also need to be running with an account that has local administrator rights for the computer you are managing.

4.1. New-IscsiServerTarget

DESCRIPTION:
Creates a new iSCSI target object with the specified name.  Afterwards, the iSCSI target can be assigned to an iSCSI initiator, and then a virtual disk can be associated with the target.

SYNTAX:
New-IscsiServerTarget [-TargetName] <string> [-ComputerName <string>] [-InitiatorId <InitiatorId[]>]

EXAMPLES:
New-IscsiServerTarget -TargetName "TargetOne"
New-IscsiServerTarget -TargetName "TargetOne" -InitiatorId IPAddress:10.10.1.1,IPAddress:10.10.1.2 -ComputerName vcoName1
New-IscsiServerTarget -TargetName "targetone" -ComputerName iSCSIsvr

4.2. Get-IscsiServerTarget

DESCRIPTION:
Obtains the iSCSI targets and their associated properties from the local server or specified computer.

SYNTAX:
Get-IscsiServerTarget [[-TargetName] <string>] [-ComputerName <string>]

EXAMPLES:
Get-IscsiServerTarget
Get-IscsiServerTarget -ComputerName vcoName1
Get-IscsiServerTarget -TargetName "TargetOne"

4.3. Set-IscsiServerTarget

DESCRIPTION:
Modifies settings for the iSCSi target and returns the corresponding iSCSI target object if the PassThru parameter is specified.

SYNTAX:
Set-IscsiServerTarget [-TargetName] <string> [-Chap <PSCredential>] [-ComputerName <string>] [-Description <string>] [-Enable <Boolean>] [-EnableChap <Boolean>] [-EnableReverseChap <Boolean>] [-EnforceIdleTimeoutDetection <Boolean>] [-FirstBurstLength <int>] [-Force] [-InitiatorId <InitiatorId[]>] [-InputObject <IscsiServerTarget>] [-MaxBurstLength <int>] [-MaxReceiveDataSegmentLength <int>] [-PassThru] [-ReceiveBufferCount <int>] [-ReverseChap <PSCredential>] [-TargetIqn <Iqn>]

EXAMPLES:
Set-IscsiServerTarget "TargetOne" -Description "new description"
Set-IscsiServerTarget "TargetOne" -EnableChap 1 -Chap chapUserName

4.4. Remove-IscsiServerTarget

DESCRIPTION:
Deletes an iSCSI target object. An iSCSI initiator cannot access the VHD or LUN after the target is deleted.

SYNTAX:
Remove-IscsiServerTarget [-TargetName] <string> [-ComputerName <string>] [-Force] [-InputObject <IscsiServerTarget>]

EXAMPLES:
Remove-IscsiServerTarget “Target One”
Get-IscsiServerTarget “Target One” | Remove-IscsiServerTarget

4.5. New-IscsiVirtualDisk

DESCRIPTION:
Creates a new iSCSI virtual hard disk (VHD) object with the specified file path and size.  Afterwards, the virtual disk can be assigned to an iSCSI target. Once a virtual disk has been assigned to a target, an iSCSI initiator can access the virtual disk after the initiator connects to the target.

SYNTAX:
New-IscsiVirtualDisk [-DevicePath] <WindowsPath> [-Size] <StorageSize> [-ComputerName <string>]

EXAMPLES:
New-IscsiVirtualDisk "E:\temp\test.vhd" -Size 10GB
New-IscsiVirtualDisk "E:\temp\test.vhd"
New-IscsiVirtualDisk "E:\temp\test.vhd" -Size 10GB -ComputerName iscsisvr

4.6. Get-IscsiVirtualDisk

DESCRIPTION:
Obtains the iSCSI virtual disks and their associated properties.

SYNTAX:
Get-IscsiVirtualDisk [[-DevicePath] <WindowsPath>] [-ComputerName <string>]

EXAMPLES:
Get-IscsiVirtualDisk
Get-IscsiVirtualDisk "E:\temp\test.vhd"
Get-IscsiVirtualDisk "E:\temp\test.vhd" -ComputerName vcoName1

4.7. Set-IscsiVirtualDisk

DESCRIPTION:
Modifies the settings for the virtual disk and returns the corresponding iSCSI virtual disk object if the PassThru parameter is specified.

SYNTAX:
Set-IscsiVirtualDisk [-DevicePath] <WindowsPath> [-ComputerName <string>] [-Description <string>] [-Enable <Boolean>] [-Force] [-InputObject <IscsiVirtualDisk>] [-PassThru] [-SnapshotStorageSize <StorageSize>]

EXAMPLE:
Set-IscsiVirtualDisk "e:\temp\vhd1.vhd" -Description "disk for data"

4.8. Remove-IscsiVirtualDisk

DESCRIPTION:
Deletes the iSCSI virtual disk object. The VHD file is not deleted.

SYNTAX:
Remove-IscsiVirtualDisk [-DevicePath] <WindowsPath> [-ComputerName <string>] [-Force] [-InputObject <IscsiVirtualDisk>]

EXAMPLE:
Remove-IscsiVirtualDisk "e:\temp\vhd1.vhd"

4.9. Add-VirtualDiskTargetMapping

DESCRIPTION:
Assigns a virtual disk to an iSCSI target. Once a virtual disk has been assigned to a target, an iSCSI initiator can access the virtual disk after the initiator connects to the target. All the virtual disks assigned to the same iSCSI target will be accessible by the connected iSCSI initiator.

SYNTAX:
Add-VirtualDiskTargetMapping [-TargetName] <string> [-DevicePath] <WindowsPath> [-ComputerName <string>] [-Lun <int>]

EXAMPLE:
Add-VirtualDiskTargetMapping -TargetName "TargetOne" -DevicePath "e:\temp\vhd1.vhd"

4.10. Remove-VirtualDiskTargetMapping

DESCRIPTION:
Removes the assignment between a virtual disk and iSCSI target. The virtual disk will be no longer accessible by an iSCSI initiator once the assignment is removed.

SYNTAX:
Remove-VirtualDiskTargetMapping [-TargetName] <string> [-DevicePath] <WindowsPath> [-ComputerName <string>] [-Force]

EXAMPLE:
Remove-VirtualDiskTargetMapping "TargetOne" "e:\temp\vhd1.vhd"

5. Examples with output

5.1. Listing existing targets in a server (only one target listed):

PS C:\> Get-IscsiServerTarget

Id : Server0.contoso.local:FileCluster
TargetName : FileCluster
TargetIqn : iqn.1991-05.com.microsoft:server0-filecluster-target
Description : Storage for File Server Cluster
Enable : True
Status : Connected
LastLogin : 9/16/2010 2:38:51 PM
EnableChap : False
EnableReverseChap : False
ComputerName : Server0.contoso.local
MaxReceiveDataSegmentLength : 65536
FirstBurstLength : 65536
MaxBurstLength : 262144
ReceiveBufferCount : 10
EnforceIdleTimeoutDetection : True
InitiatorIds : {IPAddress:192.168.100.1, IPAddress:192.168.100.2}
LunMappings : {TargetName:FileCluster;WTD:0;LUN:0, TargetName:FileCluster;WTD:1;LUN:1}
Version : 3.3.16543
ServerInfo : Server0.contoso.local

5.2. Listing existing virtual disks in a server (two virtual disks listed):

PS C:\> Get-IscsiVirtualDisk

Id : Server0.contoso.local:E:\LU0.VHD
VirtualDiskIndex : 0
DevicePath : E:\LU0.VHD
Description : LU0
Size : 1.00 GB
Status : InUse
Flags : None
SerialNumber : BBCB1D5A-3942-446B-87A7-D264B2C77216
SnapshotStorageSize : 3.20 GB
LocalMountStatus : NotMounted
LastLocalMountTime : 12/31/1600 4:00:00 PM
LocalMountDeviceId :
LocalMountPaths : {}
Enabled : True
ComputerName : Server0.contoso.local
Version : 3.3.16543
ServerInfo : Server0.contoso.local

Id : Server0.contoso.local:E:\LU1.VHD
VirtualDiskIndex : 1
DevicePath : E:\LU1.VHD
Description : LU1
Size : 10.0 GB
Status : InUse
Flags : None
SerialNumber : 152E24BF-DC02-46B6-98E2-1F517CB18A48
SnapshotStorageSize : 3.20 GB
LocalMountStatus : NotMounted
LastLocalMountTime : 12/31/1600 4:00:00 PM
LocalMountDeviceId :
LocalMountPaths : {}
Enabled : True
ComputerName : Server0.contoso.local
Version : 3.3.16543
ServerInfo : Server0.contoso.local

5.3. Listing existing LUN mappings for one Target (two mappings listed):

PS C:\> (Get-IscsiServerTarget "FileCluster").LunMappings

TargetName VirtualDiskIndex Lun
---------- ---------------- ---
FileCluster 0 0
FileCluster 1 1

5.4. Add new Target

PS C:\> New-IscsiServerTarget -TargetName SQLTarget -InitiatorId IPAddress:10.1.1.3

Id : Server0.contoso.local:SQLTarget
TargetName : SQLTarget
TargetIqn : iqn.1991-05.com.microsoft:server0-sqltarget-target
Description :
Enable : True
Status : Idle
LastLogin : 12/31/1600 4:00:00 PM
EnableChap : False
EnableReverseChap : False
ComputerName : Server0.contoso.local
MaxReceiveDataSegmentLength : 65536
FirstBurstLength : 65536
MaxBurstLength : 262144
ReceiveBufferCount : 10
EnforceIdleTimeoutDetection : True
InitiatorIds : {IPAddress:10.1.1.3}
LunMappings : {}
Version : 3.3.16543
ServerInfo : Server0.contoso.local

5.5. Add new Virtual Disk

PS C:\> New-IscsiVirtualDisk "E:\SQL-LU0.VHD" -Size 10GB

Id : Server0.contoso.local:E:\SQL-LU0.VHD
VirtualDiskIndex : 2
DevicePath : E:\SQL-LU0.VHD
Description :
Size : 10.0 GB
Status : Idle
Flags : None
SerialNumber : CD296DCA-A2CE-412D-8D0C-0D3E5077DEC7
SnapshotStorageSize : 3.20 GB
LocalMountStatus : NotMounted
LastLocalMountTime : 12/31/1600 4:00:00 PM
LocalMountDeviceId :
LocalMountPaths : {}
Enabled : True
ComputerName : Server0.contoso.local
Version : 3.3.16543
ServerInfo : Server0.contoso.local

5.6. Add new Virtual Disk Target mapping (LUN mapping) and then list it.

PS C:\> Add-VirtualDiskTargetMapping -TargetName SQLTarget -DevicePath "E:\SQL-LU0.VHD"

PS C:\> (Get-IscsiServerTarget SQLTarget).LunMappings

TargetName VirtualDiskIndex Lun
---------- ---------------- ---
SQLTarget 2 0

5.7. Listing existing targets in a server (now two targets listed):

PS C:\> Get-IscsiServerTarget

Id : Server0.contoso.local:FileCluster
TargetName : FileCluster
TargetIqn : iqn.1991-05.com.microsoft:server0-filecluster-target
Description : Storage for File Server Cluster
Enable : True
Status : Connected
LastLogin : 9/16/2010 2:38:51 PM
EnableChap : False
EnableReverseChap : False
ComputerName : Server0.contoso.local
MaxReceiveDataSegmentLength : 65536
FirstBurstLength : 65536
MaxBurstLength : 262144
ReceiveBufferCount : 10
EnforceIdleTimeoutDetection : True
InitiatorIds : {IPAddress:192.168.100.1, IPAddress:192.168.100.2}
LunMappings : {TargetName:FileCluster;WTD:0;LUN:0, TargetName:FileCluster;WTD:1;LUN:1}
Version : 3.3.16543
ServerInfo : Server0.contoso.local

Id : Server0.contoso.local:SQLTarget
TargetName : SQLTarget
TargetIqn : iqn.1991-05.com.microsoft:server0-sqltarget-target
Description :
Enable : True
Status : Idle
LastLogin : 12/31/1600 4:00:00 PM
EnableChap : False
EnableReverseChap : False
ComputerName : Server0.contoso.local
MaxReceiveDataSegmentLength : 65536
FirstBurstLength : 65536
MaxBurstLength : 262144
ReceiveBufferCount : 10
EnforceIdleTimeoutDetection : True
InitiatorIds : {IPAddress:10.1.1.3}
LunMappings : {TargetName:SQLTarget;WTD:2;LUN:0}
Version : 3.3.16543
ServerInfo : Server0.contoso.local

5.8. Listing existing LUN mappings for all Targets (three mappings listed):

PS C:\> Get-IscsiServerTarget | % { $_.LunMappings}

TargetName VirtualDiskIndex Lun
---------- ---------------- ---
FileCluster 0 0
FileCluster 1 1
SQLTarget 2 0

6. Conclusion

I hope you enjoy the new cmdlets. The best way to learn how to use them is to practice, so I encourage you to install the evaluation software on a test machine and experiment with the cmdlets yourself.

If you are an MSDN or TechNet subscriber, find the details on how to obtain an evaluation copy of the Microsoft iSCSI Software Target 3.3 at https://blogs.technet.com/b/josebda/archive/2010/09/27/windows-storage-server-2008-r2-and-the-microsoft-iscsi-software-target-3-3-are-available-on-msdn-technet-here-s-how-to-install-them.aspx

For more details about Window Storage Server and the Microsoft iSCSI Software target, check the Windows Storage Server blog at https://blogs.technet.com/b/storageserver/ and the other posts on Windows Storage Server on this blog at https://blogs.technet.com/b/josebda/archive/tags/windows+storage+server/

Comments

  • Anonymous
    January 01, 2003
    Copied from blogs.technet.com/.../windows-storage-server-2008-r2
  • Anonymous
    January 01, 2003
    Here are some relevant references to Windows Storage Server-centric content. Keep checking back for more
  • Anonymous
    January 01, 2003
    ... The good news is that PowerShell is really good at using WMI directly. So I set out to find how to create an iSCSI Target differencing disk using PowerShell and the WMI classes.
  • Anonymous
    January 01, 2003
    Here are some relevant references to Windows Storage Server-centric content. Keep checking back for more
  • Anonymous
    January 01, 2003
    Here are some relevant references to Windows Storage Server-centric content. Keep checking back for more
  • Anonymous
    January 01, 2003
    ... The good news is that PowerShell is really good at using WMI directly. So I set out to find how to create an iSCSI Target differencing disk using PowerShell and the WMI classes.
  • Anonymous
    January 01, 2003
    Here are some relevant references to Windows Storage Server-centric content. Keep checking back for more
  • Anonymous
    January 01, 2003
    Yucong: We don't test the iSCSI Target with Server Core. The offerings you will see from OEMs will not use Server Core. Having said that, there's no technical issue with it and you could try it.
  • Anonymous
    January 01, 2003
    Introduction For the last few years, I’ve been blogging about the Microsoft iSCSI Software Target
  • Anonymous
    January 01, 2003
    One of the big features in iSCSI Software Target 3.3 are the new PowerShell cmdlets.  Checkout Jose
  • Anonymous
    October 01, 2010
    Does iscsi target 3.3 support server core installation?