PFSenseModuleBase Template

Template

#!/usr/bin/python
# -*- coding: utf-8 -*-

# Copyright: (c) YYYY, Full Name <email>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

from __future__ import absolute_import, division, print_function
__metaclass__ = type

ANSIBLE_METADATA = {'metadata_version': '1.1',
                    'status': ['preview'],
                    'supported_by': 'community'}

DOCUMENTATION = """
---
module: pfsense_module
version_added: "2.10"
short_description: Manage pfSense MODULE
description:
  >
    Manage pfSense MODULE
author: Full Name (@github)
notes:
options:
  name:
    description: The name of the ITEM
    required: true
    type: str
  state:
    description: State in which to leave the ITEM
    required: true
    choices: [ "present", "absent" ]
    type: str
"""

EXAMPLES = """
"""
RETURN = """
"""

from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.network.pfsense.module_base import PFSenseModuleBase


class PFSenseMODULEModule(PFSenseModuleBase):
    """ module managing pfsense MODULE """

    def __init__(self, module, pfsense=None):
        super(PFSenseMODULEModule, self).__init__(module, pfsense)
        self.name = "pfsense_MODULE"
        self.root_elt = self.pfsense.get_element('system')

    ##############################
    # params processing
    #
    def _validate_params(self):
        """ do some extra checks on input parameters """

    def _params_to_obj(self):
        """ return a dict from module params """

    ##############################
    # Logging
    #
    def _get_obj_name(self):
        """ return obj's name """
        return "'{0}'".format(self.obj['descr'])

def main():
    module = AnsibleModule(argument_spec={
            'name': {'required': True, 'type': 'str'},
            'state': {
                'required': True,
                'choices': ['present', 'absent']
            },
        },
        supports_check_mode=True)

    pfmodule = PFSenseGroupModule(module)
    pfmodule.run(module.params)
    pfmodule.commit_changes()


if __name__ == '__main__':
    main()

Instance variables

Generally Used or set

• modules: AnsibleModule - ansible module
• name: string - ansible module name
• params: dict - ansible input parameters
• pfsense: PFSenseModule - helper module for parsing config and applying updates
• apply: bool - default: True - apply configuration at the end
• obj: dict - target pfsense config parameters
• target_elt: Element - xml object holding target pfsense parameters, generally set by _find_target() for existing items or _create_target() for new items
• root_elt: Element - xml parent of target_elt

Internal implementation

These are generally only deal with internally:

• change_descr: string - Text reported in config.xml revision description
• result: dict - ansible module return values. Some modules return:
  • 'commands': a pseudo command record of the changes made
• diff: dict - ansible diff mode structure returned as part of result

Module flow

• run():

  • _validate_params() - Mandatory
  • _params_to_obj() - Mandatory
  • _find_target() - Mandatory

• For state == present:

  • _add() - Internal
  • if self.target_elt is None: (no existing element -> add)
    • _create_target() - Mandatory
    • _copy_and_add_target() - Basic implementation but likely need to override
    • _log_create() - Internal
      • _get_obj_name() - Mandatory
      • _log_fields() - Mandatory
  • else: (existing element -> update)
    • _copy_and_update_target() - Basic implementation but likely need to override
    • _log_update(before) -
      • _get_obj_name() - Mandatory
      • _log_fields() - Manadatory

• For state == absent:

  • _remove() - Internal
    • _pre_remove_target_elt() - Basic implementation - sets diff['before'] - often overridden
    • _log_delete() - Internal
    • _remove_target_elt() - Basic implementation - usually fine
    • _post_remove_target_elt() - Noop - usually fine

• commit_changes():

  • _update() - Override if we need to run any PHP commands to apply the configuration changes