viosupgrade command

Purpose

Performs the operations of backing up the virtual and logical configuration data, installing the specified image, and restoring the virtual and logical configuration data of the Virtual I/O Server (VIOS).

Syntax

To perform the bosinst type of upgrade operation, use the following syntax:

viosupgrade -t bosinst -n hostname -m ios_mksysbname 
-p spotname  {-a RootVGCloneddisk: ... | -r RootVGInstallDisk: ...| -s} 
[-b BackupFileResource][-c][-e resources: ...] [-F skipclusterstate] [-v]

To perform the altdisk type of upgrade operation, use the following syntax:

viosupgrade -t altdisk -n hostname -m ios_mksysbname 
-a RootVGInstallDisk: ... [-b BackupFileResource] [-c] [-e
resources: ...] [-F skipclusterstate] [-v]

To perform a bosinst or altdisk type of upgrade operation across multiple nodes, use the following syntax:

viosupgrade -t {bosinst | altdisk} -f filename [-v]

To check the status of the triggered upgrade operation, use the following syntax:

viosupgrade -q { [-n hostname | -f filename] }

To create the ios_mksysb image file from the International Organization for Standardization (ISO) image files, use the following syntax:

viosupgrade -I ISOImage1:ISOImage2 -w directoryPath 
  -x iosmksysbResourceName [-y spotResourceName]

Description

When the viosupgrade command is run, the following operations are performed in the background:

Backup: The virtual and logical configuration data is backed up to ensure that the VIOS partition can be recovered after a new installation.
Installation: Performs a new and complete installation of the VIOS partition from the provided VIOS image.
Restore: The virtual and logical configuration data of the VIOS partition is restored.

Flags

Flag name	Description
-a	Specifies one or more alternative disks for the installation. One of the following actions is taken based on the type of installation: `bosinst` installation type: The provided disks are used to clone the current rootvg. After the completion of the migration process, the current rootvg disk is installed with the provided image. The provided disks are at the VIOS level before the migration process. `altdisk` installation type: The provided disks are used to install the provided image. The current rootvg disk on the VIOS partition is not impacted during the installation process. The VIOS partition remains in the running state during the installation of the alternative disk.
-b	Specifies the resource name of the VIOS configuration backup file.
-c	Specifies that cluster-level backup and restore operations are performed. Note: The `-c` flag is mandatory for the VIOS that is part of an SSP cluster.
-e	Specifies the configuration resources to be applied after the installation. The valid values are resolv_conf, script, fb_script, file_res, image_data, and log. Note: The file_res option is applicable only to `bosinst` type of installations. This option is not supported for `altdisk` type installations. If you do not specify the -e flag or if the /etc/resolv.conf and /etc/hosts files are not included in the specified configuration resources, the upgrade process backs up these files from the current system before starting the installation operation. The backed-up files are restored during the migration operation.
-f	Specifies the file name that contains the list of VIOS nodes. The values and fields in the file must be specified in a particular sequence and format. The details of the format are specified in the /usr/samples/nim/viosupgrade.inst file and they are comma-separated. The maximum number of nodes that can be installed through the `-f` option is 30. The VIOS images are installed on the nodes simultaneously. The installation status is displayed for each node. For an SSP cluster, the viosupgrade command must be run on individual nodes. Out of the `n` number of nodes in the `SSP cluster`, maximum `n-1` nodes can be upgraded at the same time. Hence, you must ensure that at least one node is always active in the cluster and is not part of the upgrade process. Note: All of the information must be entered in the specified format. You must not specify any value for blank or optional fields. Blank fields for alternate vg and rootvg disk indicates SKIP option from the user.
-F	Overrides certain default parameters to proceed with the VIOS upgrade operation. The skipclusterstate option skips the verification of the SSP cluster state, so that the VIOS upgrade operation can be triggered on multiple VIOS nodes simultaneously. Note: You must ensure that all SSP cluster nodes are not in the DOWN state at the same time. Otherwise, the SSP cluster services might become inactive permanently.
-I	Specifies the ISO image files that must be used to create the `ios_mksysb` image file.
-m	Specifies the IOS_MKSYSB resource name on the NIM Master server for the specified VIOS installation.
-n	Specifies the target VIOS host name to perform the VIOS upgrade operation.
-p	Specifies the resource object name of the Shared Product Object Tree (SPOT) for NIM installation.
-q	Queries the status of the VIOS upgrade operation.
-r	Specifies a new rootvg disk where the specified image must be installed. If you specify this flag, the existing rootvg disks are not used and the new disk is used for the installation.
-s	Skips the cloning of current rootvg disks to alternative disks and continues with the VIOS installation on the current rootvg disk. If the storage disks are not available, you can specify the `-s` flag to continue with the installation.
-t	Specifies the type of installation from the NIM server. The supported types are `bosinst` and `altdisk`. bosinst Indicates new and fresh installation on the current rootvg disk. altdisk Indicates a new installation on the alternative disk. The current rootvg disk on the VIOS partition is not impacted by this installation. The VIOS partition that has the current rootvg disk, remains in the running state during the installation of the alternative disk.
-v	Validates whether VIOS hosts are ready for the installation. The `-v` flag must be specified only for validation and can be used for preview of the installation image only.
-w	Specifies the directory path to create new ios_mksysb image file.
-x	Specifies the `ios_mksysb` image file name that must be created.
-y	Specifies new SPOT resource that must be created from the `ios_mksysb` resource.

