nimadm Command
Purpose
- 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 is migrated to a new version or release level of AIX.
- Using a NIM mksysb resource, create a new NIM mksysb resource that is 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.
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 ] [ -A ] [ -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.
- Reduced downtime. The migration is performed while the system is up and functioning normally. It is not required to boot from the installation media, and most processing occurs on the NIM master.
- The nimadm command facilitates quick recovery if migration fails. As the
nimadm command uses alt_disk_install to create a copy of
rootvg, all changes are performed to the copy (
altinst_rootvg
). If there is a serious migration installation failure, the failed migration is cleaned up and the administrator need not take any further action. If there is 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. - The nimadm command allows a high degree of flexibility and customization in
the migration process with the help of optional NIM customization resources. The NIM customization
resources are
image_data
,bosinst_data
,exclude_files
,pre-migration
script,installp_bundle
, andpost-migration
script.
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
-
- Improved performance for nimadm operations that are on relatively slow networks.
- Improved performance for nimadm operations that are bottleneck in the NFS writes (NFS writes are expensive).
- Decreased CPU usage on the client.
- Client file systems are not exported.
- Disadvantages
-
- 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)
- Increased CPU usage on the master.
- 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
-
- Make sure that you are at the latest level of bos.alt_disk_install.rte on the NIM master.
- Add the -j
VGName flag to any nimadm operations. For example,
nimadm -j rootvg
ornimadm -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 toaltinst_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:
For example, /nim_resources/520spot/usr/myclient.nimadm_cache.excl.Spot_Location/Nim_Client.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:- 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.
- 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:
- 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).
- The selected
lpp_source
NIM resource, and selected SPOT NIM resource must match the AIX level to which you are migrating. - The NIM master must be at the same or higher AIX level than the level to which it is migrated.
- The client (the system to be migrated) must be at AIX 4.3.3 or higher.
- 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.
- 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. - The NIM master must be able to execute remote commands on the client by using the
rshd
protocol. - The NIM master and client must both have a minimum of 128 megabytes of RAM.
- 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.
- The client's hardware and software must support the AIX level that is being migrated to and meet all other conventional migration requirements.
- 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:
- 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).
- All NIM resources that are used by the nimadm command must be local to the NIM master.
- 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. - You might need to tune the NFS to optimize the nimadm performance.
- 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 -llpp_source
output). It must also contain any optionalinstallp
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:
- 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. - 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.
- 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.
- If the
pre-migration
script resource is specified, the script is executed during this time. - 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. - The file sets of the system are migrated by using the
installp
. Any required RPM images are installed during this phase. - If the
post-migration
script resource is specified, the script is executed during this time. - The bosboot command is executed to create a client boot image that is written
to the client's boot logical volume (
hd5
). - The mounts that are made on the master in phase 3 are removed.
- The client exports that are created in phase 2 are removed.
- 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. - 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. - 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
- Boot logical volume size
-
The nimadm command creates a boot logical volume with appropriate size to accommodate the new boot image. When you migrate your current AIX version to AIX 7.3, the size of the boot logical volume is 40 MB.
- 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
Item | Description |
---|---|
-a PreMigrationScript | Specifies the pre-migration NIM script resource. |
-A | Adds a timestamp at the start of each phase of the nimadm operation. The timestamp is displayed in MM-DD-YYYY HH-MM-SS format. |
-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 that 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 that is used to create
altinst_rootvg (the volume group that is migrated). |
-D | Sets the nimadm command into debug mode. This function must be used only 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 be used only in the unusual condition that a client is incorrectly locked. A client is incorrectly locked 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 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 that is 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 path name 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 than one phase, the phases must be separated by spaces enclosed in double quotes 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 the 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 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: 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
- To execute nimadm migration to target NIM client aix1 by using NIM
SPOT
resource spot1, NIMlpp_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
- To execute the same operation as in the example earlier to hdisk2, and also run
pre-migration
script nimscript1 andpost-migration
script nimscript2, enter the following command:nimadm -c aix1 -s spot1 -a nimscrip1 -z nimscript2 -l lpp1 -d hdisk1 -Y
- To execute nimadm cleanup on client aix1 by using NIM
SPOT
resource spot1, enter the following command:nimadm -C -c aix1 -s spot1
- 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
- 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
- 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 thenim2
NIM mksysb resource. -
To show timestamps for nimadm migration to target NIM client
flan003
by using NIMSPOT
resourcespot1
, NIMlpp_source
resourcelpp1
, and target diskhdisk1
, enter the following command:nimadm -j nimadm -c flan003 -s spot1 -l lpp1 -d hdisk1 -Y -A
An output that is similar to the following example is displayed:Initializing the NIM master. Starting Alternate Disk Migration. +-----------------------------------------------------------------------------+ 01-12-2023 01:21:29 Executing nimadm phase 1. +-----------------------------------------------------------------------------+ Cloning altinst_rootvg on client, Phase 1. for backup and restore into the alternate file system... Phase 1 complete. +-----------------------------------------------------------------------------+ 01-12-2023 01:22:32 Executing nimadm phase 2. +-----------------------------------------------------------------------------+ Creating nimadm cache file systems on volume group nimadm.
Files
Item | Description |
---|---|
/usr/sbin/nimadm | Contains the nimadm command. |