Writing a package for PFSense

In this article I will try to show with a simple example how to create my own GUI package for pfSense . It is assumed that the reader has experience with pfSense, has some knowledge of PHP.


The pfSense router (based on FreeBSD) is used by many sysadmins due to, first of all, managing the system settings via the WEB interface. Even a novice administrator can easily cope with many settings, which allows expanding the scope of this router. At the same time, experienced colleagues can take full advantage of access to the console to study and control the operation of the system.

In addition to the standard settings of the router, most of which can be done via the WEB interface, sometimes enterprise-specific tasks arise that require the system administrator to manage settings through the console. Next, I want to show how to put my best practices in code that allows you to manage system settings from the WEB interface.

So, you have installed and configured test pfSense. To get started, we need access to the console and pfSense files via SSH. Since I am a winuser, I will also use WinSCP + Putty for the tools for work.

Using WinSCP3 we connect to pfSense and open the directory / usr / local / pkg. This folder contains files related to GUI packages. Typically, these are XML and INC files, including configuration descriptions and PHP package handlers. The GUI package configuration description is located in XML files, and contains:
  • service information;
  • header of the WEB interface page;
  • WEB interface page form;
  • information about PHP functions-handlers of events of the WEB interface.

Create two empty files mypkg.xml and mypkg.inc . The name mypkg is the name of our package, and the name of the XML file is the key to access the WEB interface of the package. The name of the inc file can be arbitrary, and the way to connect it will be shown below.

We form our XML file.

The service information contains the name, title, category, version of the GUI package and a list of connected INC files. In our case, there is only one connected INC file, the full path to the connected file must be specified.

mypkgMy First PackageTest0.1/usr/local/pkg/mypkg.inc

The WEB interface header contains the description of the GUI pages in the tabs node , and is displayed in the navigation area. We will have only one page. The text element contains the name of the navigation item in the GUI. The url element contains the relative access path to our package page.

My Package/pkg_edit.php?xml=mypkg.xml

The WEB interface form describes which controls for the parameters of our package will be available to the user. First, create one single Enable field with the checkbox element :

EnableenableCheck this for enable package.checkbox

Event handlers The WEB interface is the final section of the XML file, and describes what functions will be called at one time or another when the GUI form is running. Three commonly used handlers are presented:
  • custom_php_command_before_form - called before the form is displayed;
  • custom_php_validation_command - called when checking the data of each form element before saving its data;
  • custom_php_resync_config_command - called when saving form data

Using handlers, you can specify the names of php functions from the mypkg.inc file that will be called on an event. Specific actions to change the configuration of the router are performed in the custom_php_resync_config_command handler , which is called both by clicking the Save button on the forms and when pfSense is loaded.

Here you can see the full text of the file:

Mypkg.xml file
mypkgMy First PackageTest0.1/usr/local/pkg/mypkg.incMy Package/pkg_edit.php?xml=mypkg.xmlEnableenableCheck this for enable package.checkbox

We create the mypkg.inc file empty, because our test package does nothing.

File mypkg.inc

After saving the created files mypkg.xml and mypkg.inc in the / usr / local / pkg directory, you can check how our package will look. To do this, go to the pfSense WEB interface and add the path /pkg_edit.php?xml=mypkg.xml in the address bar . If everything is done correctly and without errors, we will get such a picture.


As a result, we received a very simple GUI package that does not perform anything useful, does not save any data, and is not even registered in the WEB interface menu. Nevertheless, with the example of this package you can get an idea of ​​the mechanism of operation of the pfSense GUI.

PS: For earlier, I apologize for possible shortcomings. This article is written for an invite.. If this topic will be of interest to the community, I will try to talk in more detail about how to create a full-fledged GUI package for pfSense.

Also popular now: