Using the PHP Shell

Using the PHP developer shell on pfSense® software allows manipulation of the firewall configuration directly without using the GUI. Using this mechanism also allows rapid deployment of pfSense software and/or the setup of exotic configurations.

The shell can be started from console menu option 12 or from the CLI by executing pfSsh.php.

Example Session

The following shows an example session, with the text coming from the help command in the PHP shell.

Follow each line or group of lines to run with exec;:

*** Welcome to pfSense ***

 WAN (wan)       -> vmx0       -> v4/DHCP4: 198.51.100.3/24
                                  v6/DHCP6: 2001:db8::ffff:22d6/128
 LAN (lan)       -> vmx1       -> v4: 10.3.0.1/24
                                  v6/t6: 2001:db8:1:eee0:20c:29ff:fe45:260/60

 0) Logout (SSH only)                  9) pfTop
 1) Assign Interfaces                 10) Filter Logs
 2) Set interface(s) IP address       11) Restart GUI
 3) Reset admin account and password  12) PHP shell + pfSense tools
 4) Reset to factory defaults         13) Update from console
 5) Reboot system                     14) Disable Secure Shell (sshd)
 6) Halt system                       15) Restore recent configuration
 7) Ping host                         16) Restart PHP-FPM
 8) Shell

Enter an option: 12

Starting the pfSense developer shell....

Welcome to the pfSense developer shell

Type "help" to show common usage scenarios.

Available playback commands:
     changepassword disablecarp disabledhcpd disablereferercheck enableallowallwan enablecarp
     enablesshd externalconfiglocator generateguicert gitsync installpkg listpkg removepkgconfig
     removeshaper restartdhcpd restartipsec svc uninstallpkg

