### Install Multiple Packages

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/package.md

This example demonstrates how to install multiple packages simultaneously by providing a list of package names.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

    oxlorg.opnsense.list:
      target: 'package'

  tasks:
    - name: Installing - multiple packages at once
      oxlorg.opnsense.package:
        name: ['os-api-backup', 'os-dmidecode']
        action: 'install'
```

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

### Basic FRR Configuration Example

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/frr_general.md

This example demonstrates a basic configuration of the FRR service. Ensure the FRR plugin is installed and the module is configured with appropriate credentials.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

  tasks:
    - name: Example
      oxlorg.opnsense.frr_general:
        # enabled: true
        # profile: 'traditional'
        # log: true
        # log_level: 'notifications'
        # snmp_agentx: false
        # carp: false
```

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

### Enabling FRR Service

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/frr_general.md

This example shows how to enable the FRR service with specific configurations for profile, logging, and log level. Ensure the FRR plugin is installed and the module is configured with appropriate credentials.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

  tasks:
    - name: Enabling FRR
      oxlorg.opnsense.frr_general:
        enabled: true
        profile: 'traditional'
        log: true
        log_level: 'notifications'
```

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

### Install Collection for Development

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/usage/4_develop.md

Install the collection from a Git repository to a specific directory for easier testing and development.

```bash
cd $PLAYBOOK_DIR
ansible-galaxy collection install git+https://github.com/O-X-L/ansible-opnsense.git,<RELEASE/BRANCH/COMMIT> -p ./collections
```

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

### Install BIND Plugin

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/bind.md

Install the BIND plugin using the command line. This can also be done via the package module.

```bash
os-bind
```

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

### Unbound General Configuration Example

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/unbound_general.md

This example demonstrates the basic structure for configuring Unbound. It shows how to set various parameters, most of which are commented out by default. Use this as a template for your Unbound configurations.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

  tasks:
    - name: Example
      oxlorg.opnsense.unbound_general:
        # enabled: true
        # port: 53
        # interfaces: ''
        # dnssec: false
        # dns64: false
        # dns64_prefix: '64:ff9b::/96'
        # aaaa_only_mode: false
        # register_dhcp_leases: false
        # dhcp_domain: ''
        # register_dhcp_static_mappings: false
        # register_ipv6_link_local: true
        # register_system_records: true
        # txt_records: false
        # flush_dns_cache: false
        # local_zone_type: 'transparent'
        # outgoing_interfaces: ''
        # wpad: false
        # reload: true

```

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

### Add a Monit Service

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/monit.md

Example of adding a basic Monit service with a name and description. Other parameters like type, pidfile, match, path, timeout, address, interface, start, stop, tests, depends, polltime, and enabled can be configured.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

    oxlorg.opnsense.list:
      target: 'monit_service'

  tasks:
    - name: Example      
      oxlorg.opnsense.monit_service:
        name: 'example'
        # type: ''
        # pidfile: ''
        # match: ''
        # path: ''
        # timeout: 300
        # address: ''
        # interface: ''
        # start: ''
        # stop: ''
        # tests: []
        # depends: []
        # polltime: ''
        # description: 'example'
        # enabled: true
        # reload: true
```

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

### Install Unit Test Dependencies

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/usage/4_develop.md

Install the necessary Python packages for running unit tests.

```bash
pip install -r requirements_unittest.txt
```

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

### Re-install a Package

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/package.md

This example shows how to re-install a package. This can be useful for troubleshooting or ensuring the package is in a known state.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

    oxlorg.opnsense.list:
      target: 'package'

  tasks:
    - name: Re-installing
      oxlorg.opnsense.package:
        name: 'os-api-backup'
        action: 'reinstall'
```

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

### Install HAProxy Plugin

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/haproxy.md

Installs the os-haproxy plugin on OPNsense. This is a prerequisite for using the HAProxy Ansible modules.

```bash
os-haproxy
```

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

### Basic Snapshot Management Example

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/snapshot.md

This example demonstrates how to create a snapshot named 'known-good'. Optional parameters like 'activate' and 'state' can be uncommented to modify behavior.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

    oxlorg.opnsense.list:
      target: 'snapshot'

  tasks:
    # add optional parameters commented-out
    # required ones normally
    # add their default values to get a brief overview of how the module works
    - name: Example
      oxlorg.opnsense.snapshot:
        name: 'known-good'
        # activate: false
        # state: 'absent'
        # debug: false

    - name: Create known-good snapshot
      oxlorg.opnsense.snapshot:
        name: 'known-good'
