### Execute Command in System Context

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_command_module.md

This example shows how to execute a command in the system context of the ASA device.

```yaml
- name: Run commands in system context
  cisco.asa.asa_command:
    commands:
      - show contexts
    context:
      system
```

--------------------------------

### Execute Multiple Show Commands

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_command_module.md

This example shows how to execute multiple show commands concurrently using the asa_command module.

```yaml
- name: Show multiple commands
  cisco.asa.asa_command:
    commands:
      - show asp drop
      - show memory
      - show interfaces
```

--------------------------------

### Gather All Facts

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_facts_module.md

This example shows how to gather all available facts, including network resources. Collected facts are available in `ansible_facts`.

```yaml
- name: Gather all available facts
  cisco.asa.asa_facts:
    gather_subset: all
    gather_network_resources: all

- name: Display collected facts
  debug:
    var: ansible_facts
```

--------------------------------

### Execute a Single Show Command

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_command_module.md

This example demonstrates how to use the asa_command module to execute a single 'show version' command on a Cisco ASA device.

```yaml
- name: Show the ASA version
  cisco.asa.asa_command:
    commands:
      - show version
```

--------------------------------

### Execute Command in a Specific Context

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_command_module.md

This example demonstrates how to run a command within a specific administrative context on the ASA device.

```yaml
- name: Run commands in specific context
  cisco.asa.asa_command:
    commands:
      - show running-config
    context:
      admin_ctx
```

--------------------------------

### Execute Command and Wait for Device Status

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_command_module.md

This example executes 'show version' and waits for the output to contain a specific phrase indicating the device is operational, with custom retry settings.

```yaml
- name: Check device is running configuration
  cisco.asa.asa_command:
    commands:
      - show version
    wait_for:
      - result[0] contains "up for"
    retries:
      5
    interval:
      2
```

--------------------------------

### Jinja2 Configuration Template Example

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_config_module.md

Demonstrates using a Jinja2 template to generate ASA configuration. Supports dynamic variable insertion for interface settings and ACL ports.

```jinja2
! Configure inside interface
interface ethernet 0/0
  nameif inside
  ip address {{ inside_ip }} {{ inside_mask }}
  no shutdown

! Configure ACL
access-list acl_https
{% for port in https_ports %}
  permit tcp any any eq {{ port }}
{% endfor %}
```

--------------------------------

### get

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/cliconf_plugin.md

Sends a specified command to the device and retrieves the output. Supports optional parameters for prompt matching and answer, and controlling command sending behavior.

```APIDOC
## get(command, prompt=None, answer=None, sendonly=False, newline=True, check_all=False)

### Description
Sends a command and retrieves output.

### Method
`get`

### Parameters
#### Query Parameters
- **command** (string) - Required - Command to execute
- **prompt** (string) - Optional - Expected prompt pattern (regex)
- **answer** (string) - Optional - Answer for prompt (if expected)
- **sendonly** (boolean) - Optional - Send command without reading response
- **newline** (boolean) - Optional - Append newline to command
- **check_all** (boolean) - Optional - Check all prompts before processing

### Returns
string with command output

### Raises
AnsibleConnectionFailure on connection error
```

--------------------------------

### Execute Command and Wait for Specific Output

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_command_module.md

This example sends a ping command and waits for the output to indicate 100% success, with a limited number of retries.

```yaml
- name: Send repeat pings and wait for 100% success
  cisco.asa.asa_command:
    commands:
      - ping 8.8.8.8 repeat 20 size 350
    wait_for:
      - result[0] contains 100%
    retries:
      2
```

--------------------------------

### Configure ASA with Specific Commands

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/cliconf_plugin.md

Example of configuring an access list on an ASA device using the `asa_config` module. This demonstrates how configuration commands are sent to the device.

```yaml
---
- name: Load configuration via cliconf
  hosts: asa
  connection: ansible.netcommon.network_cli
  
  tasks:
    - name: Configure access list
      cisco.asa.asa_config:
        lines:
          - permit ip any any
        parents:
          - access-list acl_test
```

--------------------------------

### Execute Command with Multiple 'any' Match Conditions

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_command_module.md

This example checks the failover status, waiting for the output to contain either 'Active' or 'Standby', with a limited number of retries.

```yaml
- name: Check status with any condition matching
  cisco.asa.asa_command:
    commands:
      - show failover
    wait_for:
      - result[0] contains "Active"
      - result[0] contains "Standby"
    match:
      any
    retries:
      2
```

--------------------------------

### Authentication Failure Example

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/errors.md

Indicates an issue with user credentials or insufficient privilege levels. Ensure `ansible_user` and `ansible_password` are correct.

```text
FAILED! => {
    "msg": "Authentication failure"
}
```

--------------------------------

### Install Cisco ASA Collection via requirements.yml

Source: https://github.com/ansible-collections/cisco.asa/blob/main/README.md

Include the Cisco ASA collection in a `requirements.yml` file for automated installation. This method is useful for managing collection dependencies.

```yaml
---
collections:
  - name: cisco.asa
```

