nimadm Command

Purpose

The nimadm (Network Install Manager Alternate Disk Migration) command is a utility that allows the system administrator to do the following:
  • Create a copy of rootvg to a free disk (or disks) and simultaneously migrate it to a new version or release level of AIX®.
  • Using a copy of rootvg, create a new NIM mksysb resource that has been migrated to a new version or release level of AIX.
  • Using a NIM mksysb resource, create a new NIM mksysb resource that has been migrated to a new version or release level of AIX.
  • Using a NIM mksysb resource, restore to a free disk (or disks) and simultaneously migrate to a new version or release level of AIX.
The nimadm command uses NIM resources to perform these functions.

Syntax

Perform Alternate Disk Migration:

nimadm -l lpp_source -c NIMClient -s SPOT -d TargetDisks [ -a PreMigrationScript ] [ -b installp_bundle] [ -z PostMigrationScript] [ -e exclude_files] [ -i image_data ] [ -j VGname ] [ -m NFSMountOptions ] [ -o bosinst_data] [-P Phase] [ -j VGname ] [-Y ] [ -F ] [ -D ] [ -E ] [ -V ] [ { -B | -r } ]

Cleanup Alternate Disk Migration on client:

nimadm -C -c NIMClient -s SPOT [ -F ] [ -D ] [ -E ]

Wake-up Volume Group:

nimadm -W -c NIMClient -s SPOT -d TargetDisks [-m NFSMountOptions ] [-z PostMigrationScript ] [ -F ] [ -D ] [ -E ]

Put-to-sleep Volume Group:

nimadm -S -c NIMClient -s SPOT [ -F ] [ -D ] [ -E ]

Synchronize Alternate Disk Migration Software:

nimadm -M -s SPOT -l lpp_source [ -d device ] [ -P ] [ -F ]

mksysb to Client Migration:

nimadm -T NIMmksysb -c NIMClient -s SPOT -l lpp_source -d TargetDisks -j VGname -Y [ -a PreMigrationScript ] [ -b installpBundle ] [ -z PostMigrationScript ] [ -i ImageData ] [ -m NFSMountOptions ] [ -o bosinst_data ] [ -P Phase ] [ -F ] [ -D ] [ -E ] [ -V ] [ -B | -r ]

mksysb to mksysb Migration:

nimadm -T NIMmksysb -O mksysbfile -s SPOT -l lpp_source -j VGname -Y [ -N NIMmksysb ] [ -a PreMigrationScript ] [ -b installp_bundle ] [ -z PostMigrationScript ] [ -i image_data ] [ -m NFSMountOptions ] [ -o bosinst_data ] [ -P Phase ] [ -F ] [ -D ] [ -E ] [ -V ]

Client to mksysb Migration:

nimadm -c nim_client -O mksysbfile -s SPOT -l lpp_source -j VGname -Y [ -N NIMmksysb ] [ -a PreMigrationScript ] [ -b installp_bundle ] [ -z PostMigrationScript ] [ -i image_data ] [ -m NFSMountOptions ] [ -o bosinst_data ] [ -P Phase ] [ -e exclude_files] [ -F ] [ -D ] [ -E ] [ -V ]

Description

The nimadm command is a utility that allows the system administrator to create a copy of rootvg to a free disk (or disks) and simultaneously migrate it to a new version or release level of AIX. The nimadm command uses NIM resources to perform this function.

There are several advantages to using the nimadm command over a conventional migration:
  1. Reduced downtime. The migration is performed while the system is up and functioning normally. There is no requirement to boot from install media, and the majority of processing occurs on the NIM master.
  2. The nimadm command facilitates quick recovery in the event of migration failure. As the nimadm command uses alt_disk_install to create a copy of rootvg, all changes are performed to the copy (altinst_rootvg). In the event of serious migration installation failure, the failed migration is cleaned up and there is no need for the administrator to take further action. In the event of a problem with the new (migrated) level of AIX, the system can be quickly returned to the pre-migration operating system by booting from the original disk.
  3. The nimadm command allows a high degree of flexibility and customization in the migration process. This is done with the use of optional NIM customization resources: image_data, bosinst_data, exclude_files, pre-migration script, installp_bundle, and post-migration script.
Please note that this document provides information pertaining to the nimadm command. For complete coverage of alt_disk_install, NIM, migration, and other related install issues, refer to the latest editions of the following publications:

nimadm Local Disk Caching

Local disk caching allows the NIM master to avoid having to NFS write to the client, which can be useful if the nimadm operation is not performing optimally due to an NFS write bottle neck. If this function is invoked with the -j VGname flag, the nimadm command creates file systems on the specified volume group (on the NIM master) and uses streams to cache all of the data from the client to these file systems.

