nim_backup – Uses NIM to manage backup of LPAR or VIOS clients.

Synopsis

Performs backup operations through the Network Installation Management (NIM) to create, list and view and restore backup image on LPAR and VIOS clients.

Defines mksysb or ios_backup resources on the NIM master depending on the type of the client.

Lists the mksysb or ios_backup resources available on the NIM master and allows to filter results.

Uses the NIM BOS installation operation to mksysb backup images on clients.

Uses the NIM viosbr operation to restore VIOS configuration ios_backup on clients.

Requirements

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

  • AIX >= 7.1 TL3

  • Python >= 3.6

  • Privileged user with authorizations: aix.system.install,aix.system.nim.config.server

Parameters

action (True, str, None)

Specifies the action to perform.

create performs a backup operation on targets trough the NIM master.

restore restores a backup on targets trough the NIM master.

view displays the content of a VIOS backup, only for type=backup.

list lists backups for targets on the NIM master.

type (optional, str, mksysb)

Specifies the type of backup object to operate.

mksysb specifies to operate on installable BOS backup image of the operating system (that is the root volume group) of a LPAR target.

ios_mksysb specifies to operate on installable BOS backup image of the operating system (that is, the root volume group) of a VIOS target.

ios_backup specifies to operate on virtual and logical configuration backup image of VIOS target; that is all the relevant data to recover VIOS after a fresh installation.

savevg specifies to operate volume group files backup image of LPAR target; that is not installable.

It parameter is discarded for action=view as the view action only applies to ios_backup.

targets (False, list, None)

Specifies the NIM clients to perform the action on.

foo* specifies all the NIM clients with name starting by foo.

foo[2:4] specifies the NIM clients among foo2, foo3 and foo4.

* or ALL specifies all the NIM clients.

vios or standalone specifies all the NIM clients of this type.

Required when action=create and action=restore.

When action=list it filters the results on the source_image attribute of the NIM resource.

location (optional, path, None)

Specifies the location of the backup files.

When type=mksysb, the default value is location=/export/nim/mksysb.

When type=ios_mksysb, the default value is location=/export/nim/ios_mksysb.

When type=ios_backup, the default value is location=/export/nim/ios_backup.

When type=savevg, the default value is location=/export/nim/savevg.

name (optional, str, None)

Specifies the exact name of the backup NIM resource to act on.

When action=list it filters the results on the name of the NIM resource.

Required when action=view and when action=create and type=savevg.

name_prefix (optional, str, None)

Prefix of the backup NIM resource name to act on.

The name format will be <name_prefix><target_name><name_postfix>.

Used only when name is not specified.

When action=list it filters the results on the name of the NIM resource.

name_postfix (optional, str, None)

Specifies the postfix of the backup NIM resource name to act on.

The name format will be <name_prefix><target_name><name_postfix>.

Used only when name is not specified.

When action=list it filters the results on the name of the NIM resource.

When type=mksysb or type=ios_mksysb, the default value is name_postfix=_sysb.

When type=ios_backup, the default value is name_postfix=_iosb.

When type=savevg, the default value is name_postfix=_svg.

group (optional, str, None)

Specifies the resource group used to install the BOS backup image on a client.

Can be used on a standalone client when action=restore and type=mksysb or ios_mksysb.

spot_name (optional, str, None)

Specifies the exact SPOT resource name used to install the BOS backup image on a client.

When the SPOT resource exists, it is used; otherwise it creates it pior to run BOS install.

Can be used on a standalone client when action=restore and type=mksysb or ios_mksysb.

spot_prefix (optional, str, None)

Specifies the prefix of SPOT resource name used to install the BOS backup image on a client.

When the SPOT resource exists, it is used; otherwise it creates it pior to run BOS install.

The SPOT name format will be <spot_prefix><target_name><spot_postfix>.

Used only when spot_name is not specified.

Can be used on a standalone client when action=restore and type=mksysb or ios_mksysb.

spot_postfix (optional, str, _spot)

Specifies the postfix of SPOT resource name used to install the BOS backup image on a client.

When the SPOT resource exists, it is used; otherwise it creates it pior to run BOS install.

