From 66b44e84bbb5bcc45eee6b7673fedd004b486583 Mon Sep 17 00:00:00 2001 From: Philipp Matti Date: Thu, 27 Jul 2023 17:47:16 +0200 Subject: [PATCH 1/6] add example-module + update developers-guide: Vagrant section --- docs/docsite/rst/development_guide.rst | 60 ++++++++++++++++++- galaxy.yml | 1 + plugins/modules/get_xml_tag.py | 79 ++++++++++++++++++++++++++ 3 files changed, 137 insertions(+), 3 deletions(-) create mode 100644 plugins/modules/get_xml_tag.py diff --git a/docs/docsite/rst/development_guide.rst b/docs/docsite/rst/development_guide.rst index 1c12fa12..06aedc4e 100644 --- a/docs/docsite/rst/development_guide.rst +++ b/docs/docsite/rst/development_guide.rst @@ -28,7 +28,7 @@ Ansible documentation (`Prepare your environment collection. **The cloned repository must be cloned into a folder following this path structure:** ``/ansible_collections/puzzle/opnsense``. Therefore you could clone your fork like this: - + .. code-block:: shell-session git clone git@github.com//puzzle.opnsense \ @@ -39,7 +39,7 @@ Ansible documentation (`Prepare your environment 4. Setup the pipenv: .. code-block:: shell-session - + pipenv install --dev Your environment is now set up for local development and testing. @@ -71,7 +71,7 @@ Reusable code and utilities must be added in the ``module_utils`` directory. When these utils are needed e.g. in modules they must be imported using the FQCN e.g. ``from ansible_collections.puzzle.opnsense.plugins.module_utils.xml_utils import XMLParser``. -The official Ansible Documentation (`Collection Structure +The official Ansible Documentation (`Collection Structure `__) provides further reference regarding collection structure guidelines. @@ -105,6 +105,60 @@ Here's an example of how to use the `OPNsenseConfig` utility: del config["key"] # Delete a configuration value config.save() # Save changes +Using Vagrant +============= + +Run ansible directlyagainst a running instance of opnsense with Vagrant. +For this to work it is required to have **vagrant** installed alongside with **virtualbox**. + +.. code-block:: + + Vagrant.configure(2) do |config| + config.vm.guest = :freebsd + config.vm.boot_timeout = 600 + + config.vm.box = "puzzle/opnsense" + config.vm.communicator = 'ssh' + + config.ssh.sudo_command = "%c" + config.ssh.shell = "/bin/sh" + + config.vm.provider 'virtualbox' do |vb| + vb.memory = 1024 + vb.cpus = 1 + vb.gui = false + vb.customize ['modifyvm', :id, '--nicpromisc2', 'allow-all'] + vb.customize ['modifyvm', :id, '--nicpromisc3', 'allow-all'] + vb.customize ['modifyvm', :id, '--nicpromisc4', 'allow-all'] + end + + config.vm.network :forwarded_port, guest: 443, host: 10443, auto_correct: true + config.vm.network "private_network", adapter: 2, virtualbox__intnet: true, auto_config: false + config.vm.network "private_network", adapter: 3, virtualbox__intnet: true, auto_config: false + config.vm.network "private_network", adapter: 4, virtualbox__intnet: true, auto_config: false + + config.vm.provision "ansible" do |ansible| + ansible.playbook = "playbook.yml" + end + end + +Start up the vm + +.. code-block:: + + vagrant up + +Apply any changes made, while using the vm + +.. code-block:: + + vagrant provision + +Stop the current vm + +.. code-block:: + + vagrant down Testing Your Code ================= diff --git a/galaxy.yml b/galaxy.yml index 6609ae21..3f7ffb01 100644 --- a/galaxy.yml +++ b/galaxy.yml @@ -7,6 +7,7 @@ readme: README.md authors: - Lukas Grimm (github.com/ombre8) - Fabio Bertagna (github.com/dongiovanni83) + - Philipp Matti (github.com/acteru) description: OPNsense collection for Ansible license_file: LICENSE tags: diff --git a/plugins/modules/get_xml_tag.py b/plugins/modules/get_xml_tag.py new file mode 100644 index 00000000..b9c06070 --- /dev/null +++ b/plugins/modules/get_xml_tag.py @@ -0,0 +1,79 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- + +# Copyright: (c) 2023, Philipp Matti , Puzzle ITC +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +"""Example module: Show minimal functionality of OPNsenseConfig class""" + +DOCUMENTATION = r''' +--- +author: +- Philipp Matti (@acteru) +module: get_xml_tag +short_description: Get specific xml tag from /confg/config.xml +description: +- Example module to use OPNsenseConfig module_utils +options: + tag: + description: + - String to search for tag in xml. + type: str + required: true +''' + +EXAMPLES = r''' +- name: Print the opnsense xml + puzzle.opnsense.get_xml_tag: + path: /conf/config.xml + key: "sysctl" + register: xmlconfig + +- name: Print return value + ansible.builtin.debug: + msg: "{{ xmlconfig }}" +''' + +RETURN = r''' # ''' + +from ansible.module_utils.basic import AnsibleModule +from ansible_collections.puzzle.opnsense.plugins.module_utils import config_utils + +__metaclass__ = type + + +def main(): + """ + Return requested key from config.xml + """ + + module_args = { + "tag": {"type": "str", "required": True}, + } + + module = AnsibleModule( + argument_spec=module_args, + supports_check_mode=True + ) + + result = { + 'changed': False, + 'original_message': module.params, + 'message': '', + } + + # check-mode handler + if module.check_mode: + module.exit_json(**result) + + config_mgr = config_utils.OPNsenseConfig() + + # Get xml via key + result['message'] = config_mgr[str(module.params["tag"])] + + # Return results + module.exit_json(**result) + + +if __name__ == '__main__': + main() From 65c7ae295962236fad7f2da58bd81794b9efe15e Mon Sep 17 00:00:00 2001 From: Act Date: Thu, 27 Jul 2023 18:00:08 +0200 Subject: [PATCH 2/6] Update docs/docsite/rst/development_guide.rst Co-authored-by: Fabio Bertagna <33524186+DonGiovanni83@users.noreply.github.com> --- docs/docsite/rst/development_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/development_guide.rst b/docs/docsite/rst/development_guide.rst index 06aedc4e..dff44013 100644 --- a/docs/docsite/rst/development_guide.rst +++ b/docs/docsite/rst/development_guide.rst @@ -108,7 +108,7 @@ Here's an example of how to use the `OPNsenseConfig` utility: Using Vagrant ============= -Run ansible directlyagainst a running instance of opnsense with Vagrant. +Run ansible directly against a running instance of OPNsense with Vagrant. For this to work it is required to have **vagrant** installed alongside with **virtualbox**. .. code-block:: From af77f69eae1df28cc59f8bc4d0cec7757eed4e2c Mon Sep 17 00:00:00 2001 From: Act Date: Thu, 27 Jul 2023 18:01:06 +0200 Subject: [PATCH 3/6] Update plugins/modules/get_xml_tag.py Co-authored-by: Fabio Bertagna <33524186+DonGiovanni83@users.noreply.github.com> --- plugins/modules/get_xml_tag.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/modules/get_xml_tag.py b/plugins/modules/get_xml_tag.py index b9c06070..ed274022 100644 --- a/plugins/modules/get_xml_tag.py +++ b/plugins/modules/get_xml_tag.py @@ -26,7 +26,7 @@ - name: Print the opnsense xml puzzle.opnsense.get_xml_tag: path: /conf/config.xml - key: "sysctl" + tag: "sysctl" register: xmlconfig - name: Print return value From f11207e2feaad01f74f084fe220733157888654c Mon Sep 17 00:00:00 2001 From: Act Date: Thu, 27 Jul 2023 18:01:14 +0200 Subject: [PATCH 4/6] Update plugins/modules/get_xml_tag.py Co-authored-by: Fabio Bertagna <33524186+DonGiovanni83@users.noreply.github.com> --- plugins/modules/get_xml_tag.py | 1 - 1 file changed, 1 deletion(-) diff --git a/plugins/modules/get_xml_tag.py b/plugins/modules/get_xml_tag.py index ed274022..89934c33 100644 --- a/plugins/modules/get_xml_tag.py +++ b/plugins/modules/get_xml_tag.py @@ -25,7 +25,6 @@ EXAMPLES = r''' - name: Print the opnsense xml puzzle.opnsense.get_xml_tag: - path: /conf/config.xml tag: "sysctl" register: xmlconfig From d74885379a99c9b792d0f3d81827d17692398af6 Mon Sep 17 00:00:00 2001 From: Act Date: Thu, 27 Jul 2023 18:01:22 +0200 Subject: [PATCH 5/6] Update plugins/modules/get_xml_tag.py Co-authored-by: Fabio Bertagna <33524186+DonGiovanni83@users.noreply.github.com> --- plugins/modules/get_xml_tag.py | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/plugins/modules/get_xml_tag.py b/plugins/modules/get_xml_tag.py index 89934c33..396b7418 100644 --- a/plugins/modules/get_xml_tag.py +++ b/plugins/modules/get_xml_tag.py @@ -65,10 +65,9 @@ def main(): if module.check_mode: module.exit_json(**result) - config_mgr = config_utils.OPNsenseConfig() - - # Get xml via key - result['message'] = config_mgr[str(module.params["tag"])] + with config_utils.OPNsenseConfig() as config_mgr: + # Get xml via key + result['message'] = config_mgr[str(module.params["tag"])] # Return results module.exit_json(**result) From 390349c1439bd4a531e53d28a5b911a3665d5c45 Mon Sep 17 00:00:00 2001 From: Philipp Matti Date: Thu, 27 Jul 2023 18:16:58 +0200 Subject: [PATCH 6/6] change return values to default returns, add some usefull links as comments --- plugins/modules/get_xml_tag.py | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/plugins/modules/get_xml_tag.py b/plugins/modules/get_xml_tag.py index 396b7418..04dd8505 100644 --- a/plugins/modules/get_xml_tag.py +++ b/plugins/modules/get_xml_tag.py @@ -6,6 +6,7 @@ """Example module: Show minimal functionality of OPNsenseConfig class""" +# https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html DOCUMENTATION = r''' --- author: @@ -35,6 +36,7 @@ RETURN = r''' # ''' + from ansible.module_utils.basic import AnsibleModule from ansible_collections.puzzle.opnsense.plugins.module_utils import config_utils @@ -55,10 +57,12 @@ def main(): supports_check_mode=True ) + # https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html + # https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#return-block result = { 'changed': False, - 'original_message': module.params, - 'message': '', + 'invocation': module.params, + 'msg': '', } # check-mode handler @@ -67,7 +71,7 @@ def main(): with config_utils.OPNsenseConfig() as config_mgr: # Get xml via key - result['message'] = config_mgr[str(module.params["tag"])] + result['msg'] = config_mgr[str(module.params["tag"])] # Return results module.exit_json(**result)