The advantages and disadvantages to this function are as follows:

Advantages:
  1. Improved performance for nimadm operations that are on relatively slow networks.
  2. Improved performance for nimadm operations that are bottle necked in NFS writes (NFS writes are very expensive).
  3. Decreased CPU usage on the client.
  4. Client file systems are not exported.
Disadvantages:
  1. Cache file systems take up space on the NIM master (you must have enough space to host the client's rootvg file systems and migration space for each client)
  2. Increased CPU usage on the master.
  3. Increased I/O on the master (for optimal performance use a volume group (disk) that does not contain the NIM resource being used in the operation).
How to execute disk caching:
  1. Make sure you are at the latest level of bos.alt_disk_install.rte on the NIM master.
  2. Add the -j VGName flag to any nimadm operations. For example: 
    nimadm -j rootvg ...
    or 
    nimadm -j cachevg
You can exclude specific file systems (which are not involved in the migration) from being cached over the network (they are still copied locally to altinst_rootvg on the client). To specify a list of file systems to be excluded from network caching, you must create a file in the location of the SPOT resource that is used for the migration. To get the exact location of the SPOT path, enter: 
# lsnim -a location SpotName
You must name the file in the following format: 
Nim_Client.nimadm_cache.excl
Note: This file applies to the NIM client specified in Nim_Client. The full path should be: 
Spot_Location/Nim_Client.nimadm_cache.excl
For example: /nim_resources/520spot/usr/myclient.nimadm_cache.excl.
To exclude a file system from caching, enter one file system (to be excluded) per line in this file. While excluding a file system, ensure that you:
  1. Do not exclude any file systems that are involved in the migration process. In other words, these file systems contain software files that are migrated. This can lead to unpredictable results.
  2. Do not (cannot) exclude the following AIX file systems: /, /usr, /var, /opt, /home, and /tmp.

With disk caching, the nimadm command changes the following four phases (all other phases remain the same) :

Phase 2: The NIM master creates local cache file system in specified target volume group (on the NIM master).

Phase 3: The NIM master populates the cache file systems with the client's data.

Phase 9: The NIM master writes all migrated data to the client's alternate rootvg.

Phase 10: The NIM master cleans up and removes the local cache file systems.

nimadm Requirements

The nimadm requirements are:
  1. The configured NIM master must be running AIX 5.1 or higher with AIX recommended maintenance level 5100-03 or higher.
  2. The NIM master must have the same level of bos.alt_disk_install.rte installed in its rootvg and the SPOT which is used to perform the migration. (Note: it is not necessary to install the alt_disk_install utilities on the client).
  3. The selected lpp_source NIM resource, and selected SPOT NIM resource must match the AIX level to which you are migrating.
  4. The NIM master must be at the same or higher AIX level then the level being migrated to.
  5. The client (the system to be migrated) must be at AIX 4.3.3 or higher.
  6. The client must have a disk (or disks) large enough to clone the rootvg and an additional 500 Megs (approximately) of free space for the migration. The total amount of required space depends on original system configuration and nimadm customization.
  7. The target client must be a registered with the master as a standalone NIM client (see the niminit command for more information). The NIM master must be able to execute remote commands on the client using the rshd protocol.
  8. The NIM master must be able to execute remote commands on the client using the rshd protocol.
  9. The NIM master and client must both have a minimum of 128 megabytes of RAM.
  10. A reliable network, which can facilitate large amounts of NFS traffic, must exist between the NIM master and the client. The NIM master and client must be able to perform NFS mounts and read/write operations.
  11. The client's hardware and software must support the AIX level that is being migrated to and meet all other conventional migration requirements.
  12. The application servers, such as DB2 and LDAP, must be stopped before you runn the clone rootvg command. Otherwise, the application servers do not start normally after the clone rootvg command has finished processing.
Note: If you cannot meet requirements 1-10, you must perform a conventional migration. If you cannot meet requirement 11, then migration is not possible.
Attention: Before performing a nimadm migration you must agree to all software license agreements for software to be installed. You can do this by specifying the -Y flag as an argument to the nimadm command or setting the ADM_ACCEPT_LICENSES environment variable to "yes".

nimadm Limitations

The following limitations apply to the nimadm command:
  1. If the client's rootvg has TCB turned on, you must either disable it (permanently), use the disk caching option (-j), or perform a conventional migration. (This limitation exists because TCB needs to access file metadata which is not visible over NFS).
  2. All NIM resources used by the nimadm command must be local to the NIM master.
  3. Although there is almost no interference with the client's active rootvg during the migration, the client may experience minor reduction in performance due to increased disk input/output, biod activity, and some CPU usage associated with alt_disk_install cloning.
  4. NFS tuning may be required to optimize nimadm performance.
  5. The nimadm command is not supported with the multibos command when there is a bos_hd5 logical volume.

NIM resources used by nimadm:

SPOT resource (-s flag)
The NIM spot resource is required for all nimadm operations (migration, cleanup, wake-up, sleep). All nimadm and alt_disk_install utilities that are used by the client are installed in this resource. It is not necessary to install nimadm software on the client. The NIM cust operation must be used to install the following file sets into the spot:
  • Required: bos.alt_disk_install.rte (must match the NIM master's level).
  • Optional message catalog: bos.msg.$LANG.alt_disk_install.rte
lpp_source resource (-l flag)
This NIM resource is the source of install images that are used to migrate the system. It is required for nimadm migration operations. The lpp_source must contain all system images for the level being migrated to (check the lpp_source images attribute in lsnim -l lpp_source output). It must also contain any optional installp images that need to be migrated.
pre-migration
This script resource that is run on the NIM master, but in the environment of the client's alt_inst file system that is mounted on the master (this is done by using the chroot command). This script is run before the migration begins.
post-migration
This script resource is similar to the pre-migration script, but it is executed after the migration is complete.
image_data
Specifies an image_data resource that is passed to alt_disk_install (as arguments to the -i flag). NIM allocates and mount this resource on the client before calling alt_disk_install.
exclude_files
Specifies an exclude_files resource that is passed to alt_disk_install (as an argument to the -e flag). NIM allocates and mount this resource on the client before calling alt_disk_install.
installp_bundle
This NIM resource specifies any additional software that the nimadm command installs after completing the migration.
bosinst_data
This NIM resource specifies various install settings that may be used by the nimadm command.

The nimadm Migration Process

The nimadm command performs migration in 12 phases. Each phase can be executed individually using the -P flag. The user must have a good understanding of the nimadm process before performing a migration in phases. The nimadm phases are as follows:
  1. The master issues an alt_disk_install command to the client which makes a copy of the rootvg to the target disks (coincidentally this is Phase 1 of the alt_disk_install process). In this phase altinst_rootvg (alternate rootvg) is created. If a target mksysb has been specified, the mksysb is used to create a rootvg using local disk caching on the NIM master.
  2. The master runs remote client commands to export all of the /alt_inst file systems to the master. The file systems are exported as read/write with root access to the master. If a target mksysb has been specified, the cache file systems are created based on the image data from the mksysb.
  3. The master NFS mounts the file systems exported in Phase 2. If a target mksysb has been specified, the mksysb archive is restored in the cache file systems that were created in phase 2.
  4. If a pre-migration script resource has been specified, it is executed at this time.
  5. System configuration files are saved. Initial migration space is calculated and appropriate file system expansions are made. "bos" is restored and the device database is merged (similar to a conventional migration). All of the migration merge methods are executed and some miscellaneous processing takes place.
  6. All system file sets are migrated using installp. Any required RPM images are also installed during this phase.
  7. If a post-migration script resource has been specified, it is executed at this time.
  8. bosboot is executed to create a client boot image, which is written out to the client's boot logical volume (hd5).
  9. All mounts made on the master in phase 3 are removed.
  10. All client exports created in phase 2 are removed.
  11. The alt_disk_install is called again (phase 3 of alt_disk_install) to make final adjustments and put altinst_rootvg to sleep. The bootlist is set to the target disk (unless the -B flag is used). If an output mksysb has been specified, the cache is archived into a mksysb file and made into a NIM mksysb resource.
  12. Cleanup is executed to end the migration. The client is rebooted, if the -r flag is specified.
Note: The nimadm command supports migrating several clients simultaneous.

nimadm Cleanup Operation

This operation, indicated with the "-C" flag, is designed to clean up after a failed migration that for some reason did not perform a cleanup it self. It can also be used to clear a previous migration in order to perform a new migration.

nimadm Wake-up and Sleep

After a migration completes, the nimadm command can be used to "wake-up" the migrated altinst_rootvg or the original rootvg (if booted from the migrated disk). The nimadm wake-up (-W flag) performs an alt_disk_install wake-up, NFS exports the /alt_inst file systems, and mounts them on the NIM master. The nimadm sleep function (-S flag) reverses the wake-up by unmounting the NIM master mounts, unexporting the /alt_inst file systems, and executing the alt_disk_install sleep function on the client.

Flags

Item Description
-a PreMigrationScript Specifies the pre-migration NIM script resource.
-b installp_bundle Specifies the installp_bundle NIM resource.
-B Specifies not running bootlist after the nimadm migration. If set, then -r flag cannot be used.
-c ClientDisks Specifies the NIM defined client which is the target of this nimadm operation. This flag is required for all nimadm operations.
-C Performs nimadm cleanup.
-d TargetDisks Specifies the client target disk which is used to create altinst_rootvg (the volume group that is migrated).
-D Sets the nimadm command into debug mode. This function must only be used to debug nimadm related problems and is not set by default.
-e exclude_files Specifies the exclude_files NIM resource. This resource is used by the alt_disk_install command during Phase 1.
-E Enters the nimadm debugger if a serious migration error occurs.
-F Forces a client to unlock. Normally, the nimadm command locks a client to perform various operations. While the client is locked, other nimadm or NIM operations cannot be performed. This flag must ONLY be used in the unusual condition that a client is incorrectly locked (this can happen if for some reason the nimadm command could not call cleanup after a failure).
-i image_data Specifies the image_data NIM resource. This resource is used by the alt_disk_install command during Phase 1 and 11.
-j VGname Creates file systems on the specified volume group (on the NIM master) and uses streams to cache all of the data from the client to these file systems.
-l lpp_source Specifies the lpp_source NIM resource to be used for this nimadm operation. This flag is required for migration operations.
-m NFSMountOptions Specifies arguments that are passed to the mount command that mounts client resources on the master. This flag can be used to tune nimadm related NFS performance.
-M Verifies that the levels of the alt_disk_install software (bos.alt_disk_install) on the NIM master, SPOT, lpp_source, and optional device are synchronized (match). If there is no match, the nimadm command installs the highest level found in the lpp_source or optional device.
-N NIMmksysb Specifies the unique new NIM mksysb resource to create. If the -N flag is specified, the -O flag must be specified.
-o bosinst_data Specifies bosinst_data NIM resource.
-O mksysbfile Specifies the file pathname for the migrated mksysb. If the -O flag is specified, the -j flag and either the -c or -T flag must be specified.
-P Phase The phase to execute during this invocation of the nimadm command. If there is more then one phase, the phases must be separated by spaces or commas. Valid phases are 1 through 12.
-r Specifies that the client must reboot after nimadm migration is complete.
-s SPOT Specifies the SPOT NIM resource to be used for this nimadm operation. This flag is required for all nimadm operations.
-S Performs the nimadm "sleep" function. This function must be executed to end a nimadm "wake-up".
-T NIMmksysb Specifies an existing NIM mksysb resource to migrate. If the -T flag is specified, the -j flag and either the -O or -c flag must be specified.
-V Turns on verbose output.
-W Performs the nimadm "wake-up" function.
-Y Agrees to required software license agreements for software to be installed.
-z PostMigrationScript Specifies the post-migration NIM script resource.

Exit Status

0
All the nimadm command related operations completed successfully.
>0
An error occurred.

Security

Access Control: You must have root authority to run the nimadm command.

Attention RBAC users and Trusted AIX users: This command can perform privileged operations. Only privileged users can run privileged operations. For more information about authorizations and privileges, see Privileged Command Database in Security. For a list of privileges and the authorizations associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

  1. To execute nimadm migration to target NIM client aix1, using NIM SPOT resource spot1, NIM lpp_source resource lpp1, and target disks hdisk1 & hdisk2. Note that the -Y flag agrees to all required software license agreements for software to be installed, enter the following: 
    nimadm -c aix1 -s spot1 -l lpp1 -d "hdisk1 hdisk2" -Y
  2. To execute the same operation as in the example above to hdisk2, and also run pre-migration script nimscript1 and post-migration script nimscript2, type the following: 
    nimadm -c aix1 -s spot1 -a nimscrip1 -z nimscript2 -l lpp1 -d hdisk1 -Y
  3. To execute nimadm cleanup on client aix1, using NIM SPOT resource spot1, type the following: 
    nimadm -C -c aix1 -s spot1
  4. To create a migrated new mksysb resource of a client with the filename nim1, type the following: 
       nimadm -c aix1 -s spot1 -l lpp1 -O /export/mksysb/mksysb1 -j vg00 -Y -N nim1
  5. To create a new migrated mksysb resource with the filename nim3 from an existing NIM mksysb resource, type the following: 
       nimadm -s spot1 -l lpp1 -j vg00 -Y -T nim2 -O /export/mksysb/m2 -N nim3
  6. To migrate an existing NIM resource and put it on a client, type the following: 
       nimadm -c aix1 -s spot1 -l lpp1 -d hdisk1 -j vg00 -T nim2 -Y
    Note: No changes are made to the nim2 NIM mksysb resource.

Files

Item Description
/usr/sbin/nimadm Contains the nimadm command.