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
clog to maintain a constant log size without the need for rotation.
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
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
-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
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 (
- gzip (
- xz (
- zstd (
- none (
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:
The output of that command may then be piped to tools like
clog /var/log/system.log | grep -i "error"
To follow the log files in a manner like
tail -f, use
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.
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.