nimadm Command

Purpose

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

This document provides information about the nimadm command. For complete coverage of alt_disk_install, NIM, migration, and other related installation issues, see Installing AIX.

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). Also, the nimadm command uses streams to cache all the data from the client to these file systems.

Following are the advantages and disadvantages of the nimadm local disk caching function:

Advantages

1. Improved performance for nimadm operations that are on relatively slow networks.
2. Improved performance for nimadm operations that are bottleneck in the NFS writes (NFS writes are 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 a NIM resource that is used in the operation).

How to execute disk caching

1. Make sure that 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 the following command:

# lsnim -a location SpotName

The name of the file must be in the following format:

Nim_Client.nimadm_cache.excl

Note: This file applies to the NIM client specified in Nim_Client. The full path must be in the following format:

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. To exclude a file system, you must ensure the following points:

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. Excluding such files can lead to unpredictable results.
2. Do not (cannot) exclude the following AIX file systems: /, /usr, /var, /opt, /home, and /tmp.

Following four phases are changed by the nimadm command with disk caching (all other phases remain the same):

• Phase 2 - The NIM master creates a local cache file system in the 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

Following are the nimadm requirements:

1. The NIM master must have the same level of bos.alt_disk_install.rte installed in its rootvg and the SPOT that is used to perform the migration. (Note: it is not necessary to install the alt_disk_install utilities on the client).
2. The selected lpp_source NIM resource, and selected SPOT NIM resource must match the AIX level to which you are migrating.
3. The NIM master must be at the same or higher AIX level than the level to which it is migrated.
4. The client (the system to be migrated) must be at AIX 4.3.3 or higher.
5. The client must have a disk (or disks) large enough to clone the rootvg and an extra 500 Megs (approximately) of free space for the migration. The total amount of required space depends on original system configuration and nimadm customization.
6. The target client must be a registered with the master as a stand-alone NIM client. For more information, see the niminit command. The NIM master must be able to execute remote commands on the client by using the rshd protocol.
7. The NIM master must be able to execute remote commands on the client by using the rshd protocol.
8. The NIM master and client must both have a minimum of 128 megabytes of RAM.
9. 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.
10. The client's hardware and software must support the AIX level that is being migrated to and meet all other conventional migration requirements.
11. All application and database servers, such as DB2 and LDAP, must be stopped before you run the nimadm command to clone the rootvg of a client system. Otherwise, the application servers and the database servers do not start normally after the nimadm command operations are complete.

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 agree to all software license agreements for software to be installed 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 trusted computing base (TCB) is turned on in the client's rootvg, you must disable it (permanently), use the disk caching option (-j), or perform a conventional migration. This limitation exists because TCB must access the file metadata, which is not accessible through Network File System (NFS).
2. All NIM resources that are 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 volume group during the migration, the client might experience minor reduction in performance due to increased disk I/O, biod activity, and CPU usage associated with cloning the alt_disk_install command.
4. You might need to tune the NFS to optimize the nimadm performance.
5. The reserved directory names on the NIM client for nimadm are /ALT_MIG_SPOT, /ALT_MIG_EXCL, /ALT_MIG_IMAGES, and /ALT_MIG_IMD. The nimadm command fails if these names are used.

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 installation 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 to which the system is migrated (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 operation 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 mounts 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 mounts 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 the migration is completed.

bosinst_data

This NIM resource specifies various installation settings that might be used by the nimadm command.

The nimadm migration process

The nimadm command performs migration in 12 phases. Each phase can be executed individually by using the -P flag. The nimadm phases must be run sequentially. Following are the nimadm phases:

1. The master issues an alt_disk_install command to the client that makes a copy of the rootvg volume group to the target disks (coincidentally this operation is Phase 1 of the alt_disk_install process). In this phase altinst_rootvg (alternate rootvg) is created. If a target mksysb is specified, the mksysb is used to create a rootvg volume group by using local disk caching on the NIM master.
2. The master runs remote client commands to export all 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 is specified, the cache file systems are created based on the image data from the mksysb.
3. The master NFS mounts the file systems that are exported in Phase 2. If a target mksysb is specified, the mksysb archive is restored in the cache file systems that was created in phase 2.
4. If the pre-migration script resource is specified, the script is executed during 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). The migration merge methods are executed and some miscellaneous processing takes place.
6. The file sets of the system are migrated by using the installp. Any required RPM images are installed during this phase.
7. If the post-migration script resource is specified, the script is executed during this time.
8. The bosboot command is executed to create a client boot image that is written to the client's boot logical volume (hd5).
9. The mounts that are made on the master in phase 3 are removed.
10. The client exports that are 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 place altinst_rootvg to sleep. The bootlist is set to the target disk (unless the -B flag is used). If an output mksysb is 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 simultaneously.

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

Exit Status

0

All the nimadm command-related operations that are completed successfully.

>0

An error occurred.

Security

Access Control

You must have root authority to run the nimadm command.

RBAC users

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 that are associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

1. To execute nimadm migration to target NIM client aix1 by using NIM SPOT resource spot1, NIM lpp_source resource lpp1, and target disks hdisk1 & hdisk2. The -Y flag agrees to all required software license agreements for software to be installed, enter the following command:

   nimadm -c aix1 -s spot1 -l lpp1 -d "hdisk1 hdisk2" -Y

2. To execute the same operation as in the example earlier to hdisk2, and also run pre-migration script nimscript1 and post-migration script nimscript2, enter the following command:

   nimadm -c aix1 -s spot1 -a nimscrip1 -z nimscript2 -l lpp1 -d hdisk1 -Y

3. To execute nimadm cleanup on client aix1 by using NIM SPOT resource spot1, enter the following command:

   nimadm -C -c aix1 -s spot1

4. To create a migrated new mksysb resource of a client with the file name nim1, enter the following command:

   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 file name nim3 from an existing NIM mksysb resource, enter the following command:

   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, enter the following command:

   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