search

puzzle / puzzle.opnsense

An Ansible Collection to configure an opnsense Firewall
https://puzzle.github.io/puzzle.opnsense/collections/puzzle/opnsense/index.html
GNU General Public License v3.0
23 stars 12 forks source link

Introducing module firewall_alias #137

Closed KiLLuuuhh closed 2 weeks ago

KiLLuuuhh commented 2 months ago

This pull requests introduces the module firewall_alias to the puzzle.opnsense collection.

With this new module, user will be able to:

  1. set name for alias
  2. set different alias types of content such as:
    • host
    • network
    • port
    • url
    • urltable
    • geoip
    • networkgroup
    • macaddress
    • bgpasn
    • dynamicipv6host
    • opnvpngroup
    • internal
    • external
  3. Set content and validate content of the types above.
  4. Enable statistics for the alias.
  5. Set a description for the alias.
  6. Set the refresh frequency for a urltable.
  7. Set the interface for dynamicipv6host.

Disclaimer: We are aware that this module is also offered by Ansibleguy. However, we have decided to develop it independently due to compatibility issues with the different versions we support.

nerrehmit commented 1 month ago

While testing your changes against a live opnsense 24.1 installation I found a couple of things. I'm going to report them individually so that you can comment/ close them each on their own.

nerrehmit commented 1 month ago

I was able to set a host alias with spaces in the name. However updating it within opnsense then gave me an error upon save. Here is the ansible snippet that worked:

  - name: set google dns alias
    puzzle.opnsense.firewall_alias:
      name: google DNS Server
      type: host
      content: 8.8.8.8
      description: The dns servers that google uses
      state: present
nerrehmit commented 1 month ago

BGP ASN aliases added through ansible do not display a Type, compared to BGP ASN Aliases added through the UI as you can see in the screenshot: image

EDIT: fixed by updates to the module :heavy_check_mark:

nerrehmit commented 1 month ago

running ansible against an opnsense instance with a manually added BGP ASN alias errors out like this:

An exception occurred during task execution. To see the full traceback, use -vvv. The error was: ValueError: 'FirewallAliasType' enum not found for 'asn'
fatal: [opnsense]: FAILED! => {
    "changed": false,
    "rc": 1
}

MSG:

MODULE FAILURE
See stdout/stderr for the exact error

MODULE_STDOUT:

