pfSense has a completely redesigned user interface since several versions (checkout our install guide). All settings can be easily reached and adjusted with this interface. The freely configurable dashboard is also a fine thing. However, there is sometimes the case that you would like to make settings via an API or the command line. pfSense does not currently have an API, this will only be available in one of the upcoming versions. Until then you can use the pfSense developer shell, also called pfSsh.php.

Accessing pfSsh.php

The fastest way to get to the developer shell is to connect to pfSense via SSH or directly connect a screen to the firewall. If SSH is not yet activated, you can do this in the web interface under System → Advanced.

It is better to forbid logging in with a password and only allow logging in with a certificate.

If the SSH access is activated, you can now log in with the admin user (adjust IP):

$ ssh [email protected]

Under point 12 you will find the developer shell, which is basically a PHP shell.

Example commands for pfSsh.php

Here are some sample commands to show you how to use the shell. Each input is normal PHP code and must be completed with exec;.

Show DHCP settings

pfSense shell: print_r($config["dhcpd"]);
pfSense shell: exec;
Array
(
    [lan] => Array
        (
            [range] => Array
                (
                    [from] => 10.0.1.7
                    [to] => 10.0.255.245
                )

        )

)

Set domain

pfSense shell: $config['system']['domain'] = 'mydomain.com';
pfSense shell: write_config();
pfSense shell: exec;

Execute regular shell commands

Within the PHP shell you can also execute normal shell commands by placing a “!” in front of it:

pfSense shell: ! cat /etc/version
pfSense shell: exec;
2.4.3-RELEASE

“Record” and “Playback” Commands

With pfSsh.php you can also “record” several commands and “playback” them later. These so-called sessions are useful for recurring tasks. An example:

pfSense shell: record echoTest
Recording of echoTest started.
pfSense shell: echo "This\n";
pfSense shell: echo "is\n";
pfSense shell: echo "a\n";
pfSense shell: ! echo "test\n"
pfSense shell: exec;
pfSense shell: stoprecording
Recording stopped.

The entries are saved under /etc/phpshellsessions/ and can be edited there if necessary.

The “recording” can now be played back as follows:

pfSense shell: playback echoTest

Playback of file echoTest started.

The
is
a
test

pfSense shell:

or directly from the root shell:

$ pfSsh.php playback echoTest

Conclusion

pfSsh.php is a useful tool for automating pfSense with scripts or making customizations. Especially if you manage multiple instances or need a certain setup over and over again, pfSsh.php is a great help. For example, you can pack all settings (i.e. PHP code) into one file, save them under /etc/phpshellsessions/ and execute them, or forward the output directly to pfSsh.php:

$ ssh [email protected] '/usr/local/sbin/pfSsh.php' < MyConfig.txt