System Patches Package

The System Patches package manages patches which change the behavior of pfSense® software. These patches may be bundled with the package, fetched from the official code repository, pasted in, or even uploaded from other sources.

This package makes it simple obtain official recommended security patches and bug fixes from Netgate between releases, as well as to test and deploy custom changes.

Installing the package

This package is available in the package repository:

  • Navigate to System > Packages, Available Packages tab.

  • Find System Patches in the list, or search for it.

  • Click fa-plus Install at the end of its row

  • Click fa-check Confirm to confirm the action and complete the installation.

Once the installation finishes, Patches may be managed at System > Patches.

Patch Settings

When creating or editing a Custom System Patch entry, 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 however many levels are necessary, which in this example would be 3.

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 if the patch content 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-can 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 as described earlier in this document under Recommended System Patches. The controls in this section are limited as there is no need to edit the entries or alter the list.

Warning

There is typically no need to revert Custom or Recommended patch entries before or after upgrading pfSense software. Newer releases may contain the same fix as an older patch, which means the patch may appear to be applied after upgrading. Reverting such patches will remove the fix from the new release, bringing back the old bug. As such, the best course of action is to delete outdated Custom System Patch entries without reverting them.

Adding a Custom Patch

  • Navigate to System > Patches

  • Read the text and warnings!

  • Click fa-plus Add New Patch under the Custom System Patches section

  • 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 for a patch, the entry in the patch list 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. The package will then 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

  • It is normal for an already-applied patch to show only a revert button. Similarly, if an older patch is present on a newer release which includes the fix, it will appear as already applied.

    Warning

    Do not revert these patches after upgrading! – Doing so will undo the fix and cause problems on the new release.

  • If one patch relies upon another patch being applied first, their usual actions may not appear unless taken in the proper order. For example, patch 2 may not show an Apply button until after patch 1 is applied. Likewise for reverting.

  • Click fa-arrows-rotate 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.