The SPOT name format will be <spot_prefix><target_name><spot_postfix>.

Used only when spot_name is not specified.

Can be used on a standalone client when action=restore and type=mksysb or ios_mksysb.

spot_location (optional, path, /export/nim/spot)

Specifies the location of SPOT resource on the NIM master used to install the BOS backup image on a client. created to restore the backup on a standalone client.

When the SPOT resource does not exist, it is created that this location.

Can be used on a standalone client when action=restore and type=mksysb or ios_mksysb.

bosinst_data (optional, str, None)

Specifies the bosinst_data NIM resource name to install the BOS backup image on a client.

This allows running “non-prompted” installations, and so more automated restorations.

If not specified you will be presented with a series of choices on the console.

Can be used when action=restore and type=mksysb or ios_mksysb.

oslevel (optional, str, None)

Specifies the oslevel to filter results when listing backup images.

Can be used when action=list.

volume_group (optional, str, None)

Specifies the volume group to backup on the target.

This volume group must be varied-on and the file systems must be mounted.

Required when action=create and type=savevg.

exclude_files (optional, str, None)

Specifies the exclude_files NIM resource name to create a backup image.

It represents a file that contains a list of files and directories that should be excluded from the creation.

Can be used when action=create and type=savevg.

flags (optional, str, None)

Specifies additional flags to pass to the command used.

Refer to IBM documentation for details.

For action=create and type=mksysb, you could use -a -A -b -e -i -m -p -P -T -V -X -Z.

For action=create and type=ios_mksysb, you could use -nosvg -nomedialib.

For action=create and type=savevg, you could use -a -A -e -i -m -p -r -T -v -V -X -Z.

other_attributes (optional, str, None)

Specifies additional attributes to pass to the NIM operation.

Refer to IBM documentation for details.

It is a space separated string such as other_attributes=’-a attr1=value1 -a attr2=value2’.

Discarded when action=list.

remove_spot (optional, bool, True)

Specifies to remove the SPOT resource after the restoration of the backup image.

The preexistence of the SPOT resource does not condition its removal.

The SPOT resource is not removed when the restore operation fails or in check mode.

Can be used on a standalone client when action=restore.

remove_backup (optional, bool, False)

Specifies to remove the backup resource after the restoration of the backup image.

The preexistence of the backup resource does not condition its removal.

The backup resource is not removed when the restore operation fails or in check mode.

Can be used when action=restore.

accept_licenses (optional, bool, True)

Specifies to automatically accept all licenses while installing the BOS backup image.

Can be used when action=restore and type=mksysb or ios_mksysb.

boot_target (optional, bool, True)

Specifies to boot the NIM client after installing the BOS backup image.

Can be used when action=restore and type=mksysb or ios_mksysb.

shrink_fs (optional, bool, False)

Specifies to shrink the file system contained in the volume group.

Always be sure to check the size of the file systems after the restore is complete.

Can be used when action=restore and type=savevg.

nim_node (optional, dict, None)

Allows to pass along NIM node info from a previous task to another so that it discovers NIM info only one time for all tasks. The current task might update the NIM info it needs.

Notes

Note

Examples

- name: List mksysb targeting nimclient1 at a specific level and name starting with ansible
  nim_backup:
    action: list
    targets: nimclient1
    oslevel: "7200-03-02"
    name_prefix: ansible

- name: Create a mksysb backup of a LPAR
  nim_backup:
    action: create
    targets: nimclient1
    name_postfix: _mksysb

- name: Restore a mksysb backup on a LPAR
  nim_backup:
    action: restore
    targets: nimclient1
    name_postfix: _mksysb
    spot_postfix: _spot
    remove_backup: true
    remove_spot: true
    boot_target: false
    accept_licenses: true

- name: Backup a VIOS configuration
  nim_backup:
    action: create
    type: ios_backup
    targets: vios1
    name_postfix: _iosbackup

- name: Get the backup configuration of a VIOS
  nim_backup:
    action: view
    targets: vios1

- name: Restore the backup configuration on a VIOS
  nim_backup:
    action: restore
    type: ios_backup
    targets: vios1
    name_postfix: _iosbackup