--------------------------------

### Get Defaults and Include Passwords

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_config_module.md

Retrieves default configurations for an interface and includes sensitive password information in the configuration commands.

```yaml
- name: Get all defaults
  cisco.asa.asa_config:
    lines:
      - ip address 192.168.1.1 255.255.255.0
    defaults: true
    parents:
      - interface ethernet 0/0

- name: Include passwords in config
  cisco.asa.asa_config:
    lines:
      - pre-shared-key mysecretkey
    parents:
      - crypto ikev2 policy 1
    passwords: true
```

--------------------------------

### Configure User Object Groups

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_ogs_module.md

Example of configuring user object groups, specifying user names and their domains. The `state` parameter is set to `merged`.

```yaml
- name: Configure user object groups
  cisco.asa.asa_ogs:
    config:
      - object_type: user
        object_groups:
          - name: test_og_user
            description: Test users
            user_object:
              user:
                - name: new_user_1
                  domain: LOCAL
                - name: new_user_2
                  domain: LOCAL
    state: merged

```

--------------------------------

### Get ASA Configuration

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/cliconf_plugin.md

Retrieves either the running or startup configuration from an ASA device. Requires enable mode.

```python
@enable_mode
def get_config(self, source="running", flags=None, format="text"):
    if source not in ("running", "startup"):
        return self.invalid_params(
            "fetching configuration from %s is not supported" % source,
        )
    if source == "running":
        cmd = "show running-config all"
    else:
        cmd = "show startup-config"
    return self.send_command(cmd)
```

--------------------------------

### Execute Command with Multiple 'all' Match Conditions

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_command_module.md

This example checks an interface's status by ensuring the output matches a regex and contains a specific string, requiring all conditions to be met.

```yaml
- name: Check interface status with multiple conditions
  cisco.asa.asa_command:
    commands:
      - show interface ethernet 0/0
    wait_for:
      - result[0] matches ".*up.*up.*"
      - result[0] contains "Internet address"
    match:
      all
    retries:
      3
```

--------------------------------

### Configuration Not Saved Resolution

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/errors.md

This example demonstrates how to ensure configuration changes are saved to the startup-config using the `asa_config` module. Set `save: true` and `save_when: changed` to persist changes when modifications occur.

```yaml
cisco.asa.asa_config:
  lines: [...]
  save: true
  save_when: changed
```

--------------------------------

### Gather Existing ACLs

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_acls_module.md

This example shows how to collect and register existing ACL configurations from the device without making any changes. The collected facts are stored in the 'acl_facts' variable.

```yaml
- name: Gather existing ACLs from device
  cisco.asa.asa_acls:
    state: gathered
  register: acl_facts
```

--------------------------------

### AnsibleConnectionFailure Example

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/errors.md

This error occurs due to device unreachability, SSH connection issues, or authentication failures. Verify device IP, network connectivity, and SSH status.

```text
FAILED! => {
    "msg": "Error: <class 'paramiko.ssh_exception.NoValidConnectionsError'>: Unable to open connection to host 192.168.1.10:22"
}
```

--------------------------------

### Create an extended ACL using object-groups

Source: https://github.com/ansible-collections/cisco.asa/blob/main/docs/cisco.asa.asa_acls_module.rst

This example demonstrates creating an extended ACL that utilizes network and port object-groups for source and destination definitions. It includes logging with a default setting.

```yaml
---
- name: Create an extended ACL using object-groups
  cisco.asa.asa_acls:
    config:
      acls:
        - name: test_access
          lines:
            - extended: deny
              protocol: tcp
              source:
                object_group: test_og_network
              destination:
                object_group: test_network_og
              log: default
```

--------------------------------

### Delete Specific Object Groups

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_ogs_module.md

This example demonstrates how to delete specific network and service object groups by providing their names.

```yaml
- name: Delete specific object groups
  cisco.asa.asa_ogs:
    config:
      - object_type: network
        object_groups:
          - name: test_og_network
          - name: test_network_og
      - object_type: service
        object_groups:
          - name: O-Worker
    state: deleted
```

--------------------------------

### Create Network Object Group with Nested References

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_ogs_module.md

This example demonstrates creating a network object group that references another existing object group. Ensure the referenced group exists before executing.

```yaml
- name: Create group object references
  cisco.asa.asa_ogs:
    config:
      - object_type: network
        object_groups:
          - name: base_network
            network_object:
              host:
                - 192.0.2.1
          - name: group_network_obj
            group_object:
              - base_network  # References base_network
    state: merged
```

--------------------------------

### Example of ASA Command Parameter Type Requirements

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/configuration.md

Illustrates the type requirements for parameters like 'commands', 'config', and 'lines' used in ASA Ansible modules.

```yaml
commands | list[str] | asa_command | ["show version", "show interfaces"]
config | dict | asa_acls/asa_ogs | {acls: [...]} 
lines | list[str] | asa_config | ["ip address 192.168.1.1 255.255.255.0"]
parents | list[str] | asa_config | ["interface ethernet 0/0"]
match | str | asa_config | "line" &#124; "strict" &#124; "exact" &#124; "none"
state | str | resource modules | "merged" &#124; "replaced" &#124; ...
```

