Automate pfSense with pfSsh.php
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.
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
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 ) ) )
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
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 a[email protected] '/usr/local/sbin/pfSsh.php' < MyConfig.txt