Exit Status

Return code	Description
0	Success
1	Failure

Requirements

Consider the following requirements for the viosupgrade command:

Alternate disks that are used with the -a and -r options as part of the viosupgrade command must be completely free. You must be able to list the disks by running the lspv -free command on the VIO Server.
Installations through the viosupgrade command are categorized as a New & Complete installation. Any customized configurations on the current system that are running before the installation, including the time zone, are not carried to the new installation image. If you need to copy a customized file to the new image, use the -e flag with the file_res option. The -e flag with the file_res option specifies the customized file that must be backed up after the installation. You can use the viosupgrade command with the -e flag and file_res option only for bosinst type installations. After the installation, the customized files are copied to the /home/padmin/backup_files directory.
Note: You must follow the manual steps on the NIM master to define the file_res resources before you run the viosupgrade command. The source directory, /export/nim/viosupgrade/copyfiles, is where the customized files are stored on the NIM master. The destination directory, /home/padmin/backup_files, is where the customized files are copied to on the VIOS after the installation.
For example, to restore the files in the /etc/environment and /var/custom.conf files, complete the following steps:
1. Create a source directory.
```
mkdir -p /export/nim/viosupgrade/copyfiles
```
2. Define the file_resource option.
```
nim -o define -t file_res -a location=/export/nim/viosupgrade/copyfiles -a 
dest_dir=/home/padmin/ backup_files -a server=master file_res_user
```
3. Create the /export/nim/viosupgrade/copyfiles/etc and /export/nim/copyfiles/var directories under the source directory.
```
mkdir -p /export/nim/viosupgrade/copyfiles/etc
mkdir -p /export/nim/copyfiles/var.
```
4. Copy the files from VIOS to the NIM master source directories.
```
scp -r root jaguar13:/etc/environment /export/nim/viosupgrade/copyfiles/etc
scp -r root jaguar13:/var/custom.conf /export/nim/viosupgrade/copyfiles/var
```
The viosbr restore process does not support virtual device mappings with vscsi disks that are created on the VIO Server's rootvg disks. Therefore, the viosupgrade command cannot restore vscsi mappings if LVs are created from the VIO Server's rootvg disk.
To enable the VIOS to be remotely managed by the AIX NIM master, run the remote_management command from VIOS.
The target ios_mksysb image level considerations follow:
- The level of the target ios_mksysb image must be at 3.1.0.00 level, or later.
- The target ios_mksysb image level must be higher than the current VIOS rootvg level.
The viosupgrade command on NIM server is supported from IBM® AIX® 7.2 with Technology Level 3, or later.