--------------------------------

### Invalid Configuration Commands Resolution

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/errors.md

This example shows how to resolve invalid syntax errors in configuration commands for the `asa_config` module. It demonstrates verifying syntax and using the `parents` parameter to specify the correct context.

```yaml
cisco.asa.asa_config:
  lines:
    - nameif inside
  parents:
    - interface ethernet 0/0
```

--------------------------------

### asa_acls Module Usage

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_acls_module.md

Examples demonstrating how to use the `cisco.asa.asa_acls` module for different ACL management tasks on Cisco ASA devices.

```APIDOC
## asa_acls Module

### Description
Manages Access Control Lists (ACLs) on Cisco ASA devices.

### State Behaviors
- **merged**: Merge provided config with existing config.
- **replaced**: Replace specified ACLs entirely.
- **overridden**: Replace ALL ACLs with provided config.
- **deleted**: Delete specified ACLs or all ACLs if no config provided.
- **gathered**: Collect facts from device (return only).
- **rendered**: Generate commands from config (no device interaction).
- **parsed**: Parse text config into structured format.

### Return Values
- **before** (list): Configuration prior to module invocation (always returned).
- **after** (list): Configuration after module completion (returned when changed).
- **commands** (list): Set of commands pushed to remote device (always returned).

### Usage Examples

#### Merge ACL Configuration
```yaml
- name: Merge provided ACL configuration with existing config
  cisco.asa.asa_acls:
    config:
      acls:
        - name: temp_access
          acl_type: extended
          aces:
            - grant: deny
              line: 1
              protocol_options:
                tcp: true
              source:
                address: 192.0.2.0
                netmask: 255.255.255.0
              destination:
                address: 198.51.100.0
                netmask: 255.255.255.0
                port_protocol:
                  eq: www
              log: default
    state: merged
```

#### Delete Specific ACLs
```yaml
- name: Delete specific ACLs
  cisco.asa.asa_acls:
    config:
      acls:
        - name: temp_access
        - name: global_access
    state: deleted
```

#### Replace All ACLs
```yaml
- name: Replace all ACLs with new configuration
  cisco.asa.asa_acls:
    config:
      acls:
        - name: global_access
          acl_type: extended
          aces:
            - grant: permit
              line: 1
              protocol_options:
                ip: true
              source:
                any: true
              destination:
                any: true
    state: overridden
```

#### Gather Existing ACLs
```yaml
- name: Gather existing ACLs from device
  cisco.asa.asa_acls:
    state: gathered
  register: acl_facts
```

### Protocol Options
The `protocol_options` field supports the following nested dictionaries:

| Protocol | Type | Valid Values | Description |
|----------|------|--------------|-------------|
| protocol_number | int | 0-255 | IP protocol number |
| ahp | bool | true/false | Authentication Header Protocol |
| eigrp | bool | true/false | EIGRP routing protocol |
| esp | bool | true/false | Encapsulation Security Payload |
| gre | bool | true/false | GRE tunneling |
| icmp | dict | — | ICMP with subtypes (echo, echo_reply, unreachable, etc.) |
| icmp6 | dict | — | ICMPv6 with subtypes |
| igmp | bool | true/false | Internet Gateway Message Protocol |
| igrp | bool | true/false | IGRP routing protocol |
| ip | bool | true/false | Any Internet Protocol |
| ipinip | bool | true/false | IP in IP tunneling |
| ipsec | bool | true/false | IP Security |
| nos | bool | true/false | KA9Q NOS compatible tunneling |
| ospf | bool | true/false | OSPF routing protocol |
| pcp | bool | true/false | Payload Compression Protocol |
| pim | bool | true/false | Protocol Independent Multicast |
| pptp | bool | true/false | Point-to-Point Tunneling Protocol |
| sctp | bool | true/false | Stream Control Transmission Protocol |
| snp | bool | true/false | Simple Network Protocol |
| tcp | bool | true/false | Transmission Control Protocol |
| udp | bool | true/false | User Datagram Protocol |

### ICMP Type Options
When `protocol_options.icmp` is used, the following subtypes are available:
- alternate_address, conversion_error, echo, echo_reply
- information_reply, information_request, mask_reply, mask_request
- mobile_redirect, parameter_problem, redirect
- router_advertisement, router_solicitation, source_quench
- source_route_failed, time_exceeded, timestamp_reply
- timestamp_request, traceroute, unreachable

### Supported Platforms
- Cisco ASA 9.10(1)11 and later
- Tested with Cisco ASA 9.12.3

### Notes
- Module works with `network_cli` connection type.
- Requires network OS to be set to `cisco.asa.asa`.
- Privilege escalation may be required for proper operation.
- Uses resource module framework from `ansible.netcommon`.
- Auto-generated module (changes should be made in resource module builder).
```

--------------------------------

### Configure Service Object Groups

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_ogs_module.md

