### FTD Installation with New Password

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/ftd-install-module.md

Installs an FTD image and sets a new password for the device. This example also specifies the device model explicitly.

```python
- name: Install and set new password
  ftd_install:
    device_hostname: firepower
    device_password: oldpass
    device_new_password: newpass
    device_sudo_password: rootpass
    device_ip: 192.168.0.1
    device_netmask: 255.255.255.0
    device_gateway: 192.168.0.254
    dns_server: 8.8.8.8
    device_model: 'Cisco ASA5516-X Threat Defense'
    
    console_ip: 10.89.0.0
    console_port: 2004
    console_username: console_user
    console_password: console_pass
    
    rommon_file_location: 'tftp://10.89.0.11/installers/ftd-boot.img'
    image_file_location: 'https://10.89.0.11/installers/ftd-6.3.0.pkg'
    image_version: 6.3.0
```

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

### Verify Ansible Inventory Setup

Source: https://github.com/ciscodevnet/ftdansible/blob/master/samples/deployment/aws/README.md

Lists the inventory from the EC2 dynamic inventory script to verify the setup.

```bash
ansible-inventory -i ec2.py --list 
```

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

### Create Python Virtual Environment and Install Dependencies

Source: https://github.com/ciscodevnet/ftdansible/blob/master/samples/deployment/vmware/README.md

Sets up a Python virtual environment and installs Ansible and the pyvmomi library. Ensure you activate the environment before proceeding.

```bash
python3 -m venv ./venv
source venv/bin/activate
pip install ansible pyvmomi
```

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

### Install FTD Image

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-device.md

This instance method is responsible for installing the FTD image on the device. Subclasses must override this method to provide platform-specific logic. The parameters dictionary contains all necessary details for the installation process.

```python
def install_ftd_image(self, params):
    
```

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

### Platform-Specific Install Method

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/INDEX.md

Shows the method for installing FTD images on specific platform models.

```APIDOC
## AbstractFtdPlatform subclasses
- `Ftd2100Platform.install_ftd_image(params)`
- `FtdAsa5500xPlatform.install_ftd_image(params)`
```

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

### Create Python Virtual Environment and Install Ansible

Source: https://github.com/ciscodevnet/ftdansible/blob/master/samples/deployment/kvm/README.md

Sets up a Python virtual environment and installs the Ansible package. Activate the environment before running Ansible commands.

```bash
python3 -m venv ./venv
source venv/bin/activate
pip install ansible
```

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

### Install vSphere Automation Python SDK

Source: https://github.com/ciscodevnet/ftdansible/blob/master/samples/deployment/vmware/README.md

Clones the vSphere Automation SDK for Python and installs its dependencies. This step requires Git and ensures the SDK is correctly set up with extra index URLs.

```bash
git clone https://github.com/vmware/vsphere-automation-sdk-python.git
cd vsphere-automation-sdk-python
pip install --upgrade --force-reinstall -r requirements.txt --extra-index-url file://`pwd`/lib
```

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

### Install Dependencies and Set PYTHONPATH

Source: https://github.com/ciscodevnet/ftdansible/blob/master/docs/templates/static/ftd_ansible/installation_guide.md

Install project dependencies using pip and update the PYTHONPATH to include the project directory.

```bash
pip install -r requirements.txt
export PYTHONPATH=.:$PYTHONPATH
```

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

### FTD Ansible Inventory Example

Source: https://github.com/ciscodevnet/ftdansible/blob/master/docs/templates/static/ftd_ansible/installation_guide.md

Example of an Ansible inventory file for a local FTD device. Ensure 'ansible_host', 'ansible_network_os', 'ansible_user', and 'ansible_password' are set.

```ini
[ftd]
my-ftd ansible_host=192.168.1.1 ansible_httpapi_port=443 ansible_network_os=ftd ansible_user=admin ansible_password=123qwe ansible_httpapi_use_ssl=True
```

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

### Basic FTD Image Installation

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/ftd-install-module.md

Installs a specified FTD image version using HTTP API connection details. Ensure the ROMMON and image files are accessible from the specified locations.

```python
- name: Install image v6.3.0 on FTD 5516
  ftd_install:
    device_hostname: firepower
    device_password: pass
    device_ip: 192.168.0.1
    device_netmask: 255.255.255.0
    device_gateway: 192.168.0.254
    dns_server: 8.8.8.8
    
    console_ip: 10.89.0.0
    console_port: 2004
    console_username: console_user
    console_password: console_pass
    
    rommon_file_location: 'tftp://10.89.0.11/installers/ftd-boot-9.10.1.3.lfbff'
    image_file_location: 'https://10.89.0.11/installers/ftd-6.3.0-83.pkg'
    image_version: 6.3.0-83
```

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

### ASA5500-X Platform Parameters

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/types-and-data-structures.md

Dictionary of parameters for installing on the ASA5500-X platform. Includes network, console, and image details.

```python
{
    'device_hostname': 'firepower',
    'device_password': 'pass',
    'device_ip': '192.168.1.10',
    'device_netmask': '255.255.255.0',
    'device_gateway': '192.168.1.1',
    'dns_server': '8.8.8.8',
    'search_domains': 'example.com',
    'console_ip': '10.0.0.1',
    'console_port': '2004',
    'console_username': 'console_user',
    'console_password': 'console_pass',
    'rommon_file_location': 'tftp://10.0.0.2/boot.img',
    'image_file_location': 'https://10.0.0.2/ftd-6.3.0-83.pkg',
    'image_version': '6.3.0-83'
}
```

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

