System Patches Package

The System Patches package allows patches to be added, either from the official code repository or ones pasted in from e-mail or other sources.

This makes it easier to test and deploy small changes instead of pulling in many changes.

Installing the package

As with any other pfSense® package, it’s available via the package repository.

  • Navigate to System > Packages, Available Packages tab.

  • Find System Patches in the list.

  • Click fa-plus at the end of its row, then confirm, to install.

Patches may now be managed at System > Patches.

Patch Settings

When creating or editing a patch, the following settings are available:

Description

Text identifying the patch for reference.

URL/Commit ID

A Git commit ID for the pfSense CE software repository on Github, or the full URL to a patch file.

After saving the patch, use the Fetch button to download the patch content to the firewall.

Patch Contents

The contents of the patch in unified diff format.

When using a URL or commit ID, this should be blank when first saving but will contain the patch content after fetching.

Patch File Upload

A button to populate the Patch Contents by selecting a file on the client computer.

Path Strip Count

The number of path components to remove from the paths in patch metadata.

GitHub commit IDs and URLs should be count of 2 (default and fixed automatically on save). Patches from other sources will need to be set appropriately.

For example, if a path like a/src/etc/inc/filter.inc is in the patch header, the package should strip off the a/src so a strip count of 2 is needed. If it’s deeper, such as home/me/patches/etc/inc/filter.inc, strip 3 levels.

Base Directory

The package assumes a base directory of / for patches by default, but an alternate base may be applied if a patch does not supply a full path to the file it is patching (e.g. /usr/local/www).

Ignore Whitespace

Whether or not the patching process should ignore whitespace differences in the patch data.

Patches from GitHub should work with either whitespace setting, patches from other sources may need the option set to ignore whitespace, especially if they contain DOS line endings rather than UNIX or lost tabs when copying and pasting.

Auto Apply

Whether or not the package will attempt to apply this patch on each boot of the firewall.

For patches which are included in future releases of pfSense software this is unnecessary as the appropriate fixes are included in the new release and need not be applied again. For manual custom changes this may be necessary to ensure these customizations are restored after upgrades.

The patches may be reordered in the list to arrange them so they apply in a specific order automatically, in case one patch depends on a previous patch.

Patch ID

When editing an existing patch, the GUI displays its unique ID in this field.

Managing Patch Entries

Manage patch entries at System > Patches.

The Custom System Patches list is for patches added manually by firewall administrators. The list has the following functions:

Select/Move

Selects entries to move or delete.

Clicking the fa-anchor icon moves selected patches to this position, altering the order of patches. This may be relevant with auto-apply if one patch depends upon another.

Description

Text describing the patch, for reference.

Fetch

A button to download the patch content from its source, either a custom URL or a Github commit ID.

Apply

Attempt to apply this patch.

Revert

Attempt to revert this patch.

View

View the contents of the patch data.

Debug

Test the patch and interpret the results, this will display information about why a patch may not apply or restore cleanly. The output will include a detailed analysis of the results and can optionally display full detail of patch failures.

Auto Apply

A read only indication of whether this patch entry has the auto-apply option enabled.

Edit

The fa-pencil icon edits this patch entry.

Delete

The fa-trash icon deletes this patch entry.

Add New Patch

Creates a new patch entry.

Delete Patches

Deletes all selected patch entries.

Note

The GUI does not display buttons unless they are relevant.

The lower section contains Recommended System Patches for the specific running version of pfSense software. These patches are curated by Netgate and may include security fixes, bug fixes, and other beneficial changes which come up between releases. This list is only updated when the package is updated, so check the package manager for updates. The controls in this section are limited as there is no need to edit the entries or the list.

Adding a Patch

  • Go to System > Patches

  • Read the text and warnings!

  • Click fa-plus to add a new patch

  • Enter Patch Settings as described previously using one of the following styles:

    • Commit ID (e.g. 4573641589d50718b544b778cea864cfd725078a) in the URL/Commit ID field

    • GitHub commit URL (e.g. https://github.com/pfsense/pfsense/commit/4573641589d50718b544b778cea864cfd725078a) in the URL/Commit ID field

    • GitHub Pull Request (PR) URL with ‘.diff’ appended, such as https://github.com/pfsense/pfsense/pull/XXXX.diff where XXXX is the PR number

      Set Path Strip = 2 if it does not adjust automatically

    • Full URL to a patch from another source (e.g. https://redmine.pfsense.org/attachments/594/0001-Add-support-for-aliases-in-DNS-Forwarder-fixes-2410.patch) in the URL/Commit ID field

    • Leave URL/Commit ID blank and paste the contents of a patch into Patch Contents text area or upload a patch file

  • Click Save

Applying/Reverting a patch

If a URL or commit ID was entered, the entry will have a fetch button.

Click fetch and firewall will retrieve the patch content. This does not apply the patch.

To apply the patch, click Apply and the package will apply the patch. The available link for the patch will then change to say Revert instead.

To revert, click Revert.

See also

Managing Patch Entries

Troubleshooting

  • Click fa-refresh Re-Fetch for remote patches to make sure the package has a clean copy of the patch content.

  • Click Debug to run a test and then click Detail next to either the apply or revert line to get the full patch output

  • If the above test output mentions No file to patch, double check the Path Strip Count and/or the Base Directory.

  • If every part of a patch fails, try toggling Ignore Whitespace.

Known issues

See also

The pfSense bug tracker contains a list of known issues with this package.

Package Support

This package is currently supported by Netgate TAC to those with an active support subscription.