This example demonstrates configuring service object groups with TCP and UDP protocols, including port ranges and specific port numbers. The `state` parameter is set to `merged`.

```yaml
- name: Configure service object groups
  cisco.asa.asa_ogs:
    config:
      - object_type: service
        object_groups:
          - name: O-Worker
            services_object:
              - protocol: tcp
                destination_port:
                  range:
                    start: "100"
                    end: "200"
              - protocol: tcp-udp
                source_port:
                  eq: "1234"
                destination_port:
                  gt: nfs
          - name: O-UNIX-TCP
            protocol: tcp
            port_object:
              - eq: https
              - range:
                  start: "100"
                  end: "400"
    state: merged

```

--------------------------------

### Python SDK Usage for Cliconf

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/cliconf_plugin.md

Example of using the Cliconf plugin directly within a Python script for ASA devices. This requires an active connection to the device.

```python
from ansible.plugins.loader import cliconf_loader
from ansible.parsing.dataloader import DataLoader

loader = DataLoader()
cliconf = cliconf_loader.get("asa", None)

# Requires active connection
device_info = cliconf.get_device_info()
config = cliconf.get_config(source="running")
cliconf.run_commands(["show version", "show asp drop"])
```

--------------------------------

### Create an extended ACL with logging and time-range

Source: https://github.com/ansible-collections/cisco.asa/blob/main/docs/cisco.asa.asa_acls_module.rst

This example shows how to create an extended ACL with specific IP addresses, subnet masks, port equality, logging options, and a time-range. The 'inactive' parameter is used to disable the rule.

```yaml
---
- name: Create an extended ACL with logging and time-range
  cisco.asa.asa_acls:
    config:
      acls:
        - name: temp_access
          lines:
            - extended: deny
              protocol: tcp
              source:
                address: 192.0.2.0
                netmask: 255.255.255.0
                port_protocol:
                  eq: www
              destination:
                address: 198.51.100.0
                netmask: 255.255.255.0
              log: default
            - extended: deny
              protocol: igrp
              source:
                address: 198.51.100.0
                netmask: 255.255.255.0
              destination:
                address: 198.51.110.0
                netmask: 255.255.255.0
              time_range: temp
              inactive: true
            - extended: deny
              protocol: tcp
              source:
                interface: management
                port_protocol:
                  eq: www
              destination:
                interface: management
              log: warnings
    state: merged
```

--------------------------------

### Device Configuration Not Changed Example

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/errors.md

This output indicates that the Ansible module found no differences between the desired and current configuration, meaning no changes were necessary. This is the expected behavior for idempotent operations.

```text
ok: [asa01] => {
    "changed": false,
    "commands": [],
    "msg": "no changes needed",
    "before": [...],
    "after": [...] 
}
```

--------------------------------

### Create an extended IPv6 ACL with remark and inactive entry

Source: https://github.com/ansible-collections/cisco.asa/blob/main/docs/cisco.asa.asa_acls_module.rst

This example demonstrates creating an extended IPv6 ACL with a remark and an inactive extended deny entry. The 'inactive' parameter ensures the rule is not active.

```yaml
---
- name: Create an extended IPv6 ACL with remark and inactive entry
  cisco.asa.asa_acls:
    config:
      acls:
        - name: global_access
          lines:
            - remark: test global access
            - extended: deny
              protocol: tcp
              source:
                address: any
                port_protocol:
                  eq: www
              destination:
                address: any
                port_protocol:
                  eq: telnet
              log: errors
              interval: 300
        - name: R1_traffic
          lines:
            - remark: test_v6_acls
            - extended: deny
              protocol: tcp
              source:
                address: 2001:db8:0:3::/64
                port_protocol:
                  eq: www
              destination:
                address: 2001:fc8:0:4::/64
                port_protocol:
                  eq: telnet
              inactive: true
    state: merged
```

--------------------------------

### Manage Configuration with asa_config

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/INDEX.md

Applies unstructured configuration changes to the Cisco ASA device using the 'asa_config' module. This example adds an NTP server configuration, enables configuration backup, and saves the running configuration.

```yaml
- cisco.asa.asa_config:
    lines:
      - ntp server 8.8.8.8
    backup: true
    save: true
```

--------------------------------

### Configure Object Groups Declaratively

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/INDEX.md

Manages network object groups using the 'asa_ogs' resource module. This example creates a network object group named 'trusted_networks' and adds a network object with the IP range '192.168.1.0 255.255.255.0'.

```yaml
- cisco.asa.asa_ogs:
    config:
      - object_type: network
        object_groups:
          - name: trusted_networks
            network_object:
              address:
                - "192.168.1.0 255.255.255.0"
    state: merged
```

--------------------------------

### Install Cisco ASA Collection via CLI

Source: https://github.com/ansible-collections/cisco.asa/blob/main/README.md

Install the Cisco ASA collection using the Ansible Galaxy CLI. This is a straightforward command-line installation.

```bash
ansible-galaxy collection install cisco.asa
```

--------------------------------

### Configure with Backup and Save Options

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_config_module.md

