Skip to main content
Delphix

Reconfiguring iSCSI when Changing a Windows Server Hostname

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.

Procedure

  1. Disable the dSources.
  2. Disable the VDBs.

    If your Windows server has dSources or VDBs from more than one Delphix Engine, you will 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:
    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
  4. 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 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 Address and Socket in 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
  5. 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 :

     
    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
  6. Change the host name or IQN

     
    1. 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.

    2. If you are changing the IQN only, change it through the Microsoft iSCSI Initiator GUI following the instructions in the Microsoft iSCSI User Guide.
  7. Wait for the computer to finish rebooting.
  8. 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.

  9. Refresh the environment on the Delphix Engine.
  10. Re-enable the dSources as described in Enabling and Disabling dSources.
  11. Re-enable the VDBs as described in Enabling and Disabling Virtual Databases.
  12. 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>
    [...]