Skip to main content
Delphix

Reconfiguring iSCSI when Changing a Windows Server Hostname (KBA1195)

 

KBA

KBA# 1195

 

By default, Windows servers generate an IQN based on the host name assigned to the host. Changing the host name will change the host IQN as well. Because the Delphix Engine exports storage for dSources and VDBs to Windows hosts using iSCSI, changes to the Windows host name must be made according to the following procedure. If you have set a non-default IQN on a Windows target or staging host, and want to change that IQN, you must follow these procedures when changing the IQN.

Changing the host name or IQN of a Windows target or staging server requires that you modify the iSCSI Initiator configuration on the Windows host. Doing so incorrectly can cause failures in dSources, VDBs, or non-Delphix users of iSCSI on the Windows host.

The instructions in this topic describe how to change the IQN using the iscsicli command line utility. Because many people are less familiar with the iscsicli utility, the instructions also include information for using the iSCSI Initiator graphical user interface.

Failing to carefully follow the steps below in order can cause availability issues for your dSources and virtual databases (VDBs). If you have questions about the following instructions, please contact Delphix Support for help.

How to reconfigure iSCSI when changing a Windows Server Hostname

  1. Disable the dSources.
  2. Disable the VDBs.
    If your Windows server has dSources or VDBs from more than one Delphix Engine, you need to disable the dSources and VDBs on each Delphix Engine.

  3. Remove any remaining persistent volumes from the Windows server.
    In the iSCSI Initiator configuration tool, use the options available in the Volumes and Devices tab. 
    Follow these steps to use the iscsicli command line utility:

To use the iscsicli command line utility
  1. List the persistent volumes

    PS C:\> iscsicli reportpersistentdevices
    Microsoft iSCSI Initiator Version 6.1 Build 7601
    Persistent Volumes
    "\\?\storage#volume#{bb38add1-d03f-11e1-8767-005056b37fe6}#0000000008010000#{53f5630d-b6bf-11d0-94f2-00a0c91efb8b}"
    "C:\Program Files\Delphix\DelphixConnector\564d6fbb-df9d-e90b-00f1-da37b17011d3-staging-15\ARCHIVE\"
    [...]
    
    The operation completed successfully.
  2. Volumes with a "normal" path correspond to mounted volumes. For example, "C:\Program Files\Delphix is a normal path. If you see any normal paths in the output, be sure you have disabled all of the VDBs and dSources.

  3. Volumes with a path beginning "\\?\ correspond to unmounted persistent volumes. Remove each of them:

    PS C:\> iscsicli RemovePersistentDevice 
    "\\?\storage#volume#{bb38add1-d03f-11e1-8767-005056b37fe6}#0000000008010000#{53f5630d-b6bf-11d0-94f2-00a0c91efb8b}"
  4. Alternately, if all of the persistent devices are for unmounted volumes, you can remove them all at once with this command:

    PS C:\> iscsicli clearpersistentdevices
  1. Remove all of the persistent targets.
    In the iSCSI Initiator configuration tool, use the options available in the Favorite Targets tab. 
    Follow these steps to use the iscsicli command line utility:

To use the iscsicli command line utility 
  1. List persistent targets:

    PS C:\> iscsicli ListPersistentTargets
  2. Remove the appropriate persistent targets. Below is sample output listing the persistent targets:

    PS C:\> iscsicli ListPersistentTargets
        [...]
        Target Name           : iqn.2008-07.com.delphix:02:02843619-12c4-e4d2-8041-f5c56a647bc2
        Address and Socket    : 10.43.5.45 3260
        Session Type          : Data
        Initiator Name        : Root\ISCSIPRT\0000_0
        Port Number           : <Any Port>
        Security Flags        : 0x0
        Version              : 0
        Information Specified: 0x20
        Login Flags          : 0x0
        Username             :
        [...]

    Misleading Help for RemovePersistentTarget Command

     The help for iscsicli RemovePersistentTarget is misleading:

    iscsicli RemovePersistentTarget <Initiator Name> <TargetName>
                                    <Port Number>
                                    <Target Portal Address>
                                    <Target Portal Socket>

    <Initiator Name> and <Target Name> show up in the listing and should be taken directly from there.
    <Port Number> can be taken from the listing output, but a * should be used if <Any Port> is listed.
    <Target Portal Address> and <Target Portal Socket> are shortened to AddressandSocketin the ListPersistentTargets output. The term Socket in both places is what is more typically referred to as a port.

    Use the RemovePersistentTarget command to remove the target, as shown in this example:

    PS C:\> iscsicli RemovePersistentTarget Root\ISCSIPRT\0000_0 iqn.2008-07.com.delphix:02:02843619-12c4-e4d2-8041-f5c56a647bc2 * 10.43.5.45 3260
  1. Log out of any sessions.
    In the iSCSI Initiator configuration tool, use the options available in the Targets tab to log out. Selected a connected session under Discovered Targets, and then click Disconnect
    Follow these steps to use the iscsicli command line utility:

To use the iscsicli command line utility :
  1. List the sessions:

    PS C:\> iscsicli sessionlist 
    Session Id : fffffa8003fb0018-4000013700000001
    Initiator Node Name : iqn.1991-05.com.microsoft:10-43-1-200.ad.delphix.com 
    Target Node Name : (null)
    Target Name : iqn.2008-07.com.delphix:02:02843619-12c4-e4d2-8041-f5c56a647bc2 
    [...]
  2. Log out from the target:

    PS C:\> iscsicli logouttarget fffffa8003fb0018-4000013700000001
  1. Change the host name or IQN
  • If you are changing the host name, follow the instructions in the Microsoft TechNet article (Rename the Computer).

    Note that if the computer is on a domain, you will need a domain administrator to perform the rename or re-add the computer to the domain depending on the version of Windows it is running.

  • If you are changing the IQN only, change it through the Microsoft iSCSI Initiator GUI following the instructions in the Microsoft iSCSI User Guide.
  1. Wait for the computer to finish rebooting.
  2. Verify the new IQN in the iSCSI initiator.
    If you are using the default IQN and have changed the host name, the IQN should include the new host name.
  3. Refresh the environment on the Delphix Engine.
  4. Re-enable the dSources as described in Enabling and Disabling dSources.
  5. Re-enable the VDBs as described in Enabling and Disabling Virtual Databases.
  6. Using the iscsicli command line utility, verify that the sessions on the Windows server are using the new IQN:
PS C:\> iscsicli sessionlist
Microsoft iSCSI Initiator Version 6.1 Build 7601
 
Total of 1 sessions
 
Session Id : fffffa8003f77018-4000013700000004
Initiator Node Name : <NEW IQN>
[...] 

 

Related Articles