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
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 thea/src
so a strip count of2
is needed. If it’s deeper, such ashome/me/patches/etc/inc/filter.inc
, strip3
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
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
icon edits this patch entry.
- Delete
The
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
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 fieldGitHub commit URL (e.g.
https://github.com/pfsense/pfsense/commit/4573641589d50718b544b778cea864cfd725078a
) in the URL/Commit ID fieldGitHub Pull Request (PR) URL with ‘.diff’ appended, such as
https://github.com/pfsense/pfsense/pull/XXXX.diff
where XXXX is the PR numberSet Path Strip =
2
if it does not adjust automaticallyFull 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 fieldLeave 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
Troubleshooting¶
Click
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.