### Swagger Specification Example

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-fdm-swagger-client.md

An example of a complete Swagger 2.0 specification structure, including version, base path, definitions, and paths.

```json
{
    "swagger": "2.0",
    "basePath": "/api/fdm/v2",
    "definitions": {...},
    "paths": {...}
  }
```

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

### Install Ansible and Test Dependencies Locally

Source: https://github.com/ciscodevnet/ftdansible/blob/master/README.md

Installs Ansible and necessary test dependencies using pip. Requires cloning the Ansible repository first and setting the ANSIBLE_DIR environment variable.

```bash
pip install $ANSIBLE_DIR/requirements.txt
pip install test-requirements.txt

```

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

### AbstractFtdPlatform.install_ftd_image

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-device.md

Installs the FTD image on the device. This is an abstract method that must be implemented by platform-specific subclasses.

```APIDOC
## AbstractFtdPlatform.install_ftd_image

### Description
Installs the FTD image on the device. This method must be implemented by concrete subclasses.

### Method
`def install_ftd_image(self, params)`

### Parameters
- **params** (dict) - Required - Installation parameters, including:
  - `device_hostname` (str): Device hostname.
  - `device_password` (str): Device login password.
  - `device_new_password` (str) - Optional - New password after install.
  - `device_ip` (str): Management interface IP address.
  - `device_netmask` (str): Management interface netmask.
  - `device_gateway` (str): Management interface gateway.
  - `dns_server` (str): DNS server IP address.
  - `search_domains` (str): DNS search domains.
  - `console_ip` (str): Terminal server IP address.
  - `console_port` (str): Terminal server device port.
  - `console_username` (str): Terminal server username.
  - `console_password` (str): Terminal server password.
  - `rommon_file_location` (str): TFTP path to the boot image.
  - `image_file_location` (str): URL to the FTD package image.
  - `image_version` (str): Target FTD version.

### Raises
- `NotImplementedError` - This method must be overridden in subclasses.
```

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

### Set Up Python Virtual Environment

Source: https://github.com/ciscodevnet/ftdansible/blob/master/docs/templates/static/ftd_ansible/installation_guide.md

Create and activate a Python virtual environment for the FTDAnsible project. Ensure a compatible Python version is installed.

```bash
cd FTDAnsible
python -m venv venv
. venv/bin/activate
```

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

### Create Python Virtual Environment

Source: https://github.com/ciscodevnet/ftdansible/blob/master/samples/deployment/aws/README.md

Creates a Python virtual environment and activates it. Installs dependencies from requirements.txt.

```bash
python3 -m venv ./venv
source venv/bin/activate
pip install -r requirements.txt
```

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

### Install TOX

Source: https://github.com/ciscodevnet/ftdansible/blob/master/README.md

Installs the TOX testing tool locally. TOX is used to run tests in isolated virtual environments for different Python versions.

```bash
pip install tox

```

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

### ftd_configuration Module

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/README.md

Manages device configuration via REST API. Supports operations like add, edit, delete, get, list, and upsert, with a full parameter reference, return values, and usage examples.

```APIDOC
## ftd_configuration Module

### Description
Manages device configuration via REST API. Supports operations like add, edit, delete, get, list, and upsert.

### Operations
- add
- edit
- delete
- get
- list
- upsert

### Parameters
Full parameter reference available in the module documentation.

### Return Values
Details on return values available in the module documentation.

### Exceptions
Details on exceptions available in the module documentation.

### Usage Examples
Examples for all operation types are provided in the module documentation.
```

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

### AnsibleConnectionFailure Message Example

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/errors-and-exceptions.md

An example error message indicating a failure in establishing an Ansible connection to a device, often due to authentication issues.

```text
msg: "Username and password are required for login in absence of refresh token"
```

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

### Run Ansible Playbook to Setup KVM Host

Source: https://github.com/ciscodevnet/ftdansible/blob/master/samples/deployment/kvm/README.md

Executes the Ansible playbook to set up the KVM host. Ensure the inventory.yaml file is configured with environment-specific variables.

```bash
ansible-playbook -i inventory.yaml setup_host.yaml
```

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

### ftd_install Module

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/README.md

Installs FTD pkg images on hardware, supporting both ROMMON and FTD image installation. Includes platform-specific parameters for ASA5500-X and Firepower 2100 series.

```APIDOC
## ftd_install Module

### Description
Installs FTD pkg images on hardware, supporting both ROMMON and FTD image installation.

### Supported Installations
- ROMMON image installation
- FTD image installation

### Parameters
Platform-specific parameters for ASA5500-X and Firepower 2100 series are detailed in the module documentation.

### Usage Examples
Usage examples with full configuration are provided in the module documentation.
```

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

### Download to directory

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/ftd-file-download-module.md

Example of downloading a troubleshoot report to a directory, using the filename from the Content-Disposition header.

```APIDOC
### Download to directory

```python
- name: Download troubleshoot report
  ftd_file_download:
    operation: 'gettroubleshootreport'
    destination: /var/log/ftd/ 
    # File will be saved with name from Content-Disposition header
