Installation and Configuration

Requirements

Hardware requirements

Overall, the REST API package is designed to be as lightweight as possible and should run fine on any hardware that can run pfSense. It's recommended to follow Netgate's minimum hardware requirements.

Warning

  • The package is currently not compatible with 32-bit builds of pfSense. It is recommended to use the legacy v1 package for 32-bit systems.
  • While the package should behave identically on 64-bit architectures other than amd64, automated testing only covers amd64 builds of pfSense. Support on other architectures is not guaranteed.

Supported pfSense versions

  • pfSense CE 2.7.2
  • pfSense Plus 24.03
  • pfSense Plus 24.11

Warning

Installation of the package on unsupported versions of pfSense may result in unexpected behavior and/or system instability.

Tip

Don't see your version of pfSense? Older versions of pfSense may be supported by older versions of this package. Check the releases page.

Installing the package

The pfSense REST API package is built just like any other pfSense package and can therefor be installed easily using pkg from the pfSense command line. Below are the installation commands for the latest version of the package.

Install on pfSense CE

pkg-static add https://github.com/jaredhendrickson13/pfsense-api/releases/latest/download/pfSense-2.7.2-pkg-RESTAPI.pkg

Install on pfSense Plus

pkg-static -C /dev/null add https://github.com/jaredhendrickson13/pfsense-api/releases/latest/download/pfSense-24.03-pkg-RESTAPI.pkg

Important

  • You may need to customize the installation command to reference the package built for your pfSense version. Check the releases page to find the package built for your version of pfSense.
  • When updating pfSense, you must reinstall this package afterward as pfSense removes unofficial packages during system updates and has no way to automatically reinstall them.
  • If you're looking for a method of programmatically installing the package without SSH, check out pfsense-vshell!

Configuring the package

The REST API is designed to be ready to use out of the box. However, there are a number of configuration options available to you to customize the API to your needs. The REST API settings can be configured in pfSense webConfigurator under 'System' -> 'REST API' or via PATCH request to the /api/v2/system/restapi/settings endpoint.

Deleting the package

To remove the REST API package from your pfSense instance, you can use the following command:

pfsense-restapi delete

Note

In the event that you are unable to use the pfsense-restapi command, you can manually remove the package by running pkg-static delete pfSense-pkg-RESTAPI.

Updating the package

Before updating the package, it is recommended to enable the REST API's 'Keep Backup' setting to ensure that your REST API configurations, keys and access lists are not lost during the update process. It is also highly recommended to read and understand both the release change notes on GitHub and the versioning policy to ensure you do not unintentionally introduce breaking changes to your environment.

Tip

While the package is updating, the REST API may be unavailable for a short period of time. Updates typically complete within a minute, but may vary depending on network environment and conditions. It is recommended to schedule updates during off-peak hours to minimize impact to your integrations. In the event that the update fails, or takes an excessive amount of time, it is recommended to uninstall and reinstall the package.

From the pfSense webConfigurator

You can easily update or revert the package version from the pfSense webConfigurator by navigating to 'System' -> 'REST API' -> 'Updates' and select the desired version. Click 'Save' to apply the desired version.

From the API

You can update or revert the package to a specified version by sending a request to the PATCH /api/v2/system/restapi/version endpoint. Simply set the install_version field to the desired version and send the request.

From the command line

You can update the package to latest version available to your pfSense version by running the following command:

pfsense-restapi update

If you need to revert or upgrade the package to a specific version, you can do so by running the following command:

pfsense-restapi revert <version>

Versioning policy

The REST API package loosely follows Semantic Versioning. The versioning policy is as follows:

  • Major version changes (e.g. 1.x.x to 2.x.x) may include major breaking changes and are not guaranteed to be backwards compatible. Major changes will often include significant changes to the framework, endpoints, schemas, and/or behavior.
  • Minor version changes (e.g. 2.0.x to 2.1.x) may include new features, bug fixes, and/or minor breaking changes. Breaking changes will be isolated to specific endpoints and will be documented in the release notes.
  • Patch version changes (e.g. 2.0.0 to 2.0.1) will only include bug fixes and very small enhancements. Patches will never contain breaking changes or significant new features that could impact existing functionality.

Pre-release versions

Pre-release versions are occasionally made available to the public to allow for testing of new features and fixes. Pre-releases will be notated as such on GitHub and are not considered as release candidates within the REST API package's update features by default. You may opt-in to pre-release updates by enabling the 'Allow Pre-releases' setting in the REST API settings.

Warning

Pre-release versions may contain breaking changes, bugs, and/or incomplete features. It is recommended to only use pre-release versions in testing environments and never in production.