Applies configuration changes, creates a backup with a custom filename and path, and saves the configuration when changes occur.

```yaml
- name: Configure with backup and save
  cisco.asa.asa_config:
    lines:
      - ip address 172.16.1.1 255.255.255.0
    parents:
      - interface management 0/0
    backup: true
    backup_options:
      filename: "asa_backup_{{ ansible_date_time.iso8601 }}.cfg"
      dir_path: /backups/asa
    save: true
    save_when: changed

- name: Load configuration from template
  cisco.asa.asa_config:
    src: templates/asa_config.j2
    backup: true
    save: always
```

--------------------------------

### Configure with Before and After Commands

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_config_module.md

Applies configuration lines with pre- and post-execution commands. Useful for setting up contexts or finalizing configurations.

```yaml
- name: Configure with pre/post commands
  cisco.asa.asa_config:
    before:
      - configure terminal
    lines:
      - ip address 10.0.0.1 255.255.255.0
    parents:
      - interface ethernet 0/1
    after:
      - end

- name: Enable and configure feature
  cisco.asa.asa_config:
    before:
      - feature ips
    lines:
      - ips signature-definition sig-set-create
    parents:
      - system
```

--------------------------------

### Get ASA Device Capabilities

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/module-utils.md

Fetches and caches device capabilities. Handles connection errors by failing the module.

```python
def get_capabilities(module):
    if hasattr(module, "_asa_capabilities"):
        return module._asa_capabilities
    try:
        capabilities = Connection(module._socket_path).get_capabilities()
    except ConnectionError as exc:
        module.fail_json(msg=to_text(exc, errors="surrogate_then_replace"))
    module._asa_capabilities = json.loads(capabilities)
    return module._asa_capabilities
```

--------------------------------

### No comparison, just push commands

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_config_module.md

This snippet bypasses any configuration comparison and pushes commands directly to the device. Use with caution as it does not check for existing configurations.

```yaml
- name: No comparison, just push commands
  cisco.asa.asa_config:
    lines:
      - configure terminal
      - show running-config
    match: none
```

--------------------------------

### Use Either Config or Running_Config

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/errors.md

For modules that accept configuration, provide either the `config` parameter for new configuration or `running_config` to manage the existing configuration. Do not use both.

```yaml
# Provide only ONE of these
cisco.asa.asa_acls:
  config: "{{ new_config }}"     # OR
  running_config: "{{ saved_config }}"
```

--------------------------------

### get_config

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/cliconf_plugin.md

Retrieves the device configuration from either the running or startup configuration. It supports specifying the source and returns the configuration as text. Requires enable mode.

```APIDOC
## get_config(source="running", flags=None, format="text")

### Description
Retrieves device configuration.

### Method
`get_config`

### Parameters
#### Query Parameters
- **source** (string) - Optional - Configuration source: `running` or `startup`
- **flags** (list) - Optional - Not used for ASA
- **format** (string) - Optional - Format specification (not used for ASA)

### Returns
string with configuration text

### Raises
AnsibleConnectionFailure if invalid source

### Notes
- Requires enable mode
- Automatically retrieves full running config with `show running-config all`
```

--------------------------------

### Get ASA Device Capabilities

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/cliconf_plugin.md

Retrieves device capabilities in JSON format. This method is part of the Cliconf plugin for ASA devices.

```python
def get_capabilities(self):
    result = super(Cliconf, self).get_capabilities()
    return json.dumps(result)
```

--------------------------------

### Replace object-group attributes

Source: https://github.com/ansible-collections/cisco.asa/blob/main/docs/cisco.asa.asa_ogs_module.rst

Use the 'replaced' state to modify existing object-group attributes. This example replaces attributes for a network and a protocol object-group.

```yaml
- name: "Replace module attributes of given object-group"
  cisco.asa.asa_ogs:
    config:
      - object_type: network
        object_groups:
          - name: test_og_network
            description: test_og_network_replace
            network_object:
              host:
                - 198.51.100.1
              address:
                - 198.51.100.0 255.255.255.0
      - object_type: protocol
        object_groups:
          - name: test_og_protocol
            description: test_og_protocol
            protocol_object:
              protocol:
                - tcp
                - udp
    state: replaced
```

--------------------------------

### failed_conditions Example

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/errors.md

This error occurs when `wait_for` conditions are not met within the specified retries. Check for connectivity issues, timeouts, or incorrect conditional logic.

```text
FAILED! => {
    "failed": true,
    "failed_conditions": [
        "result[0] contains 100%"
    ],
    "msg": "One or more conditional statements have not be satisfied"
}
```

--------------------------------

### Ansible Playbook to Run Commands via Cliconf

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/cliconf_plugin.md

An Ansible playbook demonstrating how to run commands like 'show version' and 'show interfaces' on ASA devices using the `ansible.netcommon.network_cli` connection.

```yaml
---
- hosts: asa_devices
  gather_facts: false
  connection: ansible.netcommon.network_cli
  
  tasks:
    - name: Run command via cliconf
      cisco.asa.asa_command:
        commands:
          - show version
          - show interfaces
```

