System Tunables

The System Tunables tab under System > Advanced provides a means to set runtime FreeBSD system tunables, also known as sysctl object identifiers (OIDs).

Tip

In most cases, the best practice is to leave these tunables at their default values.

Firewall administrators familiar with FreeBSD, or users acting under the direction of a developer or support representative, may want to adjust or add values on this page so that they will be set as the system starts.

Kernel State and Tunables

The sysctl facility on FreeBSD allows managing certain aspects of the kernel state through a “Management Information Base” (MIB) style tree composed of individual object identifiers (OIDs) containing components separated by periods. These individual sysctl OIDs are often referred to as “tunables” but not all of them can be changed.

See also

This is a simplified description. The sysctl manual page contains more detail.

The most common types of operating system tunables on FreeBSD are:

Runtime Tunables

The values of runtime tunables can be changed at any time while the system is running.

Loader Tunables

The values of loader tunables can only be changed at boot in the loader and they are read only afterward when the system is running.

Read Only Tunables

The values of read only tunables can never be changed manually, they are typically for reference or statistical purposes.

Tunable OIDs and Values

There are many OIDs available from sysctl. The full list of OIDs and their possible values is outside the scope of this documentation, but for those interested in digging a little deeper, The sysctl manual page from FreeBSD contains detailed instructions and information.

To see the current values of all visible OIDs, run:

# sysctl -a

Managing Runtime Tunables

Persistent values for runtime tunables can be managed from within the GUI.

To create a new tunable:

  • Navigate to System > Advanced, System Tunables tab

  • Click fa-plus New at the top right of the list

To edit an existing tunable:

  • Navigate to System > Advanced, System Tunables tab

  • Locate the entry to edit

  • Click fa-pencil on its row

Note

The tunables on this page are different from Loader Tunables. For details on loader tunables, see Managing Loader Tunables.

When editing or creating a tunable, the following fields are available:

Tunable:

The sysctl OID to set.

Value:

The value to which the Tunable will be set.

Note

Some values have formatting requirements. Due to the vast number of sysctl OIDs, the GUI does not validate that the given Value will work for the chosen Tunable.

Description:

An optional description for reference.

Click Save when the form is complete.

Managing Loader Tunables

Loader tunable values must be set before the kernel boots and user-defined loader tunables belong in /boot/loader.conf.local, which can be created or edited in several ways.

To determine loader tuneable values at boot the operating system first reads /boot/defaults/loader.conf, then /boot/loader.conf, and finally /boot/loader.conf.local. After the kernel boots, loader tunable values become read only.

These files each have a distinct purpose:

/boot/defaults/loader.conf

This file contains default values from FreeBSD and must not be changed as it will be rewritten during any upgrade.

/boot/loader.conf

This file contains loader values managed by pfSense software internally and must not be changed. It is rewritten each boot and when certain options are changed, and any manual modifications are discarded. Values in this file can override the operating system defaults.

/boot/loader.conf.local

Administrators can use this file to define custom loader tunable values. Since it is read last, it can override values from the OS default values as well as values set by pfSense internally.

This file does not exist by default, but can be created at any time.

This file is not backed up in config.xml, make a separate manual backup of its contents.

Note

Loader tunable values can also be defined for a single boot by setting them at the loader prompt from the boot menu.

Loader tunables are not currently manageable in the GUI in an integrated way, they must be manually managed by creating or editing the /boot/loader.conf.local file.

Users can create and edit that file in a variety of ways in the GUI or in the shell.

GUI File Editor

The file editor in the GUI can make changes to this file:

  • Navigate to Diagnostics > Edit File

  • Enter /boot/loader.conf.local in the Path to file to be edited box

  • Click Load to load the existing content in the file if any exists

    If the file does not exist, the editor will print an error. This error can be ignored.

  • Enter the loader tunable OIDs and values in the file, one per line.

    Comments can also be added by starting a line with #

    Example:

    # Disable flow control on all ix interfaces
hw.ix.flow_control="0"

  • Click Save

Reboot the firewall to activate the new tunable values.

Shell Editors

Similar to the above process, any text editor available in the shell can make changes to /boot/loader.conf.local. Available editors include vi and ee in the base system, along with vim and nano which are available to install via pkg. These changes must be made as the admin or root user, or by a user given sufficient access using the sudo package.