Merge pull request #101 from scsitteam/dhcrelay

Feature: Add modules for dhcrelay

docs/source/modules/2_reload.rst

@@ -26,7 +26,7 @@ Definition
     :header: "Parameter", "Type", "Required", "Default", "Aliases", "Comment"
     :widths: 15 10 10 10 10 45
 
-    "target","string","true","\-","tgt, t","What part of the running config should be reloaded. One of: 'alias', 'rule', 'route', 'cron', 'unbound', 'syslog', 'ipsec', 'ipsec_legacy', 'shaper', 'monit', 'wireguard', 'interface_vlan', 'interface_vxlan', 'interface_vip', 'interface_lagg', 'frr', 'webproxy', 'bind', 'ids'"
+    "target","string","true","\-","tgt, t","What part of the running config should be reloaded. One of: 'alias', 'rule', 'route', 'cron', 'unbound', 'syslog', 'ipsec', 'ipsec_legacy', 'shaper', 'monit', 'wireguard', 'interface_vlan', 'interface_vxlan', 'interface_vip', 'interface_lagg', 'frr', 'webproxy', 'bind', 'ids', 'dhcrelay'"
 
 .. include:: ../_include/param_basic.rst
 

docs/source/modules/dhcrelay_destination.rst

@@ -0,0 +1,83 @@
+.. _modules_dhcrelay_destination:
+
+.. include:: ../_include/head.rst
+
+=============================
+DHCRelay - Destinations
+=============================
+
+**STATE**: stable
+
+**TESTS**: `Playbook <https://github.com/ansibleguy/collection_opnsense/blob/latest/tests/dhcrelay_destination.yml>`_
+
+**API Docs**: `Core - DHCRelay <https://docs.opnsense.org/development/api/core/dhcrelay.html>`_
+
+**Service Docs**: `DHCRelay <https://docs.opnsense.org/manual/dhcp.html#dhcrelay>`_
+
+
+Definition
+**********
+
+..  csv-table:: Definition
+    :header: "Parameter", "Type", "Required", "Default", "Aliases", "Comment"
+    :widths: 15 10 10 10 10 45
+
+    "name","string","true","","\-","Unique name for this relay destination"
+    "server","list of strings","true","\-","\-","List of server IP addresses to relay DHCP requests to"
+    "reload","boolean","false","true","\-", .. include:: ../_include/param_reload.rst
+
+.. include:: ../_include/param_basic.rst
+
+Info
+****
+
+This module manages DHCRelay destinations. A destination can contain multiple IP addresses.
+
+Note: You can also use the shortform module name: :code:`ansibleguy.opnsense.dhcrelay_dst`
+
+Examples
+********
+
+.. code-block:: yaml
+
+    - hosts: localhost
+      gather_facts: no
+      module_defaults:
+        group/ansibleguy.opnsense.all:
+          firewall: 'opnsense.template.ansibleguy.net'
+          api_credential_file: '/home/guy/.secret/opn.key'
+
+        ansibleguy.opnsense.list:
+          target: 'dhcrelay_destination'
+
+      tasks:
+        - name: Example
+          ansibleguy.opnsense.dhcrelay_destination:
+            name: 'mydhcp'
+            server:
+              - '192.168.0.1'
+            # state: 'present'
+            # reload: true
+            # debug: false
+
+        - name: Adding
+          ansibleguy.opnsense.dhcrelay_destination:
+            name: 'mydhcp'
+            server:
+              - '192.168.0.1'
+
+        - name: Removing
+          ansibleguy.opnsense.dhcrelay_destination:
+            name: 'mydhcp'
+            server:
+              - '192.168.0.1'
+            state: 'absent'
+
+        - name: Listing
+          ansibleguy.opnsense.list:
+          #  target: 'dhcrelay_destination'
+          register: existing_entries
+
+        - name: Printing dhcrelay destinations
+          ansible.builtin.debug:
+            var: existing_entries.data

docs/source/modules/dhcrelay_relay.rst

