Skip to content
pfsensiblePublic

About

Core modules for managing pfSense firewalls with ansible

Resources

Stars

264 stars

Watchers

6 watching

Forks

Repository files navigation

ansible-pfsense / pfsensible.core

This is a set of modules to allow you to configure pfSense firewalls with ansible.

Installation using ansible galaxy

To install:

ansible-galaxy collection install pfsensible.core

Optionally, you can specify the path of the collection installation with the -p option.

ansible-galaxy collection install pfsensible.core -p ./collections

Additionally, you can set the collections_paths option in your ansible.cfg file to automatically designate install locations.

# ansible.cfg
[defaults]
collections_paths=collections

Configuration

Current versions of ansible should automatically detect the version of Python on the pfSense system. If Python discovery fails, you can set ansible_python_interpreter in your playbook or hosts vars, e.g. for pfSense 2.7.2:

ansible_python_interpreter: /usr/local/bin/python3.11

Modules must run as root in order to make changes to the system. By default pfSense does not have sudo capability so become will not work. You can install it with:

  - name: Install packages
    package:
      name:
        - pfSense-pkg-sudo
      state: present

and then configure sudo so that your user has permission to use sudo.

Configuration write protection

The shared Python writer validates XML, the configuration root/version, and the continued presence of existing system and interface sections before committing. It also validates and formats the candidate with the firewall's standalone PHP XML parser and dump_xml_config() serializer, which check pfSense-specific list tags and duplicate entries. It does not load config.inc, recover the live configuration, or run package hooks during validation and formatting.

Each write acquires pfSense's native /tmp/config.lock, checks that the file still matches the bytes read by the module, and rejects a stale snapshot. A conflict fails the task without replacing either the configuration or its backup; rerun the task/play from a fresh read after resolving overlapping writers. There is a 30-second lock timeout. Do not delete the lock file to release a lock.

Before replacing /cf/conf/config.xml, the writer atomically saves the exact pre-change bytes in /cf/conf/config.xml.ansible.bak with mode 0600. This is a single rotating pre-change copy, not a configuration history or an independently verified operational backup. Keep a separate known-good backup before a full playbook run. The config and backup temporary files are created in the config directory, flushed, synced, and renamed without a cross-filesystem copy fallback. The live configuration retains its existing owner, group, and permissions. The directory is synced, and /tmp/config.cache is invalidated while the native lock is held. Failure to persist the backup aborts the write. A failure after config replacement is reported with changed: true and the backup path, so inspect the firewall before retrying; automatic rollback could overwrite another writer's changes.

The lock is released before PHP apply hooks run, including hooks that write configuration themselves. This prevents nested-lock deadlocks. Native or external writers that read an old snapshot and later write it without conflict detection can still overwrite newer changes; the Python writer cannot make those scripts transactional. Avoid overlapping playbooks, GUI saves, HA configuration syncs, and package update jobs during a full apply. This protection does not invoke native write_config() backup history, AutoConfigBackup, or HA synchronization.

The deployed firewall's native serializer determines the final XML declaration, indentation, newline, entity spelling, CDATA fields, and explicit empty end tags. There are no copied CDATA field lists, inferred package rules, or preserved non-native CDATA markers. For example, native descr/description and ldap_basedn use escaped CDATA, while shellcmd, package cmd, URLs, and custom_options use ordinary escaped text on versions with those native rules. The Python reader decodes XML-escaped CDATA once and does not decode ordinary XML text a second time, preserving literal entity strings and multiline values. It detects the installed parser's legacy html_entity_decode($data) form and uses the HTML4 entity names expected by that parser for CDATA (for example, © and é). Modern ENT_XML1 parsers retain XML-only decoding. This capability check reads the parser source and does not invoke PHP for no-op rule checks.

Reading uses a single-pass ElementTree builder rather than constructing a DOM, serializing it, and parsing the XML again. This avoids repeated full-document conversion for every task.

The temporary transport document is parsed and reformatted by PHP before it can replace the live file. The formatted document must parse back to the same native configuration array. Quotes remain literal inside the transport's CDATA because older native HTML-entity decoder defaults may not decode apostrophe entities; this preserves quoted OpenVPN options when an unrelated task saves configuration. The native serializer still controls quote escaping in the final XML. The result must also match the intended Python values and structure. Comparison ignores formatting whitespace and order between different named fields, matching PHP associative arrays. Entries sharing a tag retain their order: firewall/NAT rules and lists of VPN servers or clients cannot be silently reordered. For example, appending a new OpenVPN server after existing clients is accepted when PHP groups it with the other server entries without changing either list's order. A mismatch aborts the write and reports config_mismatch with the first field's indexed XML path and a reason, without including configuration values. Native PHP failures also report native_validation with a fixed stage name and exit code (parser loading, candidate parsing, serialization, temporary-file writing, formatted parsing, or native round-trip comparison). Raw PHP output is never returned because it may contain configuration secrets. The final native bytes are synced before replacement and used for subsequent conflict detection. Formatting does not run interface assignment, gateway creation, CARP changes, or apply hooks.

Appliance integration tests

The system-test framework runs actual Ansible modules against a disposable pfSense VM in QEMU. It checks saved configuration, downloaded alias caches, and live PF rules and tables, including idempotence, check mode, runtime repair, and reboot persistence. Configure a prepared appliance image URL and SHA-256 to enable the GitHub system-test workflow. See the framework guide for image preparation, virtual NIC configuration, local execution, and current coverage.

Modules

The following modules are currently available:

Bulk modules

These modules allow you to make important changes at once and, using the purge parameters, to keep the targets configuration strictly synchronized with your playbooks:

Third party modules

These modules allow you to manage installed packages:

High-Availability Configuration Syncing

pfsensible modules do not trigger an XMLRPC configuration sync to a secondary system. But this can be done with the use of a handler as shown:

tasks:
  -  name: Make a chage
     pfsensible.core.alias:
       name: an_alias
       state: absent
     become: true
     notify: sync config
handlers:
  - name: sync config
    pfsensible.core.pfsense_rewrite_config:
    become: true

Writing new modules

See GENERATING_MODULES for instructions on how to use the pfensible-generate-module script to automate the task writing basic pfsensible modules.

License

GPLv3.0 or later

About

Core modules for managing pfSense firewalls with ansible

Resources

Stars

264 stars

Watchers

6 watching

Forks

Releases

Packages

Used by

Contributors

Languages