--------------------------------

### Determine Defaults Flag Support

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/module-utils.md

Determines if the device supports 'all' or 'full' defaults flag by executing a 'show running-config ?' command.

```python
def get_defaults_flag(module):
    rc, out, err = exec_command(module, "show running-config ?")
    out = to_text(out, errors="surrogate_then_replace")
    
    commands = set()
    for line in out.splitlines():
        if line:
            commands.add(line.strip().split()[0])
    
    if "all" in commands:
        return "all"
    else:
        return "full"
```

--------------------------------

### Get ASA Device Connection

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/module-utils.md

Retrieves an existing ASA device connection or creates a new one. Handles context switching and capability checks.

```python
def get_connection(module):
    if hasattr(module, "_asa_connection"):
        return module._asa_connection
    
    context = module.params.get("context")
    connection_proxy = Connection(module._socket_path)
    cap = json.loads(connection_proxy.get_capabilities())
    if cap["network_api"] == "cliconf":
        module._asa_connection = Connection(module._socket_path)
    
    if context:
        if context == "system":
            command = "changeto system"
        else:
            command = "changeto context %s" % context
        module._asa_connection.get(command)
    
    return module._asa_connection
```

--------------------------------

### Example of Mutually Exclusive Parameters in ASA Modules

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/configuration.md

Shows pairs of parameters that cannot be used together in ASA Ansible modules, such as 'config' and 'running_config', or 'lines' and 'src'.

```yaml
config, running_config | Can't specify both source and input simultaneously
lines, src | Can't specify both direct lines and file source
defaults, passwords | ASA doesn't allow both defaults and passwords together
```

--------------------------------

### get_device_info

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/cliconf_plugin.md

Retrieves essential device information by executing the 'show version' command and parsing its output. This method populates and returns a dictionary containing details about the network OS, version, model, hostname, and image.

```APIDOC
## get_device_info()

### Description
Retrieves device information from `show version` output.

### Method
`get_device_info`

### Parameters
None

### Returns
dict with device information

### Collected Information:

| Key | Type | Description |
|-----|------|-------------|
| network_os | string | Always "asa" |
| network_os_version | string | ASA software version (from "Version X.XX(Y)Z") |
| network_os_firepower_version | string | Firepower version if present |
| network_os_device_mgr_version | string | Device manager version if present |
| network_os_model | string | Device model ID or hardware model |
| network_os_hostname | string | Configured hostname |
| network_os_image | string | Image filename in use |
```

--------------------------------

### Typical Ansible Module Usage Pattern

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/module-utils.md

Illustrates a common pattern for using Cisco ASA Ansible modules. It shows argument specification, argument checking, and running commands against the device.

```python
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.cisco.asa.plugins.module_utils.network.asa.asa import (
    asa_argument_spec,
    check_args,
    run_commands,
)

def main():
    spec = dict(commands=dict(type="list", required=True))
    spec.update(asa_argument_spec)
    module = AnsibleModule(argument_spec=spec, supports_check_mode=True)
    check_args(module)
    results = run_commands(module, module.params["commands"])
    # Process results...
```

--------------------------------

### Gather configuration

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_facts_module.md

Use this snippet to collect the device's running configuration.

```yaml
```yaml
- name: Gather configuration
  cisco.asa.asa_facts:
    gather_subset:
      - config
```
```

--------------------------------

### Configuration Device Facts

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/types.md

Contains the full running configuration text from the device.

```python
{
    "ansible_net_config": str              # Full running configuration text
}
```

--------------------------------

### Delete Specific ACLs

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_acls_module.md

This example demonstrates how to delete specific ACLs by name from the device configuration. Ensure the names provided exactly match the ACLs you wish to remove.

```yaml
- name: Delete specific ACLs
  cisco.asa.asa_acls:
    config:
      acls:
        - name: temp_access
        - name: global_access
    state: deleted
```

--------------------------------

### Return Value Structure Example

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_facts_module.md

This YAML structure illustrates the typical return values from the ASA facts module, including device identity, configuration, ACLs, and object groups.

```yaml
ansible_facts:
  ansible_net_model: "ASA5506-X"
  ansible_net_version: "9.10(1)11"
  ansible_net_serialnum: "ABC123XYZ"
  ansible_net_hostname: "myasa"
  ansible_net_config: "..." # Full running-config if collected
  ansible_net_acls:
    acls: [...]  # ACL facts if gathered
  ansible_net_ogs:
    object_groups: [...]  # OG facts if gathered
warnings: []
```

--------------------------------

### Add configuration using line matching

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_config_module.md

Use this snippet to add configuration lines to a specific section on the ASA device. The 'line' matching strategy compares commands individually.

```yaml
- name: Add configuration using line matching
  cisco.asa.asa_config:
    lines:
      - interface ethernet 0/0
      - nameif inside
      - ip address 192.168.1.1 255.255.255.0
    parents:
      - interface ethernet 0/0
```

--------------------------------

### Gather all facts

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_facts_module.md

Use this snippet to collect all available facts, including both legacy device information and resource-specific details.