- name: Check the size to create a savevg image of the datavg
  nim_backup:
    action: create
    type: savevg
    targets: nimclient1
    name_postfix: _savevg
    volume_group: datavg
    exclude_files: my_exclude_file_res
    other_attributes: '-a comments="datavg savevg" -a verbose=yes'
  check_mode: true

- name: Restore a savevg image to a different disk on a LPAR
  nim_backup:
    action: restore
    type: savevg
    targets: nimclient1
    name: nimclient1_savevg
    remove_backup: true
    shrink_fs: true
    other_attributes: '-a disk=hdisk1 -a verbose=yes'

Return Values

msg (always, str, )

Status information.

targets (always, list, [‘nimclient01’, ‘nimclient02’, ‘…’])

List of NIM client actually targeted for the operation.

status (always, dict, { nimclient01: ‘SUCCESS’, nimclient02: ‘FAILURE’ })

Status of the operation for each target. It can be empty, SUCCESS or FAILURE.

<target> (when target is actually a NIM client, str, SUCCESS)

Status of the execution on the <target>.

backup_info (if I(action=list), dict, {‘backup_info’: {‘ansible_img’: {‘Rstate’: ‘ready for use’, ‘alloc_count’: ‘0’, ‘arch’: ‘power’, ‘class’: ‘resources’, ‘creation_date’: ‘Mon Feb 3 20:55:28 2020’, ‘location’: ‘/export/nim/mksysb/ansible.sysb’, ‘mod’: ‘3’, ‘oslevel_r’: ‘7200-03’, ‘oslevel_s’: ‘7200-03-02-1845’, ‘prev_state’: ‘unavailable for use’, ‘release’: ‘2’, ‘server’: ‘master’, ‘source_image’: ‘nimclient01’, ‘type’: ‘mksysb’, ‘version’: ‘7’}, ‘nimclient2_sysb’: {‘class’: ‘resources’, ‘type’: ‘mksysb’, ‘creation_date’: ‘Sun May 3 15:54:44 2020’, ‘source_image’: ‘nimclient2’, ‘arch’: ‘power’, ‘Rstate’: ‘ready for use’, ‘prev_state’: ‘unavailable for use’, ‘location’: ‘/export/nim/mksysb/nimclient2_ansible.sysb’, ‘version’: ‘7’, ‘release’: ‘2’, ‘mod’: ‘3’, ‘oslevel_r’: ‘7200-03’, ‘oslevel_s’: ‘7200-03-04-1938’, ‘alloc_count’: ‘0’, ‘server’: ‘master’}}})

The backup NIM resource information.

<backup_name> (, dict, )

Detailed information on the NIM resource.

<attribute> (, str, )

attribute of the <backup_name> resource

nim_node (always, dict, {‘nim_node’: {‘standalone’: {‘nimclient01’: {‘Cstate’: ‘ready for a NIM operation’, ‘Cstate_result’: ‘success’, ‘Mstate’: ‘currently running’, ‘cable_type1’: ‘N/A’, ‘class’: ‘machines’, ‘comments’: ‘object defined using nimquery -d’, ‘connect’: ‘nimsh’, ‘cpuid’: ‘00F600004C00’, ‘if1’: ‘master_net nimclient01.aus.stglabs.ibm.com AED8E7E90202 ent0’, ‘installed_image’: ‘ansible_img’, ‘mgmt_profile1’: ‘p8-hmc 2 nimclient-cec nimclient-vios1’, ‘netboot_kernel’: ‘64’, ‘platform’: ‘chrp’, ‘prev_state’: ‘customization is being performed’}}, ‘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’}}}})

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

standalone (always, dict, )

List of standalone NIM resources.

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

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

Detailed information on the execution on the target.

messages (always, list, )

Details on errors/warnings

res_name (if I(success=True), str, )

Name of the NIM resource created.

If action=backup it is the name of the backup resource.

If action=restore and the target is a standalone machine, then it is the name of the SPOT resource.

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

Standard output of the last command.

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

Standard error of the last command.

Status

  • This module is not guaranteed to have a backwards compatible interface. [preview]

  • This module is maintained by community.

Authors

  • AIX Development Team (@pbfinley1911)