Changing iSCSI IQN on renamed ESXi hosts to keep storage guys happy!

Today I cabled up a pair of Dell R710’s that were pulled during an upgrade in a production environment.  I used these hosts as fail-over hosts during an ESXi 5.5 Update 2 upgrade on the production side knowing they’d be moved to DR because of new hosts being added in production.  So, these hosts were upgraded already from ESXi 4.0 to 5.5 Update 2 without issue and just need their hostnames and IPs changed (and iSCSI and vMotion vmkernel IPs…) for the new environment.  The former names were AbbreviatedClientNameESX01, for instance.  I simply changed the hostnames to AbbreviatedClientDRESX01.  No big deal.  I created DNS A records for the new hosts and matched it to the new IPs I provided and away we go.

While showing a colleague how to setup iSCSI vmkernels I realized that the IQN was still “iqn.1998-01.com.vmware:OLDHOSTNAME-2cfbdc28″ – what a drag!  This has always bothered me because I’ve done a lot of moving around of hosts in many different client environments and having the IQN remain means that ACL’s on your SAN will have to reference that IQN as well, and ugh, what a mess to make sense of later on.  You don’t have to change the IQN, but you should because your storage guys are going to have to make sense of this later and it’ll be confusing.  I can hear it now, “I dunno what you’re talking about we don’t have ACLs for ServerNameHere but OldAssServer sure has a ton of connections wasn’t that decommissioned years ago?” – Ah!  In my situation, I am my storage guy, so I am preventing my own headache!  Call me self-centered…  anyway…

So, quick and easy fix!  I am doing this on my homelab machine running ESXi 6.0.0b but this works on other versions of ESXi also.  I do not think it runs on pre-4.0 versions because they had a configuration file in /etc/somethingaboutiscsi.conf or similar.  You cannot change the IQN from within the vSphere client but you can through esxcli.  You may be able to do it with PowerCLI also but I haven’t tried.  First you have to enable SSH on your host(s).  I won’t bore you with that I am sure you guys can figure that one out.  Then, simply run esxcli iscsi adapter list to get a list of currently configured iSCSI adapters:

Show IQNs

Note that the adapter is vmhba36 on my system.  Yours may vary.  So now that we know that, let’s get the current IQN of the system by running esxcli iscsi adapter get -A vmhba36 | grep iqn as shown below:

Show IQN

You’ll see that my IQN is iqn.1998-01.com.vmware:ConwayESXi-2cfbdc28 while my hostname is ConwayESX1.  So, clearly, at some point I named the host ConwayESXi – this is a great example of changing the IQN even though it was just meant to be a test as I totally forgot this host was ever renamed.  Now that we know the current IQN let’s change it.

Word of caution:  if you have iSCSI LUNs setup with access control based on IQNs you will have issues doing this in production!  Changing your IQN will cause it to not meet the required IQN name for access to volumes (and thus datastores)!  So, if you have a setup like this, tread carefully.  You might be able to preemptively add the new IQN into the access policy of your SAN and it should reconnect, but I suspect your iSCSI sessions will drop – TEST AND BE CAREFUL!  I am going to change the IQN on a host while connected to a SAN with ACL’s applied to volumes and see if it disconnects – I will update this post with that info.

So, to change the IQN we just issue esxcli iscsi adapter set -A vmhba36 -n iqn.1998-01.com.vmware:NewName-2cfbdc28 and then run the command again to show the IQN to confirm that it has been changed:

IQN Changed

Success!  We can also confirm that the IQN is changed by logging into the vSphere client and checking out the storage adapters:

IQN Changed

And that’s that.  Again, this is super useful if changing the hostname of an ESXi host and is especially relevant if you use IQN access policies on your SAN.  Years later, when someone is doing a cleanup or migration of a SAN they’ll be wondering “What the hell is iqn.1998-01.com.vmware:OldAssHost1-1814hf and why does it have 36 active sessions?!”  Even if you don’t use access policies, if you change the hostname this is good practice to avoid confusion for inventory reasons as well.

Thanks for taking the time to read this and let me know if you experience any issues!

 

Author: Jon

Share This Post On

6 Comments

  1. Fantastic post! TBH I’ve never ever had to do this but it was just what I was looking for last night.

    Post a Reply
  2. its worked for me, thanks jon

    Post a Reply
  3. You can do it with the vSphere Client.

    Click on the Host, click the Configuration tab, click the vmhba whose iSCSI name you want to change, click Properties for this vmhba, on the General tab of the Properties, click Configure, change iSCSI name, change the name and click OK. This works in ESXi 6.0 U2.

    Post a Reply
  4. Hi Jon.

    Thank you for that post and the web site.
    What would be the reason to do the changes from CLI rather than in Windows Client ?

    Just for the note, after I have renamed my iSCSI adapter from CLI (it was renamed) when I login in the SAN it still see the server under OLD name. It was our DR server, so I restarted that host and now SAN see that under new name.

    Cheers,
    Andrey

    Post a Reply
  5. Jon, great post. i’m a new syseng, this was good info & straight to the point. Did you ever lose connection to storage when you changed the iqn target?

    Post a Reply
    • Hi Hugo.

      I have tried it didn’t lost the connection.
      Mode details about my experience you can find from my comment to that post.

      Cheers,
      Andrey

      Post a Reply

Leave a Reply to Hugo Cancel reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.