```yaml
```yaml
- name: Gather all facts
  cisco.asa.asa_facts:
    gather_subset: all
```
```

--------------------------------

### Rename ACLs using Merged state

Source: https://github.com/ansible-collections/cisco.asa/blob/main/docs/cisco.asa.asa_acls_module.rst

This example shows how to rename existing ACLs on a Cisco ASA device using the 'merged' state. It renames 'global_access' to 'global_access_renamed' and 'R1_traffic' to 'R1_traffic_renamed'.

```yaml
---
- name: Rename ACL with different name using Merged state
  cisco.asa.asa_acls:
    config:
      acls:
        - name: global_access
          rename: global_access_renamed
        - name: R1_traffic
          rename: R1_traffic_renamed
    state: merged
```

--------------------------------

### Compare Configuration Against Provided Data

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_config_module.md

Compares configuration lines against a provided configuration string instead of the device's running configuration. Useful for testing or applying configurations from external sources.

```yaml
- name: Compare against provided config (not device)
  cisco.asa.asa_config:
    lines:
      - nameif inside
    parents:
      - interface ethernet 0/0
    config: "{{ asa_base_config }}"
    match: line
```

--------------------------------

### Configure Interface with Line Matching

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_config_module.md

Applies configuration lines to a specified interface, matching existing lines.

```yaml
- name: Configure interface with line matching
  cisco.asa.asa_config:
    lines:
      - nameif inside
      - ip address 192.168.1.1 255.255.255.0
      - shutdown
    parents:
      - interface ethernet 0/0

- name: Configure ACL
  cisco.asa.asa_config:
    lines:
      - permit tcp any any eq 80
      - permit tcp any any eq 443
    parents:
      - access-list acl_http
    match: line
```

--------------------------------

### Configure Enable Mode for Privilege Escalation

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/errors.md

Ensure `ansible_become` is enabled and `ansible_become_method` is set to 'enable' with the correct `ansible_become_pass`.

```yaml
# Ensure become is configured
ansible_become: true
ansible_become_method: ansible.netcommon.enable
ansible_become_pass: correct_enable_password
```

--------------------------------

### Invalid Choice Error Example

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/errors.md

This error occurs when a parameter value is not among the allowed choices for a module. Ensure the parameter value is one of the valid options listed for the specific parameter.

```text
FAILED! => {
    "msg": "invalid choice: 'invalid_state' (choose from 'merged', 'replaced', ...)"
}
```

--------------------------------

### Privilege Level Error Example

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/errors.md

Occurs when the user cannot escalate privileges, often due to an incorrect `ansible_become_pass` or insufficient user privilege level. Ensure enable mode is configured correctly.

```text
FAILED! => {
    "msg": "Error: Authentication failure"
}
```

--------------------------------

### ASA Cliconf Plugin Class Constructor

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/cliconf_plugin.md

Initializes the ASA Cliconf plugin, inheriting from CliconfBase and setting up device information storage.

```python
def __init__(self, *args, **kwargs):
    super(Cliconf, self).__init__(*args, **kwargs)
    self._device_info = {}
```

--------------------------------

### Rollback Configuration on Error

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/errors.md

Safely apply configuration changes by enabling backups and using a `block`/`rescue` structure. If an error occurs during the configuration application, the `rescue` block attempts to restore the device to its previous state using the generated backup.

```yaml
- name: Apply config with rollback
  block:
    - name: Make changes
      cisco.asa.asa_config:
        lines: "{{ new_config }}"
        backup: true
      register: config_result
  
  rescue:
    - name: Restore from backup
      cisco.asa.asa_config:
        src: "{{ config_result.backup_path }}"
      when: config_result.backup_path is defined
```

--------------------------------

### Cisco ASA Extended ACL Configuration Example

Source: https://github.com/ansible-collections/cisco.asa/blob/main/docs/cisco.asa.asa_acls_module.rst

This snippet shows the JSON structure for an extended ACL named 'test_access' with specific source and destination IP addresses, netmasks, and protocol settings.

```json
{
    "destination": {
        "address": "198.51.110.0",
        "netmask": "255.255.255.0"
    },
    "grant": "deny",
    "line": 2,
    "log": "errors",
    "protocol": "igrp",
    "protocol_options": {
        "igrp": true
    },
    "source": {
        "address": "198.51.100.0",
        "netmask": "255.255.255.0"
    }
}
```

--------------------------------

### Gather hardware facts

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_facts_module.md

Use this snippet to collect hardware-specific information, such as memory usage and file system details.

```yaml
```yaml
- name: Gather hardware facts
  cisco.asa.asa_facts:
    gather_subset:
      - hardware
```
```

--------------------------------

### State Transition Error Example

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/errors.md

This error occurs when attempting an invalid state transition, such as deleting a resource that does not exist. The resolution involves gathering the current state first and then conditionally deleting the resource.

```text
FAILED! => {
    "changed": false,
    "commands": ["no access-list nonexistent line 1 extended ..."],
    "msg": "Failed to delete configuration"
}
```

