XML Configuration File

pfSense® software stores its settings in an XML format configuration file. All configuration settings including settings for packages are held in this one file. Run-time configuration files for services and firewall behavior are generated dynamically based on the settings held within this XML configuration file.

Those familiar with FreeBSD and related operating systems have found this out the hard way, when their changes to system configuration files were repeatedly overwritten by the firewall before they came to understand that pfSense software handles everything automatically.

The configuration file is stored at /conf/config.xml on the firewall.

Manually editing the configuration

A handful of configuration options are only available by manually editing the configuration file, though this isn’t required in the vast majority of deployments. Some of these options are covered in other parts of this documentation where they are relevant. Additionally, for advanced administrators in rare cases large-scale or tricky changes may be easier to make by directly editing the configuration file.

Warning

Even for seasoned administrators it is easy to incorrectly edit the configuration file. Always keep backups and be aware that breaking the configuration will result in unintended consequences.

Edit a Backup

The safest and easiest method of editing the configuration file is to make a backup, edit the backup, and then restore:

  • Navigate to Diagnostics > Backup/Restore in the GUI

  • Download and save backup file

  • Open the file in a text editor that properly understands UNIX line endings, and preferably an editor that has special handling for XML such as syntax highlighting. Do not use notepad.exe on Windows.

  • Make changes to the configuration and save

  • Navigate to Diagnostics > Backup/Restore in the GUI

  • Restore the edited configuration

The firewall will automatically reboot as a part of the restoration process, and the new settings will be active afterward.

Edit In Place

Editing the configuration in-place is also possible in a variety of ways. The general procedure is:

  • Edit /conf/config.xml

  • Run rm /tmp/config.cache to clear the configuration cache

  • Reboot, or use the GUI to save/reload whichever part of the firewall utilizes the edited settings

From the console or ssh, administrators familiar with the vi editor can use the viconfig command to edit the running configuration, and this command automatically clears the cache file after saving and exiting.

Other editors are available on the firewall, such as ee or in the GUI under Diagnostics > Edit File (Editing Files on the Firewall). Clear the cache file manually after using one of these other methods, either using the shell or Diagnostics > Command Prompt (Command Prompt).