_nim_upgradeios – Use NIM to update a single or a pair of Virtual I/O Servers.

Synopsis

Uses the NIM to perform upgrade to Virtual I/O Server (VIOS) targets tuple.

Checks status of previous operation if provided before running its operations.

VIOSes of a tuple must be on the same cluster and the node states must be OK.

When upgrading VIOSes pair, it checks the cluster state, stop it before installing the VIOS, and restart it after installation.

Requirements

The below requirements are needed on the host that executes this module.

• AIX >= 7.1 TL3

• Python >= 3.6

Parameters

action (optional, str, migrate)

Specifies the operation to perform on the target VIOSes.

migrate to use migvios NIM operation to migrate the system software.

viosupgrade to use the viosupgrade command to upgrade. Not supported yet.

targets (True, list, None)

Specifies the list of VIOSes NIM targets to update.

You can specify a list of a VIOS to update alone, or two VIOSes to update as a couple. There are called tuple.

time_limit (optional, str, None)

Before starting the action on a VIOS tuple, the actual date is compared to this parameter value; if it is greater then the task is stopped.

The format is mm/dd/yyyy hh:mm.

The resulting status for tuples in this case will be SKIPPED-TIMEOUT.

mksysb_name (optional, str, None)

Specifies the NIM mksysb resource name that will provide the system backup image created using the mksysb command.

Can be used with action=migrate.

mksysb_prefix (optional, str, None)

Prefix of the NIM mksysb resource.

The name format will be <prefix><target_name><postfix>.

Used only if mksysb_name is not specified.

Can be used with action=migrate.

mksysb_postfix (optional, str, None)

Postfix of the NIM mksysb resource.

The name format will be <prefix><target_name><postfix>.

Used only if mksysb_name is not specified.

Can be used with action=migrate.

backup_name (optional, str, None)

Specifies the NIM ios_backup resource name that will provide the VIOS backup configuration created using the viosbr command.

Can be used with action=migrate.

backup_prefix (optional, str, None)

Prefix of the NIM ios_backup resource.

The name format will be <prefix><target_name><postfix>.

Used only if backup_name is not specified.

Can be used with action=migrate.

backup_postfix (optional, str, None)

Postfix of the NIM ios_backup resource.

The name format will be <prefix><target_name><postfix>.

Used only if backup_name is not specified.

Can be used with action=migrate.

spot_name (optional, str, None)

Specifies the NIM Shared product Object Tree (SPOT) resource name that is a fundamental resource in the NIM environment.

It is required to install or initialize all types of machine configurations.

It provides a /usr file system for diskless and dataless clients, as well as the network boot support for all clients.

Can be used with action=migrate.

spot_prefix (optional, str, None)

Prefix of the NIM SPOT resource.

The name format will be <prefix><target_name><postfix>.

Used only if spot_name is not specified.

Can be used with action=migrate.

spot_postfix (optional, str, None)

Postfix of the NIM SPOT resource.

The name format will be <prefix><target_name><postfix>.

Used only if spot_name is not specified.

Can be used with action=migrate.

lpp_source (optional, str, None)

Specifies the NIM lpp_source resource that will provide the minimum set of support images required for the BOS installation.

Can be used with action=migrate.

bosinst_data (optional, str, None)

Specifies the NIM bosinst_data resource that contains information for the BOS installation program.

Installation information is specified in a NIM resource prior to the installation to prevent the need for prompting at the console.

If not provided, missing information must be specified manually for the BOS installation to proceed.

Can be used with action=migrate.

resolv_conf (optional, str, None)

Specifies the NIM bosinst_data resource that contains valid /etc/resolv.conf entries that define Domain Name Protocol name-server information for local resolver routines.

Can be used with action=migrate.

image_data (optional, str, None)

Specifies the NIM image_data resource that contains information for the BOS installation program.

It describes how physical disks and file systems should be configured in the root volume group during installation.

Can be used with action=migrate.

log (optional, str, None)

TODO document log parameter.

Can be used with action=migrate.

file_resource (optional, str, None)

TODO document file_resource parameter.

Can be used with action=migrate.

group (optional, str, None)

Specifies the NIM resource group that contains NIM resources.

Can be used with action=migrate.

disk (optional, str, None)

Specifies the disk to migrate the VIOS to.

Can be used with action=migrate.

cluster (optional, str, None)

Specifies the name of the cluster the VIOS is a member of.

Can be used with action=migrate.

current_database (optional, str, None)

Specifies the VIOS current database name.

Can be used with action=migrate.

command_flags (optional, str, None)

Specifies additional flags to pass to the command.

Can be used with action=migrate.

viosbr_flags (optional, str, None)

Specifies additional flags to pass to the viosbr command.

Can be used with action=migrate.

mk_image (optional, bool, False)

Specifies to create the system backup image (mksysb) and create the NIM resource.

Can be used with action=migrate.

boot_client (optional, bool, False)

Specifies to boot the NIM client after the operation.

Can be used with action=migrate.

set_boot_list (optional, bool, False)

Specifies to set the boot list on the NIM client.

