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 upgrade the VIOS:

viosupgrade -l -i image_file -a mksysb_install_disk [ -c ] [-g filename ] [ -F options:... ] [ -P post_install_binary ] [-u]

To query the status of the VIOS upgrade operation after the VIOS partition restarts by using the newly installed image:

viosupgrade –l -q

To create the mksysb image file by using the ISO image files:

viosupgrade -I ISOImage1:ISOImage2 -w directoryPath

Note: The -I and -w flag options are available only in VIOS versions 2.2.6.51, 3.1.0.30 and 3.1.1.0, or later.

To restore the VIOS metadata configuration:

viosupgrade -o {restore} -A args="argument1..."

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: A New and Complete installation of the VIOS partition is completed by using the provided VIOS image.
Restore: The virtual and logical configuration data of the VIOS partition is restored.

Flags

Flag name	Description
-a	Specifies an alternative disk to install the available VIOS image. The current rootvg disk on the VIOS partition is not impacted by this installation. The VIOS partition remains in the running state during the installation of the alternative disk.
-A	Specifies the arguments based on the type of option passed by using the -o flag. The args option can be chosen from the viosbr -restore command. For more information about the viosbr -restore command options, see the viosbr Command.
-c	Specifies that cluster-level backup and restore operations are performed. Note: The -c flag is mandatory for a VIOS that is part of an Shared Storage Pool (SSP) cluster.
-F	Overrides certain default parameters to proceed with the operations of the viosupgrade installation. The following options are supported for the viosupgrade installation: skipclusterstate: Skips the verification of the SSP cluster state, so that the operations of the viosupgrade installation can be triggered on multiple VIOS nodes simultaneously. Note: You must ensure that all the SSP cluster nodes are not in DOWN state at the same time as this can bring down the SSP cluster completely. forcecopy: Copies the list of backup files (refer to -g flag) to the respective directories in the newly installed rootvg disk(s). Notes: The `forcecopy` option is applicable only with the -g flag. The -g flag without the `-F forcecopy` option copies the files to the /home/padmin/backup_files directory in the newvg volume group. You have to copy the files from the /home/padmin/backup_files directory to the corresponding directories in the newvg volume group. skiprestore: Skips the restore operation of the VIOS metadata configuration after the operations of the viosupgrade installation process is completed and the VIOS has booted from the newly installed rootvg disk(s). Notes: Details of the backup file is displayed in the output of the viosupgrade command. You can use the backup file to manually restore the VIOS metadata configuration. To restore the VIOS metadata configuration, run the `viosupgrade -o restore -A args="<viosbr arguments>"` command. The VIOS may reboot during the restore process. Alternatively, you can restore the VIOS metadata configuration by running the `viosbr -restore` command. The VIOS must be manually rebooted and the restore operation of the VIOS metadata configuration has to be rerun, if needed.
-g	Specifies the file that contains the list of files that need to be backed up from the current system and saved in the new VIOS installed image. Each line must contain a single filename along with its path. Multiple files must be specified in separate new lines.
-i	Specifies the image file that must be used for the installation on an alternative disk.
-I	Specifies the ISO image file that must be used for creating the mksysb image file.
-l	Installs the local node.
-u	Specifies that the VIOS must be manually rebooted to activate the newly installed root volume group in the VIOS partition. Note: The VIOS must be rebooted to complete the VIOS metadata restore process in the newly installed root volume group.
-o	Specifies the type of operation that can be performed by executing the viosupgrade command. The restore operation specifies that the VIOS metadata configuration is restored when you run the viosupgrade command. In this case, you must pass the `-A args="<viosbr restore arguments>"` option to the viosupgrade command. Notes: To retrieve the information about the backup file, run the `viosupgrade -l -q` command on the newvg disk. To verify the status of the restore process of the VIOS metadata configuration, run the `viosupgrade -l -q` command. The VIOS may reboot during the restore process of the VIOS metadata configuration. At a specific time, only one operation of viosupgrade restore configuration process is allowed.
-P	Specifies and runs a binary after the restore process of the VIOS metadata configuration is successful. Note: You cannot use the -P flag with the `-F skiprestore` option.
-q	Queries the status of the VIOS upgrade operation after the VIOS partition restarts by using the newly installed image.
-w	Specifies the directory path in which you want to create the mksysb image file.

Exit Status

Return code	Description
0	Success
1	Failure

Requirements

Installations through the viosupgrade command are of the type New and Complete installation. Any customized configurations that might exist on the currently running system before the installation starts (including the timezone), are not included in the new installation image. If you need to copy any customized file to the new image, use the -g flag with the file option. You must specify all the customized files in a separate line with the complete path. These files are copied to the /home/padmin/backup_files directory after the installation.

Example:
/etc/netsvc.conf
/etc/environment

