pfsense_fauxapi

FauxAPI - v1.4

A REST API interface for pfSense 2.3.x, 2.4.x, 2.5.x to facilitate devops:-

• https://github.com/ndejong/pfsense_fauxapi

Additionally available are a set of client libraries that hence make programmatic access and management of pfSense hosts for devops tasks feasible.

Important

• You MUST (manually) setup your /etc/fauxapi/credentials.ini file on the pfSense host before you continue, see the API Authentication section below.
• You MUST (manually) setup a /etc/fauxapi/pfsense_function_calls.txt file if you want to use the function_call API method. You may wish to copy the sample /etc/fauxapi/pfsense_function_calls.sample.txt as a starting point.

API Action Summary

• alias_update_urltables - Causes the pfSense host to immediately update any urltable alias entries from their (remote) source URLs.
• config_backup - Causes the system to take a configuration backup and add it to the regular set of system change backups.
• config_backup_list - Returns a list of the currently available system configuration backups.
• config_get - Returns the full system configuration as a JSON formatted string.
• config_patch - Patch the system config with a granular piece of new configuration.
• config_reload - Causes the pfSense system to perform an internal reload of the config.xml file.
• config_restore - Restores the pfSense system to the named backup configuration.
• config_set - Sets a full system configuration and (by default) reloads once successfully written and tested.
• function_call - Call directly a pfSense PHP function with API user supplied parameters.
• gateway_status - Returns gateway status data.
• interface_stats - Returns statistics and information about an interface.
• rule_get - Returns the numbered list of loaded pf rules from a pfctl -sr -vv command on the pfSense host.
• send_event - Performs a pfSense "send_event" command to cause various pfSense system actions.
• system_reboot - Reboots the pfSense system.
• system_stats - Returns various useful system stats.
• system_info - Returns various useful system info.

Approach

At its core FauxAPI simply reads the core pfSense config.xml file, converts it to JSON and returns to the API caller. Similarly it can take a JSON formatted configuration and write it to the pfSense config.xml and handles the required reload operations. The ability to programmatically interface with a running pfSense host(s) is enormously useful however it should also be obvious that this provides the API user the ability to create configurations that can break your pfSense system.

FauxAPI provides easy backup and restore API interfaces that by default store configuration backups on all configuration write operations thus it is very easy to roll-back even if the API user manages to deploy a "very broken" configuration.

Multiple sanity checks take place to make sure a user provided JSON config will correctly convert into the (slightly quirky) pfSense XML config.xml format and then reload as expected in the same way. However, because it is not a real per-action application-layer interface it is still possible for the API caller to create configuration changes that make no sense and can potentially disrupt your pfSense system - as the package name states, it is a "Faux" API to pfSense filling a gap in functionality with the current pfSense product.

Because FauxAPI is a utility that interfaces with the pfSense config.xml there are some cases where reloading the configuration file is not enough and you may need to "tickle" pfSense a little more to do what you want. This is not common however a good example is getting newly defined network interfaces or VLANs to be recognized. These situations are easily handled by calling the send_event action with the payload interface reload all - see the example included below and refer to a the resolution to Issue #10

NB: As at FauxAPI v1.2 the function_call action has been introduced that now provides the ability to issue function calls directly into pfSense.

Installation

Until the FauxAPI is added to the pfSense FreeBSD-ports tree you will need to install manually from root as shown:-

set fauxapi_base_package_url='https://raw.githubusercontent.com/ndejong/pfsense_fauxapi_packages/master'
set fauxapi_latest=`fetch -qo - ${fauxapi_base_package_url}/LATEST`
fetch ${fauxapi_base_package_url}/${fauxapi_latest}
pkg-static install ${fauxapi_latest}

Installation and de-installation is quite straight forward, further examples can be found in the README.md located here.

Refer to the published package SHA256SUMS

Hint: if not already, consider installing the jq tool on your local machine (not pfSense host) to pipe and manage JSON outputs from FauxAPI - https://stedolan.github.io/jq/

NB: you MUST at least setup your /etc/fauxapi/credentials.ini file on the pfSense host before you continue, see the API Authentication section below.

Client libraries

Python

A Python interface to pfSense was perhaps the most desired end-goal at the onset of the FauxAPI package project. Anyone that has tried to parse the pfSense config.xml files using a Python based library will understand that things don't quite work out as expected or desired.

The Python client-library can be easily installed from PyPi as such

pip3 install pfsense-fauxapi

Package Status:

Use of the package should be easy enough as shown