```
```

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

### Install Flake8 for Style Check

Source: https://github.com/ciscodevnet/ftdansible/blob/master/README.md

Installs Flake8 locally, a tool used for checking Python code style. Flake8 configuration is defined in the tox.ini file.

```bash
pip install flake8

```

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

### Download certificate

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/ftd-file-download-module.md

Example of downloading a device certificate from an FTD device.

```APIDOC
### Download certificate

```python
- name: Download device certificate
  ftd_file_download:
    operation: 'getcertificate'
    path_params:
      objId: 'default'
    destination: /certs/device-cert.pem
```
```

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

### Install FTD Image

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/README.md

Installs a new FTD image onto a device. This requires detailed device connection information, console details, and locations for the ROMMON and image files. Ensure all specified network paths are accessible.

```yaml
- name: Install FTD image
  ftd_install:
    device_hostname: firepower
    device_password: "{{ device_password }}"
    device_ip: 192.168.1.10
    device_netmask: 255.255.255.0
    device_gateway: 192.168.1.1
    dns_server: 8.8.8.8
    console_ip: 10.0.0.1
    console_port: 2004
    console_username: console_user
    console_password: "{{ console_password }}"
    rommon_file_location: tftp://10.0.0.2/boot.img
    image_file_location: https://10.0.0.2/ftd-6.3.0.pkg
    image_version: 6.3.0
```

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

### Download and Upload Configuration Files

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/README.md

Provides examples for downloading a backup file from the FTD device and uploading a configuration file to it. Ensure the destination path exists for downloads and the source file exists for uploads.

```yaml
- name: Download backup
  ftd_file_download:
    operation: getbackupfile
    path_params:
      objId: current-backup
    destination: /backups/ftd-backup.tar.gz

- name: Upload configuration
  ftd_file_upload:
    operation: postuploadconfigfile
    file_to_upload: /tmp/ftd-config.xml
    register_as: upload_result
```

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

### FTD Configuration Network Object Example

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/types-and-data-structures.md

An example of a FTD configuration object for a network, including its ID, type, name, value, subtype, and other properties. Standard properties like id, type, version, isSystemDefined, and links are common across all objects.

```python
network_object = {
    'id': 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    'type': 'networkobject',
    'name': 'production-network',
    'value': '10.0.0.0/8',
    'subType': 'NETWORK',
    'dnsResolution': 'IPV4_AND_IPV6',
    'description': 'Production environment network',
    'isSystemDefined': False,
    'version': '1',
    'links': {
        'self': {
            'href': '/api/fdm/v2/object/networks/a1b2c3d4...'
        }
    }
}
```

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

### Generate FTD API or Ansible Docs

Source: https://github.com/ciscodevnet/ftdansible/blob/master/docs/README.md

Run this command from the project root to generate documentation. Specify the doctype as 'ftd-api' or 'ftd-ansible'. Ensure common environment setup is complete.

```bash
python -m docs.build SWAGGER_HOST_URL USERNAME PASSWORD --doctype [ftd-api|ftd-ansible]
```

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

### Firepower 2100 Platform Parameters

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/types-and-data-structures.md

Dictionary of parameters for installing on the Firepower 2100 platform. Includes device credentials, network, console, and image details.

```python
{
    'device_hostname': 'firepower',
    'device_username': 'admin',
    'device_password': 'pass',
    'device_sudo_password': 'root_pass',
    'device_new_password': 'newpass',
    'device_ip': '192.168.1.10',
    'device_netmask': '255.255.255.0',
    'device_gateway': '192.168.1.1',
    'dns_server': '8.8.8.8',
    'search_domains': 'example.com,cisco.com',
    'console_ip': '10.0.0.1',
    'console_port': '2004',
    'console_username': 'console_user',
    'console_password': 'console_pass',
    'rommon_file_location': 'tftp://10.0.0.2/boot.img',
    'image_file_location': 'https://10.0.0.2/ftd-6.4.0.pkg',
    'image_version': '6.4.0'
}
```

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

### Basic Inventory with Token Path Discovery

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/httpapi-ftd-plugin.md

Example of an Ansible inventory file where the FTD token path is discovered automatically.

```ini
[ftd_devices]
firepower1 ansible_host=192.168.1.10 ansible_user=admin ansible_password=pass
```

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

### Install FTD Image on FtdAsa5500xPlatform

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-device.md

Installs an FTD image on a Cisco ASA5500-X device. It connects to the console and uses 'rommon_to_new_image' with parameters for TFTP server, image files, and network configuration. Note that device_new_password is not supported for this platform.

```python
def install_ftd_image(self, params):
```

```python
platform = FtdAsa5500xPlatform(params)
platform.install_ftd_image({
    'device_hostname': 'firepower',
    'device_password': 'pass',
    'device_ip': '192.168.1.10',
    'device_netmask': '255.255.255.0',
    'device_gateway': '192.168.1.1',
    'dns_server': '8.8.8.8',
    'search_domains': 'cisco.com',
    'console_ip': '10.0.0.1',
    'console_port': '2004',
    'console_username': 'console_user',
    'console_password': 'console_pass',
    'rommon_file_location': 'tftp://10.0.0.2/boot.img',
    'image_file_location': 'https://10.0.0.2/ftd-6.3.0-83.pkg',
    'image_version': '6.3.0-83'
})
```

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