@@ -0,0 +1,84 @@
+.. _modules_dhcrelay_relay:
+
+.. include:: ../_include/head.rst
+
+=============================
+DHCRelay - Relay
+=============================
+
+**STATE**: stable
+
+**TESTS**: `Playbook <https://github.com/ansibleguy/collection_opnsense/blob/latest/tests/dhcrelay_destination.yml>`_
+
+**API Docs**: `Core - DHCRelay <https://docs.opnsense.org/development/api/core/dhcrelay.html>`_
+
+**Service Docs**: `DHCRelay <https://docs.opnsense.org/manual/dhcp.html#dhcrelay>`_
+
+
+Definition
+**********
+
+..  csv-table:: Definition
+    :header: "Parameter", "Type", "Required", "Default", "Aliases", "Comment"
+    :widths: 15 10 10 10 10 45
+
+    "enabled","boolean","false","false","\-","Enable or disable this relay"
+    "interface","string","true","","i, int"," The interface to relay DHCP requests from"
+    "destination","string","true","\-","dest"," The destination server group to relay DHCP requests to"
+    "agent_info","boolean","false","false","\-","Add the relay agent information option"
+    "reload","boolean","false","true","\-", .. include:: ../_include/param_reload.rst
+
+.. include:: ../_include/param_basic.rst
+
+Info
+****
+
+This module manages DHCRelay relays. Each interface can be assigned a single relay.
+
+Note: You can also use the shortform module name: :code:`ansibleguy.opnsense.dhcrelay`
+
+Examples
+********
+
+.. code-block:: yaml
+
+    - hosts: localhost
+      gather_facts: no
+      module_defaults:
+        group/ansibleguy.opnsense.all:
+          firewall: 'opnsense.template.ansibleguy.net'
+          api_credential_file: '/home/guy/.secret/opn.key'
+
+        ansibleguy.opnsense.list:
+          target: 'dhcrelay_relay'
+
+      tasks:
+        - name: Example
+          ansibleguy.opnsense.dhcrelay_relay:
+            interface: 'lan'
+            destination: mydhcp
+            # enabled: false
+            # agent_info: false
+            # state: 'present'
+            # reload: true
+            # debug: false
+
+        - name: Adding
+          ansibleguy.opnsense.dhcrelay_relay:
+            interface: 'lan'
+            destination: mydhcp
+
+        - name: Removing
+          ansibleguy.opnsense.dhcrelay_relay:
+            interface: 'lan'
+            destination: mydhcp
+            state: 'absent'
+
+        - name: Listing
+          ansibleguy.opnsense.list:
+          #  target: 'dhcrelay_relay'
+          register: existing_entries
+
+        - name: Printing dhcrelay relays
+          ansible.builtin.debug:
+            var: existing_entries.data

meta/runtime.yml

@@ -120,6 +120,9 @@ action_groups:
     - ansibleguy.opnsense.openvpn_client_override
     - ansibleguy.opnsense.openvpn_client_template
     - ansibleguy.opnsense.openvpn_client_export
+  dhcrelay:
+    - ansibleguy.opnsense.dhcrelay_destination
+    - ansibleguy.opnsense.dhcrelay_relay
   all:
     - metadata:
         extend_group:
@@ -141,6 +144,7 @@ action_groups:
           - ansibleguy.opnsense.system
           - ansibleguy.opnsense.ids
           - ansibleguy.opnsense.openvpn
+          - ansibleguy.opnsense.dhcrelay
 
 plugin_routing:
   modules:
@@ -182,3 +186,7 @@ plugin_routing:
       redirect: ansibleguy.opnsense.gateway
     rule_if_group:
       redirect: ansibleguy.opnsense.rule_interface_group
+    dhcrelay:
+      redirect: ansibleguy.opnsense.dhcrelay_relay
+    dhcrelay_dst:
+      redirect: ansibleguy.opnsense.dhcrelay_destination

plugins/module_utils/main/dhcrelay_destination.py

@@ -0,0 +1,42 @@
+from ansible.module_utils.basic import AnsibleModule
+
+from ansible_collections.ansibleguy.opnsense.plugins.module_utils.base.api import \
+    Session
+from ansible_collections.ansibleguy.opnsense.plugins.module_utils.helper.main import \
+    is_unset
+from ansible_collections.ansibleguy.opnsense.plugins.module_utils.base.cls import BaseModule
+
+
+class DhcRelayDestination(BaseModule):
+    FIELD_ID = 'name'
+    CMDS = {
+        'add': 'addDest',
+        'del': 'delDest',
+        'set': 'setDest',
+        'search': 'get',
+    }
+    API_KEY_PATH = 'dhcrelay.destinations'
+    API_KEY_PATH_REQ = 'destination'
+    API_MOD = 'dhcrelay'
+    API_CONT = 'settings'
+    API_CONT_REL = 'service'
+    API_CMD_REL = 'reconfigure'
+    FIELDS_CHANGE = ['server']
+    FIELDS_ALL = [FIELD_ID]
+    FIELDS_ALL.extend(FIELDS_CHANGE)
+    FIELDS_TYPING = {
+        'list': ['server'],
+    }
+    EXIST_ATTR = 'destination'
+
+    def __init__(self, module: AnsibleModule, result: dict, session: Session = None):
+        BaseModule.__init__(self=self, m=module, r=result, s=session)
+        self.destination = {}
+
+    def check(self) -> None:
+
+        if self.p['state'] == 'present':
+            if is_unset(self.p['server']):
+                self.m.fail_json("You need to provide list of 'server' to create a dhcrelay_destination!")
+
+        self._base_check()