import pprint, sys
from PfsenseFauxapi.PfsenseFauxapi import PfsenseFauxapi
PfsenseFauxapi = PfsenseFauxapi('', '', '')

aliases = PfsenseFauxapi.config_get('aliases')
## perform some kind of manipulation to `aliases` here ##
pprint.pprint(PfsenseFauxapi.config_set(aliases, 'aliases'))

It is recommended to review the Python code examples to observe worked examples with the client library. Of small note is that the Python library supports the ability to get and set single sections of the pfSense system, not just the entire system configuration as with the Bash library.

Python examples

• usergroup-management.py - example code that provides the ability to get_users, add_user, manage_user, remove_user and perform the same functions on groups.
• update-aws-aliases.py - example code that pulls in the latest AWS ip-ranges.json data, parses it and injects them into the pfSense aliases section if required.
• function-iterate.py - iterates (almost) all the FauxAPI functions to confirm operation.

Command Line

As distinct from the Bash library as described below the Python pip also introduces a command-line tool to interact with the API, which makes a wide range of actions possible directly from the command line, for example

fauxapi --host 192.168.1.200 gateway_status | jq .

Bash

The Bash client library makes it possible to add a line with source pfsense-fauxapi.sh to your bash script and then access a pfSense host configuration directly as a JSON string

source pfsense-fauxapi.sh
export fauxapi_auth=$(fauxapi_auth  )

fauxapi_config_get  | jq .data.config > /tmp/config.json
## perform some kind of manipulation to `/tmp/config.json` here ##
fauxapi_config_set  /tmp/config.json

It is recommended to review the commented out samples in the provided fauxapi-sample.sh file that cover all possible FauxAPI calls to gain a better idea on usage.

NodeJS/TypeScript

A NodeJS client has been developed by a third party and is available here

• NPMJS: npmjs.com/package/faux-api-client
• Github: github.com/Elucidia/faux-api-client

PHP

A PHP client has been developed by a third party and is available here

• Packagist: packagist.org/packages/travisghansen/pfsense_fauxapi_php_client
• Github: github.com/travisghansen/pfsense_fauxapi_php_client

API Authentication

A deliberate design decision to decouple FauxAPI authentication from both the pfSense user authentication and the pfSense config.xml system. This was done to limit the possibility of an accidental API change that removes access to the host. It also seems more prudent to only establish API user(s) manually via the FauxAPI /etc/fauxapi/credentials.ini file - happy to receive feedback about this approach.

The two sample FauxAPI keys (PFFAexample01 and PFFAexample02) and their associated secrets in the sample credentials.sample.ini file are hard-coded to be inoperative, you must create entirely new values before your client scripts will be able to issue commands to FauxAPI.

You can start your own /etc/fauxapi/credentials.ini file by copying the sample file provided in credentials.sample.ini

API authentication itself is performed on a per-call basis with the auth value inserted as an additional fauxapi-auth HTTP request header, it can be calculated as such:-

fauxapi-auth: :::

For example:-
fauxapi-auth: PFFA4797d073:20161119Z144328:833a45d8:9c4f96ab042f5140386178618be1ae40adc68dd9fd6b158fb82c99f3aaa2bb55

Where the <hash> value is calculated like so:-

 = sha256()

NB: that the timestamp value is internally passed to the PHP strtotime function which can interpret a wide variety of timestamp formats together with a timezone. A nice tidy timestamp format that the strtotime PHP function is able to process can be obtained using bash command date --utc +%Y%m%dZ%H%M%S where the Z date-time seperator hence also specifies the UTC timezone.

This is all handled in the client libraries provided, but as can be seen it is relatively easy to implement even in a Bash shell script.

Getting the API credentials right seems to be a common source of confusion in getting started with FauxAPI because the rules about valid API keys and secret values are pedantic to help make ensure poor choices are not made.

The API key + API secret values that you will need to create in /etc/fauxapi/credentials.ini have the following rules:-

• and may have alphanumeric chars ONLY!
• MUST start with the prefix PFFA (pfSense Faux API)
• MUST be >= 12 chars AND = 40 chars AND System Logs->General or via the console using the clog tool

$ clog /var/log/system.log | grep fauxapi

Configuration Backups

All configuration edits through FauxAPI create configuration backups in the same way as pfSense does with the webapp GUI.

These backups are available in the same way as edits through the pfSense GUI and are thus able to be reviewed and diff'd in the same way under Diagnostics->Backup & Restore->Config History.

Changes made through the FauxAPI carry configuration change descriptions that name the un