### Download backup with specific name

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/ftd-file-download-module.md

Example of downloading a specific backup file from an FTD device.

```APIDOC
### Download backup with specific name

```python
- name: Download backup file
  ftd_file_download:
    operation: 'getbackupfile'
    path_params:
      objId: 'backup-2023-01-15'
    destination: /backups/ftd-backup.tar.gz
```
```

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

### Install FTD Image on Ftd2100Platform

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-device.md

Installs an FTD image on a Cisco Firepower 2100 device. It establishes an SSH connection to the console and uses the 'baseline_fp2k_ftd' function with detailed parameters for TFTP server, image files, and network configuration.

```python
def install_ftd_image(self, params):
```

```python
platform = Ftd2100Platform(params)
platform.install_ftd_image({
    'device_hostname': 'firepower',
    'device_username': 'admin',
    'device_password': 'oldpass',
    'device_new_password': 'newpass',
    'device_ip': '192.168.1.10',
    'device_netmask': '255.255.255.0',
    'device_gateway': '192.168.1.1',
    'dns_server': '8.8.8.8',
    'search_domains': 'example.com',
    'console_ip': '10.0.0.1',
    'console_port': '2004',
    'console_username': 'console_user',
    'console_password': 'console_pass',
    'rommon_file_location': 'tftp://10.0.0.2/boot.img',
    'image_file_location': 'https://10.0.0.2/ftd-6.4.0.pkg',
    'image_version': '6.4.0'
})
```

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

### Upload Backup File with ftd_file_upload

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/ftd-file-upload-module.md

This example demonstrates uploading a backup file to the FTD device. The 'operation' should be 'postuploadbackupfile', and the result can be registered using 'register_as'.

```ansible
- name: Upload backup configuration
  ftd_file_upload:
    operation: 'postuploadbackupfile'
    file_to_upload: /tmp/backup.tar.gz
    register_as: 'backup_upload_result'

```

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

### Run Playbook Locally

Source: https://github.com/ciscodevnet/ftdansible/blob/master/README.md

Executes an Ansible playbook using the locally installed Ansible environment.

```bash
ansible-playbook samples/network_object.yml
```

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

### Download pending changes

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/ftd-file-download-module.md

Example of downloading pending changes from an FTD device.

```APIDOC
### Download pending changes

```python
- name: Download pending changes
  ftd_file_download:
    operation: 'getdownload'
    path_params:
      objId: 'default'
    destination: /tmp/
```
```

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

### ftd_configuration Module Parameters

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/types-and-data-structures.md

Example of parameters for the ftd_configuration Ansible module, including operation, data, query parameters, path parameters, registration name, and filters.

```python
# ftd_configuration module parameters
params = {
    'operation': 'addNetworkObject',           # Required operation name
    'data': {                                  # Object data (for add/edit)
        'name': 'new-network',
        'value': '10.0.0.0/8',
        'subType': 'NETWORK',
        'type': 'networkobject'
    },
    'query_params': {                          # URL query parameters
        'limit': '100',
        'offset': '0'
    },
    'path_params': {                           # URL path parameters
        'objId': 'abc123'                      # For edit/delete operations
    },
    'register_as': 'my_network_object',       # Fact registration name
    'filters': {                               # For filtering list results
        'name': 'production-*',
        'subType': 'NETWORK'
    }
}
```

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

### API Response with List

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/types-and-data-structures.md

Example of a successful REST API response containing a list of items and paging information.

```python
response = {
    'success': True,
    'status_code': 200,
    'response': {
        'items': [
            {'id': '1', 'type': 'networkobject', 'name': 'net1'},
            {'id': '2', 'type': 'networkobject', 'name': 'net2'}
        ],
        'paging': {
            'offset': 0,
            'limit': 10,
            'count': 2
        }
    }
}
```

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

### Run Unit Tests with TOX

Source: https://github.com/ciscodevnet/ftdansible/blob/master/README.md

Runs unit tests in virtual environments for specified Python versions using TOX. Requires the corresponding Python versions to be installed locally.

```bash
tox -e py27,py35,py36,py37

```

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

### Ansible Facts - List Results

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/types-and-data-structures.md

Example of Ansible facts registered from a list response, typically containing multiple items.

```python
# List results
ansible_facts = {
    'query_results': [
        {'id': '1', 'type': 'networkobject', 'name': 'net1'},
        {'id': '2', 'type': 'networkobject', 'name': 'net2'}
    ]
}
```

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

### Handle FtdConfigurationError

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/errors-and-exceptions.md

Example of catching FtdConfigurationError and failing the Ansible module with relevant error messages and objects.

```python
try:
    resource.execute_operation('addNetworkObject', params)
except FtdConfigurationError as e:
    module.fail_json(msg=f"Configuration error: {e.msg}", obj=e.obj)
```

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

### Inventory with Explicit Token Path

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/httpapi-ftd-plugin.md

Example of an Ansible inventory file specifying an explicit FTD token path for API authentication.

```ini
[ftd_devices]
firepower1 ansible_host=192.168.1.10 ansible_user=admin ansible_password=pass ansible_httpapi_ftd_token_path=/api/fdm/v2/fdm/token
```

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

### Ansible Facts - Custom Name with register_as

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/types-and-data-structures.md