pfSense shell: help

     Enter a series of commands and then execute the set with "exec".

     For example:
     echo "foo"; // php command
     echo "foo2"; // php command
     ! echo "heh" # shell command
     exec

     Example commands:

     record <recordingfilename>
     stoprecording
     showrecordings

     parse_config(true);  # reloads the $config array

     $temp = print_r($config, true);
     more($temp);

     /* to output a configuration array */
     print_r($config);

     /* to output the interfaces configuration portion of config.xml */
     print_r($config['interfaces']);

     /* to output the dhcp server configuration */
     print_r($config['dhcpd']);

     /* to exit the  developer shell */
     exit

     /* to output supported wireless modes for an interface */
     print_r(get_wireless_modes(\"ath0\"));

     /* to enable SSH */
     $config['system']['enablesshd'] = true;

     /* change OPTX to the OPT interface name such as BACKHAUL */
     $config['interfaces']['optx']['wireless']['standard'] = "11a";
     $config['interfaces']['optx']['wireless']['mode'] = "hostap";
     $config['interfaces']['optx']['wireless']['channel'] = "6";

     /* to enable dhcp server for an optx interface */
     $config['dhcpd']['optx']['enable'] = true;
     $config['dhcpd']['optx']['range']['from'] = "192.168.31.100";
     $config['dhcpd']['optx']['range']['to'] = "192.168.31.150";

     /* to disable the firewall filter */
     $config['system']['disablefilter'] = true;

     /* to enable an interface and configure it as a DHCP client */
     $config['interfaces']['optx']['disabled'] = false;
     $config['interfaces']['optx']['ipaddr'] = "dhcp";

     /* to enable an interface and set a static IPv4 address */
     $config['interfaces']['wan']['enable'] = true;
     $config['interfaces']['wan']['ipaddr'] = "192.168.100.1";
     $config['interfaces']['wan']['subnet'] = "24";

     /* to save out the new configuration (config.xml) */
     write_config();

     /* to reboot the system after saving */
     system_reboot_sync();

Playback Scripts

There are several pre-defined playback scripts for the PHP Shell that automate simple tasks or enable access to the GUI.

These scripts are run from within the PHP shell like so:

pfSense shell: playback scriptname

Warning

The PHP shell is not designed to run multiple playback scripts in a single session. After executing a playback script, exit the PHP shell and start it again. Otherwise subsequent scripts may fail to run. Alternately, run the playback scripts using the CLI method.

The scripts can also run from the command line:

# pfSsh.php playback scriptname

Warning

This must be run from an actual shell prompt over SSH or at the console. Do not attempt to run this through the GUI.

changepassword

This script changes the password for a user, and also prompts to reset the account properties if it is disabled or expired.

cryptconfig

This script can encrypt or decrypt configuration backups using the same method as doing so in the GUI when creating or restoring backups.

In either case, the script will prompt for the encryption passphrase. When decrypting, this passphrase must exactly match the passphrased used to encrypt the configuration file.

Usage:

# pfSsh.php playback cryptconfig <action> <input filename> <output filename>

To encrypt a configuration file:

# pfSsh.php playback crypt encrypt /conf/config.xml /root/config-backup.xml

To decrypt a configuration file:

# pfSsh.php playback crypt decrypt /root/config-backup.xml /root/config.xml

disablecarp / enablecarp

These scripts disable and enable CARP high availability functions, and will deactivate CARP type Virtual IP addresses.

This action does not persist across reboots.

disablecarpmaint / enablecarpmaint

These scripts disable and enable CARP maintenance mode, which leaves CARP active but demotes this unit so the other node can assume control.

This maintenance mode will persist across reboots.

disabledhcpd

This script removes all DHCP configuration from the firewall, effectively disabling the DHCP service and completely removing all of its settings.

disablereferercheck

This script disables the HTTP_REFERER check mentioned in Browser HTTP_REFERER enforcement. This can help gain access to the GUI if a browser session is triggering this protection.

enableallowallwan

This script adds an allow all rule for IPv4 and IPv6 to the WAN interface.

Warning

Be extremely careful with this option, it is meant to be a temporary measure to gain access to services on the WAN interface of the firewall in situations where the LAN is not usable. Once proper access rules are put in place, remove the rules added by this script.

enablesshd

This script enables the SSH daemon, the same as the console menu option or GUI option.

externalconfiglocator

This script looks for a config.xml file on an external device, such as a USB thumb drive, and will move it in place for use by the firewall.

gatewaystatus

This script prints the current gateway status and statistics. It also accepts an optional parameter brief which prints only the gateway name and status, omitting the addresses and statistical data.

generateguicert

This script creates a new self-signed certificate for the firewall and activates it for use in the GUI. This is useful in cases where the previous certificate is invalid or otherwise not usable. It fills in the certificate details using the firewall hostname and other custom information.

gitsync

This complex script synchronizes the PHP and other script sources with files from the pfSense CE software Github repository. It is most useful on CE development snapshots to pick up changes from more recent commits.

Warning

This script can be dangerous to use in other circumstances. Only use this under the direction of a knowledgeable developer or support representative.

Warning

This script is not currently compatible with pfSense Plus software.

If the script is run without any parameters it prints a help message outlining its use. More information can be found at Using gitsync to Update pfSense® Software Between Snapshots.

installpkg / listpkg / uninstallpkg

These scripts interface with the package system in a similar way to the GUI. These are primarily used for debugging package issues, comparing information in config.xml compared to the package database.

pfanchordrill

This script recursively searches through pf anchors and prints any NAT or firewall rules it finds. This can help track down unexpected behavior in areas such as UPnP or Captive Portal which rely on rules in anchors that are not otherwise visible in the GUI.

pftabledrill

This script prints the contents of all pf tables, which contain addresses used in firewall aliases as well as built-in system tables for features such as bogon network blocking, snort, and GUI/SSH lockout. This script is useful for checking if a specific IP address is found in any table, rather than searching individually.

removepkgconfig

This script removes all traces of package configuration data from the running config.xml. This can be useful if a package has corrupted settings or has otherwise left the packages in an inconsistent state.

removeshaper

This script removes ALTQ traffic shaper settings, which can be useful if the shaper configuration is preventing rules from loading or is otherwise incorrect and preventing proper operation of the firewall.

resetwebgui

This script resets the GUI settings for widgets, dashboard columns, the theme, and other GUI-related settings. It can return the GUI, particularly the dashboard, to a stable state if it is not functioning properly.

restartallwan

This script disables and re-enables each WAN-type interface, which reapplies the interface configuration.

restartdhcpd

This script stops and restarts the DHCP daemon.

restartipsec

This script rewrites and reloads the IPsec configuration for strongSwan.

svc

This script controls the services running on the firewall, similar to interacting with services at Status > Services.

The general form of the command is:

# pfSsh.php playback svc <action> <service name> [service-specific options]

The action can be stop, start, or restart.

The service name is the name of the services as found under Status > Services. If the name includes a space, enclose the name in quotes.

The service-specific options vary depending on the service, they are used to uniquely identify services with multiple instances, such as OpenVPN or Captive Portal entries.

Examples:

Stop miniupnpd:

# pfSsh.php playback svc stop miniupnpd

Restart OpenVPN client with ID 2:

# pfSsh.php playback svc restart openvpn client 2

Start the Captive Portal process for zone “MyZone”:

# pfSsh.php playback svc start captiveportal MyZone

upgradeconfig

Runs the current configuration, or optionally an arbitrary configuration file, through the configuration upgrade process.

The general form of the command is:

# pfSsh.php playback upgradeconfig [<input filename> <output filename>]

To force the current running configuration through the upgrade process:

# pfSsh.php playback upgradeconfig

To run the configuration upgrade process on a different configuration file:

# pfSsh.php playback upgradeconfig /root/oldconfig.xml /root/newconfig.xml

Warning

Some configuration upgrade steps may contain a directive to write the configuration which may unintentionally replace the current running configuration with the copy being upgraded at that step. After running this script on an arbitrary file, visit the configuration history (Configuration History) and roll back to the correct configuration if it was replaced. The upgrade process does not apply settings, so no additional action should be necessary.

Recording and Playback

Aside from the predefined scripts, users may create their own playback scripts by recording sessions.

This can easily automate a number of commands to repeat them later, saving time and effort.

Recording a session

# pfSsh.php
[...]

pfSense shell: record resetrrd
Recording of resetrrd started.
pfSense shell: require_once("filter.inc");
pfSense shell: require("shaper.inc");
pfSense shell: require_once("rrd.inc");
pfSense shell: ! rm /var/db/rrd/*.rrd
pfSense shell: enable_rrd_graphing();
pfSense shell: setup_gateways_monitor();
pfSense shell: stoprecording
Recording stopped.
pfSense shell: exit

Playing back a session

# pfSsh.php
[...]

pfSense shell: playback resetrrd

Playback of file resetrrd started.

pfSense shell: exit

Warning

The PHP shell is not designed to run multiple playback scripts in a single session. After executing a playback script, exit the PHP shell and start it again. Otherwise subsequent scripts may fail to run. Alternately, run the playback scripts using the CLI method.

Sessions can be played back directly from the command line as well:

# pfSsh.php playback resetrrd