Traceback (most recent call last):
  File "/root/.ansible/tmp/ansible-tmp-1720813227.9266646-65215-109775695243004/AnsiballZ_firewall_alias.py", line 107, in <module>
    _ansiballz_main()
  File "/root/.ansible/tmp/ansible-tmp-1720813227.9266646-65215-109775695243004/AnsiballZ_firewall_alias.py", line 99, in _ansiballz_main
    invoke_module(zipped_mod, temp_path, ANSIBALLZ_PARAMS)
  File "/root/.ansible/tmp/ansible-tmp-1720813227.9266646-65215-109775695243004/AnsiballZ_firewall_alias.py", line 47, in invoke_module
    runpy.run_module(mod_name='ansible_collections.puzzle.opnsense.plugins.modules.firewall_alias', init_globals=dict(_module_fqn='ansible_collections.puzzle.opnsense.plugins.modules.firewall_alias', _modlib_path=modlib_path),
  File "<frozen runpy>", line 226, in run_module
  File "<frozen runpy>", line 98, in _run_module_code
  File "<frozen runpy>", line 88, in _run_code
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/modules/firewall_alias.py", line 273, in <module>
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/modules/firewall_alias.py", line 232, in main
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/module_utils/firewall_alias_utils.py", line 275, in __init__
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/module_utils/firewall_alias_utils.py", line 288, in _load_aliases
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/module_utils/firewall_alias_utils.py", line 288, in <listcomp>
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/module_utils/firewall_alias_utils.py", line 174, in from_xml
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/module_utils/firewall_alias_utils.py", line 118, in __init__
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/module_utils/firewall_alias_utils.py", line 131, in __post_init__
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/module_utils/enum_utils.py", line 39, in from_string
ValueError: 'FirewallAliasType' enum not found for 'asn'

EDIT: fixed by updates to the module :heavy_check_mark:

nerrehmit commented 1 month ago

We should definitely explain the "refreshfrequency" a bit more. This input is considered fractions of a day. So a value of "0.5" leads to 12 hours, "1.1" to 1d 2.4h. The smallest possible value is "0.0003" which leads to 0.01h in the UI, so a refresh about every minute. This is the opnsense minimum according to https://forum.opnsense.org/index.php?topic=15483.0 I think we should have an example using that key.

Also this value only shows up in the UI if you configure type "urltable" but the module accepts it for other types. Not sure if that could lead to problems down the line?

nerrehmit commented 1 month ago

the BGP ASN type alias offers a selection for IPv4 and/or IPv6 when done through the UI. We do not have that option in our module yet. We should either add that functionality or mention that restriction in the docs to prevent any surprises for users.

KiLLuuuhh commented 1 month ago

BGP ASN aliases added through ansible do not display a Type, compared to BGP ASN Aliases added through the UI as you can see in the screenshot: image

fixed in 64ba9b0.

KiLLuuuhh commented 1 month ago

running ansible against an opnsense instance with a manually added BGP ASN alias errors out like this:

An exception occurred during task execution. To see the full traceback, use -vvv. The error was: ValueError: 'FirewallAliasType' enum not found for 'asn'
fatal: [opnsense]: FAILED! => {
    "changed": false,
    "rc": 1
}

MSG:

MODULE FAILURE
See stdout/stderr for the exact error

MODULE_STDOUT:

Traceback (most recent call last):
  File "/root/.ansible/tmp/ansible-tmp-1720813227.9266646-65215-109775695243004/AnsiballZ_firewall_alias.py", line 107, in <module>
    _ansiballz_main()
  File "/root/.ansible/tmp/ansible-tmp-1720813227.9266646-65215-109775695243004/AnsiballZ_firewall_alias.py", line 99, in _ansiballz_main
    invoke_module(zipped_mod, temp_path, ANSIBALLZ_PARAMS)
  File "/root/.ansible/tmp/ansible-tmp-1720813227.9266646-65215-109775695243004/AnsiballZ_firewall_alias.py", line 47, in invoke_module
    runpy.run_module(mod_name='ansible_collections.puzzle.opnsense.plugins.modules.firewall_alias', init_globals=dict(_module_fqn='ansible_collections.puzzle.opnsense.plugins.modules.firewall_alias', _modlib_path=modlib_path),
  File "<frozen runpy>", line 226, in run_module
  File "<frozen runpy>", line 98, in _run_module_code
  File "<frozen runpy>", line 88, in _run_code
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/modules/firewall_alias.py", line 273, in <module>
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/modules/firewall_alias.py", line 232, in main
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/module_utils/firewall_alias_utils.py", line 275, in __init__
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/module_utils/firewall_alias_utils.py", line 288, in _load_aliases
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/module_utils/firewall_alias_utils.py", line 288, in <listcomp>
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/module_utils/firewall_alias_utils.py", line 174, in from_xml
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/module_utils/firewall_alias_utils.py", line 118, in __init__
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/module_utils/firewall_alias_utils.py", line 131, in __post_init__
  File "/tmp/ansible_puzzle.opnsense.firewall_alias_payload_qmsbwmar/ansible_puzzle.opnsense.firewall_alias_payload.zip/ansible_collections/puzzle/opnsense/plugins/module_utils/enum_utils.py", line 39, in from_string
ValueError: 'FirewallAliasType' enum not found for 'asn'

fixed in https://github.com/puzzle/puzzle.opnsense/commit/64ba9b04fa2a6c3c634a465c1445949d00424fc8.

KiLLuuuhh commented 1 month ago

the BGP ASN type alias offers a selection for IPv4 and/or IPv6 when done through the UI. We do not have that option in our module yet. We should either add that functionality or mention that restriction in the docs to prevent any surprises for users.

fixed in 944146be1f972350e1779d206859dfb40463aa97.