Developer’s Guide

We use Asciidoctor tags for section titles (headings) in place of AsciiDoc tags, see table below for equivalence:

We use inter-document cross references feature to make links between all PacketFence guides. When we need to link to a specific section of a document, we use automatic anchors feature to have a correct display in PDF.

Source: AsciiDoc Mark-up Quick Reference for Red Hat Documentation

This is a guide on how to setup/use the PacketFence Golang libraries.

In order to bootstrap your environment:

If you work directly on sources, you can run:

This will install Golang version use to build PacketFence Golang binaries and check if all modules defined in go.mod are available.

You should then source your .bashrc to get the new environment variables:

You can get a complete overview of your Golang environment with go env command.

Dependencies use go modules and will be fetched automatically during build time.

You will also need ipset-devel and pkgconfig libraries which can be installed using the following command:

All code should be built into a Caddy middleware which we’ll then use in a Caddyfile to create our recipes. Only reason for not using Caddy would be that the binaries doesn’t interact using HTTP (which Caddy can handle at some point). For now, we’ll focus only on services using HTTP until we’re confortable with Caddy.

A local version of Caddy is in caddy/caddy. This is a vendored version of Caddy which includes the plugins and middlewares for PacketFence.

In order to build the Caddy HTTP service (pfhttpd):

Do the same to build pfdns, pfdhcp, pfdetect and pfstats:

Once you’ve built pfhttpd, you can use a Caddyfile to load your middleware and bind it on a specific port:

This file should be put in /usr/local/pf/conf/caddy-services/pfexample.conf

Note how you can control the logger configuration from the Caddyfile. If your middleware (in this example pfsso) uses or calls the logger, you must declare it in your Caddyfile.

If your middleware uses statsd, you don’t have to configure statsd in your Caddyfile which will result in the packets just not being sent (a dummy statsd client will be created).

You can start pfhttpd with your Caddyfile using the following command:

Once you have ascertained that the service is working correctly, you need to create an instance of pf::services::manager for it. You will also need to create a unitfile for it in conf/systemd like the following:

Make sure that the packaging is also updated to copy those files in the /usr/lib/systemd/system directory.

Like the perl unit tests, the Golang tests rely on the presence of the test pfconfig process to execute properly.

In order to start the test pfconfig process:

You can proceed to execute all or some of the Golang unit tests:

In order to run all the tests easily you can also do:

The pfperl-api command located in /usr/local/pf/sbin/ directory can be use directly from a PacketFence server to query the API without having to specify an authentication token and extra-parameters.

Example to get your general configuration:

Example to create a node:

Example to create a node with JSON payload in a dedicated file:

First, get an authentication token with the webservices credentials or an admin account:

You will get following response :

Then use this token to query the API. The following example fetches the general configuration:

Although the API should mostly stay the same, backward compatibility is not 100% guaranteed for the moment until the v1 API reaches full maturity.

In this case, the field is part of one of the main PacketFence tables, but PacketFence is unaware of it. PacketFence won’t consult the field and won’t be able to modify it. A possible usage scenario would be a 3rd party application which maintains this field.

Since PacketFence doesn’t have to know about the field, all you have to do is execute your SQL ALTER TABLE query and you are done.

In this case, PacketFence can show the contents of the table using both pfcmd but won’t be able to modify the contents of the field.

Start by modifying the database table using an SQL ALTER TABLE query.

Then, modify the Perl module having the same name as the table you have added the field to, i.e. If you added the field to the node table, then edit /usr/local/pf/lib/pf/node.pm. You’ll have to modify the SQL SELECT queries at the beginning of the file to include your new field and, possibly the functions using these queries. If your new field should be used in reports, the dashboard or graphs, you’ll also have to modify the queries in /usr/local/pf/lib/pf/pfcmd/graph.pm, /usr/local/pf/lib/pf/pfcmd/report.pm and /usr/local/pf/lib/pf/pfcmd/dashboard.pm.

Start by creating the read-only field as described above.

Then, modify the SQL UPDATE and INSERT queries in the database tables' Perl module, as well as the associated functions.

You need to define a new class which inherits from pf::Switch and defines at least the following functions:

The parseTrap function will need to return an hash with keys trapType and trapIfIndex. The associated values must be up or down for trapType and the traps' ifIndex for trapIfIndex. See a similar switch’s implementation for inspiration. Usually recent modules are better coded than older ones.

In addition to the functions mentioned for link change, you need to define the following function:

Also, your parseTrap function will need to return trapOperation, trapVlan and trapMac keys in addition to trapType equals mac. See a similar switch’s implementation for inspiration. Usually recent modules are better coded than older ones.

In addition to the functions mentioned for link change, you need to define the following functions:

In this case, the parseTrap function needs to return secureMacAddrViolation for the trapType key. See a similar switch’s implementation for inspiration. Usually recent modules are better coded than older ones.

RADIUS Dynamic Authorization also known as RADIUS Change of Authorization (CoA) or RADIUS Disconnect Messages is supported by PacketFence starting with version 3.1.

On wired network devices CoA can be used to change the security posture of a MAC and perform other functions like bounce a port. So far we only encountered support for CoA on the wired side on the Cisco hardware. For an implementation example check _radiusBounceMac in pf::Switch::Cisco.

Floating Network Devices are described in the Administration Guide under "Floating Network Devices" in the "Optional Components" section. Refer to this documentation if you don’t know what Floating Network Devices are.

In order to support Floating Network Devices on a switch, you need to implement the following methods:

You might need to implement the following:

Once all the required methods are implemented, enable the capability in the switch’s code with:

PacketFence’s minimum requirements regarding Wireless hardware is:

Most of these features are available on enterprise grade Access Points (AP) or Controllers. Where the situation starts to vary wildly is for deauthentication support.

Start with a copy of the template module pf/lib/pf/Switch/WirelessModuleTemplate.pm and fill in appropriate documentation and code.

You need to implement at least:

If default implementation of the following methods doesn’t work you will need to override them:

It is important to validate the Access-Point (AP) to Controller relationship when operating in bridged mode versus when operating in tunneled mode. For example, some hardware will send the RADIUS Access-Request from the AP when in bridged mode even though it is controlled by a controller. This behavior impacts deauthentication because it still needs to be performed on the controller. To support this behavior a switches.conf parameter was introduced: controller_ip.

When adding a new Wireless module try to validate the bridged versus tunneled behavior and modify deauthenticateMac() to honor controller_ip if required.

To start building PacketFence, we need to install specific things in images like:

We use Ansible and shell scripts to cover these steps. It’s possible because Python is already installed in buildpkg Docker images.

When GPG keys from upstream repos can’t be download automatically from Internet, we store them in ci/packer/provisionners/upstream directory to upload them in Docker images.

Build dependencies need to be install in Docker images before starting build process. We rely on gitlab-buildpkg-tools to automatically install those dependencies based on packages specifications file. Consequently, all build requires need to be define in packages specifications file.

We use Packer to set up a Golang environment in order to build Golang binaries in Docker images.

We also set environment variables in Docker images, using ENV directives, to simplify usage of go commands.

To make Docker images lightweight, we make a clean up at end of the process.

Because we run build inside a GitLab pipeline, many environment variables can be set to change build behavior. A Makefile and a wrapper are provided to simplify creation of a new Docker images based on environment variables.

Install following softwares:

For day to day development one can run a checkout of the current development branch in /usr/local/pf/ and develop there within a working setup.

If you prefer to use packages, you can install latest PacketFence packages from nightly builds.

You can meet these prerequisites by starting a pf*dev Vagrant virtual machine using instructions in Virtual environment: initial setup section.

Inside pf*dev virtual machines, t directory will be available under /src/t.

After a vagrant up command, unit tests should have been run. If you want to run them again, execute following command:

This will upload run-tests.sh script on virtual machine to run it.

If you want to run only Perl unit tests, disable Golang unit tests using GOLANG_UNIT_TESTS environment variable:

If you want to run only Golang unit tests, disable Perl unit tests using PERL_UNIT_TESTS environment variable:

You can get more details on Golang unit tests in Golang section.

In ci/lib/test, you will find a Makefile used as a wrapper to start, test and destroy virtual machines. Examples:

This topology require a working libvirt setup (Virtualbox is not supported) and is defined as Infrastructure-as-code in two Vagrantfiles.

We use the hosted service Transifex to translate PacketFence’s PO files. It offers the possibility to translate all the strings online as well as providing a command-line tool to push your changes. It’s very convenient.

To use Transifex, you must first sign up for a free account here: https://www.transifex.net/plans/signup/free/

If you need further help about using Transifex, you might want to have a look here.

If you want to add support for a new language, please follow these steps:

Submit your new translation to the PacketFence project by contacting us at packetfence-devel@lists.sourceforge.net.

You can add customize templates to the /usr/local/pf/html/pfappserver/root-custom/ folder to override current templates.

However when doing this you must keep track of any changes to those templates across versions.

The main stylesheet is the result of processing some Sass files structured around the excellent Bootstrap framework.

In order to prepare your environment, you need to install grunt (the task runner) and bower (the package manager):

Once all modules and components are downloaded, you can customize the Sass files or JavaScript files and generate a new version of the static files:

You change the behavior of the controllers by modifying the controllers in the path.

/usr/local/pf/html/pfappserver/lib/pfappserver/Controller/

However when doing this you must keep track of any changes to those Controllers across versions.