Can be used with action=migrate.

concurrent (optional, bool, False)

Specifies the upgrade operation can be run in parallel on NIM clients.

Can be used with action=migrate.

manage_cluster (optional, bool, True)

Specifies to manage the cluster if the NIM client is part of one.

Can be used with action=migrate.

debug (optional, bool, False)

Specifies the operation to execute in debug mode that is more verbose.

Can be used with action=migrate.

vios_status (optional, dict, None)

Specifies the result of a previous operation.

If set then the vios_status of a target tuple must contain SUCCESS to attempt update.

If no vios_status value is found for a tuple, then returned status for this tuple is set to SKIPPED-NO-PREV-STATUS.

nim_node (optional, dict, None)

Allows to pass along NIM node info from a task to another so that it discovers NIM info only one time for all tasks.

Notes

Note

• Debug on NIM master could be done using the following command nim -o showlog -a full_log=yes -a log_type=script vios_target

Examples

- name: Perform a backup of nimvios01
  _nim_upgradeios:
    targets: "(nimvios01)"
    action: backup

Return Values

msg (always, str, NIM upgradeios operation completed. See status and meta for details.)

The execution message.

targets (always, list, [‘vios1’, ‘vios2, vios3’, ‘…’])

List of VIOSes actually targeted for the operation.

stdout (If the command was run., str, )

Standard output of the command.

stderr (If the command was run., str, )

Standard error of the command.

status (always, dict, {‘status’: {‘vios1-vios2’: ‘SUCCESS-UPGR2’, ‘vios3’: ‘SUCCESS-ALTDC’, ‘vios4-vios5’: ‘FAILURE-CLUSTER’, ‘vios6’: ‘FAILURE-UPGR1-INIT’, ‘vios7-vios8’: ‘SKIPPED-TIMEOUT’}})

Status of the execution on each target <tuple>.

If the operation status is not avalaible, the vios_status passed in parameter is returned.

<tuple> (when tuple are actually a NIM client., str, SUCCESS-UPGR2)

Status of the execution on the <tuple>.

The <tuple> elements are sorted to form the key of the dictionary.

Previous vios_status when the tuple status does not contains SUCCESS.

SKIPPED-NO-PREV-STATUS when no vios_status value is found for the tuple.

SUCCESS-UPGR1 when upgrade of first VIOS of the tuple succeeded.

SUCCESS-UPGR2 when upgrade of second VIOS of the tuple succeeded.

SKIPPED-TIMEOUT when the time_limit is reached before updating the 1st VIOS of the tuple.

FAILURE-CLUSTER when cluster checks or operation failed.

FAILURE-UPGR1-INIT when upgrade of first VIOS of the tuple failed to start.

FAILURE-UPGR2-INIT when upgrade of second VIOS of the tuple failed to start.

FAILURE-UPGR1-WAIT when an error occured waiting for the upgrade of first VIOS of the tuple to complete.

FAILURE-UPGR2-WAIT when an error occured waiting for the upgrade of second VIOS of the tuple to complete.

FAILURE-UPGR1 when upgrade of first VIOS of the tuple failed.

FAILURE-UPGR2 when upgrade of second VIOS of the tuple failed.

nim_node (always, dict, {‘nim_node’: {‘vios’: {‘vios1’: {‘Cstate’: ‘ready for a NIM operation’, ‘Cstate_result’: ‘success’, ‘Mstate’: ‘currently running’, ‘cable_type1’: ‘N/A’, ‘class’: ‘management’, ‘connect’: ‘nimsh’, ‘cpuid’: ‘00F600004C00’, ‘if1’: ‘master_net vios1.aus.stglabs.ibm.com 0’, ‘mgmt_profile1’: ‘p8-hmc 1 vios-cec’, ‘netboot_kernel’: ‘64’, ‘platform’: ‘chrp’, ‘prev_state’: ‘alt_disk_install operation is being performed’, ‘hostname’: ‘vios1.aus.stglabs.ibm.com’, ‘cluster’: {‘vios1’: {‘repos_state’: ‘’, ‘state’: ‘DOWN’}, ‘vios2’: {‘repos_state’: ‘OK’, ‘state’: ‘OK’}, ‘name’: ‘mycluster’, ‘nodes’: [‘vios1’, ‘vios2’], ‘state’: ‘DEGRADED’}}}}})

NIM node info. It can contains more information if passed as option nim_node.

vios (always, dict, )

List of VIOS NIM resources.

meta (always, dict, )

Detailed information on the module execution.

messages (always, list, see below)

Details on errors/warnings not related to a specific tuple.

<tuple> (when target is actually a NIM client, dict, )

Detailed information on the execution on the target tuple.

messages (always, list, )

Details on errors/warnings.

<vios> (when target is actually a NIM client., dict, )

updateios information for a specific vios.

cmd (If the command was run., str, )

Command exectued.

stdout (If the command was run., str, )

Standard output of the command.

stderr (If the command was run., str, )

Standard error of the command.

Status

• This module is . [deprecated]

• This module is maintained by community.

Authors

• AIX Development Team (@pbfinley1911)