Working with Log Files

pfSense® software version 2.5.0 uses plain text log files which can be used by a variety of traditional shell utilities.

The firewall periodically rotates log files to keep their size in check. The rotation behavior is controlled by the log settings (Log Rotation Settings). There is one main log file, plus a number of rotated log files. The rotated log files are compressed by default. The GUI understands each compression option and will display and search contents of rotated log files in addition to the main log file. This adds processing time but vastly increases the amount of log data available to the GUI.

pfSense® software versions older than 2.5.0 use a binary circular log format known as clog to maintain a constant log size without the need for rotation. As syslogd writes new entries to a clog file, it removes older entries automatically. As such, the older data is lost.

Though there were multiple benefits to binary circular logs, such as restricting log file sizes, the downsides were too significant on modern systems. Among other reasons, binary circular logs were not very flexible, could not be used directly by shell utilities, were susceptible to corruption, and could not reliably store larger amounts of log data. Furthermore, the original justification for size restrictions were primarily based on hardware choices from over a decade ago. Hardware, even embedded system hardware, is much more capable now.

Viewing Log Contents (2.5.0 and later)

To view the contents of a log, use common shell utilities, such as cat, grep, and so on:

cat /var/log/filter.log
grep -i "error" /var/log/system.log

To follow the contents of a log file in real time, use tail -f or tail -F. The latter form will also follow the log to a new file after rotation.

tail -F /var/log/filter.log

In addition to the main log file, the rotated log files can be viewed and searched by passing them through utilities specific to the format with which they are compressed. For example, the default compression type is bzip2, so use bzcat, or bzgrep:

bzcat /var/log/filter.log.0.bz2
bzgrep -i "error" /var/log/system.log.0.bz2

Additional utilities can be utilized by piping the output.

The following list contains the different compression options and a sample of utilities which can parse their contents:

bzip2 (*.log.<number>.bz2)

bzcat, bzgrep, bzless.

gzip (*.log.<number>.gz)

zcat, zgrep, zless.

xz (*.log.<number>.xz)

xzcat, xzgrep, xzless.

zstd (*.log.<number>.zst)

zstdcat, zstdgrep, zstdless.

none (*.log.<number>)

cat, grep, less, plus anything else capable of parsing text files.

Viewing Log Contents (< 2.5.0, clog)

On versions of pfSense software before 2.5.0, the clog command must be used to view the contents of binary circular log files from the shell:

clog /var/log/filter.log

The output of that command may then be piped to tools like grep:

clog /var/log/system.log | grep -i "error"

To follow the log files in a manner like tail -f, use clog -f:

clog -f /var/log/filter.log

The command prints the entire contents of the log file to the console, and then prints new entries as they are written.

Log Sizes

The default is 500 KiB per log file, and there are around 20 log files. When increasing log sizes, keep disk space in mind. There is a disk space indicator for the filesystem containing the logs under the Log File Size (Bytes) text description on Log Settings.

On 2.5.0, space for rotated log files is in addition to this limit. The rotation settings are described in Log Rotation Settings.

The log files created for use by pfSense with clog are a fixed size that holds a certain amount of data total, not log entries. As such, the number of log entries may vary widely depending on the length of the lines and message content. Log files typically contain between 2000 and 4000 entries, but it could be much more or less than that.

The GUI only shows 50 lines per log by default but the files contain many more entries. See Log Settings for more information on that setting.