Developer Notes

pfSense stores it's configuration information in an XML file: /cf/conf/config.xml See https://docs.netgate.com/pfsense/en/latest/book/config/pfsense-xml-configuration-file.html

pfSense writes a cached version of the config.xml file as /tmp/config.cache in json format. This what the GUI loads, so we remove it after writing a new config.xml file so that pfSense automatically regenerates it from the new configuration.

pfSense does not provide any kind of API and does not have any separation between the web front-end and back-end configuration - it's all one big pile of code. So we need to replicate all input validation and call the php functions directly to implement changes when needed. It does provide a php developer shell that allows us to do this. See https://docs.netgate.com/pfsense/en/latest/development/using-the-php-pfsense-shell.html

Functions for applying configurations:

• captiveportal_allowedhostname_configure()
• captiveportal_allowedip_configure()
• captiveportal_configure()
• captiveportal_filterdns_configure()
• captiveportal_passthrumac_configure($filename = false, $startindex = 0, $stopindex = 0)
• filter_configure($reset_accounts = true)
• filter_configure()
• interface_6rd_configure($interface = "wan", $wancfg)
• interface_6to4_configure($interface = "wan", $wancfg)
• interface_bridge_configure(&$bridge, $checkmember = 0)
• interface_carp_configure(&$vip, $maintenancemode_only = false)
• interface_configure($interface = "wan", $reloadall = false, $linkupevent = false)
• interface_dhcp_configure($interface = "wan")
• interface_dhcpv6_configure($interface = "wan", $wancfg)
• interface_gif_configure(&$gif, $gifkey = "")
• interface_gre_configure(&$gre, $grekey = "")
• interface_ipalias_configure(&$vip)
• interface_ipsec_vti_configure($ph1ent)
• interface_lagg_configure($lagg)
• interface_ppps_configure($interface)
• interface_proxyarp_configure($interface = "")
• interface_qinq2_configure(&$qinq, &$cmdbuf, $macaddr)
• interface_qinq_configure(&$qinq, $fd = NULL)
• interface_track6_6rd_configure($interface = "lan", $lancfg)
• interface_track6_6to4_configure($interface = "lan", $lancfg)
• interface_track6_configure($interface = "lan", $wancfg, $linkupevent = false)
• interface_vlan_configure(&$vlan)
• interface_wireless_configure($if, &$wl, &$wlcfg)
• interfaces_bridge_configure($checkmember = 0, $realif = "")
• interfaces_carp_configure()
• interfaces_configure()
• interfaces_gif_configure($checkparent = 0, $realif = "")
• interfaces_gre_configure($checkparent = 0, $realif = "")
• interfaces_ipsec_vti_configure()
• interfaces_lagg_configure($realif = "")
• interfaces_loopback_configure()
• interfaces_qinq_configure()
• interfaces_staticarp_configure($if)
• interfaces_vips_configure($interface = "")
• interfaces_vlan_configure($realif = "")
• relayd_configure($kill_first=false)
• services_dhcpd_configure($family = "all", $blacklist = array())
• services_dhcpdv4_configure()
• services_dhcpdv6_configure($blacklist = array())
• services_dhcrelay6_configure()
• services_dhcrelay_configure()
• services_dnsmasq_configure($restart_dhcp = true)
• services_dyndns_configure($int = "")
• services_igmpproxy_configure()
• services_radvd_configure($blacklist = array())
• services_snmpd_configure()
• services_unbound_configure($restart_dhcp = true)
• system_dhcpleases_configure()
• system_hostname_configure()
• system_ntp_configure()
• system_routing_configure($interface = "")
• system_staticroutes_configure($interface = "", $update_dns = false)
• system_timezone_configure()
• voucher_configure($sync = false)
• vpn_ipsec_configure($restart = false)
• vpn_l2tp_configure()
• vpn_pppoe_configure(&$pppoecfg)
• vpn_pppoes_configure()

When changes are made in the GUI that are not immediately applied (like filewall rules), it will mark that system as "dirty". The GUI will then show that there are outstanding changes to be applied. After we apply our changes via the php shell we also clear the subsystem as being dirty. This because our action will have applied any other outstanding changes made in the GUI. Another possibility is for us to check if the subsystem is dirty and to abort making any changes in that situation. But those changes will have already been written to config.xml so there isn't any possibility of unexpected changes being applied after ours.

Subsystems:

• aliases
• filter
• gwgroup.' . $gateway_group['name']);
• hosts
• igmpproxy
• interfaces
• ipsec
• l2tpusers
• loadbalancer
• natconf
• pkg
• restore
• shaper
• staticmaps
• staticmapsv6
• staticroutes
• sysctl
• unbound
• vip
• vpnpppoe