$ ansible-doc -t module cisco.sccfm.list_ftd_not_on_version
> MODULE cisco.sccfm.list_ftd_not_on_version (sccfm-ansible/plugins/modules/list_ftd_not_on_version.py)
Queries FTD devices managed by SCC Firewall Manager and returns only
those that are NOT currently running the specified or recommended
software version.
Use `version' to check against a specific version string, or
`recommended' to check each device against its Cisco-suggested
upgrade version.
Devices can be filtered by a Lucene query or by specifying a list of
UIDs. If neither is provided, all FTD devices are checked.
In `version' mode, comparison is performed client-side against the
`softwareVersion' field returned by the inventory API.
In `recommended' mode, the compatible-versions API is called per
device to determine the suggested version.
OPTIONS (= indicates it is required):
- api_token API token for SCCFM.
set_via:
env:
- name: SCCFM_API_TOKEN
default: null
no_log: true
type: str
- limit Maximum number of devices to fetch when using `query' or no
filter.
Ignored when using `uids'.
default: 50
type: int
- offset Pagination offset when using `query' or no filter.
Ignored when using `uids'.
default: 0
type: int
- query Lucene query to narrow the set of FTD devices to check.
Mutually exclusive with `uids'.
The query is automatically combined with FTD device type
filters.
If omitted, all FTD devices are checked.
default: null
type: str
- recommended When true, check each device against its
Cisco-recommended (suggested) upgrade version instead
of a fixed version string.
Mutually exclusive with `version'.
default: false
type: bool
- region SCCFM region (int, us, eu, apj, au, uae, in, or ci).
set_via:
env:
- name: SCCFM_REGION
default: null
type: str
- uids List of device UIDs to check.
Mutually exclusive with `query'.
If omitted, all FTD devices are checked (or those matching
`query').
default: null
elements: str
type: list
- version The target software version to check against (e.g.
`7.4.1').
Devices NOT running this exact version will be returned.
Mutually exclusive with `recommended'.
default: null
type: str
AUTHOR: Cisco SCCFM Team
EXAMPLES:
# Example 1: List all FTDs not on a specific version
- name: Find FTDs not on 7.4.1
cisco.sccfm.list_ftd_not_on_version:
version: "7.4.1"
region: "{{ sccfm_region }}"
api_token: "{{ sccfm_api_token }}"
register: result
- name: Show devices that need upgrading
ansible.builtin.debug:
msg: "{{ item.name }} is on {{ item.software_version }}"
loop: "{{ result.devices }}"
# Example 2: Check against the recommended version
- name: Find FTDs not on recommended version
cisco.sccfm.list_ftd_not_on_version:
recommended: true
register: result
- name: Show non-compliant devices
ansible.builtin.debug:
msg: "{{ item.name }} is on {{ item.software_version }}, recommended: {{ item.recommended_version }}"
loop: "{{ result.devices }}"
# Example 3: Filter by name pattern
- name: Find branch FTDs not on 7.4.1
cisco.sccfm.list_ftd_not_on_version:
version: "7.4.1"
query: "name:branch-*"
register: result
# Example 4: Using module_defaults (recommended)
- name: Identify devices needing upgrade
hosts: localhost
gather_facts: false
module_defaults:
group/cisco.sccfm.all:
region: "{{ sccfm_region }}"
api_token: "{{ sccfm_api_token }}"
tasks:
- name: Find FTDs not on target version
cisco.sccfm.list_ftd_not_on_version:
version: "7.4.1"
register: result
- name: Fail if any devices are not on target version
ansible.builtin.fail:
msg: "{{ result.device_count }} device(s) not on target version"
when: result.device_count > 0
RETURN VALUES:
- device_count Number of devices not on the specified or recommended
version.
returned: success
type: int
- devices List of FTD devices that are NOT running the specified or
recommended version.
elements: dict
returned: success
type: list
contains:
- config_state The device configuration state.
type: str
- connectivity_state The device connectivity state.
type: str
- name The device name.
type: str
- recommended_version The Cisco-recommended version for this
device (only in recommended mode).
type: str
- software_version The current software version running on
the device.
type: str
- uid The UID of the device.
type: str
- matched_device_count Number of FTD devices matched before version
comparison.
returned: success
type: int
- mode The evaluation mode used (`specified' or `recommended').
returned: success
type: str
- skipped Devices that could not be evaluated (only in recommended
mode).
returned: success (recommended mode only, when devices were skipped)
type: dict