Example of Ansible facts registered using the 'register_as' parameter for a custom fact name.

```python
# With register_as parameter
ansible_facts = {
    'my_custom_fact_name': {
        'id': 'abc123',
        'type': 'networkobject',
        'name': 'my-network',
        'value': '10.0.0.0/8'
    }
}
```

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

### Swagger 2.0 Specification Example

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-fdm-swagger-client.md

This JSON snippet demonstrates the required structure for a Swagger 2.0 specification, including API base path, model definitions, and endpoint configurations.

```json
{
    "basePath": "/api/fdm/v2",
    "definitions": {
        "NetworkObject": {
            "type": "object",
            "properties": {
                "id": {"type": "string"},
                "name": {"type": "string"},
                "value": {"type": "string"}
            },
            "required": ["name", "value"]
        }
    },
    "paths": {
        "/object/networks": {
            "post": {
                "operationId": "addNetworkObject",
                "parameters": [{
                    "name": "body",
                    "in": "body",
                    "schema": {"$ref": "#/definitions/NetworkObject"}
                }],
                "responses": {
                    "200": {
                        "schema": {"$ref": "#/definitions/NetworkObject"}
                    }
                }
            }
        }
    }
}
```

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

### Validation Report Examples

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/types-and-data-structures.md

Illustrates the structure of validation reports for both successful and failed operations. The report details missing required fields or fields with invalid types.

```python
# Validation success
is_valid, report = validator.validate_data('addNetworkObject', data)
# is_valid = True, report = None

# Validation failure
is_valid, report = validator.validate_data('addNetworkObject', data)
# is_valid = False, report = {
#     'required': [
#         'name',                      # Simple field
#         'network.id',               # Nested object field
#         'servers[2].address'        # Array element field
#     ],
#     'invalid_type': [
#         {
#             'path': 'limit',
#             'expected_type': 'integer',
#             'actually_value': 'abc'
#         },
#         {
#             'path': 'network[0].id',
#             'expected_type': 'string',
#             'actually_value': 123
#         }
#     ]
# }
```

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

### Ftd2100Platform Constructor

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-device.md

Initializes the Ftd2100Platform with device connection parameters. Requires hostname, username, and password; sudo password is optional.

```python
def __init__(self, params):
```

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

### Run Ansible Playbook

Source: https://github.com/ciscodevnet/ftdansible/blob/master/docs/templates/static/ftd_ansible/installation_guide.md

Execute an Ansible playbook after setting up FTD devices and inventory.

```bash
ansible-playbook test_playbook.yml
```

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

### Device Model Validation and Platform Creation

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-device.md

Demonstrates the usage flow for validating a device model and creating a platform instance using FtdModel and FtdPlatformFactory. Ensure the device model is supported before proceeding.

```python
from module_utils.device import FtdModel, FtdPlatformFactory

# 1. Validate model
device_model = 'Cisco ASA5516-X Threat Defense'
if not FtdModel.has_value(device_model):
    raise ValueError(f"Unsupported model: {device_model}")

# 2. Create platform instance
module_params = {
    'device_hostname': 'firepower',
    'device_password': 'pass',
    'device_sudo_password': 'root_pass'
    # ... other params
}
platform = FtdPlatformFactory.create(device_model, module_params)

# 3. Install image
install_params = {
    # ... all installation parameters
}
platform.install_ftd_image(install_params)
```

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

### Get Operation Specification by Name

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/httpapi-ftd-plugin.md

Retrieves the API specification for a named operation. Use this to get details like URL, HTTP method, and expected parameters for a specific API call.

```python
def get_operation_spec(self, operation_name):

```

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

### Create Virtual Environment

Source: https://github.com/ciscodevnet/ftdansible/blob/master/README.md

Creates and activates a Python virtual environment for local playbook execution.

```bash
python3 -m venv venv
. venv/bin/activate
```

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

### List Available TOX Environments

Source: https://github.com/ciscodevnet/ftdansible/blob/master/README.md

Lists all the testing environments configured in the TOX configuration file. Environments with '_-integration' postfix are for integration tests.

```bash
tox -l

```

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

### Python Class Method: is_upsert_operation

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-configuration.md

Checks if an operation name starts with 'upsert'.

```python
is_upsert_operation(operation_name)
```

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

### FtdAsa5500xPlatform

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-device.md

Platform implementation for Cisco ASA5500-X series devices. It supports installing FTD images.

```APIDOC
## FtdAsa5500xPlatform

### Description
Platform implementation for Cisco ASA5500-X series devices.

### Constructor
```python
def __init__(self, params):
```

**Parameters:**
- `params` (dict): Must contain:
  - `device_hostname`: Device hostname
  - `device_password`: Device password
  - `device_sudo_password`: Root password (optional, defaults to device_password)

### install_ftd_image(params)

Installs FTD image on ASA5500-X device.

```python
def install_ftd_image(self, params):
```

**Parameters:** Same as AbstractFtdPlatform.install_ftd_image

**Behavior:**
1. Establishes SSH connection to device console via terminal server
2. Calls rommon_to_new_image on console line object with specified parameters.
3. Ensures console connection closed.

**Note:** ASA5500-X devices do not support device_new_password.

**Example:**
```python
platform = FtdAsa5500xPlatform(params)
platform.install_ftd_image({
    'device_hostname': 'firepower',
    'device_password': 'pass',
    'device_ip': '192.168.1.10',
    'device_netmask': '255.255.255.0',
    'device_gateway': '192.168.1.1',
    'dns_server': '8.8.8.8',
    'search_domains': 'cisco.com',
    'console_ip': '10.0.0.1',
    'console_port': '2004',
    'console_username': 'console_user',
    'console_password': 'console_pass',
    'rommon_file_location': 'tftp://10.0.0.2/boot.img',
    'image_file_location': 'https://10.0.0.2/ftd-6.3.0-83.pkg',
    'image_version': '6.3.0-83'
})
```
```

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

