This topic describes how to change the hostname (IP address) or iSCSI Qualified Name (IQN) of a Windows Target or Staging host.

By default, Windows servers generate an IQN based on the hostname assigned to it. Changing the hostname 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 hostname 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.

Changing the hostname 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 sequence can cause availability issues for your dSources and VDBs. If you have questions about the following instructions, please contact Delphix Support for help.

  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. 
    From the Server Manager\Tools\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
      "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 
    4. Alternatively, 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.
    From the Server Manager\Tools\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           :
          Address and Socket    : 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.

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

      PS C:\> iscsicli RemovePersistentTarget Root\ISCSIPRT\0000_0 * 3260
  5. Log out of any sessions. 
    From the Server Manager\Tools\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 : 
      Target Node Name : (null)
      Target Name : 
    2. Log out from the target.

      PS C:\> iscsicli logouttarget fffffa8003fb0018-4000013700000001
  6. Change the hostname (IP address) or IQN in the Delphix engine.

    1. If you are changing the hostname, 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. To use the Delphix Setup application, go to Manage → Environments screen and select the Target host. To modify the Host Address for the environment, use the Edit (Pencil) icon next to the Attributes panel. Update the Host Address to reflect the new IP address, and then use the Save (Tick) icon to confirm the change. This will automatically trigger an action to Refresh the Environment. The refresh process includes steps to configure the iSCSI Target and verify that it is reachable.
    3. 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 hostname (IP address), the IQN should include the new hostname.

  9. Refresh the environment on the Delphix Engine.
  10. Re-enable the dSources.
  11. Re-enable the VDBs. 
  12. Using the iscsi cli 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 Topics