```

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

### Install a Single Package

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/package.md

Use this snippet to install a single package on the OPNsense firewall. Ensure the package name is correct.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

    oxlorg.opnsense.list:
      target: 'package'

  tasks:
    - name: Installing
      oxlorg.opnsense.package:
        name: 'os-api-backup'
        action: 'install'
```

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

### Add DNS Blocklist with Specific Providers

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/unbound_dnsbl.md

This example demonstrates how to add a DNS blocklist named 'example DNS-BL' using the 'atf' provider. It also shows commented-out parameters for further customization.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

    oxlorg.opnsense.list:
      target: 'unbound_dnsbl'

  tasks:
    # add optional parameters commented-out
    # required ones normally
    # add their default values to get a brief overview of how the module works
    - name: Example
      oxlorg.opnsense.unbound_dnsbl:
        name: 'example DNS-BL'
        providers: ['atf']
        # download_urls: ['https://example.com/dns.blocklist']
        # domains_allow: ['opnsense.org', 'oxl.at']
        # domains_block: ['example.porn.org']
        # wildcard_domains_block: ['evil.org']
        # source_networks: ['10.0.10.0/24', '10.2.10.0/24']
        # nxdomain_address: '192.168.255.255'
        # nxdomain: false
        # enabled: false
        # state: 'absent'
        # debug: false

```

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

### Install Ansible OPNsense Collection

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/README.md

Install the Ansible collection for OPNsense from GitHub or Ansible Galaxy. The latest version can be installed directly from the Git repository.

```bash
# latest version:
ansible-galaxy collection install git+https://github.com/O-X-L/ansible-opnsense.git
```

```bash
# stable/tested version:
ansible-galaxy collection install git+https://github.com/O-X-L/ansible-opnsense.git,25.7.8
```

```bash
## OR
ansible-galaxy collection install oxlorg.opnsense
```

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

### Install Ansible Collection (Latest from Git)

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/usage/1_install.md

Install the latest development version of the Ansible collection directly from the GitHub repository.

```bash
ansible-galaxy collection install git+https://github.com/O-X-L/ansible-opnsense.git
```

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

### Unlock a Package

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/package.md

This example demonstrates how to unlock a previously locked package, allowing it to be updated or managed again.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

    oxlorg.opnsense.list:
      target: 'package'

  tasks:
    - name: Unlocking
      oxlorg.opnsense.package:
        name: 'os-api-backup'
        action: 'unlock'
```

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

### Install Nginx Plugin

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/nginx.md

Install the os-nginx plugin using the command line. This plugin is a prerequisite for using the Nginx Ansible modules.

```bash
os-nginx
```

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

### Install os-squid Plugin

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/webproxy.md

Installs the os-squid plugin required for Web Proxy functionality. This can also be managed by the oxlorg.opnsense.package module.

```bash
os-squid
```

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

### Add an Alias with Default Settings

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/alias.md

This example demonstrates adding an alias with minimal required parameters. The 'name' and 'content' are essential.

```yaml
- name: Adding
  oxlorg.opnsense.alias:
    name: 'ANSIBLE_TEST2'
    content: '192.168.1.1'
```

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

### Pytest Mocking HTTP Responses Example

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/usage/4_develop.md

A starting point for utilizing HTTP response mocking in Pytest. This example demonstrates how to set up mock responses using a test data controller.

```python
from ansible_collections.oxlorg.opnsense.plugins.module_utils.test.testdata.<module>_testdata import Testdata_25_7_3

def test_multi_validate_entry(mocker, entry, entry_args, fail_verify, raises):
    testdata = Testdata_25_7_3()
    pytest_mock_http_responses(
        mocker=mocker,
        handler=testdata,
    )

# test go here

```

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

### Configure Web Proxy General Settings

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/webproxy.md