```yaml
- name: Gather ACLs first
  cisco.asa.asa_acls:
    state: gathered
  register: current_acls

- name: Delete only if exists
  cisco.asa.asa_acls:
    config:
      acls:
        - name: "{{ item }}"
    state: deleted
  loop: "{{ current_acls.gathered[0].acls | map(attribute='name') | list }}"
```

--------------------------------

### Declarative vs. Imperative Configuration

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/INDEX.md

Compares the declarative approach using resource modules (e.g., asa_acls) with the imperative approach using asa_config for unstructured changes. The declarative method is preferred for its idempotency.

```yaml
- cisco.asa.asa_acls:
    config:
      acls:
        - name: test_acl
          aces:
            - grant: permit
    state: merged
    # Module figures out what commands to send

# Imperative (asa_config) - for unstructured changes
- cisco.asa.asa_config:
    lines:
      - "permit ip any any"
    parents:
      - "access-list test_acl"
    # You specify exact commands
```

--------------------------------

### Manage ACLs with Cisco ASA Collection (Merge)

Source: https://github.com/ansible-collections/cisco.asa/blob/main/README.md

Example playbook task to merge ACL configurations on a Cisco ASA device using the `cisco.asa.asa_acls` module. This task registers the result for further inspection.

```yaml
---
- hosts: asa01
  gather_facts: false
  connection: network_cli

  collections:
    - cisco.asa

  tasks:
    - name: Merge the provided configuration with the existing running configuration
      register: result
      cisco.asa.asa_acls: &id001
        config:
          - acls:
              - name: test_global_access
                acl_type: extended
                aces:
                  - grant: deny
                    line: 1
                    protocol: tcp
                    protocol_options:
                      tcp: true
                    source:
                      address: 192.0.2.0
                      netmask: 255.255.255.0
                    destination:
                      address: 192.0.3.0
                      netmask: 255.255.255.0
                      port_protocol:
                        eq: www
                    log: default
              - name: test_R1_traffic
                acl_type: extended
                aces:
                  - grant: deny
                    line: 1
                    protocol_options:
                      tcp: true
                    source:
                      address: 2001:db8:0:3::/64
                      port_protocol:
                        eq: www
                    destination:
                      address: 2001:fc8:0:4::/64
                      port_protocol:
                        eq: telnet
                    inactive: true
        state: merged
```

--------------------------------

### Gather all except configuration

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/api-reference/asa_facts_module.md

Use this snippet to collect all facts except for the device's running configuration.

```yaml
```yaml
- name: Gather all except configuration
  cisco.asa.asa_facts:
    gather_subset:
      - '!config'
```
```

--------------------------------

### Execute Show Commands

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/INDEX.md

Executes a list of 'show' commands on the Cisco ASA device using the 'asa_command' module. The output of the commands is captured and registered in the 'output' variable.

```yaml
- cisco.asa.asa_command:
    commands:
      - show failover
      - show interface summary
  register: output
```

--------------------------------

### Cisco ASA Inventory Configuration

Source: https://github.com/ansible-collections/cisco.asa/blob/main/README.md

Example inventory file for connecting to a Cisco ASA device. Ensure sensitive information like passwords is managed securely using Ansible Vault in production environments.

```ini
[asa01]
host_asa.example.com

[asa01:vars]
ansible_user=admin
ansible_ssh_pass=password
ansible_become=true
ansible_become_method=ansible.netcommon.enable
ansible_become_pass=become_password
ansible_connection=ansible.netcommon.network_cli
ansible_network_os=cisco.asa.asa
ansible_python_interpreter=python
```

--------------------------------

### Apply Configuration Lines with Parents

Source: https://github.com/ansible-collections/cisco.asa/blob/main/docs/cisco.asa.asa_config_module.rst

Applies a list of configuration lines under a specified parent context. Useful for configuring network objects or similar hierarchical settings.

```yaml
- cisco.asa.asa_config:
    lines:
      - network-object host 10.80.30.18
      - network-object host 10.80.30.19
      - network-object host 10.80.30.20
    parents: [object-group network OG-MONITORED-SERVERS]
```

--------------------------------

### Conditional Error Reporting

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/errors.md

Report specific error messages based on the outcome of a task. This example registers the result of an ACL configuration and then uses a `debug` task to display an error message only when the ACL task has failed.

```yaml
- name: Apply changes only if valid
  cisco.asa.asa_acls:
    config: "{{ acl_config }}"
    state: merged
  register: acl_result
  
- name: Report on failure
  debug:
    msg: "ACL configuration failed: {{ acl_result.msg }}"
  when: acl_result is failed
```

--------------------------------

### Configure Match Criteria for ASA Command Wait For

Source: https://github.com/ansible-collections/cisco.asa/blob/main/_autodocs/configuration.md

Specify how to match conditions when waiting for command results. Use 'any' to match if any condition is met.

```yaml
cisco.asa.asa_command:
  commands:
    - show version
  wait_for:
    - result[0] contains Version 9.10
    - result[0] contains ASA
  match: any
```