Working with Log Files

The format of log files is described in Log Format, read that section before proceeding.

pfSense® Plus software version 21.02, pfSense CE software version 2.5.0, and later versions utilize plain text log files which can be used by a variety of traditional shell utilities. There are also utilities compatible with the various types of compressed rotated log files.

pfSense® software versions older than 21.02/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. These binary log files cannot be processed directly by shell utilities and must first be unwrapped with the clog utility.

Viewing Log Contents (21.02/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 follows 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 (< 21.02/2.5.0, clog)

On versions of pfSense software before 21.02/2.5.0, the contents of binary circular log files can only be read using the clog command:

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.