You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Ad Schellevis 555408d11e Phalcon 5 / php 8.1 compatibility 3 months ago
cache initial working version including basic documentation 5 years ago
conf work in progress, use run_server.php to startup a local webserver and browse to /ui/ pages locally, when -d is specified xdebug is enabled (slow, but functional). 5 years ago
config work in progress to support phalcon 5 ( 6 months ago
public Phalcon 5 / php 8.1 compatibility 3 months ago
stubs Phalcon 5 / php 8.1 compatibility 3 months ago
temp initial working version including basic documentation 5 years ago
.gitignore initial working version including basic documentation 5 years ago
LICENSE Initial commit 5 years ago add README section for preparing osx 1 year ago
run_server.php fix open_basedir restriction handling 5 years ago


Support tools to ease local frontend development using the built-in
php webserver.

The main goal of this repository is to allow user interface development without the need
for an actual OPNsense deployment, which eases the process of designing frontend modules.

Debugging (using xdebug) is supported, although keep in mind that this will slow down all requests as
the static pages are also delivered using the php interpreter.


Make sure you have the same php ( and phalcon ( versions installed on the target to
which you would like to deploy the test server.

As of this writing OPNsense uses php 7.4.x and Phalcon 4.1.x.

In theory this approach should function on both unix like machines and Windows.

Prepare machine (OSX)

When using homebrew ( on OSX, the easiest option to get you started is by executing
the following commands:

brew install php@7.4
brew tap phalcon/extension
brew install phalcon


Clone this repository and copy config/config.local.php.sample to
config/config.local.php then fill in the required parameters as noted in the
configuration sample.

Normally the only relevant configuration section is the environment section, which needs
absolute paths to both the OPNsense core files and the plugins you wish to expose.

For example, using the default build directories:

    'environment' => array(
        /* packages to include in setup */
        'packages'      => array(
        /* location of OPNsense core package */
        'coreDir'        => '/usr/core',

All working directories are pointed to the local directory where this
repository is checked out, to minimize the dependencies.


Startup the local server, which listens to port 8000 on localhost

php run_server.php

Finally point your browser to http://localhost:8000/ and test your ui software.

Using configd locally [*nix only]

To test drive template generation and command execution, it can be practical to have a configd instance running as well on your local machine.

In most cases paths will differ on a development machine, but being able to generate templates and execute commands may help the development process.

The documentation for configd itself can be found here

First step is to copy all the files in our service directory to your development location (the example below assumes current working directory):

rsync -avz /<path_to_core>/src/opnsense/service/* configd
cd configd
mkdir tmp

Next edit conf/configd.conf and change pid and socket location to something writeable from the current user.

To control where the templates are generated and which config it will use, you can edit the template configuration and change the config and root attributes in all sections

In conf/actions.d/actions_template.conf change:

  • config --> to our config to use
  • root --> where to write our template output

Finally let's spin up the configd process in a console (install missing python plugins using pip, when you are unable to start the process):

python console

Symlink the socket to the expected location (which OPNsense uses) so both our UI and command
line tools can reach it:

sudo ln -s /<install location>/configd/tmp/configd.socket /var/run/configd.socket

And check it's status in a new console, using:

python configd actions

Which should display a list of registered commands.

Finally make sure you disable simulate_mode in the config.local.php of your
local server (restart to apply changes).