plugins/module_utils/main/dhcrelay_relay.py

@@ -0,0 +1,59 @@
+from ansible.module_utils.basic import AnsibleModule
+
+from ansible_collections.ansibleguy.opnsense.plugins.module_utils.base.api import \
+    Session
+from ansible_collections.ansibleguy.opnsense.plugins.module_utils.helper.main import \
+    is_unset
+from ansible_collections.ansibleguy.opnsense.plugins.module_utils.base.cls import BaseModule
+
+
+class DhcRelayRelay(BaseModule):
+    FIELD_ID = 'interface'
+    CMDS = {
+        'add': 'addRelay',
+        'del': 'delRelay',
+        'set': 'setRelay',
+        'search': 'get',
+        'toggle': 'toggleRelay',
+    }
+    API_KEY_PATH = 'dhcrelay.relays'
+    API_KEY_PATH_REQ = 'relay'
+    API_MOD = 'dhcrelay'
+    API_CONT = 'settings'
+    API_CONT_REL = 'service'
+    API_CMD_REL = 'reconfigure'
+    FIELDS_CHANGE = ['destination', 'agent_info']
+    FIELDS_ALL = [FIELD_ID, 'enabled']
+    FIELDS_ALL.extend(FIELDS_CHANGE)
+    FIELDS_TYPING = {
+        'select': ['interface', 'destination'],
+        'bool': ['enabled', 'agent_info']
+    }
+    EXIST_ATTR = 'relay'
+    SEARCH_ADDITIONAL = {
+        'existing_destinations': 'dhcrelay.destinations',
+    }
+
+    def __init__(self, module: AnsibleModule, result: dict, session: Session = None):
+        BaseModule.__init__(self=self, m=module, r=result, s=session)
+        self.relay = {}
+        self.existing_destinations = None
+
+    def check(self) -> None:
+        if self.p['state'] == 'present':
+            if is_unset(self.p['destination']):
+                self.m.fail_json("You need to provide a 'destination' to create a dhcrelay_relay!")
+
+        self._base_check()
+
+        if not is_unset(self.p['destination']) and self.existing_destinations:
+            for key, values in self.existing_destinations.items():
+                if values['name'] == self.p['destination']:
+                    self.p['destination'] = key
+                    break
+
+    def get_existing(self) -> list:
+        existing = self.b.get_existing()
+        for relay in existing:
+            relay['destination'] = self.existing_destinations[relay['destination']]['name']
+        return existing

plugins/modules/dhcrelay_destination.py

@@ -0,0 +1,66 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright: (C) 2024, AnsibleGuy <[email protected]>
+# GNU General Public License v3.0+ (see https://www.gnu.org/licenses/gpl-3.0.txt)
+
+# see: https://docs.opnsense.org/development/api/core/dhcrelay.html
+
+from ansible.module_utils.basic import AnsibleModule
+
+from ansible_collections.ansibleguy.opnsense.plugins.module_utils.base.handler import \
+    module_dependency_error, MODULE_EXCEPTIONS
+
+try:
+    from ansible_collections.ansibleguy.opnsense.plugins.module_utils.helper.wrapper import module_wrapper
+    from ansible_collections.ansibleguy.opnsense.plugins.module_utils.defaults.main import \
+        OPN_MOD_ARGS, STATE_ONLY_MOD_ARG, RELOAD_MOD_ARG
+    from ansible_collections.ansibleguy.opnsense.plugins.module_utils.main.dhcrelay_destination import \
+        DhcRelayDestination
+
+except MODULE_EXCEPTIONS:
+    module_dependency_error()
+
+
+# DOCUMENTATION = 'https://opnsense.ansibleguy.net/en/latest/modules/dhcrelay_destination.html'
+# EXAMPLES = 'https://opnsense.ansibleguy.net/en/latest/modules/dhcrelay_destination.html'
+
+
+def run_module():
+    module_args = dict(
+        name=dict(
+            type='str', required=True,
+            description='A unique name for this relay destination.',
+        ),
+        server=dict(
+            type='list', elements='str', required=False,
+            description='A list of server IP addresses to relay DHCP requests to.'
+        ),
+        **RELOAD_MOD_ARG,
+        **STATE_ONLY_MOD_ARG,
+        **OPN_MOD_ARGS,
+    )
+
+    result = dict(
+        changed=False,
+        diff={
+            'before': {},
+            'after': {},
+        }
+    )
+
+    module = AnsibleModule(
+        argument_spec=module_args,
+        supports_check_mode=True,
+    )
+
+    module_wrapper(DhcRelayDestination(module=module, result=result))
+    module.exit_json(**result)
+
+
+def main():
+    run_module()
+
+
+if __name__ == '__main__':
+    main()