### Build Custom AMI Image with Ansible

Source: https://github.com/ciscodevnet/ftdansible/blob/master/samples/deployment/aws/README.md

Runs the Ansible playbook to build a custom AMI image. Ensure placeholder values in vars.yaml are replaced.

```bash
ANSIBLE_HOST_KEY_CHECKING=False ansible-playbook -i ec2.py build_ami_vftd.yaml
```

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

### FtdPlatformFactory.create

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-device.md

Creates an appropriate FTD platform instance based on the device model. It inspects available platform subclasses and instantiates the one that supports the given model.

```APIDOC
## FtdPlatformFactory.create

### Description
Creates an appropriate platform-specific installation handler instance based on the device model.

### Method
`staticmethod create(model, module_params)`

### Parameters
- **model** (str) - Required - Device model name (must match FtdModel enum value).
- **module_params** (dict) - Required - Module parameters containing credentials and network info.

### Returns
AbstractFtdPlatform subclass instance (e.g., Ftd2100Platform or FtdAsa5500xPlatform).

### Raises
- `ValueError` if the model is not supported.

### Behavior
- Inspects all `AbstractFtdPlatform` subclasses.
- Calls `supports_ftd_model` on each until a match is found.
- Creates and returns the matched platform subclass instance.

### Example
```python
from module_utils.device import FtdPlatformFactory

params = {
    'device_hostname': 'firepower',
    'device_password': 'pass',
    'console_ip': '10.0.0.1',
    'console_port': '2004',
    'console_username': 'console_user',
    'console_password': 'console_pass',
    'rommon_file_location': 'tftp://10.0.0.2/boot.img',
    'image_file_location': 'https://10.0.0.2/ftd-6.3.0.pkg',
    'image_version': '6.3.0'
}

platform = FtdPlatformFactory.create('Cisco ASA5506-X Threat Defense', params)
platform.install_ftd_image(params)
```
```

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

### Handle FtdInvalidOperationNameError

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/errors-and-exceptions.md

Example of catching FtdInvalidOperationNameError and failing the Ansible module with the invalid operation name.

```python
try:
    response = resource.execute_operation('addNetworkObject', params)
except FtdInvalidOperationNameError as e:
    module.fail_json(msg=f"Invalid operation: {e.operation_name}")
```

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

### Ansible Connection Object Methods

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/types-and-data-structures.md

Demonstrates how to use the Connection object for interacting with devices via an httpapi plugin. Ensure the connection object is initialized with the module's socket path.

```python
# Module receives connection via socket path
connection = Connection(module._socket_path)

# Connection has httpapi plugin (ftd) backing it
# Available methods:
connection.get_operation_spec(operation_name)
connection.send_request(url_path, method, body_params, path_params, query_params)
connection.upload_file(local_path, remote_url)
connection.download_file(remote_url, local_path, path_params)
connection.validate_data(operation_name, data)
connection.validate_query_params(operation_name, params)
connection.validate_path_params(operation_name, params)
```

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

### Check firepower-kickstart Availability

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-device.md

Indicates whether the firepower-kickstart library is available on the system. This is a module-level constant.

```python
HAS_KICK = True|False  # True if firepower-kickstart library is available
```

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

### Ftd2100Platform

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-device.md

Platform implementation for Cisco Firepower 2100 series devices. It supports installing FTD images.

```APIDOC
## Ftd2100Platform

### Description
Platform implementation for Cisco Firepower 2100 series devices.

### Constructor
```python
def __init__(self, params):
```

**Parameters:**
- `params` (dict): Must contain:
  - `device_hostname`: Device hostname
  - `device_username`: Device username (default: 'admin')
  - `device_password`: Device password
  - `device_sudo_password`: Root password (optional, defaults to device_password)

### install_ftd_image(params)

Installs FTD image on Firepower 2100 device.

```python
def install_ftd_image(self, params):
```

**Parameters:** Same as AbstractFtdPlatform.install_ftd_image

**Behavior:**
1. Establishes SSH connection to device console via terminal server
2. Calls baseline_fp2k_ftd on console line object with specified parameters.
3. Ensures console connection closed.

**Example:**
```python
platform = Ftd2100Platform(params)
platform.install_ftd_image({
    'device_hostname': 'firepower',
    'device_username': 'admin',
    'device_password': 'oldpass',
    'device_new_password': 'newpass',
    'device_ip': '192.168.1.10',
    'device_netmask': '255.255.255.0',
    'device_gateway': '192.168.1.1',
    'dns_server': '8.8.8.8',
    'search_domains': 'example.com',
    'console_ip': '10.0.0.1',
    'console_port': '2004',
    'console_username': 'console_user',
    'console_password': 'console_pass',
    'rommon_file_location': 'tftp://10.0.0.2/boot.img',
    'image_file_location': 'https://10.0.0.2/ftd-6.4.0.pkg',
    'image_version': '6.4.0'
})
```
```

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