For the NIM bosinst method of installation, the following are the current VIOS levels that are supported:
- 2.2.6.30, or later for a Shared Storage Pool Cluster environment
- 2.2.x.x, or later for a non-Shared Storage Pool Cluster environment
On the NIM master, VIOS must be defined along with the Network Adapter Hardware Address (MAC) or Network Adapter Logical Device Name (ent name) in the NIM object's if1 definition. If not defined, the viosupgrade command displays a message that the network boot operation might be delayed or fail.
For a NIM bosinst type of installation, the interface resource (MAC or ent name), defined on the NIM object's if1 definition for any given VIOS, must adhere to the following considerations:
- The interface resource can be any available Ethernet interface that is connected to the network.
- The interface resource can be a physical interface that is part of a Shared Ethernet Adapter (SEA).
- The interface resource cannot be a Shared Ethernet Adapter (SEA) interface.
This is mandatory for the viosupgrade command to trigger the VIOS restore process after the installation.
For a NIM altdisk type of installation, the current VIOS levels that are supported are 2.2.6.30, or later.
The NIM altdisk type of installation is not supported for VIOS when an SEA is the only primary interface for communication.
Note: To enable the NIM altdisk type of installation for the preceding case, you must configure an additional Ethernet interface as the primary interface for remote management. The NIM master must be able to establish the network connection with the VIOS using the IP address that is configured on this interface by default.
If a node is part of a cluster, then the hostname of the node must be resolvable during the metadata restore process after the installation is complete, This can be achieved either by passing the resolv.conf file or a script to add an entry in the /etc/hosts file, along with the -e option.
If the VIOS belongs to an SSP cluster and if the current VIOS version is older than 2.2.6.30, the following two-step upgrade process is necessary to upgrade to VIOS 3.1.0.00, or later.
1. Upgrade the VIOS to version 2.2.6.30 through the upgrade methods such as by using the updateios command.
2. Use the viosupgrade command to upgrade to the VIOS to version 3.1.0.00, or later.
If you are using altdisk method for installing the VIOS, and if the VIOS has altinst_rootvg or old_rootvg disks, the viosupgrade command fails indicating the user to rename the disks.
The NIM master might reboot the VIOS and re-initiate the restore process to restore multiple virtual IO mappings through the viosbr restore process after the installation.
If the NIM master fails to restore all of the mappings, you must manually re-initiate the restore operation on the NIM master by using the following commands:
- VIOS-non SSP:
```
nim -o viosbr -a viosbr_action=restore -a ios_backup=<BackupObjectName> <VIOSObjectName>
```
- VIOS-SSP Cluster:
```
nim -o viosbr -a viosbr_action=restore -a ios_backup=<BackupObjectName> -a 
clustername=<clusterName> -a viosbr_flags="-curnode"  <VIOSObjectName>
```
  Note: The BackupObjectName would generally be <VIOSName>_backup. You can get the list of backup object names from the command, lsnim -t ios_backup.
If you installed additional software on the VIOS that is not part of the base VIOS image, the viosupgrade command might fail to restore configurations that are related to that software. To handle this case, you must create a customized VIOS image with the software applications that you want to include and provide this customized VIOS image as an input to the viosupgrade command for installation.
The viosupgrade command identifies the software applications that are not included in the ios_mksysb image file, but are installed in the current system, such as the Subsystem Device Driver (SDD), or the Subsystem Device Driver Path Control Module (SDDPCM). The viosupgrade command displays a warning prompt on the console output during software validation or before installing the software. You can choose to continue or terminate the upgrade process by selecting the corresponding option. For example, if the software application that is installed on the VIOS is SDDPCM, you must customize the ios_mksysb image file to include the SDDPCM application and to provide the customized VIOS image file as an input to the viosupgrade command.

