Map VIOS LUNs with minimal requirement

This article maps the logical unit numbers (LUNs) between the client and the server. The only requirement it has is to run as root and be able to use Secure Shell (SSH) to connect an IBM® AIX® jump server to the VIOS client and server without entering the password. It provides a lot of information including the Virtual I/O Server (VIOS) that is providing the Shared Ethernet Adapter (SEA), the virtual Small Computer System Interface (VSCSI), and the command to re-create the virtual target device as well.


Christopher Narcouzi (, Senior AIX Systems Administrator, IBM

Photo of Christopher NarcouziChristopher is a Senior AIX System Administrator. He has written many scripts in Korn shell (KSH) and Perl. He has also written some Expect scripts as well. He has three other articles published on IBM developerWorks and three scripts published by

02 May 2014

Also available in Russian

Creating a UDID script with minimum requirement

Not long ago, I searched in Google for a script that would map the LUNs between AIX VIOS client and sever using the unique disk identifier (UDID), similar to physical volume ID (PVID). The search was unsuccessful, and therefore, I decided to create my own script. I wanted to write a script that runs virtually in any environment and helps with storage area network (SAN) migration and VIOS migration as well.

This script is simple to use. This script can be run on a jump AIX server from which you can use Secure Shell (SSH) to connect to the VIOS client and server without entering the password. You have to be the root user or you can use your user ID. If you run it with your user ID, you have to update the script to use the sudo command. This script does not use SSH to connect to the Hardware Management Console (HMC), and instead, uses the UDID to do the mapping. Refer to map_vio_client_report for more details.

This script is more than just mapping the LUN report. It is intended to help with SAN migration and VIOS migration. This is particularly true if you are migrating from VIOS 1.5 to VIOS 2.2. The viosbr command is not available in VIOS 1.5.

Another script that can use this script to generate reports to many VIOS servers along with their clients is also included. Follow the instructions documented in map_vio_client_report_all to run it.

Comparing PVID and UDID

I decided to use UDID to map the LUNs. There are three ways to map the LUNs.

1. Use VSCSI on client and HMC, and lsmap on the VIOS server

2. Use PVID on VIOS client and server

3. Use UDID on VIOS client and server

You can use the VSCSI on the VIOS client to get the logical partition (LPAR) ID and slot. Then, you need to get to the HMC to find the corresponding VIOS server slot. Then, use the lsmap command on the VIOS server to finish the work. Too much work for me.

You can use the lspv command on the VIOS client to get the PVID of the hdisk. You can then use the lspv command on the VIOS server and grep for that PVID and find the corresponding hdisk. This works, but not all the time. There will be times when the VIOS server does not have the PVID of the corresponding hdisk. Here is how it could happen. Say, you just got a new LUN assigned to your VIOS server. Say, you don't use the chdev command to assign a PVID to your new disk, but instead, you assign it to one of your VIOS clients. On the client, say, you add it to a group and use it in that group. Now, if you use the lspv command, this disk will not show a PVID on the VIOS server but it will show a PVID on the client. If you try to use the chdev command to assign a PVID on the VIOS server, you will get a message saying that the disk is busy and you won't be able to do it. The disk is busy because it is being used by the client and a part of the group. In summary, PVID is not 100% reliable for mapping the disks. There are also other cases where the PVID can be different on the VIOS client and server but we won't get into that here.

UDID, which stands for unique disk ID is used by multipath I/O (MPIO). UDID is 100% accurate and thus can be used for mapping the LUNs. To get the UDID on a VIOS client, I used the lsattr -El hdisk30 command as an example. On the VIOS server, I used the Object Data Manager (ODM) command, odmget -q 'name=hdisk4 AND attribute=unique_id' CuAt. Here is an example of the UDID on the VIOS server and client:

Client: hdisk0 48333321360050768018E0218580000000000034304214503IBMfcp05VDASD03AIXvscsi

Server: hdisk2 3321360050768018E0218580000000000034304214503IBMfcp

Note that both UDIDs have the SAN LUN as a substring, which in this case is "60050768018E02185800000000000343". Also, the client UDID starts with 4833, and then the server UDID follows, and then "05VDASD03AIXvscsi" is added at the end. In other words, the server UDID is a substring of the client UDID in this case. I use this relationship to map the LUNs in this case.

Script output

This script generates a lot of output. I still support VIOS 1.5 and the viosbr command is not available on it. So, this script is very handy for capturing the environment and helping with the migration from 1.5 to 2.2. The output of this script is in the CSV format, and therefore, it is very easy to copy the output and to a Microsoft® Excel sheet. You have to watch for the LUNs because the Excel sheet might use scientific notations to represent them. The label for the columns is also included in the report produced by this script.

The following are the column labels in the report:


The first seven fields refer the VIOS client. The next six refer to the VIOS server. The last column contains the command that can re-create the virtual target device (VTD). The first three fields are self explanatory. The fourth field "CLIENT VSCSI" comes from the kdb command. On VIOS 1.5, the kdb command does not work. and in this case you will see in this field, "kdb_command_FAILED". The fifth field, ENABLED|FAILED comes from the lspath command. These are not the only two possible values, but I don't have space to mention all of them. The six field is ACTIVE VSCSI. It is taken from the lspath command for a particular hdisk. Let us say, we have two VSCSI, vscsi0 and vscsi1. Let us say, we are looking at hdisk5. When you run the lspath command, if vscsi0 is displayed before vscsi1 in the output of the lspath command for hdisk5, then this value is set to vscsi0. If vscsi1 is displayed first, then this value is set to vscsi1. The lspath command displays the active VSCSI first in its output. This really depends on the value of the algorithm in lsattr -El hdisk5. If it is set to round_robin, then the VSCSI will alternate between vscsi0 and vscsi1 and you can't count on this field. Ideally, ALGORITHM should be set to fail_over in which case it would validate the ACITIVE VSCSI field. The next field tells you the value to which ALGORITHM is set to. The ALGORITHM field comes from the lsattr command. It is intended to remind you that if you want to fail over the disk paths to the other VIOS, then certain parameters for hdisk need to be set up first (similar to the ALGORITHM parameter in addition to reserve_policy and hcheck_interval before you can do that). It is just a kind of reminder and at the same time if it is not set to fail_over you know it won't work. All the fields after that all the way to STORAGE TYPE are self explanatory. The storage is derived from the lsdev -Cc disk command. It tells you if it is (for example) an IBM System Storage® SAN Volume Controller (SVC) or IBM System Storage DS8000® type. Here is a list of storage types:

2105 - Displays all 2105 models (ESS) 
2145 - Displays all 2145 models (2145 used for SVC) 
1750 - Displays all 1750 devices (DS6000) 
2107 - Displays all 2107 devices (DS8000) 
1724 - Displays all 1724 devices (DS 4100) 
1814 - Displays all 1814 devices (DS3950 and DS4200 and DS4700 and DS5020)
1722 - Displays all 1722 devices (DS4300) 
1742 - Displays all 1742 devices (DS4400 and DS4500) 
1815 - Displays all 1815 devices (DS4800) 
1818 - Displays all 1818 devices (DS5000) 
1820 - Displays all 1820 devices (RSSM)

The last field COMMAND has the command that you can run to re-create the VTD for this hdisk, if needed.

You can run this script against one VIOS server and one client at a time. If you are troubleshooting problems on a client, then you can run this report to see all the mapping on your disks. If you have to allocate LUNs to a certain client, then you can run this script before and after you allocate the LUNs and make sure that the correct LUNs have been allocated. If you are migrating to new SAN, then you can verify whether all LUNs have been migrated and no one was left behind with this script before the SAN team pulls the plug on your old LUNs.

Refer to Table 1 for an example of the output from this script sorted by “CLIENT NAME”, “CLIENT VG”, and “CLIENT DISK” in order to have the report sorted by volume group (VG).

I will discuss here the last three rows in the output. Here is an example of these rows:

 SEA, ent6 not active, on VIO1
ACTIVE VSCSI is, vscsi0, on VIO1, iostat -DlaTR 
ACTIVE VSCSI, column above, from lspath, first occurrence, of hdisk

The first one tells you whether the SEA is active on the VIO server. It is taken from the entstat -d ent6 command. The second line tells you the active VSCSI and the VIOS name that it comes from. This value is different from the "ACTIVE VSCSI" column, which is derived from lspath. This value is derived from the iostat -DlaTR|grep vscsi command. In one of the VIOS clients, the hdisk path can come from VIO1 or VIO2 and that will be indicated in the "CLIENT VSCSI" column although it is highly unlikely to happen. In most cases, the values should be the same. As an additional note, I personally like to highlight the first row (the column heading) and the last three rows in this report. The third line is a just a reminder that the "CLIENT VSCSI" column is derived from lspath as opposed to the iostat command.

Using the script

To run this script, you need to be on an AIX jump server, which means a server from which you can use SSH to connect to the client and server without having to enter a password. You also have to be the root user. You have to give the script two input fields. The first one is the VIOS client name and the second is the VIOS server name.

Here is an example:

 your_script_name <VIO client name> <VIO server name>

map.ksh thumb valveeta (The AIX server names that I encountered several years ago, in case you were wondering)

If you have two VIOS servers VIO1 and VIO2 and three clients, then you can run the script three times with VIO1 and three times with VIO2. You can combine all the three reports for the three clients and VIO1 to get an Excel sheet for VIO1 and all of its clients. This way, at one glance, you can see VIO1 along with its clients and all the mapping. You can sort this report on "CLIENT NAME", "CLIENT VG", and "CLIENT DISK" in order to have the report sorted by VG. This way, you can easily see all the hdisks that belong to the same volume group, within a particular client, along with their corresponding LUN.

Refer to Table 2 to see a sample output.

You can also create a similar report for VIO2. You can combine the last two reports from VIO1 and VIO2 in a new Excel sheet. You can sort this new report by "CLIENT NAME", "CLIENT DISK", and "VIO NAME" first and then by "CLIENT NAME", "CLIENT VG", and "CLIENT DISK". Refer to Table 3 to see a sample output.

Note that "VIO DISK", "VHOST", and "VTD" are the same on both VIO1 and VIO2. This might not be the case always. It is nice if it is, but it does not have to be. You can have, for example, on VIO1 hdisk5 and VIO2 hdisk40. The nice thing about this script is that it maps all this for you and saves you a lot of time.


developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into AIX and Unix on developerWorks

Zone=AIX and UNIX
ArticleTitle=Map VIOS LUNs with minimal requirement