This example demonstrates how to configure the general settings for the web proxy. It shows how to set various parameters like ICP port, logging, and DNS servers. Use this snippet to manage the global web proxy configuration.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

    oxlorg.opnsense.list:
      target: 'webproxy_general'

  tasks:
    - name: Example
      oxlorg.opnsense.webproxy_general:
        # errors: 'opnsense'
        # icp_port: ''
        # log: true
        # log_store: true
        # log_target: 'file'
        # log_ignore: []
        # dns_servers: []
        # use_via_header: true
        # suppress_version: false
        # pinger: true
        # hostname: ''
        # connect_timeout: ''
        # email: 'admin@localhost.local'
        # handling_forwarded_for: 'default'
        # handling_uri_whitespace: 'strip'
        # errors: 'opnsense'
        # enabled: true
        # reload: true
        # debug: false

    - name: Pulling settings
      oxlorg.opnsense.list:
      #  target: 'webproxy_general'
      register: current_config

    - name: Printing settings
      ansible.builtin.debug:
        var: current_config.data
```

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

### Install Tester Dependencies

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/tests/README.md

Installs necessary Python packages for testing from the requirements_test.txt file.

```bash
python3 -m pip install -r requirements_test.txt
```

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

### Reloading Multiple Configuration Targets

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/general/reload.md

This example demonstrates reloading multiple OPNsense configuration targets sequentially using a loop. It's useful after making several changes to different components.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

  tasks:
    - name: Adding routes
      oxlorg.opnsense.route:
        network: "{{ item.nw }}"
        gateway: "{{ item.gw }}"
        reload: false
      loop:
        - {nw: '10.206.0.0/16', gw: 'VPN_GW'}
        - {nw: '10.67.0.0/16', gw: 'VPN2_GW'}

    - name: Adding DNS overrides
      oxlorg.opnsense.unbound_host:
        hostname: "{{ item.host }}"
        domain: 'opnsense.template.opnsense.oxl.app'
        value: "{{ item.value }}"
        reload: false
      loop:
        - {host: 'a', value: '192.168.0.1'}
        - {host: 'd', value: '192.168.0.5'}

    - name: Reloading
      oxlorg.opnsense.reload:
        target: "{{ item }}"
      loop:
        - 'route'
        - 'unbound'
```

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

### Install FRR Plugin

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/frr_bfd.md

Installs the FRR plugin using the default package manager.

```shell
os-frr
```

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

### Install Ansible Collection (Stable)

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/usage/1_install.md

Install the stable version of the Ansible collection using ansible-galaxy.

```bash
ansible-galaxy collection install oxlorg.opnsense
```

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

### Manage Multiple Bind Records

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/bind.md

This example demonstrates how to manage multiple DNS records using the `bind_record_multi` module. It shows how to add a new record with specific details.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

    oxlorg.opnsense.bind_record_multi:
      match_fields: ['domain', 'name', 'type']

  tasks:
    - name: Example
      oxlorg.opnsense.bind_record_multi:
        records:
          - name: 'example'
            domain: 'template.opnsense.oxl.app'
            value: '192.168.1.1'

        multi_control:
          # fail_verify: false
          # fail_processing: false
          # enabled: true
          # output_info: false

        # match_fields: ['domain', 'name', 'type']
        # reload: true

```

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

### Install httpx Python Module

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/README.md

Install or upgrade the httpx Python module, which is required for API communications.

```bash
python3 -m pip install --upgrade httpx
```

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

### Configure DNSMasq Boot Options

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/dnsmasq.md

Configure PXE boot settings using the `oxlorg.opnsense.dnsmasq_boot` module. This is essential for network booting clients, specifying boot file names and server addresses.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.oxlorg.net'
      api_credential_file: '/home/guy/.secret/opn.key'

    oxlorg.opnsense.list:
      target: 'dnsmasq_boot'

  tasks:
    - name: Example
      oxlorg.opnsense.dnsmasq_boot:
        description: 'Boot PXELinux'
        # interface:
        # tag:
        filename: '/tftpboot/pxelinux.0'
        # servername:
        # address:
        # state: 'absent'
        # debug: false

    - name: Adding something
      oxlorg.opnsense.dnsmasq_boot:
        description: 'Boot PXELinux'
        filename: '/tftpboot/pxelinux.0'

    - name: Changing something
      oxlorg.opnsense.dnsmasq_boot:
        description: 'Boot PXELinux'
        filename: '/tftpboot/pxelinux.0'
        address: '192.168.1.1'

    - name: Listing Boot
      oxlorg.opnsense.list:
      #  target: 'dnsmasq_boot'
      register: existing_boot

    - name: Printing
      ansible.builtin.debug:
        var: existing_boot.data
```

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

### List and Debug Snapshots

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/snapshot.md

