Tutorial
Migrate Network Installation Manager (NIM) clients concurrently using nimadm
Use the new -n and -f options of the nimadm commandIntroduction
Traditionally, you can use the Network Installation Manager alternate disk migration (nimadm) command to migrate a copy of the root volume group (rootvg) present in a free disk of a single Network Installation Management (NIM) client at a time from the NIM master. While it is technically feasible to run multiple nimadm commands concurrently, for example, by employing the no hang-up command (nohup) or using separate terminals, these methods lack user-friendliness in terms of console logging and monitoring.
IBM AIX 7.3 Technology Level (TL) 3 (7.3.3.0) introduces the new feature of concurrent execution of independently monitored nimadm processes for multiple NIM clients with the nimadm command. This feature improves the overall efficiency and speed of the migration process for multiple NIM clients.
This tutorial explains how to enable and use the new concurrent migration option introduced in nimadm.
Understanding the basics
The nimadm command now comes with a new command line option, -n. This makes the command switch over to the multiclient mode. The command also comes with a new -f option where you can provide the required NIM client migration data.
There are two ways in which you can enter all the NIM clients’ data to perform NIM alternate disk migration.
- If you pass only the
-noption to thenimadmcommand, it provides an interactive questionnaire session where you can provide multiple NIM client data. A client_data.json file is created automatically under the /var/adm/ras directory during the interactive questionnaire session. If there is any existing file with the same name as the client_data.json file in the /var/adm/ras directory, the existing file is backed up as the client_data.json.prev file in the same directory before the new file gets created. - You can also provide the full path to a customized JSON file by using the
-fflag along with the-nflag. You can also use the JSON file to run thenimadmcommand using the System Management Interface Tool (SMIT) interface. For more information about creating a JSON file, refer to the following sections.
Pass NIM client data interactively during the NIM alternate disk migration operation
Perform the following steps to pass the NIM client data to the nimadm command:
- Run the
nimadmcommand with the-n(multi-client mode) and the-Y(accept licenses) options./usr/sbin/nimadm -n –Y In the interactive session, enter the NIM client names and other data corresponding to the prompts. Note: After completing the questionnaire successfully, the
nimadmcommand will create a JSON file, named client_data.json, under /var/adm/ras and save your input over there.# /usr/sbin/nimadm -n -Y Client #1 ############## Enter client name - -> lpar1 Enter target disk - -> hdisk2 No lpp_source is provided in the command line. Enter lpp_source name - -> lpp2 No spot is provided in the command line. Enter spot name - -> spot2 .... .... Do you want to add any more clients? Type 'y' for yes, 'n' for no -> y Client #2 ############## Enter client name - -> lpar2 Enter target disk - -> hdisk3 0505-201 nimadm: Target disk hdisk3 does not exist. Enter target disk - -> hdisk1 No lpp_source is provided in the command line. Enter lpp_source name - -> lpp1 No spot is provided in the command line. Enter spot name - -> spot1 .... .... Do you want to add any more clients? Type 'y' for yes, 'n' for no -> n Creation of 'client_data.json' file is successful. It is located in /var/adm/ras directory.- The interactive session will end with the question “Do you want to continue with the nimadm process? (yes/no)”. Enter yes to start the actual nimadm processes for individual NIM clients concurrently. Enter no to exit the nimadm process.
Do you want to continue with the nimadm process? (yes/no) -> yes Starting:/usr/sbin/nimadm -c lpar2 -d hdisk1 -l lpp1 -s spot1 -Y -U -A 2>/var/adm/ras/ nimadm_parallel/lpar2_error.log Starting:/usr/sbin/nimadm -c lpar1 -d hdisk2 -l lpp2 -s spot2 -T mksysb_72X -j nimadmVg2 -B -Y -A 2>/var/adm/ras/nimadm_parallel/lpar1_error.log 02-21-2024 09:40:38 : Started nimadm for lpar2 02-21-2024 09:40:38 : Started nimadm for lpar1 ...
Pass a client data JSON file to the nimadm command
You can reuse a pre-composed JSON file consisting of NIM client migration data whenever you want to use the nimadm command to perform the actual migration process for the target NIM clients.
Perform the following steps to compose a client data JSON file and reuse it for multiple nimadm executions.
Step 1. Create a JSON file that includes the NIM client data
You can create a JSON file using any one of the following methods:
The
nimadmcommand with just the–n(as explained above) option allows you to create a client_data.json file under /var/adm/ras. If you want to defer the actual migration process to some later point of time, just exit after the JSON file gets created.Example:
Creation of 'client_data.json' file is successful. It is located in /var/adm/ras directory. Do you want to continue with the nimadm process? (yes/no) -> noYou can use this new /var/adm/ras/client_data.json file as the value of the
-foption in thenimadmcommand whenever you want to trigger the actual migration process.You can also manually create your own JSON file from scratch. To create the client JSON file, you must use the following template for each client LPAR data:
{ "client_1":"<name of the nim client lpar>", "client_1_target_disk":"<Target disk for the client lpar>", "client_1_res_lpp_source":"<LPP-source resource name>", "client_1_res_spot":"<Spot resource name>", "client_1_res_target_mksysb":"<existing NIM mksysb resource to migrate>", "client_1_vgname":"<volume group (on the NIM master) to cache all of the data from the client to these file systems>", "client_1_res_premig_script":"<premigration script resource name>", "client_1_res_postmig_script":"<post migration script resource name>", "client_1_res_image_data":"<Image data resource name>", "client_1_res_exclude_files":"<Exclude files resource name>", "client_1_res_install_img_bundle":"<Installp bundle resource name>", "client_1_res_bosinst_data":"<Bosinst data resource name>", "client_1_opt_nfs_mount":"<nfs mount options>", "client_1_opt_skip_bootlist":"<Do you want to skip running bootlist after the nimadm migration? (Enter y for yes/n for no)>", "client_1_opt_reboot":"<Should client be rebooted after migration? (Enter y for yes/n for no)>", "client_1_opt_update":"<Do you want to perform a TL/SP update? (Enter y for yes/n for no)>" }You can add more NIM client data to the same JSON file by using the same format. Following is an example of a JSON file with two NIM clients:
{ "client_1":"aix1", "client_1_target_disk":"hdisk1", "client_1_res_lpp_source":"lpp1", "client_1_res_spot":"spot1", "client_1_res_target_mksysb":"mksysb_72Z", "client_1_vgname":"nimadmVg1", "client_1_res_premig_script":"premig1", "client_1_res_postmig_script":"postmig1", "client_1_res_image_data":"img1", "client_1_res_exclude_files":"excl1", "client_1_res_install_img_bundle":"instl1", "client_1_res_bosinst_data":"bi1", "client_1_opt_nfs_mount":"-Vcdrfs", "client_1_opt_skip_bootlist":"y", "client_1_opt_update":"n", "client_2":"aix2", "client_2_target_disk":"hdisk2", "client_2_res_lpp_source":"lpp2", "client_2_res_spot":"spot2", "client_2_res_target_mksysb":"mksysb_72X", "client_2_vgname":"nimadmVg2", "client_2_res_premig_script":"premig2", "client_2_res_postmig_script":"postmig2", "client_2_res_image_data":"img2", "client_2_res_exclude_files":"excl2", "client_2_res_install_img_bundle":"instl2", "client_2_res_bosinst_data":"bi2", "client_2_opt_nfs_mount":"-vcdrfs", "client_2_opt_skip_bootlist":"n", "client_2_opt_reboot":"n", "client_2_opt_update":"y" }
Step 2. Use the NIM client migration data JSON file in the nimadm command
After creating the JSON file with the migration related information for each NIM client, you can use the same in the nimadm command.
Here is an example using a customized JSON file (/home/dev/client_data.json).
# nimadm -n –f /home/dev/client_data.json -l lpp1 –s spot1 –Y
Starting:/usr/sbin/nimadm -c lpar2 -d hdisk1 -l lpp1 -s spot1 -Y -U -A 2>/var/adm/ras/nimadm_parallel/lpar2_error.log
Starting:/usr/sbin/nimadm -c lpar1 -d hdisk2 -l lpp1 -s spot1 -T mksysb_72X -j nimadmVg2 -B -Y -A 2>/var/adm/ras/nimadm_parallel/lpar1_error.log
02-21-2024 09:40:38 : Started nimadm for lpar2
02-21-2024 09:40:38 : Started nimadm for lpar1
...
Step 3. Use the JSON file having the client LPAR migration data in the SMIT interface
After creating the JSON file with the migration related information for each NIM client, you can use the same in the SMIT interface.
Perform the following steps to run the multi-client nimadm command using the SMIT interface:
- Run the
smit nimadmcommand.
- In the SMIT menu, select the Perform multi-client NIM Alt. Disk Migration (parallel) option.
- In the parallel (concurrent) migration menu, provide the required data to trigger the multi-client nimadm process.
The following example depicts how to do so using /home/dev/client_data.json.
After providing all the data, press Enter to initiate the actual alternate disk migration process.
Note: If any attribute has common data for all the NIM clients, you can mention the value once in the command line instead of repeating the same value for each NIM client in the JSON file or during the interactive questionnaire session.
For example, if you want to use the same lpp-source (lpp1) and spot (spot1) for all your target NIM clients, you can mention those in the command line or in the SMIT interface, instead of including it in the JSON file.
Note: For all the attributes for which the arguments can be passed either by using a client JSON file or by using the command line, the values mentioned in the client JSON file are preferred over the command line for a particular client.
Some interesting facts about this new feature
- Depending on the number of dedicated processors allocated to the NIM master, the
nimadmcommand determines the number of NIM clients it can allow for parallel migration at a time. - To allow any kind of parallel multi-client migration, there should be at least one processor dedicated to the NIM master. The multi-client
nimadmcommand throws an error for any lesser processor count. - You can migrate any number of NIM clients with just one CPU processor that is dedicated to NIM master.
- However, to fully use the parallel migration feature, you must have sufficient CPU processors when dealing with multiple NIM clients.
- If ‘x’ number of CPU processors are dedicated to the NIM master, then 3 * ‘x’ clients can be migrated in parallel. For example, with one CPU processor that is dedicated to NIM master, three NIM client LPARs can be simultaneously used with a maximum of 95% CPU usage to achieve maximum efficiency during multi-client nimadm operation.
- If the number of target NIM clients are more than the expected count corresponding to the allocated number of dedicated physical CPU processors, then the
nimadmcommand groups and picks those up in subsequent batches. To include more than three NIM clients in one batch, then the number of processors need to be increased to achieve maximum efficiency during the multi-client nimadm operation. To find out the number of dedicated processors, run the
lparstat -icommand. The Entitled Capacity value provides you the count.# lparstat -i | grep "Entitled Capacity" Entitled Capacity : 1.00The following analysis has been made to calculate the optimum number of processors versus the number of clients.
Dedicated processor count Memory Parallel NIM clients count Time taken for the entire nimadm process Maximum CPU utilization 1 8 1 ~ 1 hour 20 minutes ~ 62 percent 1 8 6 ~ 4 hours 13 minutes ~ 100 percent 2 8 1 ~ 1 hour 20 minutes ~ 58 percent 2 8 6 ~ 3 hours 30 minutes ~ 94 percent 4 8 6 ~ 3 hours 10 minutes ~ 57 percent 6 8 6 ~ 3 hours ~ 60 percent 1 8 3 ~ 2 hours 10 minutes ~ 95 percent In the NIM master, for all the NIM clients participating in the concurrent migration process, you need to maintain a free disk size that is at least equivalent to the rootvg size of the target NIM client.
The
nimadmcommand monitors the phase-wise execution of the alternate disk migration process for each target NIM client LPAR. It also prints the start and the end date timestamp of each phase followed by a migration summary of all the NIM clients at the end of the entire operation.For example:
# nimadm -Y -n -f /var/adm/ras/client_data.json '/var/adm/ras/nimadm_parallel/lpar1_error.log' has been backed up as '/var/adm/ras/nimadm_parallel/lpar1_error.log.prev' successfully. '/var/adm/ras/nimadm_parallel/lpar2_error.log' has been backed up as '/var/adm/ras/nimadm_parallel/lpar2_error.log.prev' successfully. '/var/adm/ras/nimadm_parallel/lpar3_error.log' has been backed up as '/var/adm/ras/nimadm_parallel/lpar3_error.log.prev' successfully. Starting:/usr/sbin/nimadm -c "lpar3" -d "hdisk1" -l "lpp1" -s "spot1" -r -Y -A 2>/var/adm/ras/nimadm_parallel/lpar3_error.log Starting:/usr/sbin/nimadm -c "lpar2" -d "hdisk1" -l "lpp1" -s "spot1" -r -Y -A 2>/var/adm/ras/nimadm_parallel/lpar2_error.log 12-03-2024 11:34:59 : Started nimadm for lpar3 12-03-2024 11:34:59 : Started nimadm for lpar2 Starting:/usr/sbin/nimadm -c "lpar1" -d "hdisk1" -l "lpp1" -s "spot1" -r -Y -A 2>/var/adm/ras/nimadm_parallel/lpar1_error.log 12-03-2024 11:34:59 : Started nimadm for lpar1 12-03-2024 11:37:50 : Please Wait... Performing pre-requisite steps of nimadm for client lpar3 -------------------- 12-03-2024 11:37:51 : Please Wait... Performing pre-requisite steps of nimadm for client lpar2 -------------------- 12-03-2024 11:37:56 : Please Wait... Performing pre-requisite steps of nimadm for client lpar1 -------------------- lpar3 : 12-03-2024 11:38:20 Executing nimadm phase 1. -------------------- lpar2 : 12-03-2024 11:38:21 Executing nimadm phase 1. -------------------- lpar1 : 12-03-2024 11:38:26 Executing nimadm phase 1. -------------------- lpar3 : 12-03-2024 11:40:27 Phase 1 complete. -------------------- lpar3 : 12-03-2024 11:40:27 Executing nimadm phase 2. -------------------- lpar2 : 12-03-2024 11:41:55 Phase 1 complete. -------------------- lpar2 : 12-03-2024 11:41:55 Executing nimadm phase 2. -------------------- lpar1 : 12-03-2024 11:42:07 Phase 1 complete. -------------------- lpar1 : 12-03-2024 11:42:07 Executing nimadm phase 2. -------------------- lpar3 : 12-03-2024 11:42:31 Phase 2 complete. -------------------- lpar3 : 12-03-2024 11:42:31 Executing nimadm phase 3. -------------------- ...... ...... lpar2 : 12-03-2024 12:34:25 Phase 11 complete. -------------------- lpar2 : 12-03-2024 12:34:25 Executing nimadm phase 12. -------------------- 12-03-2024 12:35:22 : Please Wait... Executing nimadm for client lpar3 : phase 1 -------------------- lpar3 : 12-03-2024 12:35:26 Phase 11 complete. -------------------- lpar3 : 12-03-2024 12:35:26 Executing nimadm phase 12. -------------------- lpar2 : 12-03-2024 12:36:20 Phase 12 complete. -------------------- lpar3 : 12-03-2024 12:37:21 Phase 12 complete. -------------------- lpar1 : 12-03-2024 12:37:36 Phase 11 complete. -------------------- lpar1 : 12-03-2024 12:37:36 Executing nimadm phase 12. -------------------- lpar1 : 12-03-2024 12:39:31 Phase 12 complete. -------------------- Client Name:lpar1 :: Target Disk:hdisk1 => Result:Success Client Name:lpar2 :: Target Disk:hdisk1 => Result:Success Client Name:lpar3 :: Target Disk:hdisk1 => Result:Success NIMADM successful for all client lpars.
Key insights about the new nimadm feature
The following list provides insights about the new nimadm feature.
- This feature supports concurrent NIM client migration (using lpp-source, mksysb) and TL/SP update. Note: Other nimadm migration types such as mksysb to mksysb and client to mksysb operations are not supported by this concurrent migration feature.
- The detailed nimadm execution progress gets logged in the /var/adm/ras/alt_mig/
_alt_mig.log file. - Run time errors during the multi-client nimadm process gets logged in the /var/adm/ras/nimadm_parallel/
_error.log file. - In the event of any issue with the nimadm process, you need to share the logs with the IBM support team while opening the ticket.
Summary
This tutorial explained how to use the new -n and -f options of the nimadm command to perform alternate disk migration of multiple NIM clients in parallel. It also explained how to make use of the parallel migration feature in the SMIT interface.