cisco.nxos.nxos_gir module – Trigger a graceful removal or insertion (GIR) of the switch.

Note

This module is part of the cisco.nxos collection (version 4.4.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install cisco.nxos.

To use it in a playbook, specify: cisco.nxos.nxos_gir.

New in cisco.nxos 1.0.0

Synopsis

  • Trigger a graceful removal or insertion (GIR) of the switch.

  • GIR processing may take more than 2 minutes. Timeout settings are automatically extended to 200s when user timeout settings are insufficient.

Note

This module has a corresponding action plugin.

Parameters

Parameter

Comments

state

string

Specify desired state of the resource.

Choices:

  • "present" ← (default)

  • "absent"

system_mode_maintenance

boolean

When system_mode_maintenance=true it puts all enabled protocols in maintenance mode (using the isolate command). When system_mode_maintenance=false it puts all enabled protocols in normal mode (using the no isolate command).

Choices:

  • false

  • true

system_mode_maintenance_dont_generate_profile

boolean

When system_mode_maintenance_dont_generate_profile=true it prevents the dynamic searching of enabled protocols and executes commands configured in a maintenance-mode profile. Use this option if you want the system to use a maintenance-mode profile that you have created. When system_mode_maintenance_dont_generate_profile=false it prevents the dynamic searching of enabled protocols and executes commands configured in a normal-mode profile. Use this option if you want the system to use a normal-mode profile that you have created.

Choices:

  • false

  • true

system_mode_maintenance_on_reload_reset_reason

string

Boots the switch into maintenance mode automatically in the event of a specified system crash. Note that not all reset reasons are applicable for all platforms. Also if reset reason is set to match_any, it is not idempotent as it turns on all reset reasons. If reset reason is match_any and state is absent, it turns off all the reset reasons.

Choices:

  • "hw_error"

  • "svc_failure"

  • "kern_failure"

  • "wdog_timeout"

  • "fatal_error"

  • "lc_failure"

  • "match_any"

  • "manual_reload"

  • "any_other"

  • "maintenance"

system_mode_maintenance_shutdown

boolean

Shuts down all protocols, vPC domains, and interfaces except the management interface (using the shutdown command). This option is disruptive while system_mode_maintenance (which uses the isolate command) is not.

Choices:

  • false

  • true

system_mode_maintenance_timeout

string

Keeps the switch in maintenance mode for a specified number of minutes. Range is 5-65535.

Notes

Note

  • Tested against NXOSv 7.3.(0)D1(1) on VIRL

  • Unsupported for Cisco MDS

  • state has effect only in combination with system_mode_maintenance_timeout or system_mode_maintenance_on_reload_reset_reason.

  • Using system_mode_maintenance and system_mode_maintenance_dont_generate_profile would make the module fail, but the system mode will be triggered anyway.

  • For information on using CLI and NX-API see the :ref:`NXOS Platform Options guide <nxos_platform_options>`

  • For more information on using Ansible to manage network devices see the :ref:`Ansible Network Guide <network_guide>`

  • For more information on using Ansible to manage Cisco devices see the `Cisco integration page <https://www.ansible.com/integrations/networks/cisco>`_.

Examples

# Trigger system maintenance mode
- cisco.nxos.nxos_gir:
    system_mode_maintenance: true
    host: '{{ inventory_hostname }}'
    username: '{{ un }}'
    password: '{{ pwd }}'
# Trigger system normal mode
- cisco.nxos.nxos_gir:
    system_mode_maintenance: false
    host: '{{ inventory_hostname }}'
    username: '{{ un }}'
    password: '{{ pwd }}'
# Configure on-reload reset-reason for maintenance mode
- cisco.nxos.nxos_gir:
    system_mode_maintenance_on_reload_reset_reason: manual_reload
    state: present
    host: '{{ inventory_hostname }}'
    username: '{{ un }}'
    password: '{{ pwd }}'
# Add on-reload reset-reason for maintenance mode
- cisco.nxos.nxos_gir:
    system_mode_maintenance_on_reload_reset_reason: hw_error
    state: present
    host: '{{ inventory_hostname }}'
    username: '{{ un }}'
    password: '{{ pwd }}'
# Remove on-reload reset-reason for maintenance mode
- cisco.nxos.nxos_gir:
    system_mode_maintenance_on_reload_reset_reason: manual_reload
    state: absent
    host: '{{ inventory_hostname }}'
    username: '{{ un }}'
    password: '{{ pwd }}'
# Set timeout for maintenance mode
- cisco.nxos.nxos_gir:
    system_mode_maintenance_timeout: 30
    state: present
    host: '{{ inventory_hostname }}'
    username: '{{ un }}'
    password: '{{ pwd }}'
# Remove timeout for maintenance mode
- cisco.nxos.nxos_gir:
    system_mode_maintenance_timeout: 30
    state: absent
    host: '{{ inventory_hostname }}'
    username: '{{ un }}'
    password: '{{ pwd }}'

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

changed

boolean

check to see if a change was made on the device

Returned: always

Sample: true

final_system_mode

string

describe the last system mode

Returned: verbose mode

Sample: "normal"

updates

list / elements=string

commands sent to the device

Returned: verbose mode

Sample: ["terminal dont-ask", "system mode maintenance timeout 10"]

Authors

  • Gabriele Gerbino (@GGabriele)