Starting point for developing a Package?

luckman212

Hi, hope everyone is safe!

One of my rainy-day projects has been to create a pfSense Package. I've had a few ideas kicking around for years now. Since I have a bit of extra downtime these days I figured now might be a good time to take a crack at it.

The Netgate Docs at https://docs.netgate.com/pfsense/en/latest/development/developing-packages.html haven't been updated since circa-pfSense v2.3 which is 2+ years old at this point.

Just wondering if these instructions are still valid for 2.4.x or if there is possibly a newer guide somewhere that covers getting started, pitfalls, etc?

Gertjan

Hi,

Actually, you have all the details already at your disposal. No real need to look up any wiki or manual.
These packages :
cron - Notes - RRD_Summary - Shellcmd and System_Patches just to name some simple ones - mostly wriiten by pfSense / Netgate guys (do they have girls ?).

Then, step up and see how acme was build. It's uses a known script from a very known GitHub location, and a bucnh of code was written eround it so it fits into the pfSense GUI / Cert store, etc.

Take Avahi if you want to see how the usual GUI 'gleu' code is build (the settings page) and how a process is installed, and stopped / started etc.

And yes, you should know how the pfSense GUI works ....

So, it boils down to : if you can read - understand what you read, then you can "copy" that info and start from there.
Still, all this does not make your package show up in the Repository ... for that to happen, you have to convince Netgate (they will call you when the times comes ;) )

Btw : I saw a lot of package related code, still I don't haven't seen yet an "entry point" where one can place a "package file" so it gets installed into pfSense.
Maybe it still exists .... I did, in the past - I guess .... not sure anymore.

Also : the package system uses the 'pkg' FreeBSD package system. That one is documented. keep in mind to write for "FreeBSD 11.3" version of code, and know, that Netgate can shift any time to something else like FreeBSD 12.x.

I have to add : I would love to read the story of @BBcan177 : how he did it. From the begins to ... now. And if he would do it again, knowing what he knows now ;)

I which you much and wich could find time to do the same thing. It's one of the best ways of learning a system : attributing to it.

bmeeks

You have two options for developing a package on pfSense. One is to use the builtin XML framework and the other is to code everything in pure PHP. To be 100% accurate, there is a type of hybrid option available; but it can be a bit cumbersome in my opinion.

The XML framework is what you found documented in the link you shared. The framework is great for limited functionality GUI implementations. Many packages exist that solely use the XML framework. However, other packages need to do more complex GUI things and those packages tend to be pure PHP. Of course all packages, whether using the framework or pure PHP, need to provide the manifest file so that the package subsystem within pfSense knows how to install the package.

When I was taking over maintaining the Snort package I spent a lot of time looking at the source code of other packages. You can gain valuable insights that way.

I suggest creating a pfSense virtual machine and then installing a package or two on it and start looking through the source code. You can also look at the Github source to gain insights. Here is a link to the Snort GUI package's Github source in the pfSense FreeBSD-ports repository: https://github.com/pfsense/FreeBSD-ports/tree/devel/security/pfSense-pkg-snort. Look through all the subdirectories in that link and you can see which files go where. Open up and look into the files and you can see what they are doing and/or what they are providing.

The general rule for 100% pure PHP packages is that direct GUI generation files would go in /usr/local/www/pkg_name and supporting files with common functions and such go in /usr/local/pkg/pkg_name. So using Snort as an example, files that generate GUI screens are in /usr/local/www/snort and files that provide common support functions are in /usr/local/pkg/snort.

Finally, it is the case that most packages on pfSense actually exist to simply create a configuration file for an underlying binary executable to use. The Snort and Suricata packages simply create the snort.conf or suricata.yaml conf files for the underlying snort and suricata binaries to use. All the real work of traffic inspection is done within those binary modules, and the binaries come from separate FreeBSD ports. Any binary runtime dependencies are specified in the Makefile for the package.

luckman212

@bmeeks Great, this is very helpful information (and thanks for your work on the Snort package! )