viosupgrade command

Purpose

The purpose of viosupgrade command is 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 ] [-X options:...] [-k pre_restore_script] [-u]

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

viosupgrade –l -q [-S]

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

To rerun the upgrade operation on the new rootvg disk:

viosupgrade -o rerun

Description

When the viosupgrade command is run, the following operations are done 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.

Note: When you use the viosupgrade command, the logical partition can be installed and configured only one time during the entire upgrade operation.

Flags

Flag name	Description
-a	Specifies a colon-delimited alternative disk on which the available VIOS image would be installed. This installation does not impact the current rootvg disk on the VIOS partition. The VIOS partition remains in the running state when the VIOS image is installed on the alternative disk.
-A	Specifies the arguments based on the type of option that is 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 done. Note: The -c flag is mandatory for a VIOS that is part of a 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: devname: Allows you to preserve the device names in the newvg volume group. The following virtual host adapter devices are preserved: vfchost adapter devices fcnvme, nvme devices fscsi devices iSCSI devices network adapter devices. Note: The viosupgrade command preserves the device names for the following types of network adapters: shared Ethernet adapter (SEA) virtual local area network (VLAN) EtherChannel. The viosupgrade command also preserves the virtual target device (VTD) names for all the backing devices. The preservation of network adapter device names can fail when any other type of network adapter is present in between or after the list of supported adapters in the newvg volume group. forcecopy: Copies the list of backup files (refer to -g flag) to the respective directories in the newly installed rootvg disks. Notes: The `forcecopy` option is applicable only with the -g flag. Do not use the `forcecopy` option for copying system-level files. The -g flag, without the `-F forcecopy` option, copies the backup files to the /home/padmin/backup_files directory in the newvg volume group. You must merge the contents of the backup 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 operation of the viosupgrade installation process is completed and the VIOS is booted from the newly installed rootvg disk. Notes: Details of the backup file are files 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 might 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 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.
-k	Specifies the script name that runs before the system configuration is restored. Note: You cannot use the -k flag with the -F `skiprestore` option. If there are dependencies that are associated with the pre_restore_script, you must ensure that those files or dependencies are copied to the newvg volume group by using the -g option or through the mount path that is mounted in the script. If a nonzero value is returned from the pre_restore_script, the upgrade operation exits with a failure message. You must resolve the issue and rerun the operation by using -o rerun option.
-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. If the VIOS belongs to a SSP cluster, the cluster services will be down until you reboot the VIOS. 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 running the viosupgrade command. restore: Specifies that the VIOS metadata configuration is restored when you run the viosupgrade command. Include the `-A args="<viosbr restore arguments>"` option with the viosupgrade command. Notes: To retrieve information about the backup file name that is created on old rootvg disk during viosupgrade command operation or to retrieve the status of the restore operation, run the `viosupgrade -l -q` command on the new rootvg disk. The VIOS might reboot during the restore process of virtual devices. rerun: Specifies to rerun the upgrade operation on the new rootvg disk. This option can be used when the pre-restore script (specified with the -k flag option while triggering viosupgrade command in oldvg disk) fails. You must re-run the upgrade operation by using this option after resolving the pre-restore script issues.
-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.
-X	Specifies the list of system files or configurations settings that must be excluded from the mksysb image installation. The following file types can be excluded: PROFILE: Indicates the /usr/ios/cli/.profile file. ROOTCRON: Indicates the root Cron tab entries. KSHRC: Indicates the home/padmin/.kshrc file. SSHKEY: Indicates the SSH keys that are used in the system files. PASSWD: Indicates the `padmin` password. ROOTUSRFS: Indicates the user file systems on the rootvg disk. TUNABLES: Indicates the /etc/tunables tunables.
-S	Provides the summary of the files that are migrated to the VIOS, if any. You must use the -q option with the -S flag.

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 time zone), 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. 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 then you must rename them.
Note: As a root user, you can run the alt_rootvg_op command to rename the volume groups before you install 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, ensure that at least one node is always active in the cluster and that must not be part of the upgrade process (single-node cluster upgrade operation is not allowed).
Note: For the SSP cluster configuration, the viosupgrade command can be run on only one node at a time. You cannot upgrade other nodes simultaneously.
If the viosupgrade command fails to restore all of the mappings, you must manually reinitiate 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 is at the location “/home/padmin/cfgbackups/” and prefixed with the hostname. For example: /home/padmin/cfgbackups/hostname_filename.tar.gz
If any additional software is already installed 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, 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 must 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 the 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 this command is run.
To copy files from the current rootvg disk to the respective directories of a newly installed rootvg disk, 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 copy system-specific files like /etc/group 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
```
Ensure that you merge the contents of the /etc/group file from the /home/padmin/backup_files directory to the /etc/group file in the new rootvg volume group.
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 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.
To run a script before the restore process of virtual devices on the new rootvg disk, type the following command:
```
viosupgrade -l -i mymksysbA -a hdisk1:hdisk2 -k <pre_restore_binary>
```
Where, mymksysbA is the name of the image and hdisk1 & hdisk2 are the new rootvg disks. The pre_restore_script is the script that must be run.
To rerun the upgrade operation after restoring the pre_restore script on the new rootvg disk, type the following command:
```
viosupgrade –o rerun
```

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.