This example shows how to list existing snapshots using the 'oxlorg.opnsense.list' module with the target set to 'snapshot', and then prints the retrieved snapshot data using the 'ansible.builtin.debug' module.

```yaml
- name: Listing snapshots
  oxlorg.opnsense.list:
  #  target: 'snapshot'
  register: existing_snapshots

- name: Printing snapshots
  ansible.builtin.debug:
    var: existing_snapshots.data
```

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

### List Installed Packages

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/package.md

This snippet uses the `oxlorg.opnsense.list` module to retrieve a list of installed packages. The output is registered and can be further processed.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

    oxlorg.opnsense.list:
      target: 'package'

  tasks:
    - name: Listing
      oxlorg.opnsense.list:
      #  target: 'package'
      register: existing_entries

    - name: Printing installed packages
      ansible.builtin.debug:
        var: existing_entries.data
```

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

### FRR Diagnostic Example

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/frr_diagnostic.md

Example of using the frr_diagnostic module to retrieve general routing information and then printing the retrieved data.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

  tasks:
    - name: Example
      oxlorg.opnsense.frr_diagnostic:
        target: 'generalroute'
      register: frr_info

    - name: Printing
      ansible.builtin.debug:
        var: frr_info.data
```

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

### Add Syslog Entry

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/syslog.md

This example demonstrates how to add a new syslog entry to the OPNsense firewall configuration. It specifies the target IP address for the syslog server.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

    oxlorg.opnsense.syslog:
      match_fields: ['description']

    oxlorg.opnsense.list:
      target: 'syslog'

  tasks:
    - name: Example
      oxlorg.opnsense.syslog:
        target: '192.168.0.1'
        # port: 514
        # transport: 'udp4'
        # level: ['info', 'notice', 'warn', 'err', 'crit', 'alert', 'emerg']
        # program: ['firewall', 'openvpn']
        # facility: ['security']
        # certificate: 'certificate-id'
        # rfc5424: false
        # description: 'example'
        # match_fields: ['target', 'facility', 'program']

    - name: Adding 1
      oxlorg.opnsense.syslog:
        description: 'test1'
        target: '192.168.0.1'
        # match_fields: ['description']

    - name: Listing
      oxlorg.opnsense.list:
      #  target: 'syslog'
      register: existing_entries

    - name: Printing entries
      ansible.builtin.debug:
        var: existing_entries.data
```

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

### Use Shorter Parameter Aliases

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/rule_multi.md

This example shows how to use shorter aliases for rule parameters to simplify configuration. It includes aliases for source, destination, destination port, protocol, interface, and enabled status.

```yaml
- name: Changing
  oxlorg.opnsense.rule_multi:
    rules:
      - name: 'test1'
        src: 'ALIAS_URLTABLE_TOR_EXIT_NODES'
        int: 'wan'
        action: 'block'

      - name: 'test2'
        src: 'ALIAS_URLTABLE_TOR_EXIT_NODES'
        int: 'wan'
        action: 'block'
        ip_proto: 'inet6'
        state: 'absent'

      - name: 'test3'
        s: '192.168.0.0/16'  # source
        d: '10.81.53.0/24'  # destination
        dp: 443  # destination_port
        p: 'TCP'  # protocol
        i: ['lan', 'opt1']  # interface
        en: false  # enabled

    # match_fields: ['description']