The level of the target mksysb image must be at version 3.1.0.00, or later.
The viosupgrade command is supported from VIOS Version 2.2.6.30, or later.
If the VIOS belongs to an SSP cluster and if the current VIOS version is earlier than version 2.2.6.32, complete the following upgrade process to upgrade your current VIOS version to VIOS Version 3.1.0.00, or later:
1. Upgrade the VIOS to version 2.2.6.32 by using other upgrade methods, such as by running the updateios command. For more information, see the updateios Command.
2. Use the viosupgrade command to upgrade to VIOS Version 3.1.0.00, or later.
If the altinst_rootvg or old_rootvg disks are already available in the VIOS, you must rename them.
Note: As a root user, you can run the alt_rootvg_op command to rename the volume groups before installing the VIOS.
The size of the target disk, where the VIOS is being installed, must be greater than or equal to 30G.
The disks that are specified for the VIOS installation must not be in use. That is, you must be able to list the disks by running the lspv –free command.
In an SSP cluster, the viosupgrade command must be run on individual nodes. Out of n number of nodes in the SSP cluster, only 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.
If the viosupgrade command fails to restore all of the mappings, you must manually re-initiate the restore operation on the VIOS by running the following commands:
- For a VIOS – non SSP:
```
viosbr -restore -file <BackupFileName>
```
- For a VIOS – SSP cluster, you must first restore the network and then restore the cluster by completing the following steps:
```
viosbr -restore -file <BackupFileName> - clustername <clusterName> -type net -curnode
```
```
viosbr -restore -file <BackupFileName> -clustername <clusterName> -curnode
```
  Note: The BackupFileName will be at the location “/home/padmin/cfgbackups/” and prefixed with the hostname. For example: /home/padmin/cfgbackups/hostname_filename.tar.gz
If you have installed any additional software on the VIOS apart from what is supplied as part of the base VIOS image, the viosupgrade command might fail to restore configurations that are related to that software. To manage this scenario, you must create a customized VIOS image with the software applications that you might want to include and provide this customized VIOS image as an input to the viosupgrade command for installation.
For example: If the Software application that is installed on the VIOS is Subsystem Device Driver Path Control Module (SDDPCM), then you have to prepare the mksysb image including SDDPCM, and provide this customized VIOS image as an input to the viosupgrade command.

Note: For more information about creating customized VIOS images, see backupios command

Examples

To view the Help information for the viosupgrade command, type the following command:
```
viosupgrade -h
```
```
viosupgrade -help
```
To perform the VIOS upgrade operation, type the following command:
```
viosupgrade -l -i mymksysbA -a hdisk1:hdisk2
```
Where, mymksysbA is the image name and the specified new rootvg disks are hdisk1 and hdisk2.

A new rootvg resource is created on the specified disks.
To manually reboot the VIOS partition and to perform the VIOS upgrade operation, type the following command:
```
viosupgrade -l -i mymksysbA -a hdisk1:hdisk2 -u
```
To upgrade the VIOS that belongs to an SSP cluster, type the following command:
```
viosupgrade -l -i mymksysbA -a hdisk1:hdisk2 -c
```
Where, mymksysbA is the image name and the specified new rootvg disks are hdisk1 and hdisk2.
To query the status of the VIOS upgrade operation after the VIOS partition restarts by using the newly installed image, type the following command:
```
viosupgrade -l -q
```
To copy files from the current rootvg disk to a newly installed VIOS image, type the following command:
```
viosupgrade -l -i mymksysbA -a hdisk1:hdisk2 -g file_list_name
```
Where, mymksysbA is the image name, the specified new rootvg disks are hdisk1 and hdisk2 and file_list_name is the file that contains the list of files to be copied to the new rootvg image.
To create the mksysb image file by using the ISO image files, type the following command:
```
viosupgrade -I /home/padmin/dvdimage.v1.iso:/home/padmin/dvdimage.v2.iso -w /home/myNewIosMksysbImageDir
```
Where, /home/padmin/dvdimage.v1.iso and /home/padmin/dvdimage.v2.iso are the directory paths that contain the ISO image files, and /home/myNewIosMksysbImageDir is the directory path that contains the mksysb image file that will be created after running this command.
To override the verification of the SSP Cluster state during the viosupgrade installation, type the following command:
```
viosupgrade -l -i mymksysbA -a hdisk1:hdisk2 -F skipclusterstate -c
```
Where, mymksysbA is the name of the image and hdisk1 and hdisk2 are the new rootvg disks.
To copy files from the current rootvg disk to the respective directories of a newly installed rootvg disk(s), type the following command:
```
viosupgrade -l -i mymksysbA -a hdisk1:hdisk2 -g file_list_name -F forcecopy
```
Where, mymksysbA is the name of the image and hdisk1 and hdisk2 are the new rootvg disks. The file_list_name is the file that contains the list of files to be copied to the new rootvg image.
To skip the restore process of the VIOS metadata configuration on the new rootvg disk after the viosupgrade installation, type the following command:
```
viosupgrade -l -i mymksysbA -a hdisk1:hdisk2 -F skiprestore -c
```
Where, mymksysbA is the name of the image and hdisk1 and hdisk2 are the new rootvg disks.
To perform the restore process of the VIOS metadata configuration on the new rootvg disk, type the following command:
```
viosupgrade -o restore -A args="-file viosbr_backupfile.tar.gz"
```
Where, -file viosbr_backupfile.tar.gz is the argument of viosbr -restore command. Similar to this any valid viosbr -restore command arguments can be sent to the -A args parameter.
To specify and run a binary after the restore process of the VIOS metadata configuration is successful on the new rootvg disk, type the following command:
```
viosupgrade -l -i mymksysbA -a hdisk1:hdisk2 -P <post_install_binary>
```
Where, mymksysbA is the name of the image and hdisk1 and hdisk2 are the new rootvg disks. The post_install_binary is the binary that must be run.

Restrictions

The viosbr -restore command does not support mapping virtual devices with vSCSI disks that are created on the rootvg disks of a VIOS. Hence, the viosupgrade command cannot restore mapping information of vSCSI if logical volumes are created from the rootvg disk of a VIOS.