### Add Network Object and Access Policy

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/README.md

Demonstrates adding a network object and then referencing it in an access policy. Ensure the network object is created before the policy that uses it.

```yaml
- name: Create network object
  ftd_configuration:
    operation: addNetworkObject
    data:
      name: prod-network
      value: 10.0.0.0/8
      subType: NETWORK
      type: networkobject
    register_as: prod_net

- name: Create access policy using network reference
  ftd_configuration:
    operation: addAccessPolicy
    data:
      name: allow-prod
      type: accesspolicy
      sourceNetworks:
        - id: "{{ prod_net.id }}"
          type: networkobject
```

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

### Run Ansible Playbook to Deploy New vFTD

Source: https://github.com/ciscodevnet/ftdansible/blob/master/samples/deployment/kvm/README.md

Executes the Ansible playbook to deploy a new vFTD instance. The inventory.yaml file must be correctly configured.

```bash
ansible-playbook -i inventory.yaml deploy_vm.yaml
```

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

### Ansible Facts - Auto-generated Name

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/types-and-data-structures.md

Example of Ansible facts automatically registered from a network object response.

```python
# Auto-generated fact name
ansible_facts = {
    'networkobject_my_network': {
        'id': 'abc123',
        'type': 'networkobject',
        'name': 'my-network',
        'value': '10.0.0.0/8'
    }
}
```

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

### Python Function Definition: get_operation_specs_by_model_name

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-configuration.md

Defines a function to get all operations applicable to a specific model type.

```python
def get_operation_specs_by_model_name(self, model_name):
```

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

### Object Comparison Utility

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/INDEX.md

Demonstrates the use of utility functions for comparing objects, dictionaries, and lists, including checking for object references. Useful for determining if existing and requested configurations are equivalent.

```python
from module_utils.common import equal_objects, equal_dicts, equal_lists, is_object_ref

if equal_objects(existing, requested):
    # Objects have same content (ignoring id, version, etc.)
```

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

### Deploy vFTD using Custom AMI

Source: https://github.com/ciscodevnet/ftdansible/blob/master/samples/deployment/aws/README.md

Runs the Ansible playbook to deploy a new vFTD instance using the custom AMI image. Set the FTD version and admin password in the playbook.

```bash
ansible-playbook -i ec2.py deploy.yaml
```

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

### Handle CheckModeException

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/errors-and-exceptions.md

Example of catching CheckModeException in a try-except block to gracefully handle operations that cannot run in check mode.

```python
try:
    resource.execute_operation('someOperation', params)
except CheckModeException:
    module.exit_json(changed=False)
```

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

### Handle FtdUnexpectedResponse

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/errors-and-exceptions.md

Example of catching FtdUnexpectedResponse when an API response has an unexpected format, failing the module with a descriptive message.

```python
try:
    result = connection.send_request(url, 'get')
except FtdUnexpectedResponse as e:
    module.fail_json(msg=f"Unexpected response format: {e}")
```

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

### ConnectionError Message Example - Invalid JSON Response

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/errors-and-exceptions.md

An error message indicating that the received response from the server was not valid JSON.

```text
"Invalid JSON response: {response_text}"
```

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

### Initialize BaseConfigurationResource

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-configuration.md

Initializes the BaseConfigurationResource class with an Ansible httpapi connection instance and an optional check mode flag.

```python
class BaseConfigurationResource(object):
    def __init__(self, conn, check_mode=False):

```

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

### Create FTD Platform Instance

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-device.md

Use this factory method to create a platform-specific handler based on the device model. Ensure module parameters include necessary credentials and network information.

```python
from module_utils.device import FtdPlatformFactory

params = {
    'device_hostname': 'firepower',
    'device_password': 'pass',
    'console_ip': '10.0.0.1',
    'console_port': '2004',
    'console_username': 'console_user',
    'console_password': 'console_pass',
    'rommon_file_location': 'tftp://10.0.0.2/boot.img',
    'image_file_location': 'https://10.0.0.2/ftd-6.3.0.pkg',
    'image_version': '6.3.0'
}

platform = FtdPlatformFactory.create('Cisco ASA5506-X Threat Defense', params)
platform.install_ftd_image(params)
```

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

### Python Class Method: is_get_list_operation

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-configuration.md

Checks if an operation is a list retrieval operation. It verifies the method is GET and returnMultipleItems is True.

```python
is_get_list_operation(operation_name, operation_spec)
```

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

### upsert_object

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-configuration.md

Creates or updates an object. If the object exists, it is updated; otherwise, it is created. The operation name must start with 'upsert'.

```APIDOC
## upsert_object(operation_name, params)

### Description
Creates or updates an object (update if exists, create if not).

### Method
Not specified (assumed to be part of a client library)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters:
- `operation_name` (str): Upsert operation name (must start with 'upsert')
- `params` (dict): Operation parameters with 'data'

### Returns:
dict - Created or updated object

### Behavior:
- Detects upsert by operation name prefix
- Checks if object already exists using get_list operation
- If exists and equal: returns existing object with `config_changed = False`
- If exists and different: calls edit operation
- If not exists: calls add operation
- Raises FtdConfigurationError if multiple matching objects found or add not supported
```

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

