{"id":23165930,"url":"https://github.com/ndejong/pfsense_fauxapi","last_synced_at":"2025-04-04T20:09:28.432Z","repository":{"id":48171803,"uuid":"74257324","full_name":"ndejong/pfsense_fauxapi","owner":"ndejong","description":"REST based API interface for pfSense 2.3.x and 2.4.x to facilitate devops","archived":false,"fork":false,"pushed_at":"2021-05-29T15:11:28.000Z","size":852,"stargazers_count":355,"open_issues_count":20,"forks_count":61,"subscribers_count":42,"default_branch":"master","last_synced_at":"2025-03-28T19:08:04.511Z","etag":null,"topics":["api","devops","pfsense","pfsense-fauxapi","restful-api"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ndejong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-11-20T06:36:35.000Z","updated_at":"2025-03-11T05:06:36.000Z","dependencies_parsed_at":"2022-09-26T18:40:34.241Z","dependency_job_id":null,"html_url":"https://github.com/ndejong/pfsense_fauxapi","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndejong%2Fpfsense_fauxapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndejong%2Fpfsense_fauxapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndejong%2Fpfsense_fauxapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndejong%2Fpfsense_fauxapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ndejong","download_url":"https://codeload.github.com/ndejong/pfsense_fauxapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247242678,"owners_count":20907134,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","devops","pfsense","pfsense-fauxapi","restful-api"],"created_at":"2024-12-18T01:30:05.709Z","updated_at":"2025-04-04T20:09:28.406Z","avatar_url":"https://github.com/ndejong.png","language":"PHP","readme":"# FauxAPI - v1.4\nA REST API interface for pfSense 2.3.x, 2.4.x, 2.5.x to facilitate devops:-\n - https://github.com/ndejong/pfsense_fauxapi\n\nAdditionally available are a set of [client libraries](#client-libraries) \nthat hence make programmatic access and management of pfSense hosts for devops \ntasks feasible.\n\n### Important\n* You MUST (manually) setup your `/etc/fauxapi/credentials.ini` file on the pfSense host before \n  you continue, see the [API Authentication](#api-authentication) section below.\n* You MUST (manually) setup a `/etc/fauxapi/pfsense_function_calls.txt` file if you want to use\n  the `function_call` API method.  You may wish to copy the sample `/etc/fauxapi/pfsense_function_calls.sample.txt`\n  as a starting point.\n\n## API Action Summary\n - [alias_update_urltables](#user-content-alias_update_urltables) - Causes the pfSense host to immediately update any urltable alias entries from their (remote) source URLs.\n - [config_backup](#user-content-config_backup) - Causes the system to take a configuration backup and add it to the regular set of system change backups.\n - [config_backup_list](#user-content-config_backup_list) - Returns a list of the currently available system configuration backups.\n - [config_get](#user-content-config_get) - Returns the full system configuration as a JSON formatted string.\n - [config_patch](#user-content-config_patch) - Patch the system config with a granular piece of new configuration.\n - [config_reload](#user-content-config_reload) - Causes the pfSense system to perform an internal reload of the `config.xml` file.\n - [config_restore](#user-content-config_restore) - Restores the pfSense system to the named backup configuration.\n - [config_set](#user-content-config_set) - Sets a full system configuration and (by default) reloads once successfully written and tested.\n - [function_call](#user-content-function_call) - Call directly a pfSense PHP function with API user supplied parameters.\n - [gateway_status](#user-content-gateway_status) - Returns gateway status data.\n - [interface_stats](#user-content-interface_stats) - Returns statistics and information about an interface.\n - [rule_get](#user-content-rule_get) - Returns the numbered list of loaded pf rules from a `pfctl -sr -vv` command on the pfSense host.\n - [send_event](#user-content-send_event) - Performs a pfSense \"send_event\" command to cause various pfSense system actions.\n - [system_reboot](#user-content-system_reboot) - Reboots the pfSense system.\n - [system_stats](#user-content-system_stats) - Returns various useful system stats.\n - [system_info](#user-content-system_info) - Returns various useful system info.\n\n\n## Approach\nAt its core FauxAPI simply reads the core pfSense `config.xml` file, converts it \nto JSON and returns to the API caller.  Similarly it can take a JSON formatted \nconfiguration and write it to the pfSense `config.xml` and handles the required \nreload operations.  The ability to programmatically interface with a running \npfSense host(s) is enormously useful however it should also be obvious that this \nprovides the API user the ability to create configurations that can break your \npfSense system.\n\nFauxAPI provides easy backup and restore API interfaces that by default store\nconfiguration backups on all configuration write operations thus it is very easy \nto roll-back even if the API user manages to deploy a \"very broken\" configuration.\n\nMultiple sanity checks take place to make sure a user provided JSON config will \ncorrectly convert into the (slightly quirky) pfSense XML `config.xml` format and \nthen reload as expected in the same way.  However, because it is not a real \nper-action application-layer interface it is still possible for the API caller \nto create configuration changes that make no sense and can potentially disrupt \nyour pfSense system - as the package name states, it is a \"Faux\" API to pfSense\nfilling a gap in functionality with the current pfSense product.\n\nBecause FauxAPI is a utility that interfaces with the pfSense `config.xml` there\nare some cases where reloading the configuration file is not enough and you \nmay need to \"tickle\" pfSense a little more to do what you want.  This is not \ncommon however a good example is getting newly defined network interfaces or \nVLANs to be recognized.  These situations are easily handled by calling the\n**send_event** action with the payload **interface reload all** - see the example \nincluded below and refer to a the resolution to [Issue #10](https://github.com/ndejong/pfsense_fauxapi/issues/10)\n\n__NB:__ *As at FauxAPI v1.2 the **function_call** action has been introduced that \nnow provides the ability to issue function calls directly into pfSense.*\n\n\n## Installation\nUntil the FauxAPI is added to the pfSense FreeBSD-ports tree you will need to \ninstall manually from **root** as shown:-\n```bash\nset fauxapi_base_package_url='https://raw.githubusercontent.com/ndejong/pfsense_fauxapi_packages/master'\nset fauxapi_latest=`fetch -qo - ${fauxapi_base_package_url}/LATEST`\nfetch ${fauxapi_base_package_url}/${fauxapi_latest}\npkg-static install ${fauxapi_latest}\n```\n\nInstallation and de-installation is quite straight forward, further examples can \nbe found in the `README.md` located [here](https://github.com/ndejong/pfsense_fauxapi_packages).\n\nRefer to the published package [`SHA256SUMS`](https://github.com/ndejong/pfsense_fauxapi_packages/blob/master/SHA256SUMS)\n\n**Hint:** if not already, consider installing the `jq` tool on your local machine (not \npfSense host) to pipe and manage JSON outputs from FauxAPI - https://stedolan.github.io/jq/\n\n**NB:** you MUST at least setup your `/etc/fauxapi/credentials.ini` file on the \npfSense host before you continue, see the API Authentication section below.\n\n## Client libraries\n\n#### Python\nA [Python interface](https://github.com/ndejong/pfsense_fauxapi_client_python) \nto pfSense was perhaps the most desired end-goal at the onset of the FauxAPI \npackage project.  Anyone that has tried to parse the pfSense `config.xml` files \nusing a Python based library will understand that things don't quite work out as \nexpected or desired.\n\nThe Python client-library can be easily installed from PyPi as such\n```bash\npip3 install pfsense-fauxapi\n```\n\nPackage Status: [![PyPi](https://img.shields.io/pypi/v/pfsense-fauxapi.svg)](https://pypi.org/project/pfsense-fauxapi/) [![Build Status](https://travis-ci.org/ndejong/pfsense_fauxapi_client_python.svg?branch=master)](https://travis-ci.org/ndejong/pfsense_fauxapi_client_python)\n\nUse of the package should be easy enough as shown\n```python\nimport pprint, sys\nfrom PfsenseFauxapi.PfsenseFauxapi import PfsenseFauxapi\nPfsenseFauxapi = PfsenseFauxapi('\u003chost-address\u003e', '\u003cfauxapi-key\u003e', '\u003cfauxapi-secret\u003e')\n\naliases = PfsenseFauxapi.config_get('aliases')\n## perform some kind of manipulation to `aliases` here ##\npprint.pprint(PfsenseFauxapi.config_set(aliases, 'aliases'))\n```\n\nIt is recommended to review the [Python code examples](https://github.com/ndejong/pfsense_fauxapi_client_python/tree/master/examples)\nto observe worked examples with the client library.  Of small note is that the \nPython library supports the ability to get and set single sections of the pfSense \nsystem, not just the entire system configuration as with the Bash library.\n\n**Python examples**\n - `usergroup-management.py` - example code that provides the ability to `get_users`, \n   `add_user`, `manage_user`, `remove_user` and perform the same functions on groups.\n - `update-aws-aliases.py` - example code that pulls in the latest AWS `ip-ranges.json` \n   data, parses it and injects them into the pfSense aliases section if required.\n - `function-iterate.py` - iterates (almost) all the FauxAPI functions to \n   confirm operation.  \n\n#### Command Line\nAs distinct from the Bash library as described below the Python pip also introduces\na command-line tool to interact with the API, which makes a wide range of actions\npossible directly from the command line, for example\n```bash\nfauxapi --host 192.168.1.200 gateway_status | jq .\n```\n\n#### Bash\nThe [Bash client library](https://github.com/ndejong/pfsense_fauxapi_client_bash) \nmakes it possible to add a line with `source pfsense-fauxapi.sh` to your bash script \nand then access a pfSense host configuration directly as a JSON string\n```bash\nsource pfsense-fauxapi.sh\nexport fauxapi_auth=$(fauxapi_auth \u003cfauxapi-key\u003e \u003cfauxapi-secret\u003e)\n\nfauxapi_config_get \u003chost-address\u003e | jq .data.config \u003e /tmp/config.json\n## perform some kind of manipulation to `/tmp/config.json` here ##\nfauxapi_config_set \u003chost-address\u003e /tmp/config.json\n```\n\nIt is recommended to review the commented out samples in the provided \n`fauxapi-sample.sh` file that cover all possible FauxAPI calls to gain a better\nidea on usage.\n\n#### NodeJS/TypeScript\nA NodeJS client has been developed by a third party and is available here\n - NPMJS: [npmjs.com/package/faux-api-client](https://www.npmjs.com/package/faux-api-client)\n - Github: [github.com/Elucidia/faux-api-client](https://github.com/Elucidia/faux-api-client)\n\n#### PHP\nA PHP client has been developed by a third party and is available here\n - Packagist: [packagist.org/packages/travisghansen/pfsense_fauxapi_php_client](https://packagist.org/packages/travisghansen/pfsense_fauxapi_php_client)\n - Github: [github.com/travisghansen/pfsense_fauxapi_php_client](https://github.com/travisghansen/pfsense_fauxapi_php_client)\n\n\n## API Authentication\nA deliberate design decision to decouple FauxAPI authentication from both the \npfSense user authentication and the pfSense `config.xml` system.  This was done \nto limit the possibility of an accidental API change that removes access to the \nhost.  It also seems more prudent to only establish API user(s) manually via the \nFauxAPI `/etc/fauxapi/credentials.ini` file - happy to receive feedback about \nthis approach.\n\nThe two sample FauxAPI keys (PFFAexample01 and PFFAexample02) and their \nassociated secrets in the sample `credentials.sample.ini` file are hard-coded to \nbe inoperative, you must create entirely new values before your client scripts\nwill be able to issue commands to FauxAPI.\n\nYou can start your own `/etc/fauxapi/credentials.ini` file by copying the sample\nfile provided in `credentials.sample.ini`\n\nAPI authentication itself is performed on a per-call basis with the auth value \ninserted as an additional **fauxapi-auth** HTTP request header, it can be \ncalculated as such:-\n```\nfauxapi-auth: \u003capikey\u003e:\u003ctimestamp\u003e:\u003cnonce\u003e:\u003chash\u003e\n\nFor example:-\nfauxapi-auth: PFFA4797d073:20161119Z144328:833a45d8:9c4f96ab042f5140386178618be1ae40adc68dd9fd6b158fb82c99f3aaa2bb55\n```\n\nWhere the \u0026lt;hash\u0026gt; value is calculated like so:-\n```\n\u003chash\u003e = sha256(\u003capisecret\u003e\u003ctimestamp\u003e\u003cnonce\u003e)\n```\n\nNB: that the timestamp value is internally passed to the PHP `strtotime` function \nwhich can interpret a wide variety of timestamp formats together with a timezone.\nA nice tidy timestamp format that the `strtotime` PHP function is able to process\ncan be obtained using bash command `date --utc +%Y%m%dZ%H%M%S` where the `Z` \ndate-time seperator hence also specifies the UTC timezone.  \n\nThis is all handled in the [client libraries](#client-libraries) \nprovided, but as can be seen it is relatively easy to implement even in a Bash \nshell script.\n\nGetting the API credentials right seems to be a common source of confusion in\ngetting started with FauxAPI because the rules about valid API keys and secret \nvalues are pedantic to help make ensure poor choices are not made.\n\nThe API key + API secret values that you will need to create in `/etc/fauxapi/credentials.ini`\nhave the following rules:-\n - \u003capikey_value\u003e and \u003capisecret_value\u003e may have alphanumeric chars ONLY!\n - \u003capikey_value\u003e MUST start with the prefix PFFA (pfSense Faux API)\n - \u003capikey_value\u003e MUST be \u003e= 12 chars AND \u003c= 40 chars in total length\n - \u003capisecret_value\u003e MUST be \u003e= 40 chars AND \u003c= 128 chars in length\n - you must not use the sample key/secret in the `credentials.ini` since they\n   are hard coded to fail.\n\nTo make things easier consider using the following shell commands to generate \nvalid values:-\n\n#### apikey_value\n```bash\necho PFFA`head /dev/urandom | base64 -w0 | tr -d /+= | head -c 20`\n```\n\n#### apisecret_value\n```bash\necho `head /dev/urandom | base64 -w0 | tr -d /+= | head -c 60`\n```\n\nNB: Make sure the client side clock is within 60 seconds of the pfSense host \nclock else the auth token values calculated by the client will not be valid - 60 \nseconds seems tight, however, provided you are using NTP to look after your \nsystem time it's quite unlikely to cause issues - happy to receive feedback \nabout this.\n\n__Shout Out:__ *Seeking feedback on the API authentication, many developers \nseem to stumble here - if you feel something could be improved without compromising\nsecurity then submit an Issue ticket via Github.*\n\n\n## API Authorization\nThe file `/etc/fauxapi/credentials.ini` additionally provides a method to restrict\nthe API actions available to the API key using the **permit** configuration \nparameter.  Permits are comma delimited and may contain * wildcards to match more\nthan one rule as shown in the example below.\n\n```\n[PFFAexample01]\nsecret = abcdefghijklmnopqrstuvwxyz0123456789abcd\npermit = alias_*, config_*, gateway_*, rule_*, send_*, system_*, function_*\ncomment = example key PFFAexample01 - hardcoded to be inoperative\n```\n\n## Debugging\nFauxAPI comes with awesome debug logging capability, simply insert `__debug=true` \nas a URL request parameter and the response data will contain rich debugging log \ndata about the flow of the request.\n\nIf you are looking for more debugging at various points feel free to submit a \npull request or lodge an issue describing your requirement and I'll see what\ncan be done to accommodate.\n\n\n## Logging\nFauxAPI actions are sent to the system syslog via a call to the PHP `syslog()` \nfunction thus causing all FauxAPI actions to be logged and auditable on a per \naction (callid) basis which provide the full basis for the call, for example:-\n```text\nJul  3 04:37:59 pfSense php-fpm[55897]: {\"INFO\":\"20180703Z043759 :: fauxapi\\\\v1\\\\fauxApi::__call\",\"DATA\":{\"user_action\":\"alias_update_urltables\",\"callid\":\"5b3afda73e7c9\",\"client_ip\":\"192.168.1.5\"},\"source\":\"fauxapi\"}\nJul  3 04:37:59 pfSense php-fpm[55897]: {\"INFO\":\"20180703Z043759 :: valid auth for call\",\"DATA\":{\"apikey\":\"PFFAdevtrash\",\"callid\":\"5b3afda73e7c9\",\"client_ip\":\"192.168.1.5\"},\"source\":\"fauxapi\"}\n```\nEnabling debugging yields considerably more logging data to assist with tracking \ndown issues if you encounter them - you may review the logs via the pfSense GUI\nas usual unser Status-\u003eSystem Logs-\u003eGeneral or via the console using the `clog` tool\n```bash\n$ clog /var/log/system.log | grep fauxapi\n``` \n\n## Configuration Backups\nAll configuration edits through FauxAPI create configuration backups in the \nsame way as pfSense does with the webapp GUI.  \n\nThese backups are available in the same way as edits through the pfSense \nGUI and are thus able to be reviewed and diff'd in the same way under \nDiagnostics-\u003eBackup \u0026 Restore-\u003eConfig History.\n\nChanges made through the FauxAPI carry configuration change descriptions that\nname the unique `callid` which can then be tied to logs if required for full \nusage audit and change tracking.\n\nFauxAPI functions that cause write operations to the system config `config.xml` \nreturn reference to a backup file of the configuration immediately previous\nto the change.\n\n\n## API REST Actions\nThe following REST based API actions are provided, example cURL call request \nexamples are provided for each.  The API user is perhaps more likely to interface \nwith the [client libraries](#client-libraries) as documented above \nrather than directly with these REST end-points.\n\nThe framework around the FauxAPI has been put together with the idea of being\nable to easily add more actions at a later time, if you have ideas for actions \nthat might be useful be sure to get in contact.\n\nNB: the cURL requests below use the '--insecure' switch because many pfSense\ndeployments do not deploy certificate chain signed SSL certificates.  A reasonable \nimprovement in this regard might be to implement certificate pinning at the \nclient side to hence remove scope for man-in-middle concerns.\n\n---\n### alias_update_urltables\n - Causes the pfSense host to immediately update any urltable alias entries from their (remote) \n   source URLs.  Optionally update just one table by specifying the table name, else all \n   tables are updated.\n - HTTP: **GET**\n - Params:\n    - **table** (optional, default = null)\n\n*Example Request*\n```bash\ncurl \\\n    -X GET \\\n    --silent \\\n    --insecure \\\n    --header \"fauxapi-auth: \u003cauth-value\u003e\" \\\n    \"https://\u003chost-address\u003e/fauxapi/v1/?action=alias_update_urltables\"\n```\n\n*Example Response*\n```javascript\n{\n  \"callid\": \"598ec756b4d09\",\n  \"action\": \"alias_update_urltables\",\n  \"message\": \"ok\",\n  \"data\": {\n    \"updates\": {\n      \"bruteforceblocker\": {\n        \"url\": \"https://raw.githubusercontent.com/firehol/blocklist-ipsets/master/bruteforceblocker.ipset\",\n        \"status\": [\n          \"no changes.\"\n        ]\n      }\n    }\n  }\n}\n```\n\n---\n### config_backup\n - Causes the system to take a configuration backup and add it to the regular \n   set of pfSense system backups at `/cf/conf/backup/`\n - HTTP: **GET**\n - Params: none\n\n*Example Request*\n```bash\ncurl \\\n    -X GET \\\n    --silent \\\n    --insecure \\\n    --header \"fauxapi-auth: \u003cauth-value\u003e\" \\\n    \"https://\u003chost-address\u003e/fauxapi/v1/?action=config_backup\"\n```\n\n*Example Response*\n```javascript\n{\n  \"callid\": \"583012fea254f\",\n  \"action\": \"config_backup\",\n  \"message\": \"ok\",\n  \"data\": {\n    \"backup_config_file\": \"/cf/conf/backup/config-1479545598.xml\"\n  }\n}\n```\n\n---\n### config_backup_list\n - Returns a list of the currently available pfSense system configuration backups.\n - HTTP: **GET**\n - Params: none\n\n*Example Request*\n```bash\ncurl \\\n    -X GET \\\n    --silent \\\n    --insecure \\\n    --header \"fauxapi-auth: \u003cauth-value\u003e\" \\\n    \"https://\u003chost-address\u003e/fauxapi/v1/?action=config_backup_list\"\n```\n\n*Example Response*\n```javascript\n{\n  \"callid\": \"583065cb670db\",\n  \"action\": \"config_backup_list\",\n  \"message\": \"ok\",\n  \"data\": {\n    \"backup_files\": [\n      {\n        \"filename\": \"/cf/conf/backup/config-1479545598.xml\",\n        \"timestamp\": \"20161119Z144635\",\n        \"description\": \"fauxapi-PFFA4797d073@192.168.10.10: update via fauxapi for callid: 583012fea254f\",\n        \"version\": \"15.5\",\n        \"filesize\": 18535\n      },\n      ....\n```\n\n---\n### config_get\n - Returns the system configuration as a JSON formatted string.  Additionally, \n   using the optional **config_file** parameter it is possible to retrieve backup\n   configurations by providing the full path to it under the `/cf/conf/backup` \n   path.\n - HTTP: **GET**\n - Params:\n    - **config_file** (optional, default=`/cf/config/config.xml`)\n\n*Example Request*\n```bash\ncurl \\\n    -X GET \\\n    --silent \\\n    --insecure \\\n    --header \"fauxapi-auth: \u003cauth-value\u003e\" \\\n    \"https://\u003chost-address\u003e/fauxapi/v1/?action=config_get\"\n```\n\n*Example Response*\n```javascript\n{\n    \"callid\": \"583012fe39f79\",\n    \"action\": \"config_get\",\n    \"message\": \"ok\",\n    \"data\": {\n      \"config_file\": \"/cf/conf/config.xml\",\n      \"config\": {\n        \"version\": \"15.5\",\n        \"staticroutes\": \"\",\n        \"snmpd\": {\n          \"syscontact\": \"\",\n          \"rocommunity\": \"public\",\n          \"syslocation\": \"\"\n        },\n        \"shaper\": \"\",\n        \"installedpackages\": {\n          \"pfblockerngsouthamerica\": {\n            \"config\": [\n             ....\n```\n\nHint: use `jq` to parse the response JSON and obtain the config only, as such:-\n```bash\ncat /tmp/faux-config-get-output-from-curl.json | jq .data.config \u003e /tmp/config.json\n```\n\n---\n### config_patch\n - Allows the API user to patch the system configuration with the existing system config\n - A **config_patch** call allows the API user to supply the partial configuration to be updated \n   which is quite different to the **config_set** function that requires the full configuration\n   to be posted.\n - HTTP: **POST**\n - Params:\n    - **do_backup** (optional, default = true)\n    - **do_reload** (optional, default = true)\n\n*Example Request*\n```bash\ncat \u003e /tmp/config_patch.json \u003c\u003cEOF\n{\n  \"system\": {\n    \"dnsserver\": [\n      \"8.8.8.8\",\n      \"8.8.4.4\"\n    ],\n    \"hostname\": \"newhostname\"\n  }\n}\nEOF\n\ncurl \\\n    -X POST \\\n    --silent \\\n    --insecure \\\n    --header \"fauxapi-auth: \u003cauth-value\u003e\" \\\n    --header \"Content-Type: application/json\" \\\n    --data @/tmp/config_patch.json \\\n    \"https://\u003chost-address\u003e/fauxapi/v1/?action=config_patch\"\n```\n\n*Example Response*\n```javascript\n{\n  \"callid\": \"5b3b506f72670\",\n  \"action\": \"config_patch\",\n  \"message\": \"ok\",\n  \"data\": {\n    \"do_backup\": true,\n    \"do_reload\": true,\n    \"previous_config_file\": \"/cf/conf/backup/config-1530613871.xml\"\n  }\n```\n\n---\n### config_reload\n - Causes the pfSense system to perform a reload action of the `config.xml` file, by \n   default this happens when the **config_set** action occurs hence there is \n   normally no need to explicitly call this after a **config_set** action.\n - HTTP: **GET**\n - Params: none\n\n*Example Request*\n```bash\ncurl \\\n    -X GET \\\n    --silent \\\n    --insecure \\\n    --header \"fauxapi-auth: \u003cauth-value\u003e\" \\\n    \"https://\u003chost-address\u003e/fauxapi/v1/?action=config_reload\"\n```\n\n*Example Response*\n```javascript\n{\n  \"callid\": \"5831226e18326\",\n  \"action\": \"config_reload\",\n  \"message\": \"ok\"\n}\n```\n\n---\n### config_restore\n - Restores the pfSense system to the named backup configuration.\n - HTTP: **GET**\n - Params:\n    - **config_file** (required, full path to the backup file to restore)\n\n*Example Request*\n```bash\ncurl \\\n    -X GET \\\n    --silent \\\n    --insecure \\\n    --header \"fauxapi-auth: \u003cauth-value\u003e\" \\\n    \"https://\u003chost-address\u003e/fauxapi/v1/?action=config_restore\u0026config_file=/cf/conf/backup/config-1479545598.xml\"\n```\n\n*Example Response*\n```javascript\n{\n  \"callid\": \"583126192a789\",\n  \"action\": \"config_restore\",\n  \"message\": \"ok\",\n  \"data\": {\n    \"config_file\": \"/cf/conf/backup/config-1479545598.xml\"\n  }\n}\n```\n\n---\n### config_set\n - Sets a full system configuration and (by default) takes a system config\n   backup and (by default) causes the system config to be reloaded once \n   successfully written and tested.\n - NB1: be sure to pass the *FULL* system configuration here, not just the piece you \n   wish to adjust!  Consider the **config_patch** or **config_item_set** functions if \n   you wish to adjust the configuration in more granular ways.\n - NB2: if you are pulling down the result of a `config_get` call, be sure to parse that\n   response data to obtain the config data only under the key `.data.config`\n - HTTP: **POST**\n - Params:\n    - **do_backup** (optional, default = true)\n    - **do_reload** (optional, default = true)\n\n*Example Request*\n```bash\ncurl \\\n    -X POST \\\n    --silent \\\n    --insecure \\\n    --header \"fauxapi-auth: \u003cauth-value\u003e\" \\\n    --header \"Content-Type: application/json\" \\\n    --data @/tmp/config.json \\\n    \"https://\u003chost-address\u003e/fauxapi/v1/?action=config_set\"\n```\n\n*Example Response*\n```javascript\n{\n  \"callid\": \"5b3b50e8b1bc6\",\n  \"action\": \"config_set\",\n  \"message\": \"ok\",\n  \"data\": {\n    \"do_backup\": true,\n    \"do_reload\": true,\n    \"previous_config_file\": \"/cf/conf/backup/config-1530613992.xml\"\n  }\n}\n```\n\n---\n### function_call\n - Call directly a pfSense PHP function with API user supplied parameters.  Note\n   that is action is a *VERY* raw interface into the inner workings of pfSense \n   and it is not recommended for API users that do not have a solid understanding \n   of PHP and pfSense.  Additionally, not all pfSense functions are appropriate \n   to be called through the FauxAPI and only very limited testing has been \n   performed against the possible outcomes and responses.  It is possible to \n   harm your pfSense system if you do not 100% understand what is going on.\n - Functions to be called via this interface *MUST* be defined in the file \n   `/etc/pfsense_function_calls.txt` only a handful very basic and \n   read-only pfSense functions are enabled by default.\n - You can start your own `/etc/fauxapi/pfsense_function_calls.txt` file by \n   copying the sample file provided in `pfsense_function_calls.sample.txt`\n - HTTP: **POST**\n - Params: none\n\n*Example Request*\n```bash\ncurl \\\n    -X POST \\\n    --silent \\\n    --insecure \\\n    --header \"fauxapi-auth: \u003cauth-value\u003e\" \\\n    --header \"Content-Type: application/json\" \\\n    --data \"{\\\"function\\\": \\\"get_services\\\"}\" \\\n    \"https://\u003chost-address\u003e/fauxapi/v1/?action=function_call\"\n```\n\n*Example Response*\n```javascript\n{\n  \"callid\": \"59a29e5017905\",\n  \"action\": \"function_call\",\n  \"message\": \"ok\",\n  \"data\": {\n    \"return\": [\n      {\n        \"name\": \"unbound\",\n        \"description\": \"DNS Resolver\"\n      },\n      {\n        \"name\": \"ntpd\",\n        \"description\": \"NTP clock sync\"\n      },\n      ....\n\n```\n\n---\n### gateway_status\n - Returns gateway status data.\n - HTTP: **GET**\n - Params: none\n\n*Example Request*\n```bash\ncurl \\\n    -X GET \\\n    --silent \\\n    --insecure \\\n    --header \"fauxapi-auth: \u003cauth-value\u003e\" \\\n    \"https://\u003chost-address\u003e/fauxapi/v1/?action=gateway_status\"\n```\n\n*Example Response*\n```javascript\n{\n  \"callid\": \"598ecf3e7011e\",\n  \"action\": \"gateway_status\",\n  \"message\": \"ok\",\n  \"data\": {\n    \"gateway_status\": {\n      \"10.22.33.1\": {\n        \"monitorip\": \"8.8.8.8\",\n        \"srcip\": \"10.22.33.100\",\n        \"name\": \"GW_WAN\",\n        \"delay\": \"4.415ms\",\n        \"stddev\": \"3.239ms\",\n        \"loss\": \"0.0%\",\n        \"status\": \"none\"\n      }\n    }\n  }\n}\n```\n\n---\n### interface_stats\n - Returns interface statistics data and information - the real interface name must be provided \n   not an alias of the interface such as \"WAN\" or \"LAN\"\n - HTTP: **GET**\n - Params:\n    - **interface** (required)\n\n*Example Request*\n```bash\ncurl \\\n    -X GET \\\n    --silent \\\n    --insecure \\\n    --header \"fauxapi-auth: \u003cauth-value\u003e\" \\\n    \"https://\u003chost-address\u003e/fauxapi/v1/?action=interface_stats\u0026interface=em0\"\n```\n\n*Example Response*\n```javascript\n{\n  \"callid\": \"5b3a5bce65d01\",\n  \"action\": \"interface_stats\",\n  \"message\": \"ok\",\n  \"data\": {\n    \"stats\": {\n      \"inpkts\": 267017,\n      \"inbytes\": 21133408,\n      \"outpkts\": 205860,\n      \"outbytes\": 8923046,\n      \"inerrs\": 0,\n      \"outerrs\": 0,\n      \"collisions\": 0,\n      \"inmcasts\": 61618,\n      \"outmcasts\": 73,\n      \"unsuppproto\": 0,\n      \"mtu\": 1500\n    }\n  }\n}\n```\n\n---\n### rule_get\n - Returns the numbered list of loaded pf rules from a `pfctl -sr -vv` command \n   on the pfSense host.  An empty rule_number parameter causes all rules to be\n   returned.\n - HTTP: **GET**\n - Params:\n    - **rule_number** (optional, default = null)\n\n*Example Request*\n```bash\ncurl \\\n    -X GET \\\n    --silent \\\n    --insecure \\\n    --header \"fauxapi-auth: \u003cauth-value\u003e\" \\\n    \"https://\u003chost-address\u003e/fauxapi/v1/?action=rule_get\u0026rule_number=5\"\n```\n\n*Example Response*\n```javascript\n{\n  \"callid\": \"583c279b56958\",\n  \"action\": \"rule_get\",\n  \"message\": \"ok\",\n  \"data\": {\n    \"rules\": [\n      {\n        \"number\": 5,\n        \"rule\": \"anchor \\\"openvpn/*\\\" all\",\n        \"evaluations\": \"14134\",\n        \"packets\": \"0\",\n        \"bytes\": \"0\",\n        \"states\": \"0\",\n        \"inserted\": \"21188\",\n        \"statecreations\": \"0\"\n      }\n    ]\n  }\n}\n```\n\n---\n### send_event\n - Performs a pfSense \"send_event\" command to cause various pfSense system \n   actions as is also available through the pfSense console interface.  The \n   following standard pfSense send_event combinations are permitted:-\n    - filter: reload, sync\n    - interface: all, newip, reconfigure\n    - service: reload, restart, sync\n - HTTP: **POST**\n - Params: none\n\n*Example Request*\n```bash\ncurl \\\n    -X POST \\\n    --silent \\\n    --insecure \\\n    --header \"fauxapi-auth: \u003cauth-value\u003e\" \\\n    --header \"Content-Type: application/json\" \\\n    --data \"[\\\"interface reload all\\\"]\" \\\n    \"https://\u003chost-address\u003e/fauxapi/v1/?action=send_event\"\n```\n\n*Example Response*\n```javascript\n{\n  \"callid\": \"58312bb3398bc\",\n  \"action\": \"send_event\",\n  \"message\": \"ok\"\n}\n```\n\n---\n### system_reboot\n - Just as it says, reboots the system.\n - HTTP: **GET**\n - Params: none\n\n*Example Request*\n```bash\ncurl \\\n    -X GET \\\n    --silent \\\n    --insecure \\\n    --header \"fauxapi-auth: \u003cauth-value\u003e\" \\\n    \"https://\u003chost-address\u003e/fauxapi/v1/?action=system_reboot\"\n```\n\n*Example Response*\n```javascript\n{\n  \"callid\": \"58312bb3487ac\",\n  \"action\": \"system_reboot\",\n  \"message\": \"ok\"\n}\n```\n\n---\n### system_stats\n - Returns various useful system stats.\n - HTTP: **GET**\n - Params: none\n\n*Example Request*\n```bash\ncurl \\\n    -X GET \\\n    --silent \\\n    --insecure \\\n    --header \"fauxapi-auth: \u003cauth-value\u003e\" \\\n    \"https://\u003chost-address\u003e/fauxapi/v1/?action=system_stats\"\n```\n\n*Example Response*\n```javascript\n{\n  \"callid\": \"5b3b511655589\",\n  \"action\": \"system_stats\",\n  \"message\": \"ok\",\n  \"data\": {\n    \"stats\": {\n      \"cpu\": \"20770421|20494981\",\n      \"mem\": \"20\",\n      \"uptime\": \"1 Day 21 Hours 25 Minutes 48 Seconds\",\n      \"pfstate\": \"62/98000\",\n      \"pfstatepercent\": \"0\",\n      \"temp\": \"\",\n      \"datetime\": \"20180703Z103358\",\n      \"cpufreq\": \"\",\n      \"load_average\": [\n        \"0.01\",\n        \"0.04\",\n        \"0.01\"\n      ],\n      \"mbuf\": \"1016/61600\",\n      \"mbufpercent\": \"2\"\n    }\n  }\n}\n```\n---\n### system_info\n - Returns various useful system info.\n - HTTP: **GET**\n - Params: none\n\n*Example Request*\n```bash\ncurl \\\n    -X GET \\\n    --silent \\\n    --insecure \\\n    --header \"fauxapi-auth: \u003cauth-value\u003e\" \\\n    \"https://\u003chost-address\u003e/fauxapi/v1/?action=system_info\"\n```\n\n*Example Response*\n```javascript\n{\n    \"callid\": \"5e1d8ceb8ff47\",\n    \"action\": \"system_info\",\n    \"message\": \"ok\",\n    \"data\": {\n        \"info\": {\n            \"sys\": {\n                \"platform\": {\n                    \"name\": \"VMware\",\n                    \"descr\": \"VMware Virtual Machine\"\n                },\n                \"serial_no\": \"\",\n                \"device_id\": \"719e8c91c2c43b820400\"\n            },\n            \"pfsense_version\": {\n                \"product_version_string\": \"2.4.5-DEVELOPMENT\",\n                \"product_version\": \"2.4.5-DEVELOPMENT\",\n                \"product_version_patch\": \"0\"\n            },\n            \"pfsense_remote_version\": {\n                \"version\": \"2.4.5.a.20200112.1821\",\n                \"installed_version\": \"2.4.5.a.20191218.2354\",\n                \"pkg_version_compare\": \"\u003c\"\n            },\n            \"os_verison\": \"FreeBSD 11.3-STABLE\",\n            \"cpu_type\": {\n                \"cpu_model\": \"Intel(R) Core(TM) i7-7700 CPU @ 3.60GHz\",\n                \"cpu_count\": \"4\",\n                \"logic_cpu_count\": \"4 package(s)\",\n                \"cpu_freq\": \"\"\n            },\n            \"kernel_pti_status\": \"enabled\",\n            \"mds_mitigation\": \"inactive\",\n            \"bios\": {\n                \"vendor\": \"Phoenix Technologies LTD\",\n                \"version\": \"6.00\",\n                \"date\": \"07/29/2019\"\n            }\n        }\n    }\n}\n```\n---\n\n## Versions and Testing\nThe FauxAPI has been developed against the following pfSense versions \n - **2.3.x** - 2.3.2, 2.3.3, 2.3.4, 2.3.5\n - **2.4.x** - 2.4.3, 2.4.4, 2.4.5\n - **2.5.x** - 2.5.0-DEVELOPMENT-amd64-20200527-1410\n \nFauxAPI has not been tested against 2.3.0 or 2.3.1.  Additionally, it is apparent the pfSense \npackaging technique changed significantly prior to 2.3.x so it is unlikely it will be backported \nto anything prior to 2.3.0.\n\nTesting is reasonable but does not achieve 100% code coverage within the FauxAPI \ncodebase.  Two client side test scripts (1x Bash, 1x Python) that both \ndemonstrate and test all possible server side actions are provided.  Under the \nhood FauxAPI, performs real-time sanity checks and tests to make sure the user \nsupplied configurations will save, load and reload as expected.\n\n__Shout Out:__ *Anyone that happens to know of _any_ test harness or test code \nfor pfSense please get in touch - I'd very much prefer to integrate with existing \npfSense test infrastructure if it already exists.*\n\n\n## Releases\n#### v1.0 - 2016-11-20\n - initial release\n\n#### v1.1 - 2017-08-12\n - 2x new API actions **alias_update_urltables** and **gateway_status**\n - update documentation to address common points of confusion, especially the \n   requirement to provide the _full_ config file not just the portion to be \n   updated.\n - testing against pfSense 2.3.2 and 2.3.3\n\n#### v1.2 - 2017-08-27\n - new API action **function_call** allowing the user to reach deep into the inner \n   code infrastructure of pfSense, this feature is intended for people with a \n   solid understanding of PHP and pfSense.\n - the `credentials.ini` file now provides a way to control the permitted API \n   actions.\n - various update documentation updates.\n - testing against pfSense 2.3.4\n\n#### v1.3 - 2018-07-02\n - add the **config_patch** function providing the ability to patch the system config, \n   thus allowing API users to make granular configuration changes.  \n - added a \"previous_config_file\" response attribute to functions that cause write \n   operations to the running `config.xml`\n - add the **interface_stats** function to help in determining the usage of an \n   interface to (partly) address [Issue #20](https://github.com/ndejong/pfsense_fauxapi/issues/20)\n - added a \"number\" attibute to the \"rules\" output making the actual rule number more \n   explict as described in [Issue #13](https://github.com/ndejong/pfsense_fauxapi/issues/13)\n - addressed a bug with the **system_stats** function that was preventing it from \n   returning, caused by an upstream change(s) in the pfSense code.\n - rename the confusing \"owner\" field in `credentials.ini` to \"comment\", legacy \n   configuration files using \"owner\" are still supported. \n - added a \"source\" attribute to the logs making it easier to grep fauxapi events, \n   for example `clog /var/log/system.log | grep fauxapi`\n - plenty of documentation fixes and updates\n - added documentation highlighting features and capabilities that existed but were not \n   previously obvious\n - added the [`extras`](https://github.com/ndejong/pfsense_fauxapi/tree/master/extras) path \n   in the project repo as a better place to keep non-package files, `client-libs`, `examples`,\n   `build-tools` etc\n - testing against pfSense 2.3.5\n - testing against pfSense 2.4.3\n\n#### v1.4 - 2020-05-31\n - Added **system_info** function to return various useful system information.\n - include include `phpsessionmanager.inc` since it is commonly required in other function calls\n - testing against pfSense 2.4.5\n - testing against pfSense 2.5.0 (pfSense-CE-2.5.0-DEVELOPMENT-amd64-20200527-1410.iso)\n\n## FauxAPI License\n```\nCopyright 2016-2020 Nicholas de Jong\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fndejong%2Fpfsense_fauxapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fndejong%2Fpfsense_fauxapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fndejong%2Fpfsense_fauxapi/lists"}