Skip to content

Custom Firewall Provider

You can easily integrate your own firewall into Tenantos with a custom provider.

Despite the name, this is not limited to packet firewalls. It fits access control lists, DDoS protection, game filters and similar systems just as well, because the implementation decides what a rule and a setting actually contain.

For the general firewall behaviour, the tab, the capabilities and the permissions, see Firewall Management.

Quick Facts:

  • A custom firewall provider is one PHP class placed under /var/www/html/app/Custom/Modules/Firewall/<YourFirewallName>.
  • A provider is always backed by an external provider.
  • The capabilities are provider-driven. Your implementation declares whether it supports rules, settings, staged editing and reordering, and the interface adapts to it.
  • It is not limited to firewalls in the narrow sense. You can model access control lists, DDoS protection with attack types and thresholds, game filters and so on.
  • Everything under app/Custom survives Tenantos upgrades.

How it works

Every custom firewall provider is backed by an external provider. The external provider is where you should keep everything that is shared across all connections of that type. That is the API endpoint, an API token or a username and password, a region and any other account-wide setting.

Each server then receives a firewall connection that points to that external provider. The connection only carries what is specific to that one server, for example an identifier of the server inside the provider, if the provider needs one at all.

This split is by design - secrets and global configuration stay in a single place (the external provider) and server connection assignments only contain the server-specific information.

Your class declares which fields belong on the external provider and which belong on the connection. Tenantos renders both setup forms from that declaration, resolves the connection and its external provider, and hands your class a ready-to-use context with the credentials, the provider settings and the connection details. Your class implements the firewall interface and reads those values. It does not need to deal with the layers in between.

Where to find the example

A complete, commented example ships with every installation at:

/var/www/html/app/Custom/Modules/Firewall/Examplefw/Examplefw.php.example

It is a working, rule-based provider that documents every capability, every field type and the optional hooks.

How to add a new provider

The quickest start is to copy the Examplefw folder in /var/www/html/app/Custom/Modules/Firewall/, rename the folder, the file and the class, and then adjust describe() and the methods so they talk to your system.

The folder, the file and the class must share the same name, with a capital first letter. A provider named CiscoASA therefore lives in CiscoASA/CiscoASA.php with the class CiscoASA.

Once the class is in place:

  • Add an external provider of your new type. It appears in the provider list automatically.
  • Add a firewall connection assignment on every server that should use it, pointing at the external provider you created.
  • The Firewall tab and the features your provider declares show up on those servers right away.