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 (Restoring from the Config 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