Changing the hostname (IP address) or IQN of a SQL server target or staging host

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.

Disable the dSources.
Disable the VDB’s.

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.

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. or, Follow these steps to use the iscsicli command-line utility: List the persistent volumes.

CODE

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.

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

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

CODE

PS C:\> iscsicli RemovePersistentDevice 
"\\?\storage#volume#{bb38add1-d03f-11e1-8767-005056b37fe6}#0000000008010000#{53f5630d-b6bf-11d0-94f2-00a0c91efb8b}"

c. Alternatively, if all of the persistent devices are for unmounted volumes, you can remove them all at once with this command:

CODE

PS C:\> iscsicli clearpersistentdevices

Remove all of the persistent targets. From the Server Manager\Tools\iSCSI Initiator configuration tool, use the options available in the Favorite Targets tab. or,
Follow these steps to use iscsicli command-line utility:

a. List persistent targets:

CODE

PS C:\> iscsicli ListPersistentTargets

Remove the appropriate persistent targets. Below is sample output listing the persistent targets:

CODE

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:

CODE

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.

c. Use the RemovePersistentTargetcommand to remove the target, as shown in this example:

CODE

PS C:\> iscsicli RemovePersistentTarget Root\ISCSIPRT\0000_0 iqn.2008-07.com.delphix:02:02843619-12c4-e4d2-8041-f5c56a647bc2 * 10.43.5.45 3260

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.
or, Follow these steps to use the iscsicli command-line utility: List the sessions.

CODE

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 
[...]

b. Log out from the target.

CODE

PS C:\> iscsicli logouttarget fffffa8003fb0018-4000013700000001

Change the hostname (IP address) or IQN in the Delphix engine.

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

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

c. If you are changing the IQN only, change it through the Microsoft iSCSI Initiator GUI following the instructions in the Microsoft iSCSI User Guide.

Wait for the computer to finish rebooting.

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.

Refresh the environment on the Delphix Engine.Re-enable the dSources.
Re-enable the dSources.
Re-enable the VDBs.

Using the iscsi cli command-line utility, verify that the sessions on the Windows server are using the new IQN.

CODE

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>
[...]