Note: For more information about creating a customized VIOS image, refer to the backupios command.
To create the ios_mksysb image file from the ISO image files, you require approximately 4 GB memory in the directory that you specify by using the -w flag in the viosupgrade command.

Examples

To validate the VIOS upgrade operation by using the bosinst method, type the following command:
```
viosupgrade -v -t bosinst -n systemA -m mksysbA -p spotA -s
```
Where, target VIOS node is systemA, mksysb image name is mksysbA, spot name is spotA and the type of install is bosinst.
To validate the VIOS upgrade operation by using the bosinst method, type the following command:
```
viosupgrade -v -t bosinst -n clusternodeA -m mksysbA -p spotA -r hdisk1:hdisk2 -c -b clusterbackup -e resolv_conf:script
```
Where, target cluster VIOS node is clusternodeA, mksysb image name is mksysbA, spot name is spotA, VIOS configuration backup resource is clusterbackup, NIM resources are resolv_conf and script, type of install is bosinst and provided new rootvg disks are hdisk1 and hdisk2.
To perform the VIOS upgrade operation by using the bosinst method by skipping the current rootvg cloning, type the following command
```
viosupgrade -t bosinst -n systemA -m mksysbA -p spotA -s
```
Where, target VIOS node is systemA, mksysb image name is mksysbA, spot name is spotA and type of install is bosinst.
Note: After the installation, the new rootvg will be the current rootvg.
To perform the VIOS upgrade operation by using the bosinst method by installing on provided disks, type the following command:
```
viosupgrade -t bosinst -n systemA -m mksysbA -p spotA -r hdisk1:hdisk2
```
Where, target VIOS node is systemA, mksysb image name is mksysbA, spot name is spotA, type of install is bosinst and provided new rootvg disks are hdisk1 and hdisk2.
Note: After reinstall new rootvg will be on the provided disks.
To perform the VIOS upgrade operation by using the bosinst method by doing the backup of current rootvg on provided alternate disks, type the following command:
```
viosupgrade -t bosinst -n systemA -m mksysbA -p spotA -a hdisk3:hdisk4
```
To perform the VIOS upgrade operation through bosinst method by using the provided VIOS configuration backup file, type the following command:
```
viosupgrade -t bosinst -n systemA -m mksysbA -p spotA -s -b backup
```
Where the target VIOS node is systemA, mksysb image name is mksysbA, spot name is spotA, VIOS configuration resource is backup, and the type of install is bosinst.
To perform the SSP cluster VIOS upgrade operation by using the bosinst method on the provided disks, type the following command:
```
viosupgrade -t bosinst -n clusternodeA -m mksysbA -p spotA -r hdisk1:hdisk2 -c
```
Where, target cluster VIOS node is clusternodeA, mksysb image name is mksysbA, spot name is spotA, type of install is bosinst and provided disks for new rootvg are hdisk1 and hdisk2.
You can perform the VIOS upgrade operation by using the bosinst method and the provided NIM resources. You can also create a backup of the current rootvg on a provided alternate disk. To perform all three of these operations, type the following command:
```
viosupgrade -t bosinst -n systemA -m mksysbA -p spotA -a hdisk3:hdisk4 -e resolv_conf:script:fb_script
```
Where, the target VIOS node is systemA, mksysb image name is mksysbA, spot name is spotA, type of install is bosinst and provided alternate rootvg disks are hdisk3 and hdisk4, provided NIM resources are resolv_conf, script, fb_script.
To validate the VIOS upgrade operation by using the altdisk method, type the following command:
```
viosupgrade -v -t altdisk -n systemA -m mksysbA -a hdisk3:hdisk4
```
Where, the target VIOS node is systemA, mksysb image name is mksysbA, alternate disks are hdisk3, hdisk4, and type of install is altdisk.
To perform the VIOS upgrade operation by using the altinst method, type the following command:
```
viosupgrade -t altdisk -n systemA -m mksysbA -a hdisk3:hdisk4
```
Where, the target VIOS node is mysystemA, mksysb image name is mymksysbA, type of install is altdisk and provided alternate rootvg disks are hdisk3 and hdisk4.
To perform the SSP cluster VIOS upgrade operation by using the altinst method, type the following command :
```
viosupgrade -t altdisk -n clusternodeA -m mksysbA -a hdisk3:hdisk4:hdisk5 -c
```
Where, the target cluster node is clusternodeA, mksysb image name is mksysbA, type of install is altdisk and provided alternate rootvg disks are hdisk3, hdisk4, hdisk5.
To validate the upgrade operation of one or more VIOS nodes in the provided file by using the bosinst method, type the following command:
```
viosupgrade -v -t bosinst -f  "/usr/samples/nim/viosupgrade.inst"
```
Note: Refer /usr/samples/nim/viosupgrade.inst for more information.
To perform the upgrade operation on a provided VIOS node in file by using the bosinst method, type the following command:
```
viosupgrade -t bosinst -f  "/usr/samples/nim/viosupgrade.inst"
```
If the target VIOS node is systemA, mksysb image name is mksysbA, spot name is spotA, provided alternate rootvg are hdisk3 and hdisk4, type of install is bosinst and file that contains VIOS node information is /usr/samples/nim/viosupgrade.inst then, file should contain the following data:
```
systemA, mksysbA, spotA, ,hdisk3:hdisk4
```
To perform the upgrade operation on provided SSP cluster VIOS nodes in file through the bosinst method then, type the following command:
```
viosupgrade -t bosinst -f  "/usr/samples/nim/viosupgrade.inst"
```
If the target cluster VIOS node is clusternodeA, mksysb image name is mksysbA, spot name is spotA, type of install is bosinst and file that contains VIOS nodes information is /usr/samples/nim/viosupgrade.inst then, file must contains the following data:
```
clusternodeA, mksysbA, spotA, , , , c,
```
To perform the upgrade operation on the provided VIOS nodes in the file by using the altdisk method then, type the following command:
```
viosupgrade -v -t altdisk -f  "/usr/samples/nim/viosupgrade.inst"
```
To perform the VIOS upgrade operation by using the bosinst method and to restore files from the current rootvg to a newly installed image, type the following command:
```
viosupgrade -t bosinst -n systemA -m mksysbA -p spotA -s -e file_res
```
Where, the target VIOS node is systemA, mksysb image name is mksysbA, spot name is spotA, file_res is file_res_user and type of install is bosinst.
To create the ios_mksysb image file and SPOT resource from ISO image files, enter the following command:
```
viosupgrade -I /home/padmin/dvdimage.v1.iso:/home/padmin/dvdimage.v2.iso -w /home/myNewIosMksysbImageDir 
-x myIosMkysysbRes -y mySPOTResource
```
Where, /home/padmin/dvdimage.v1.iso and /home/padmin/dvdimage.v2.iso are the ISO image files, /home/myNewIosMksysbImageDir is the path where the ios_mksysb image file is created, myIosMkysysbRes is the name of the ios_mksysb image file that is created, and mySPOTResource is the name of the SPOT resource that is created.
To perform the VIOS upgrade operation by using the bosinst method on specified disks and to override the verification of the SSP cluster state, type the following command:
```
viosupgrade -t bosinst -n systemA -m mksysbA -p spotA -r hdisk1:hdisk2 -F skipclusterstate -c
```
Where, systemA is the target VIOS node, mksysbA is the name of the mksysb image, spotA is the name of the SPOT resource, the type of installation is bosinst, and the specified new rootvg disks are hdisk1 and hdisk2.