### Set VMware Environment Variables

Source: https://github.com/ciscodevnet/ftdansible/blob/master/samples/deployment/vmware/README.md

Configures essential environment variables for vCenter connection. Replace the placeholder values with your actual vCenter hostname, username, and password.

```bash
export VMWARE_SERVER=...vCenter hostname...
export VMWARE_USERNAME=...vCenter username...
export VMWARE_PASSWORD=...vCenter password...
```

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

### FTD Object Reference Example

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/types-and-data-structures.md

A lightweight reference to another object, used for specifying relationships. Objects are compared by ID and type only.

```python
object_ref = {
    'id': 'network-uuid-123456',
    'type': 'networkobject'
}
```

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

### FT-Ansible Project File Structure

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/README.md

Outlines the directory layout of the FT-Ansible project, indicating the purpose of each main directory.

```text
ftdansible/
├── library/                           # Ansible modules
│   ├── ftd_configuration.py
│   ├── ftd_file_upload.py
│   ├── ftd_file_download.py
│   └── ftd_install.py
├── httpapi_plugins/                   # Connection plugins
│   └── ftd.py
├── module_utils/                      # Shared libraries
│   ├── common.py
│   ├── configuration.py
│   ├── device.py
│   └── fdm_swagger_client.py
├── samples/                           # Example playbooks
├── test/                              # Unit tests
└── docs/                              # Documentation build
```

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

### Parsed Swagger Output Format

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-fdm-swagger-client.md

Example of the output format produced by FdmSwaggerParser.parse_spec, detailing models, operations, and operations grouped by model.

```python
{
    'models': {
        'NetworkObject': {
            'type': 'object',
            'properties': {...},
            'required': ['name', 'value']
        }
    },
    'operations': {
        'addNetworkObject': {
            'method': 'post',
            'url': '/api/fdm/v2/object/networks',
            'modelName': 'NetworkObject',
            'returnMultipleItems': False,
            'parameters': {
                'path': {...},
                'query': {...}
            }
        }
    },
    'model_operations': {
        'NetworkObject': {
            'addNetworkObject': {...},
            'editNetworkObject': {...},
            'deleteNetworkObject': {...}
        }
    }
}
```

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

### Run Integration Tests with TOX

Source: https://github.com/ciscodevnet/ftdansible/blob/master/README.md

Executes integration tests in virtual environments using TOX. Requires setting the REPORTS_DIR environment variable and specifying test files and inventory.

```bash
export REPORTS_DIR=<path to the folder where JUnit reports will be stored>
tox -e py27-integration,py35-integration,py36-integration,py37-integration -- samples/network_object.yml -i inventory/sample_hosts

```

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

### Python Class Method: is_get_operation

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-configuration.md

Checks if an operation is a single object retrieval operation. It verifies the method is GET and returnMultipleItems is False.

```python
is_get_operation(operation_name, operation_spec)
```

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

### Ansible Module Execution Flow Diagram

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/INDEX.md

Illustrates the sequence of operations from playbook execution to FTD device interaction.

```text
Playbook → Ansible Module → Connection → HttpApi Plugin → FTD Device
                              ↓
                         BaseConfigurationResource
                         OperationChecker
                         OperationSpecParser
```

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

### Python Class Method: is_delete_operation

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-configuration.md

Checks if an operation is an object deletion operation. It verifies the name starts with 'delete' and the method is DELETE.

```python
is_delete_operation(operation_name, operation_spec)
```

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

### Build Docker Image for Tests

Source: https://github.com/ciscodevnet/ftdansible/blob/master/README.md

Builds the Docker image required for running unit tests. Ensure Ansible version in requirements.txt is as desired before building.

```bash
docker build -t ftd-ansible-test -f Dockerfile.tests .

```

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

### Python Class Method: is_edit_operation

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-configuration.md

Checks if an operation is an object update operation. It verifies the name starts with 'edit' and the method is PUT.

```python
is_edit_operation(operation_name, operation_spec)
```

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

### CRUD Operations for Network Objects

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/README.md

Demonstrates the syntax for Create, Read, Update, and Delete operations on network objects using the ftd_configuration module. Each operation specifies the command, HTTP method, and relevant parameters.

```yaml
CREATE: operation starts with 'add', method=POST
  → ftd_configuration:
      operation: addNetworkObject
      data: {name: test, value: 10.0.0.0/8}

READ:   operation starts with 'get', method=GET
  → ftd_configuration:
      operation: getNetworkObject
      path_params: {objId: abc123}

UPDATE: operation starts with 'edit', method=PUT
  → ftd_configuration:
      operation: editNetworkObject
      path_params: {objId: abc123}
      data: {description: updated}

DELETE: operation starts with 'delete', method=DELETE
  → ftd_configuration:
      operation: deleteNetworkObject
      path_params: {objId: abc123}
```

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

### Python Class Method: is_add_operation

Source: https://github.com/ciscodevnet/ftdansible/blob/master/_autodocs/module-utils-configuration.md

Checks if an operation is an object creation operation. It verifies the name starts with 'add' and the method is POST.

```python
is_add_operation(operation_name, operation_spec)
```