```

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

### Install Ansible Collection to Specific Directory

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/usage/1_install.md

Install the Ansible collection from GitHub to a specific local directory for development purposes. Ensure you are in your playbook directory before running.

```bash
cd $PLAYBOOK_DIR
ansible-galaxy collection install git+https://github.com/O-X-L/ansible-opnsense.git -p ./collections
```

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

### Basic OPNsense Rule Configuration

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/rule.md

Demonstrates a basic Ansible task to create or manage a firewall rule on OPNsense. It specifies source, destination, port, protocol, and description, with `match_fields` set to 'description' for unique identification. Includes examples of listing existing rules and debugging.

```yaml
- hosts: firewalls
  connection: local
  gather_facts: false
  module_defaults:
    group/oxlorg.opnsense.all:
      firewall: 'opnsense.template.opnsense.oxl.app'
      api_credential_file: '/home/guy/.secret/opn.key'

    oxlorg.opnsense.list:
      target: 'rule'

  tasks:
    - name: Example
      oxlorg.opnsense.rule:
        source_net: '192.168.0.0/24'  # host, network, alias or 'any'
        destination_net: '192.168.10.0/24'
        destination_port: 443  # alias not supported, leave unset for 'any'
        protocol: 'TCP'
        description: 'Generic test'
        match_fields: ['description']
        # sequence: 1
        # action: 'pass'
        # quick: true
        # interface: 'lan'
        # interface_invert: false
        # direction: 'in'
        # ip_protocol: 'inet' or 'inet6'
        # source_invert: false
        # source_port: ''
        # destination_invert: false
        # gateway: 'LAN_GW'
        # replyto: ''
        # disable_replyto: false
        # log: true
        # allow_opts: false
        # state_type: keep
        # state_policy: None
        # state_timeout: None
        # max_states: None
        # max_src_nodes: None
        # max_src_states: None
        # max_src_conn: None
        # max_src_conn_rate: None
        # max_src_conn_rates: None
        # overload: None
        # adaptive_start: None
        # adaptive_end: None
        # prio: ''
        # set_prio: ''
        # set_prio_low: ''
        # tag: ''
        # tagged: ''
        # tcp_flags: None
        # tcp_flags_clear: None
        # schedule: None
        # tos: None
        # icmp_type: []
        # state: 'present'
        # enabled: true
        # uuid: 'a9d85c00-0aa2-4705-b855-96aae16e05d7'  # optionally use uuid to identify existing rules
        # debug: true
        # reload: true

    - name: Listing
      oxlorg.opnsense.list:
      #  target: 'rule'
      register: existing_entries

    - name: Printing rules
      ansible.bultin.debug:
        var: existing_entries.data
```

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

### List OpenVPN Clients

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/openvpn.md

This snippet demonstrates how to list existing OpenVPN client configurations and print their data. It uses the `oxlorg.opnsense.list` module.

```yaml
    - name: Listing
      oxlorg.opnsense.list:
        # target: 'openvpn_instance'
      register: existing_entries

    - name: Printing instances
      ansible.builtin.debug:
        var: existing_entries.data
```

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

### Run All Test Modules

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/tests/README.md

Executes all test modules. Requires firewall, API key file, local collection path (or '0' to clone), and optional virtual environment path.

```bash
bash scripts/test.sh
> Arguments:
>   1: firewall
>   2: api key file
>   3: path to local collection - set to '0' to clone from github
>   4: path to virtual environment (optional)
```

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

### Add and Update Multiple Rules

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/basics/multi.md

This example shows how to manage multiple firewall rules using the `rule_multi` module. It includes rules with various configurations like source/destination networks, protocols, and actions.

```yaml
- name: Adding & Updating multiple Aliases
  oxlorg.opnsense.rule_multi:
    rules:
      - name: 'ANSIBLE_TEST_2_1'
        source_net: '192.168.1.0/24'
        destination_invert: true
        destination_net: '10.1.0.0/8'
        action: 'block'

      - name: 'ANSIBLE_TEST_2_2'
        source_net: '192.168.0.0/24'
        destination_net: '192.168.10.0/24'
        destination_port: 8080
        protocol: 'TCP'
        interface: ['lan']

      - name: 'ANSIBLE_TEST_2_3'
        source_invert: true
        source_net: 'bogons'
        ip_protocol: 'inet6'
        action: 'block'

    multi_control:
      purge_unconfigured: true  # remove all existing entries not found in the provided entries (unconfigured/orphaned)
```

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

### Dnsmasq Tag Module Usage

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/dnsmasq.md

Examples of how to use the oxlorg.opnsense.dnsmasq_tag module to add or remove tags.

```APIDOC
## oxlorg.opnsense.dnsmasq_tag

### Description
Manages Dnsmasq tags on OPNsense firewalls.

### Parameters
#### Parameters
- **tag** (string) - Required - The name of the tag to manage.
- **state** (string) - Optional - The desired state of the tag. Can be 'present' (default) or 'absent'.
- **debug** (boolean) - Optional - Enable debug logging. Defaults to false.
```

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

### Disable an Alias

Source: https://github.com/o-x-l/ansible-opnsense/blob/latest/docs/source/modules/alias.md

This example shows how to disable an alias without removing it, by setting the 'enabled' parameter to 'false'.

```yaml
- name: Disabling
  oxlorg.opnsense.alias:
    name: 'ANSIBLE_TEST2'
    enabled: false
```